Add a router chapter.

2 files changed, 105 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 4a2623b23..2e78995b5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -28,6 +28,7 @@ Narrative documentation in chapter form explaining how to use
    narr/install
    narr/project
    narr/startup
+   narr/router
    narr/urlmapping
    narr/traversal
    narr/urldispatch
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
new file mode 100644
index 000000000..a44709cba
--- /dev/null
+++ b/docs/narr/router.rst
@@ -0,0 +1,104 @@
+.. _startup_chapter:
+
+How :mod:`repoze.bfg` Processes A Request
+=========================================
+
+Once a :mod:`repoze.bfg` application is up and running, it is ready to
+accept requests and return responses.
+
+What happens from the time a :term:`WSGI` request enters a
+:mod:`repoze.bfg` application through to the point that
+:mod:`repoze.bfg` hands off a response back to WSGI for upstream
+processing?
+
+#. A user initiates a request from his browser to the hostname and
+   port number of the WSGI server used by the :mod:`repoze.bfg`
+   application.
+
+#. The WSGI server used by the :mod:`repoze.bfg` application passes
+   the WSGI environment to the ``__call__`` method of the
+   :mod:`repoze.bfg` :term:`router` object.
+
+#. To service :term:`url dispatch`, the :mod:`repoze.bfg`
+   :term:`router` calls a :term:`Routes` "mapper" callable, which acts
+   as a :term:`root factory`.  The job of the mapper is to examine the
+   ``PATH_INFO`` and other various keys in the environment to
+   determine whether any user-defined :term:`route` matches the
+   current WSGI environment.  The :term:`router` passes the WSGI
+   environment as an argument to the mapper.
+
+#. If any route matches, the WSGI environment is mutated; a
+   ``bfg.routes.route`` key and a ``bfg.routes.matchdict`` are added
+   to the WSGI environment.  If a route *doesn't* match, neither of
+   these keys is added to the WSGI environment.
+
+#. Regardless of whether any route matched or not, the Routes mapper
+   returns a root object.  If a particular :term:`route` named a
+   ``factory`` argument, this factory is used to generate the root
+   object, otherwise a default :term:`root factory` is used.  If a
+   root factory argument was passed to the
+   ``repoze.bfg.router.make_app``, that callable is used to generate
+   the root object.  If the root factory argument passed to
+   ``make_app`` is ``None``, a default root factory is used to
+   generate a root.
+
+#. A :term:`WebOb` :term:`request` is generated using the WSGI
+   environment.  The request type (its class and any :term:`interface`
+   attached to it) is dependent upon a combination of the
+   ``REQUEST_METHOD`` of the WSGI environment as well as any
+   :term:`route` match.  For example, a very particular kind of
+   request object is generated when the request has a
+   ``REQUEST_METHOD`` of ``POST`` and a :term:`route` named "home"
+   matches.  We use the request type to determine exactly which
+   :term:`view` to call later.
+
+#. A ``NewRequest`` :term:`event` is sent to any subscribers.
+
+#. The :mod:`repoze.bfg` router calls a "traverser" function with the
+   root object and the WSGI environment.  The traverser function
+   attempts to traverse the root object (using any existing
+   ``__getitem__`` on the root object and subobjects) to find a
+   :term:`context`.  If the root object has no ``__getitem__`` method,
+   the root itself is assumed to be the context.  The exact traversal
+   agorithm is described in :ref:`traversal_chapter`. The traverser
+   function returns a dictionary, which contains a :term:`context` and
+   a :term:`view name` as well as other ancillary information.
+
+#. The request is decorated with various names returned from the
+   traverser (such as ``context``, ``view_name``, ``matchdict``, and
+   so forth), so they can be accessed via e.g. ``request.context``
+   within :term:`view` code.
+
+#. If an :term:`authentication policy` is in use, :mod:`repoze.bfg`
+   passes the context, the request, and the view_name to a function
+   which determines whether the view being asked for can be executed
+   by the requesting user, based on credential information in the
+   request and security information attached to the context.  If it
+   returns True, :mod:`repoze.bfg` allows processing to continue.  If
+   it returns False, it uses a "forbidden" view callable to generate a
+   response, and returns that response.
+
+#. If view execution is determined to be allowed, :mod:`repoze.bfg`
+   looks up a :term:`view` callable using the context, the request,
+   and the view name.  If a view callable doesn't exist for this
+   combination of objects (based on the type of the context, the type
+   of the request, and the value of the view name), :mod:`repoze.bfg`
+   uses a "not found" view callable to generate a response, and
+   returns that response.
+
+#. If a view callable was found, :mod:`repoze.bfg` calls the view
+   function.  The view function's response is a :term:`response`
+   object.
+
+#. A ``NewResponse`` :term:`event` is sent to any subscribers.
+
+#. The response object's ``app_iter``, ``status``, and ``headerlist``
+   attributes are used to generate a WSGI response.  The response is
+   sent back to the upstream WSGI server.
+
+This is a very high-level overview that leaves out various details.
+For more detail about subsystems invoked by the BFG router (like
+traversal, URL dispatch, views, and events), see
+:ref:`url_mapping_chapter`, :ref:`traversal_chapter`,
+:ref:`urldispatch_chapter`, :ref:`views_chapter`, and
+:ref:`events_chapter`.