couchdb-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Walker <>
Subject CouchDB::ExternalProcess
Date Sat, 21 Feb 2009 15:36:27 GMT
Hi All,

I'd like to announce version 0.01 of CouchDB::ExternalProcess, a Perl
module that makes writing CouchDB External Processes easier.

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

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

So, with the following code in "", 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:

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

  _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:

And you can get an HTML confirmation of dancing at:


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:


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:


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 :)


View raw message