Update README with the new configuration and API

deps/rabbitmq_web_dispatch/README

@@ -2,7 +2,7 @@ rabbitmq-mochiweb
 --------
 
 rabbitmq-mochiweb is a thin veneer around mochiweb that provides the ability
-for multiple RabbitMQ plugins to co-exist under a single web-app root. Applications
+for multiple applications to co-exist on mochiweb listeners. Applications
 can register static docroots along with dynamic handlers to be executed based on
 various incoming request properties.
 
@@ -12,22 +12,87 @@ features introduced in Erlang R13A.
 Environment Variables
 ---------------------
 
-rabbitmq-mochiweb uses the standard OTP environment variables mechanism. It understands
-these variables:
+rabbitmq-mochiweb uses the standard OTP environment variables
+mechanism. It has this structure:
 
-* port -       The port to listen on (by default 55672);
+    Env = [{listeners, [Listener...]}, {contexts, [Context...]}]
+
+    Listener = {Name, [{port, Port} | Option...]}
+
+    Context = {Name, ListenerName}
+            | {Name, ListenerName, Path}
 
 Installation
 ------------
 
-After you've successfully run make on the plugin, the plugin can be installed by copying
-both mochiweb.ez and rabbitmq-mochiweb.ez to your Rabbit installation's plugins directory,
-then executing rabbitmq-activate-plugins.
+After you've successfully run make on the plugin, the plugin can be
+installed by copying both mochiweb.ez and rabbitmq-mochiweb.ez to your
+Rabbit installation's plugins directory.
 
-Configuration
--------------
+Configuration and API
+---------------------
 
-As indicated in the Environment Variables section, the rabbitmq-mochiweb plugin supports
-OTP application configuration values. These values can be set as either Erlang startup
-parameters or via the rabbitmq.config file, with a block such as:
-  {rabbit_mochiweb, [{port, 8080}]}
+As indicated in the Environment Variables section, the
+rabbitmq-mochiweb plugin supports OTP application configuration
+values. These values can be set as either Erlang startup parameters or
+via the rabbitmq.config file, with a block such as:
+
+    {rabbitmq_mochiweb, [{listeners, [{'*', [{port, 55672}]}]},
+                         {contexts,  []}]}
+
+There must be at least a default listener, named `'*'`. Each listener
+must have a port number, and may have other options, which are
+supplied to mochiweb as-is, aside from `name` and `loop`. `name`
+because that is generated from the listener name, and `loop` because
+that is supplied for each context.
+
+Each context must give the name of a listener that appears in the list
+of listeners. It may give a path, which overrides any path given for a
+context when it is registered.
+
+The procedures `register_*` exported from the module `rabbit_mochiweb`
+all take a context and a path as the first two arguments.
+
+When an application registers a context with rabbitmq-mochiweb, it
+supplies a context name, which is expected to be unique to that
+application, and a path prefix. If this context is mentioned in the
+environment, it is assigned to the listener given there. Its path
+prefix may also be overidden if it is given in the configuration. If
+it is not mentioned, it is assigned to the default listener.
+
+For example, for the configuration
+
+    {rabbitmq_mochiweb, [{listeners, [{'*', [{port, 55672}]},
+                                      {internal, [{port, 55670}]}]},
+                         {contexts,  [{myapp, internal, "myapp"}]}]}
+
+an application registering the context name 'myapp' will be assigned
+to the listener 'internal', listening on port 55670, and be available
+under the path `/myapp/` in URLs. An application registering with the
+context 'myotherapp' and the path "other" will be assigned to the
+default listener ('*'), listening on port 55672, and be available
+under "/other/".
+
+There is no attempt made to avoid clashes of paths, either those given
+in configuration or those given when registering.  Also note that an
+application may register more than one context.
+
+The most general registration procedure is
+`rabbit_mochiweb:register_context_handler/4`. This takes a callback
+procedure of the form
+
+    loop({PathPrefix, Listener}, Request) ->
+      ...
+
+The procedures `rabbit_mochiweb:context_path/1` and
+`rabbit_mochiweb:context_listener/1` may be used to obtain information
+about a context and the listener it is assigned to; for example, its
+port.
+
+The module `rabbit_webmachine` provides a means of running more than
+one webmachine in a VM, and understands rabbitmq-mochiweb contexts. To
+use it, supply a dispatch table term of the kind usually given to
+webmachine in the file `priv/dispatch.conf`.
+
+`setup/{1,2}` in the same module allows some global configuration of
+webmachine logging and error handling.