| 1 | package McBain::WithGearmanXS; | ||
| 2 | |||
| 3 | # ABSTRACT: Load a McBain API as a Gearman worker | ||
| 4 | |||
| 5 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | |||
| 8 | 1 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 0 | ▶ | use Gearman::XS qw(:constants); |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 10 | use Gearman::XS::Worker; | ||
| 11 | use JSON; | ||
| 12 | |||
| 13 | our $VERSION = "2.000000"; | ||
| 14 | $VERSION = eval $VERSION; | ||
| 15 | |||
| 16 | =head1 NAME | ||
| 17 | |||
| 18 | McBain::WithGearmanXS - Load a McBain API as a Gearman worker | ||
| 19 | |||
| 20 | =head1 SYNOPSIS | ||
| 21 | |||
| 22 | # write your API as you normally would, and create | ||
| 23 | # a simple start-up script: | ||
| 24 | |||
| 25 | #!/usr/bin/perl -w | ||
| 26 | |||
| 27 | use warnings; | ||
| 28 | use strict; | ||
| 29 | use MyAPI -withGearmanXS; | ||
| 30 | |||
| 31 | MyAPI->work('localhost', 4730); | ||
| 32 | |||
| 33 | =head1 DESCRIPTION | ||
| 34 | |||
| 35 | C<McBain::WithGearmanXS> turns your L<McBain> API into a L<Gearman worker|Gearman::XS::Worker>, | ||
| 36 | making it easy to consume your APIs with L<Gearman clients|Gearman::XS::Client>. | ||
| 37 | |||
| 38 | When your API is loaded, this module will traverse its routes, and create a queue for each | ||
| 39 | methods found. So, for example, if your API looks like this... | ||
| 40 | |||
| 41 | package MyAPI; | ||
| 42 | |||
| 43 | use McBain; | ||
| 44 | |||
| 45 | get '/multiply' => ( | ||
| 46 | ... | ||
| 47 | ); | ||
| 48 | |||
| 49 | post '/divide' => ( | ||
| 50 | ... | ||
| 51 | ); | ||
| 52 | |||
| 53 | ...then the following queues will be created: | ||
| 54 | |||
| 55 | GET:/multiply | ||
| 56 | POST:/divide | ||
| 57 | |||
| 58 | The workers created receive payloads in JSON format, and convert them into the hash-refs your | ||
| 59 | API's methods expect to receive. Results are sent back to the clients in JSON as well. Note | ||
| 60 | that if an API method does not return a hash-ref, this runner module will automatically | ||
| 61 | turn it into a hash-ref to ensure that conversion into JSON will be possible. The created | ||
| 62 | hash-ref will have one key - holding the method's name, with whatever was returned from the | ||
| 63 | method as its value. For example, if method C<GET:/divide> in topic C</math> returns an | ||
| 64 | integer (say 7), then the client will get the JSON C<{ "GET:/math/divide": 7 }>. | ||
| 65 | |||
| 66 | =head2 CAVEATS | ||
| 67 | |||
| 68 | There are some disadvantages to using this runner: | ||
| 69 | |||
| 70 | =over | ||
| 71 | |||
| 72 | =item * Since a queue is created for every route and method in the API, C<McBain> cannot | ||
| 73 | intercept calls to routes that do not exist. | ||
| 74 | |||
| 75 | =item * You can't use regular expressions when defining queues. Well, you can, but they | ||
| 76 | won't work. | ||
| 77 | |||
| 78 | =item * Gearman provides no way of providing a detailed error message when jobs fail, | ||
| 79 | therefore all C<McBain> can do is indicate that the job has failed and no more. | ||
| 80 | |||
| 81 | =back | ||
| 82 | |||
| 83 | The first two I hope to overcome in a next version, or even a different runner, by creating | ||
| 84 | just one queue that simply forwards the requests to C<McBain>. | ||
| 85 | |||
| 86 | =head1 METHODS EXPORTED TO YOUR API | ||
| 87 | |||
| 88 | =head2 work( [ $host, $port ] ) | ||
| 89 | |||
| 90 | Connects the Gearman worker created by the module to the Gearman server | ||
| 91 | running at the host and port provided. If none are provided, C<localhost> | ||
| 92 | and C<4730> are used, respectively. | ||
| 93 | |||
| 94 | The method never returns, so that the worker listens for jobs continuously. | ||
| 95 | |||
| 96 | =head1 METHODS REQUIRED BY MCBAIN | ||
| 97 | |||
| 98 | This runner module implements the following methods required by C<McBain>: | ||
| 99 | |||
| 100 | =head2 init( ) | ||
| 101 | |||
| 102 | Creates the L</"work( $host, $port )"> method for the root topic of the API. | ||
| 103 | |||
| 104 | =cut | ||
| 105 | |||
| 106 | sub init { | ||
| 107 | my ($class, $target) = @_; | ||
| 108 | |||
| 109 | if ($target->is_root) { | ||
| 110 | no strict 'refs'; | ||
| 111 | *{"${target}::work"} = sub { | ||
| 112 | my ($pkg, $host, $port) = @_; | ||
| 113 | |||
| 114 | $host ||= 'localhost'; | ||
| 115 | $port ||= 4730; | ||
| 116 | |||
| 117 | my $worker = Gearman::XS::Worker->new; | ||
| 118 | |||
| 119 | $class->_register_functions($worker, $pkg, $McBain::INFO{$target}); | ||
| 120 | |||
| 121 | $worker->add_server($host, $port) == GEARMAN_SUCCESS | ||
| 122 | || confess "Can't connect to gearman server at $host:$port, ".$worker->error; | ||
| 123 | |||
| 124 | while (1) { | ||
| 125 | $worker->work(); | ||
| 126 | } | ||
| 127 | }; | ||
| 128 | } | ||
| 129 | } | ||
| 130 | |||
| 131 | =head2 generate_env( $job ) | ||
| 132 | |||
| 133 | Receives the L<Gearman::XS::Job> object and creates C<McBain>'s standard env | ||
| 134 | hash-ref from it. | ||
| 135 | |||
| 136 | =cut | ||
| 137 | |||
| 138 | sub generate_env { | ||
| 139 | my ($self, $job) = @_; | ||
| 140 | |||
| 141 | confess { code => 400, error => "Namespace must match <METHOD>:<ROUTE> where METHOD is one of GET, POST, PUT, DELETE or OPTIONS" } | ||
| 142 | unless $job->function_name =~ m/^(GET|POST|PUT|DELETE|OPTIONS):[^:]+$/; | ||
| 143 | |||
| 144 | my ($method, $route) = split(/:/, $job->function_name); | ||
| 145 | |||
| 146 | return { | ||
| 147 | METHOD => $method, | ||
| 148 | ROUTE => $route, | ||
| 149 | PAYLOAD => $job->workload ? decode_json($job->workload) : {} | ||
| 150 | }; | ||
| 151 | } | ||
| 152 | |||
| 153 | =head2 generate_res( $env, $res ) | ||
| 154 | |||
| 155 | Converts the result from an API method in JSON. Read the discussion under | ||
| 156 | L</"DESCRIPTION"> for more info. | ||
| 157 | |||
| 158 | =cut | ||
| 159 | |||
| 160 | sub generate_res { | ||
| 161 | my ($self, $env, $res) = @_; | ||
| 162 | |||
| 163 | $res = { $env->{METHOD}.':'.$env->{ROUTE} => $res } | ||
| 164 | unless ref $res eq 'HASH'; | ||
| 165 | |||
| 166 | return encode_json($res); | ||
| 167 | } | ||
| 168 | |||
| 169 | =head2 handle_exception( $err, $job ) | ||
| 170 | |||
| 171 | Simply calls C<< $job->send_fail >> to return a job failed | ||
| 172 | status to the client. | ||
| 173 | |||
| 174 | =cut | ||
| 175 | |||
| 176 | sub handle_exception { | ||
| 177 | my ($class, $err, $job) = @_; | ||
| 178 | |||
| 179 | $job->send_fail; | ||
| 180 | } | ||
| 181 | |||
| 182 | sub _register_functions { | ||
| 183 | my ($class, $worker, $target, $topic) = @_; | ||
| 184 | |||
| 185 | foreach my $route (keys %$topic) { | ||
| 186 | foreach my $meth (keys %{$topic->{$route}}) { | ||
| 187 | my $namespace = $meth.':'.$route; | ||
| 188 | $namespace =~ s!/$!! | ||
| 189 | unless $route eq '/'; | ||
| 190 | unless ( | ||
| 191 | $worker->add_function($namespace, 0, sub { | ||
| 192 | $target->call($_[0]); | ||
| 193 | }, {}) == GEARMAN_SUCCESS | ||
| 194 | ) { | ||
| 195 | confess "Can't register function $namespace, ".$worker->error; | ||
| 196 | } | ||
| 197 | } | ||
| 198 | } | ||
| 199 | } | ||
| 200 | |||
| 201 | =head1 CONFIGURATION AND ENVIRONMENT | ||
| 202 | |||
| 203 | No configuration files are required. | ||
| 204 | |||
| 205 | =head1 DEPENDENCIES | ||
| 206 | |||
| 207 | C<McBain::WithGearmanXS> depends on the following CPAN modules: | ||
| 208 | |||
| 209 | =over | ||
| 210 | |||
| 211 | =item * L<Carp> | ||
| 212 | |||
| 213 | =item * L<Gearman::XS> | ||
| 214 | |||
| 215 | =item * L<JSON> | ||
| 216 | |||
| 217 | =back | ||
| 218 | |||
| 219 | =head1 INCOMPATIBILITIES WITH OTHER MODULES | ||
| 220 | |||
| 221 | None reported. | ||
| 222 | |||
| 223 | =head1 BUGS AND LIMITATIONS | ||
| 224 | |||
| 225 | Please report any bugs or feature requests to | ||
| 226 | C<bug-McBain-WithGearmanXS@rt.cpan.org>, or through the web interface at | ||
| 227 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=McBain-WithGearmanXS>. | ||
| 228 | |||
| 229 | =head1 SUPPORT | ||
| 230 | |||
| 231 | You can find documentation for this module with the perldoc command. | ||
| 232 | |||
| 233 | perldoc McBain::WithGearmanXS | ||
| 234 | |||
| 235 | You can also look for information at: | ||
| 236 | |||
| 237 | =over 4 | ||
| 238 | |||
| 239 | =item * RT: CPAN's request tracker | ||
| 240 | |||
| 241 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=McBain-WithGearmanXS> | ||
| 242 | |||
| 243 | =item * AnnoCPAN: Annotated CPAN documentation | ||
| 244 | |||
| 245 | L<http://annocpan.org/dist/McBain-WithGearmanXS> | ||
| 246 | |||
| 247 | =item * CPAN Ratings | ||
| 248 | |||
| 249 | L<http://cpanratings.perl.org/d/McBain-WithGearmanXS> | ||
| 250 | |||
| 251 | =item * Search CPAN | ||
| 252 | |||
| 253 | L<http://search.cpan.org/dist/McBain-WithGearmanXS/> | ||
| 254 | |||
| 255 | =back | ||
| 256 | |||
| 257 | =head1 AUTHOR | ||
| 258 | |||
| 259 | Ido Perlmuter <ido@ido50.net> | ||
| 260 | |||
| 261 | =head1 LICENSE AND COPYRIGHT | ||
| 262 | |||
| 263 | Copyright (c) 2013, Ido Perlmuter C<< ido@ido50.net >>. | ||
| 264 | |||
| 265 | This module is free software; you can redistribute it and/or | ||
| 266 | modify it under the same terms as Perl itself, either version | ||
| 267 | 5.8.1 or any later version. See L<perlartistic|perlartistic> | ||
| 268 | and L<perlgpl|perlgpl>. | ||
| 269 | |||
| 270 | The full text of the license can be found in the | ||
| 271 | LICENSE file included with this module. | ||
| 272 | |||
| 273 | =head1 DISCLAIMER OF WARRANTY | ||
| 274 | |||
| 275 | BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | ||
| 276 | FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN | ||
| 277 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | ||
| 278 | PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER | ||
| 279 | EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
| 280 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE | ||
| 281 | ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH | ||
| 282 | YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL | ||
| 283 | NECESSARY SERVICING, REPAIR, OR CORRECTION. | ||
| 284 | |||
| 285 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | ||
| 286 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | ||
| 287 | REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE | ||
| 288 | LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, | ||
| 289 | OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE | ||
| 290 | THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING | ||
| 291 | RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A | ||
| 292 | FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF | ||
| 293 | SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF | ||
| 294 | SUCH DAMAGES. | ||
| 295 | |||
| 296 | =cut | ||
| 297 | |||
| 298 | 1; | ||
| 299 | __END__ | ||