Skip to content
Newer
Older
100644 223 lines (157 sloc) 6.45 KB
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
1 # JSON-RPC client and server
2
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
3 Supports [2.0 specification](http://jsonrpc.org/spec.html).
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
4
aa2f96b @bbkr Module is included in Rakudo Star distribution now.
authored Apr 26, 2012
5 Compatible with Perl 6 [Rakudo](http://rakudo.org/) 2012.01+,
6 included in Rakudo Star 2012.04+.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
7
8 ## CLIENT
9
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
10 ```perl
11 use JSON::RPC::Client;
12
13 # create new client with url to server
14 my $c = JSON::RPC::Client.new( url => 'http://localhost:8080' );
15
16 # method without params
17 say $c.ping;
18
19 # method with positional params
20 say $c.hi( 'John Doe' );
21
22 # method with named params
23 say $c.hello( name => 'John Doe' );
24 ```
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
25
26 ## SERVER
27
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
28 ```perl
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
29 use JSON::RPC::Server;
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
30
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
31 # define application class
32 # that will handle remote procedure calls
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
33 class My::App {
34
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
35 # method without params
36 method ping { return 'pong' }
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
37
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
38 # method with positional params
39 method hi ( Str $name! ) { return 'Hi ' ~ $name }
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
40
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
41 # method with named params
42 method hello ( Str :$name! ) { return 'Hello ' ~ $name }
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
43
44 # multi method with different signatures
45 multi method offer ( Int $age where { $age < 8 } ) {
46 return [ 'Toy' ];
47 }
48 multi method offer ( Int $age where { 8 <= $age <= 16 } ) {
49 return [ 'Computer', 'Pet' ];
50 }
51
52 }
53
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
54 # start server with your application as handler
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
55 JSON::RPC::Server.new( application => My::App ).run;
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
56 ```
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
57
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
58 Your server is now available at [http://localhost:8080](http://localhost:8080).
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
59
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
60 ## ADVANCED STUFF
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
61
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
62 Examples above _make easy things easy_, now it is time to make _hard things possible_.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
63
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
64 ### Protocol versions
65
66 There are 3 specs of JSON-RPC published:
67
68 * [1.0](http://json-rpc.org/wiki/specification) - Vanilla spec support is on TODO list.
69 * [1.1](http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html) - This one is unlikely to be supported as it is not popular and requires complex two-level error handlers.
70 * [2.0](http://jsonrpc.org/spec.html) - This one is almost fully supported, notifications and batches are on TODO list.
71
72 ### Can I bind server to other port that 8080?
73
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
74 Use port param in `run()` method.
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
75
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
76 ```perl
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
77 .run( port => 9999 );
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
78 ```
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
79
80 ### Should I use class name or object instance as server handler?
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
81
82 You can use both. Using class name results in static dispatch while using object instance allows you to initialize attributes in your class.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
83
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
84 ```perl
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
85 class My::App {
86
87 has $!db;
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
88 submethod BEGIN { $!db = ... } # connect to database
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
89
90 method ping ( ) { return 'pong' }
91
92 }
93
94 # BEGIN is not called
95 JSON::RPC::Server.new( application => My::App ).run;
96
97 # BEGIN is called
98 JSON::RPC::Server.new( application => My::App.new ).run;
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
99 ```
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
100
101 ### How can method be excluded from server handler dispatch?
102
103 Declare it as private.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
104
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
105 ```perl
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
106 method !get_database_info ( ) {
107 return 'username', 'password';
108 }
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
109 ```
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
110
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
111 ### Should I declare signatures for server handler methods?
112
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
113 It is recommended that you validate params in signatures instead of method bodies. This way server correctly returns "Invalid params" error (more info later) and method is not called if signature does not match - you can easily separate validation from logic.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
114
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
115 ```perl
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
116 method add_programmer (
117 Str :$name!,
118 Int :$age! where { $age >= 0 },
119 Int :$experience! where { $experience <= $age }
120 ) {
121 # params can be trusted here
122 # all fields are required and
123 # negative age or experience exceeding age shall not pass
124 $!db.insert( $name, $age, $experience );
125 }
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
126 ```
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
127
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
128 ### What happens when more than one server handler candidate matches?
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
129
130 When request can be dispatched to more than one multi method then first candidate in definition order is chosen. This is not an error.
131
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
132 ### Error handling
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
133
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
134 Errors defined in 2.0 spec are represented by `JSON::RPC::Error` exceptions:
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
135
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
136 * `JSON::RPC::ParseError` - Invalid JSON was received by the server.
137 * `JSON::RPC::InvalidRequest` - The structure sent by client is not a valid Request object.
138 * `JSON::RPC::MethodNotFound` - The method does not exist in server handler application.
139 * `JSON::RPC::InvalidParams` - Invalid method parameters, no handler candidates with matching signature found.
140 * `JSON::RPC::InternalError` - Remote method died.
141 * `JSON::RPC::TransportError` - Client specific error that may happen on transport layer.
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
142
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
143 Every exception has numeric `code` attribute that indicates the error type that occurred, text `message` attribute that provides a short description of the error and optional `data` attribute that contains additional information about the error.
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
144
934fc6a @bbkr Fixed formatting
authored Feb 9, 2012
145 **Client** can catch those exceptions.
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
146
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
147 ```perl
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
148 try {
149 $c.hello( 'John Doe' );
150 CATCH {
151 when JSON::RPC::MethodNotFound {
152 say 'Server is rude';
153 }
154 default {
155 # stringified exception is in human-readable form
156 say ~$_;
157 }
158 }
159 }
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
160 ```
5a1fd22 @bbkr NOM-compatible release
authored Feb 9, 2012
161
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
162 **Server** does all the exception handling automatically. For example if you provide application handler without some method client will receive "Method not found" error on call to this method. However if you want to report error from method it can be done in two ways.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
163
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
164 * End method using die.
fcbddbc @bbkr Fixed formatting
authored Feb 9, 2012
165
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
166 ```perl
167 method divide ( Int $x, Int $y ) {
168 die 'Cannot divide by 0' if $y ~~ 0;
169 return $x / $y;
170 }
171 ```
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
172
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
173 Client will receive `message` attribute 'Internal error' with explanation "Cannot divide by 0" as `data` attribute.
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
174
175 * Throw `JSON::RPC::Error` exception.
fcbddbc @bbkr Fixed formatting
authored Feb 9, 2012
176
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
177 ```perl
178 class My::App {
179 method treasure {
180 JSON::RPC::Error.new( code => -1, message => 'Access denied', data => 'Thou shall not pass' ).throw;
181 }
182 }
183 ```
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
184
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
185 Exception `JSON::RPC::Error` is composable so you can easily define your own errors.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
186
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
187 ```perl
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
188 class My::Error does JSON::RPC::Error {
27b498d @bbkr Compatibility fixes for 2012.02 Rakudo Star release.
authored Mar 1, 2012
189 method new {
190 self.bless( *, code => -1, message => "Access denied", data => "Thou shall not pass" );
191 }
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
192 }
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
193 ```
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
194
195 And use them in application handler.
196
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
197 ```perl
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
198 method treasure {
4fb3248 @bbkr Fixed formatting
authored Feb 9, 2012
199 My::Error.new.throw;
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
200 }
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
201 ```
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
202
203 ## TODO
204
948d577 @bbkr Bettter documentation of spec versions and error handling
authored Feb 9, 2012
205 * Notifications.
206 * Batches.
207 * Spec 1.0 support.
208 * Move to dedicated HTTP transport modules when available.
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
209
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
210 ##CHANGELOG
211
212 * 0.3 - compatibility fixes for Rakudo Star 2012.02
213 * 0.2 - working server, compatibility fixes for Rakudo NOM
214 * 0.1 - working client with 1.0 spec support
215
32127d4 @bbkr Added license info.
authored Mar 12, 2012
216 ##LICENSE
217
218 Released under [Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0).
219
bf07348 @bbkr Working server with full 2.0 spec support and tests.
authored Feb 4, 2012
220 ## CONTACT
221
222 You can find me (and many awesome people who helped me to develop this module)
792b3e9 @bbkr reformatted code blocks in documentation with syntax highlighting, ad…
authored Mar 1, 2012
223 on irc.freenode.net #perl6 channel as **bbkr**.
Something went wrong with that request. Please try again.