couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Couchdb Wiki] Update of "ExternalProcesses" by JoschaFeth
Date Sat, 26 Dec 2009 02:25:59 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "ExternalProcesses" page has been changed by JoschaFeth.
The comment on this change is: BLOB to CLOB, use base64 for binary data.


  = External Processes =
  CouchDB now allows for the ability to develop custom behaviors via processes that communicate
over ''stdin'' and ''stdout''. Requests to CouchDB that are captured by the external process
handler are passed via JSON object to the external process over ''stdin'' and reads a JSON
object from ''stdout''. Without further ado...
  == JSON Requests ==
  Requests capture information about the incoming HTTP request and transform it into a JSON
object. I've formatted the object here, though in real life this object would contain no new
lines and all embedded white space would be normalized to a single ' ' (space) character.
  An example object:
@@ -31, +29 @@

      'method': 'GET'
  In order:
   * ''body'' - Raw post body
@@ -46, +42 @@

  Note: Before CouchDB 0.11 `method` was `verb`.
  == JSON Response ==
  The response object has five possible elements
   * ''code'' - HTTP response code [Default is 200]. Note that this must be a number and cannot
be a string (no "").
   * ''headers'' - An object with key-value pairs that specify HTTP headers to send to the
   * ''json'' - An arbitrary JSON object to send the client. Automatically sets the Content-Type
header to "application/json"
-  * ''body'' - An arbitrary BLOB to be sent to the client. Content-Type header defaults to
+  * ''body'' - An arbitrary CLOB to be sent to the client. Content-Type header defaults to
   * ''base64'' - Arbitrary binary data for the response body, base64-encoded
  While nothing breaks if you specify both a ''json'' and ''body'' member, it is undefined
which response will be used. If you specify a Content-Type header in the ''headers'' member,
it will override the default.
  == Common Pitfalls ==
   * When responding to queries always remember to turn off buffering for ''stdout'' or issue
a ''flush()'' call on the file handle.
   * All interaction is in the form of single lines. Each response should include *exactly*
one new line that terminates the JSON object.
   * CouchDB 0.10 looks for a case-sensitive match of the Content-Type header -- a user-defined
header must specify "Content-Type", not "content-type" or "CoNtEnT-type".  This is fixed in
future releases.
  == Configuration ==
  Adding external processes is as easy as pie. Simply place key=command pairs in the ''[external]''
section of your ''local.ini'' and then map those handlers in the ''[httpd_db_handlers]'' section,
@@ -82, +75 @@

  ;unique notifier name=/full/path/to/exe -with "cmd line arg"
  This configuration will make the ''/usr/local/src/couchdb/'' responsible for handling
requests from the url:
  == Example External Process ==
  Here is a complete Python external process that does a whole lot of nothing except show
the mechanics.
- {{{
- #! /usr/bin/env python
+ {{{#! /usr/bin/env python
  import sys

View raw message