Externals API article cleanup.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b35bf757 Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b35bf757 Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b35bf757 Branch: refs/heads/1781-reorganize-and-improve-docs Commit: b35bf757e2376dac20b5a295e08bf208e5aa3ba0 Parents: fe79a4d Author: Alexander Shorin <[email protected]> Authored: Sun Aug 25 16:52:13 2013 +0400 Committer: Alexander Shorin <[email protected]> Committed: Fri Sep 27 22:01:47 2013 +0400 ---------------------------------------------------------------------- share/doc/src/externals.rst | 77 ++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 42 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/b35bf757/share/doc/src/externals.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst index 10ed34a..9b4530f 100644 --- a/share/doc/src/externals.rst +++ b/share/doc/src/externals.rst @@ -19,9 +19,10 @@ CouchDB Externals API :Author: Paul Joseph Davis :Date: 2010-09-26 +:Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html -For a bit of background, CouchDB has had an API for managing external OS -processes [1] that are capable of handling HTTP requests for a given +For a bit of background, CouchDB has had an API for managing `external OS +processes`_ that are capable of handling HTTP requests for a given URL prefix. These OS processes communicate with CouchDB using JSON over stdio. They're dead simple to write and provide CouchDB users an easy way to extend CouchDB functionality. @@ -50,7 +51,7 @@ fringe benefits as well. I'm always a fan of extra awesomeness. After hitting on the idea of adding a reverse proxy, people quickly pointed out that it would require users to start manually managing their external -processes using something like Runit [2] or Supervisord [3]. After some +processes using something like `Runit`_ or `Supervisord`_. After some more discussions I ran into people that wanted something like _externals that didn't handle HTTP requests. After that it was easy to see that adding a second feature that managed OS processes was the way to go. @@ -60,26 +61,23 @@ of working but requiring more testing. In the case of the HTTP proxy I have no tests because I can't decide how to test the thing. If you have ideas, I'd sure like to hear them. -[Update]: I woke up the other morning realizing that I was being an idiot and -that Erlang is awesome. There's no reason that I can't have an HTTP client, +**[Update]**: I woke up the other morning realizing that I was being an idiot +and that Erlang is awesome. There's no reason that I can't have an HTTP client, proxy, and server all hosted in the same process. So that's what I did. It turns out to be a fairly nice way of configuring matching assertions between the client and the server to test the proxy transmissions. -The code for both features is in this branch: - - http://github.com/davisp/couchdb/tree/new_externals - How does it work? - HTTP Proxying --------------------------------- -To configure a proxy handler, edit your local.ini and add a section like such: +To configure a :ref:`proxy handler <config/proxy>`, edit your `local.ini` and +add a section like such:: [httpd_global_handlers] _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985";>>} -This would be approximately what you'd need to do to get CouchDB-Lucene handled -through this interface. The URL you use to access a query would be: +This would be approximately what you'd need to do to get `CouchDB-Lucene`_ +handled through this interface. The URL you use to access a query would be: http://127.0.0.1:5984/_fti/db_name/_design/foo/by_content?q=hello @@ -105,7 +103,7 @@ one instance of it is alive. If you have something where you want multiple processes, you need to either tell CouchDB about each one, or have a main process that forks off the required sub-processes. -To configure an OS daemon, add this to your local.ini:: +To configure an :ref:`OS daemon <config/os_daemons>`, add this to your local.ini:: [os_daemons] my_daemon = /path/to/command -with args @@ -116,8 +114,8 @@ Configuration API As an added benefit, because stdio is now free, I implemented a simple API that OS daemons can use to read the configuration of their CouchDB host. This way you can have them store their configuration inside CouchDB's config system -if you desire. Or they can peek at things like the bind_address and port that -CouchDB is using. +if you desire. Or they can peek at things like the :ref:`bind_address +<config/httpd/bind_address>` and port that CouchDB is using. A request for a config section looks like this:: @@ -135,7 +133,7 @@ And the response:: "/path/to/command -with args"\n -All requests and responses are terminated with a newline (indicated by \n). +All requests and responses are terminated with a newline (indicated by ``\n``). Logging API +++++++++++ @@ -144,24 +142,26 @@ There's also an API for adding messages to CouchDB's logs. Its simply:: ["log", $MESG]\n -Where $MESG is any arbitrary JSON. There is no response from this command. As -with the config API, the trailing "\n" represents a newline byte. +Where ``$MESG`` is any arbitrary JSON. There is no response from this command. As +with the config API, the trailing ``\n`` represents a newline byte. Dynamic Daemons +++++++++++++++ The OS daemons react in real time to changes to the configuration system. If -you set or delete keys in the os_daemons section, the corresponding daemons -will be started or killed as appropriate. +you set or delete keys in the :ref:`os_daemons <config/os_daemons>` section, +the corresponding daemons will be started or killed as appropriate. Neat. But So What? ------------------ -It was suggested that a good first demo would be a Node.js [5] handler. So, I +It was suggested that a good first demo would be a `Node.js`_ handler. So, I present to you a "Hello, World" Node.js handler. Also, remember that this -currently relies on code in my fork on GitHub [6]. +currently relies on code in my fork on `GitHub`_. + +File `node-hello-world.js`: -File `node-hello-world.js`:: +.. code-block:: javascript var http = require('http'); var sys = require('sys'); @@ -202,7 +202,9 @@ File `node-hello-world.js`:: console.log(JSON.stringify(["get", "node_hello", "port"])); -File `local.ini` (Just add these to what you have):: +File `local.ini` (Just add these to what you have): + +.. code-block:: ini [log] level = info @@ -216,7 +218,9 @@ File `local.ini` (Just add these to what you have):: [httpd_global_handlers] _hello = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:8000";>>} -And then start CouchDB and try:: +And then start CouchDB and try: + +.. code-block:: bash $ curl -v http://127.0.0.1:5984/_hello * About to connect() to 127.0.0.1 port 5984 (#0) @@ -247,20 +251,9 @@ The corresponding CouchDB logs look like:: [info] [<0.95.0>] Daemon "node-hello" :: GET / -[1]: http://wiki.apache.org/couchdb/ExternalProcesses -[2]: http://smarden.org/runit/ -[3]: http://supervisord.org/ -[4]: http://www.mikealrogers.com/ -[5]: http://nodejs.org/ -[6]: http://github.com/davisp/couchdb/tree/new_externals - - -Copyright Notice ----------------- - -Copyright 2008-2010 Paul Joseph Davis - -License -------- - -http://creativecommons.org/licenses/by/3.0/ +.. _external OS processes: http://wiki.apache.org/couchdb/ExternalProcesses +.. _Runit: http://smarden.org/runit/ +.. _Supervisord: http://supervisord.org/ +.. _Node.js: http://nodejs.org/ +.. _GitHub: http://github.com/davisp/couchdb/tree/new_externals +.. _CouchDB-Lucene: https://github.com/rnewson/couchdb-lucene
