CouchDB::ExternalProcess

[Mike Walker]

Hi All,

I'd like to announce version 0.01 of CouchDB::ExternalProcess, a Perl
module that makes writing CouchDB External Processes easier.
   
http://search.cpan.org/~fansipans/CouchDB-ExternalProcess-0.01/lib/CouchDB/ExternalProcess.pm

All the work of reading input, parsing JSON, serializing a JSON
response, and writing output is managed, and can be overridden as
needed.

All that's needed to create a your own External Process is:

   use base qw/CouchDB::ExternalProcess/;

And then all subroutines marked with the ":Action" attribute can be
requested as a path component after the External Process' URL.

All :Action subroutines receive a parsed data structure from the
original JSON input, and simply return a Perl data structure in the same
structure as described by

   http://wiki.apache.org/couchdb/ExternalProcesses

So, with the following code in "Party.pm", in the directory "/mydir":

   package Party;
   use base qw/CouchDB::ExternalProcess/;

   my @styles = qw/ Ska Mosh Tango Hokey-Pokey /;

   sub dance :Action {
       my ($self, $req) = @_;

       my $style = $req->{query}->{style};

       die "Can't dance without a dance style!"
           unless $style;

       die "Invalid dance style specified"
           unless grep { $style eq $_ } @styles;

       my $response = {
           body => "<b>Dancing enabled!</b>";
       };

       return $response;
   }

   sub dance_styles :Action {
       return {
           json => {
               styles => \...@styles
           }
       };
   }

And the following configuration in your CouchDB's local.ini:

 [external]
 party = perl -I/mydir -MParty -e 'Party->new->run'

 [httpd_db_handlers]
 _party = {couch_httpd_external, handle_external_req, <<"party">>}


Now for any database DATABASE on your server SERVER you can get a JSON
data structure of allowed dance styles at:

   http://SERVER/DATABASE/_party/dance_styles

And you can get an HTML confirmation of dancing at:

   http://SERVER/DATABASE/_party/dance?style=Ska

Errors and exceptions from die() are captured and returned in a JSON
data structure containing the error message.

Pre/post request processing is allowed by defining _before and _after,
respectively. See the tests in the t/ directory of the distribution.

The logic that extracts the name of the Action to execute can be
overridden, currently the third path component is used:

   /database/external/ACTION_NAME

That can be overridden to use a CGI::Application style "rm" request
parameter with just:

   sub _extract_action_name {
       my ($self,$req) = @_;
       return $req->{query}->{rm};
   }

Also there's preliminary support for self-documentation of provided
services. :Action subroutines can also use the following attributes:

   :Description("...")
   :Args(...)

Then if the "Action" "_meta" is requested, a JSON document is returned
describing all services and their arguments.

Any comments / criticisms are welcome. Obviously this is 0.01 and I've
got a few things to improve. I do kindly request that all flames and
threats be submitted in haiku format.

Thanks and props to the CouchDB team! You guys are working on a
really cool project :)

-Mike