doc: add sections on theory/{routes,route_matching}

Co-authored-by: Roberto Abdelkader Martínez Pérez <robertomartinezp@gmail.com>

docs/source/index.rst

@@ -20,6 +20,7 @@
    theory/philosophy
    theory/request_life_cycle
    theory/resource_tree
+   theory/routes
 
 
 

docs/source/theory/route_matching.rst

@@ -0,0 +1,12 @@
+Route Matching
+==============
+
+Route table
+-----------
+
+    Kapow! maintains a route table as provided by the user, and uses it to determine
+    which handler should an incoming request be dispatched to.
+
+    Each incoming request is matched against the routes in the route table in
+    strict order, for each route in the route table, the criteria are checked.
+    If the request does not match, the next route in the route list is examined.

docs/source/theory/routes.rst

@@ -0,0 +1,124 @@
+Routes
+======
+
+A Kapow! route specifies the matching criteria for an incoming request on
+the `User HTTP Interface`, and the details to handle it.
+
+Kapow! implements a *route table* where all routes reside.
+
+
+A route can be set like this:
+
+.. code-block:: bash
+
+   $ kapow route add \
+      -X POST \
+      '/register/{username}' \
+      -e '/bin/bash -c' \
+      -c 'touch /var/lib/mydb/"$(kapow get /request/matches/username)"' \
+      | jq
+   {
+      "id": "deadbeef-0d09-11ea-b18e-106530610c4d",
+      "method": "POST",
+      "url_pattern": "/register/{username}",
+      "entrypoint": "/bin/bash -c",
+      "command": "touch /var/lib/mydb/\"$(kapow get /request/matches/username)\""
+   }
+
+Let's use this example to discuss its elements.
+
+
+Elements
+--------
+
+``id`` Route Element
+~~~~~~~~~~~~~~~~~~~~
+
+Uniquely identifies each route. It is used for instance by ``kapow route remove
+<route_id>``.
+
+.. note::
+
+   The current implementation of Kapow! autogenerates a `UUID` for this field.
+   In the future the use will be able to specify a custom value.
+
+
+``method`` Route Element
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Specifies the HTTP method for the route to match the incoming request.
+
+The route shown above will only match a ``POST`` request.
+
+
+``url_pattern`` Route Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It matches the `path` component of the `URL` of the incoming request.
+
+It can contain regex placeholders for easily capturing fragments of the path.
+
+In the route shown above, a request with a URL ``/register/joe`` would match,
+assigning `joe` to the placeholder ``username``.
+
+Kapow! leverages Gorilla Mux for managing routes.  For the full story, see
+https://github.com/gorilla/mux#examples
+
+
+``entrypoint`` Route Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This sets the executable to be spawned, along with any arguments required.
+
+In the route shown above, the entrypoint that will be run is ``/bin/bash -c``,
+which is an incomplete recipe.  It is completed by the `command` element.
+
+.. todo::
+
+   link to command below
+
+
+.. note::
+
+   The semantics of this element closely match `Docker`'s ``ENTRYPOINT`` directive.
+
+.. todo::
+
+   link to Docker docu
+
+
+``command`` Route Element
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an optional last argument to be passed to the ``entrypoint``.
+
+In the route shown above, it completes the `entrypoint` to form the final
+incantation to be executed:
+
+.. todo::
+
+   link to entrypoint above
+
+.. code-block::
+
+   /bin/bash -c 'touch /var/lib/mydb/"$(kapow get /request/matches/username)"'
+
+.. note::
+
+   The semantics of this element closely match `Docker`'s ``COMMAND`` directive.
+
+.. todo::
+
+   link to Docker docu
+
+
+Matching Algorithm
+------------------
+
+`Kapow!` leverages Gorilla Mux for this task. You can see the gory details in
+their documentation.
+
+
+.. todo::
+
+   link to Gorilla Mux docu