Merge remote-tracking branch 'origin/master'
This commit is contained in:
cr0hn
@@ -20,7 +20,8 @@
|
||||
theory/philosophy
|
||||
theory/request_life_cycle
|
||||
theory/resource_tree
|
||||
|
||||
theory/route_matching
|
||||
theory/routes
|
||||
|
||||
|
||||
Indices and tables
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user