From f9867fb26964f8bf1908e596f67d0d6bb092d8e3 Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Fri, 22 Nov 2019 12:04:03 +0100 Subject: [PATCH 1/3] doc: add sections on theory/{routes,route_matching} MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Roberto Abdelkader Martínez Pérez --- docs/source/index.rst | 1 + docs/source/theory/route_matching.rst | 12 +++ docs/source/theory/routes.rst | 124 ++++++++++++++++++++++++++ 3 files changed, 137 insertions(+) create mode 100644 docs/source/theory/route_matching.rst create mode 100644 docs/source/theory/routes.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index cd47276..21290ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,7 @@ theory/philosophy theory/request_life_cycle theory/resource_tree + theory/routes diff --git a/docs/source/theory/route_matching.rst b/docs/source/theory/route_matching.rst new file mode 100644 index 0000000..31d58bd --- /dev/null +++ b/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. 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 From b522d9d847cb7ee9e05ddfa324ca5da9433a44ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Fri, 22 Nov 2019 12:05:07 +0100 Subject: [PATCH 2/3] Add additional information to title to better distinguish verbatim text. --- docs/source/theory/resource_tree.rst | 60 ++++++++++++++-------------- 1 file changed, 30 insertions(+), 30 deletions(-) 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. From 26145cba79105d33a5bb6c2bc6190ef60856b082 Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Fri, 22 Nov 2019 12:13:25 +0100 Subject: [PATCH 3/3] doc: updates to route_matching section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Roberto Abdelkader Martínez Pérez --- docs/source/index.rst | 2 +- docs/source/theory/route_matching.rst | 16 +++++++++------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 21290ba..826cba1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,10 +20,10 @@ theory/philosophy theory/request_life_cycle theory/resource_tree + theory/route_matching theory/routes - Indices and tables ================== diff --git a/docs/source/theory/route_matching.rst b/docs/source/theory/route_matching.rst index 31d58bd..c77d75b 100644 --- a/docs/source/theory/route_matching.rst +++ b/docs/source/theory/route_matching.rst @@ -1,12 +1,14 @@ Route Matching ============== -Route table ------------ +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. - Kapow! maintains a route table as provided by the user, and uses it to determine - which handler should an incoming request be dispatched to. +.. todo:: - 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. + 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.