This file is indexed.

/usr/share/perl5/JSON/RPC.pm is in libjson-rpc-perl 1.06-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
package JSON::RPC;
use strict;
our $VERSION = '1.06';

1;

__END__

=head1 NAME

JSON::RPC - JSON RPC 2.0 Server Implementation

=head1 SYNOPSIS

    # app.psgi
    use strict;
    use JSON::RPC::Dispatch;

    my $dispatch = JSON::RPC::Dispatch->new(
        prefix => "MyApp::JSONRPC::Handler",
        router => Router::Simple->new( ... )
    );

    sub {
        my $env = shift;
        $dispatch->handle_psgi($env);
    };

=head1 DESCRIPTION

JSON::RPC is a set of modules that implement JSON RPC 2.0 protocol.

    If you are using old JSON::RPC code (up to 0.96), DO NOT EXPECT
    YOUR CODE TO WORK WITH THIS VERSION. THIS VERSION IS 
    ****BACKWARDS INCOMPATIBLE****

=head1 BASIC USAGE

The JSON::RPC::Dispatch object is responsible for marshalling the request.

    my $dispatch = JSON::RPC::Dispatch->new(
        router => ...,
    );

The routing between the JSON RPC methods and their implementors are handled by
Router::Simple. For example, if you want to map method "foo" to a "MyApp::JSONRPC::Handler" object instance's "handle_foo" method, you specify something like the following in your router instance:

    use Router::Simple::Declare;
    my $router = router {
        connect "foo" => {
            handler => "+MyApp::JSONRPC::Handler",
            action  => "handle_foo"
        };
    };

    my $dispatch = JSON::RPC::Dispatch->new(
        router => $router,
    );

The "+" prefix in the handler classname denotes that it is already a fully qualified classname. Without the prefix, the value of "prefix" in the dispatch object will be used to qualify the classname. If you specify it in your Dispatch instance, you may omit the prefix part to save you some typing:

    use JSON::RPC::Dispatch;
    use Router::Simple::Declare;

    my $router = router {
        connect "foo" => {
            handler => "Foo",
            action  => "process",
        };
        connect "bar" => {
            handler => "Bar",
            action => "process"
        }
    };
    my $dispatch = JSON::RPC::Dispatch->new(
        prefix => "MyApp::JSONRPC::Handler",
        router => $router,
    );

    # The above will roughly translate to the following:
    #
    # for method "foo"
    #    my $handler = MyApp::JSONRPC::Handler::Foo->new;
    #    $handler->process( ... );
    #
    # for method "bar"
    #    my $handler = MyApp::JSONRPC::Handler::Bar->new;
    #    $handler->process( ... );


The implementors are called handlers. Handlers are simple objects, and will be instantiated automatically for you. Their return values are converted to JSON objects automatically.

You may also choose to pass objects in the handler argument to connect in  your router. This will save you the cost of instantiating the handler object, and you also don't have to rely on us instantiating your handler object.

    use Router::Simple::Declare;
    use MyApp::JSONRPC::Handler;

    my $handler = MyApp::JSONRPC::Handler->new;
    my $router = router {
        connect "foo" => {
            handler => $handler,
            action  => "handle_foo"
        };
    };

=head1 HANDLERS

Your handlers are objects responsible for returning some sort of reference structure that can be properly encoded via JSON/JSON::XS. The handler only needs to implement the methods that you specified in your router.

The handler methods will receive the following parameters:

    sub your_handler_method {
        my ($self, $params, $procedure, @extra_args) = @_;

        return $some_structure;
    }

In most cases you will only need the parameters. The exact format of the $params is dependent on the caller -- you will be passed whatever JSON structure that caller used to call your handler.

$procedure is an instance of JSON::RPC::Procedure. Use it if you need to figure out more about the procedure.

@extra_args is optional, and will be filled with whatever extra arguments you passed to handle_psgi(). For example, 

    # app.psgi
    sub {
        $dispatch->handle_psgi($env, "arg1", "arg2", "arg3");
    }

will cause your handlers to receive the following arguments:

    sub your_handler_method {
        my ($self, $params, $procedure, $arg1, $arg2, $arg3) = @_;

    }

This is convenient if you have application-specific data that needs to be passed to your handlers.

=head1 EMBED IT IN YOUR WEBAPP

If you already have a web app (and whatever framework you might already have), you may choose to embed JSON::RPC in your webapp instead of directly calling it in your PSGI application.

For example, if you would like to your webapp's "rpc" handler to marshall the JSON RPC request, you can do something like the following:

    package MyApp;
    use My::Favorite::WebApp;

    sub rpc {
        my ($self, $context) = @_;

        my $dispatch =  ...; # grab it from somewhere
        $dispatch->handle_psgi( $context->env );
    }

=head1 ERRORS

When your handler dies, it is automatically included in the response hash, unless no response was requested (see L</NOTIFICATIONS>).

For example, something like below 

    sub rpc {
        ...
        if ($bad_thing_happend) {
            die "Argh! I failed!";
        }
    }

Would result in a response like

    {
        error => {
            code => -32603,
            message => "Argh! I failed! at ...",
        }
    }

However, you can include custom data by die()'ing with a hash:

    sub rpc {
        ...
        if ($bad_thing_happend) {
            die { message => "Argh! I failed!", data => time() };
        }
    }

This would result in:

    {
        error => {
            code => -32603,
            message => "Argh! I failed! at ...",
            data => 1339817722,
        }
    }

=head1 NOTIFICATIONS

Notifications are defined as procedures without an id.
Notification handling does not produce a response. When all procedures are notifications no content is returned (if the request is valid).
To maintain some basic compatibility with relaxed client implementations, JSON::RPC::Dispatch includes responses when procedures do not have a "jsonrpc" field set to "2.0".

Note that no error is returned in response to a notification when the handler dies or when the requested method is not available.

For example, a request structure like this:

    [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "keep_alive"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"}
    ]

Would result in a response like

    [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

=head1 BACKWARDS COMPATIBILITY

Eh, not compatible at all. JSON RPC 0.xx was fine, but it predates PSGI, and things are just... different before and after PSGI.

Code at version 0.96 has been moved to JSON::RPC::Legacy namespace, so change your application to use JSON::RPC::Legacy if you were using the old version.

=head1 AUTHORS

Daisuke Maki

Shinichiro Aska

Yoshimitsu Torii

=head1 AUTHOR EMERITUS

Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> - JSON::RPC modules up to 0.96

=head1 COPYRIGHT AND LICENSE

The JSON::RPC module is

Copyright (C) 2011 by Daisuke Maki

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.0 or,
at your option, any later version of Perl 5 you may have available.

See JSON::RPC::Legacy for copyrights and license for previous versions.

=cut