Merge remote-tracking branch 'origin/master'

docs/source/index.rst

@@ -20,7 +20,8 @@
    theory/philosophy
    theory/request_life_cycle
    theory/resource_tree
-
+   theory/route_matching
+   theory/routes
 
 
 Indices and tables

docs/source/theory/resource_tree.rst

@@ -50,8 +50,8 @@ Overview
 Resources
 ---------
 
-``/request/method``
+``/request/method`` Resource
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The HTTP method of the incoming request.
 
@@ -71,8 +71,8 @@ then, when handling the request:
    POST
 
 
-``/request/host``
+``/request/host`` Resource
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``Host`` header as defined in the HTTP/1.1 spec of the incoming
 request.
@@ -93,8 +93,8 @@ then, when handling the request:
    kapow.example
 
 
-``/request/path``
+``/request/path`` Resource
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the path substring of the URL.
 
@@ -113,8 +113,8 @@ then, when handling the request:
    $ kapow get /request/path
    /foo/bar
 
-``/request/matches/<name>``
+``/request/matches/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the part of the URL captured by the pattern ``name``.
 
@@ -139,8 +139,8 @@ then, when handling the request:
    $ kapow get /request/matches/mymatch
    1234
 
-``/request/params/<name>``
+``/request/params/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the URL parameter ``name``
 
@@ -160,8 +160,8 @@ then, when handling the request:
    myparam
 
 
-``/request/headers/<name>``
+``/request/headers/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the HTTP header ``name`` of the incoming request.
 
@@ -181,8 +181,8 @@ then, when handling the request:
    Bar
 
 
-``/request/cookies/<name>``
+``/request/cookies/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the HTTP cookie ``name`` of the incoming request.
 
@@ -201,8 +201,8 @@ then, when handling the request:
    $ kapow get /request/cookies/MYCOOKIE
    Bar
 
-``/request/form/<name>``
+``/request/form/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the field ``name`` of the incoming request.
 
@@ -222,8 +222,8 @@ then, when handling the request:
    foo
 
 
-``/request/files/<name>/filename``
+``/request/files/<name>/filename`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the name of the file uploaded through the incoming request.
 
@@ -243,8 +243,8 @@ then, when handling the request:
    filename.txt
 
 
-``/request/files/<name>/content``
+``/request/files/<name>/content`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contents of the file that is being uploaded in the incoming request.
 
@@ -264,8 +264,8 @@ then, when handling the request:
    ...filename.txt contents...
 
 
-``/request/body``
+``/request/body`` Resource
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Raw contents of the incoming request HTTP body.
 
@@ -285,8 +285,8 @@ then, when handling the request:
    foobar
 
 
-``/response/status``
+``/response/status`` Resource
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the status code given in the user response.
 
@@ -301,8 +301,8 @@ If during the request handling:
 then the response will have the status code ``418 I am a Teapot``.
 
 
-``/response/headers/<name>``
+``/response/headers/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the header ``name`` in the user response.
 
@@ -318,8 +318,8 @@ then the response will contain an HTTP header named ``X-My-Header`` with
 value ``Foo``.
 
 
-``/response/cookies/<name>``
+``/response/cookies/<name>`` Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the cookie ``name`` that will be set to the user
 response.
@@ -337,8 +337,8 @@ then the response will set the cookie ``MYCOOKIE`` to the user in
 following requests.
 
 
-``/response/body``
+``/response/body`` Resource
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the value of the response HTTP body.
 

docs/source/theory/route_matching.rst

@@ -0,0 +1,14 @@
+Route Matching
+==============
+
+Kapow! maintains a route table with a list of routes as provided by the user,
+and uses it to determine which handler should an incoming request be dispatched
+to.
+
+.. todo::
+
+   link routes to its section
+
+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