CouchDB::ExternalProcess

[Mike Walker <mi...@napkindrawing.com>]

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