You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/08/26 18:22:20 UTC
[4/6] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 26d9c02
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/bf9d9ce5
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/bf9d9ce5
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/bf9d9ce5
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: bf9d9ce53f4bfcd4ffdb1ff9e081509c121ffd03
Parents: 49d6be6
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 16:52:13 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sun Aug 25 16:52:13 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/bf9d9ce5/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