diff --git a/docs/source/index.rst b/docs/source/index.rst index cd47276..826cba1 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index eed1d67..81f710e 100644 --- a/docs/source/theory/resource_tree.rst +++ b/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/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/matches/`` 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/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/params/`` Resource +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contains the value of the URL parameter ``name`` @@ -160,8 +160,8 @@ then, when handling the request: myparam -``/request/headers/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/headers/`` 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/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/cookies/`` 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/`` -~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/form/`` Resource +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contains the value of the field ``name`` of the incoming request. @@ -222,8 +222,8 @@ then, when handling the request: foo -``/request/files//filename`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/files//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//content`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/request/files//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/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/response/headers/`` 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/`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``/response/cookies/`` 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. diff --git a/docs/source/theory/route_matching.rst b/docs/source/theory/route_matching.rst new file mode 100644 index 0000000..c77d75b --- /dev/null +++ b/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. diff --git a/docs/source/theory/routes.rst b/docs/source/theory/routes.rst new file mode 100644 index 0000000..d262ffd --- /dev/null +++ b/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 +``. + +.. 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