From c2a62814b5c9fbd26bf2d6b50b819fee29ba6931 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 13:25:03 +0100 Subject: [PATCH 1/7] Resource tree documentation. --- docs/source/theory/resource_tree.rst | 231 +++++++++++++++++++++++---- 1 file changed, 199 insertions(+), 32 deletions(-) diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index 7c9cb88..4fcf91e 100644 --- a/docs/source/theory/resource_tree.rst +++ b/docs/source/theory/resource_tree.rst @@ -53,133 +53,300 @@ Resources ``/request/method`` ~~~~~~~~~~~~~~~~~~~ + The HTTP method of the incoming request. Sample usage: -.. code-block:: bash - $ kapow get /request/method - GET - -``/request/host`` -~~~~~~~~~~~~~~~~~ - -The ``Host`` header as defined in the HTTP/1.1 spec. - -Sample usage: - If the user runs: .. code-block:: bash - $ curl http://kapow.example:8080 + $ curl -X POST http://kapow.example:8080 then, when handling the request: .. code-block:: bash + + $ kapow get /request/method + POST + + +``/request/host`` +~~~~~~~~~~~~~~~~~ + +The ``Host`` header as defined in the HTTP/1.1 spec of the incoming +request. + +Sample usage: + +If the user runs: + +.. code-block:: bash + + $ curl http://kapow.example:8080 + +then, when handling the request: + +.. code-block:: bash + $ kapow get /request/host kapow.example ``/request/path`` ~~~~~~~~~~~~~~~~~ -Contains the path substring of the URL. +Contains the path substring of the URL. Sample usage: +If the user runs: + .. code-block:: bash - # GET http://url.example/foo/bar?q=1 + + $ curl http://kapow.example:8080/foo/bar?qux=1 + +then, when handling the request: + +.. code-block:: bash + $ kapow get /request/path /foo/bar ``/request/matches/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the part of the URL captured by the pattern ``name``. + Sample usage: +For a route defined like this: + .. code-block:: bash - $ kapow get + + $ kapow route add /foo/{mymatch}/bar + +if the user runs: + +.. code-block:: bash + + $ curl http://kapow.example:8080/foo/1234/bar + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/matches/mymatch + 1234 ``/request/params/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the URL parameter ``name`` + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl http://kapow.example:8080/foo?myparam=bar + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/params/myparam + myparam + ``/request/headers/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the HTTP header ``name`` of the incoming request. + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl -H X-My-Header=Bar http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/headers/X-My-Header + Bar + ``/request/cookies/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the HTTP cookie ``name`` of the incoming request. + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl --cookie "MYCOOKIE=Bar" http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/cookies/MYCOOKIE + Bar ``/request/form/`` ~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the field ``name`` of the incoming request. + Sample usage: -.. code-block:: bash - $ kapow get - -``/request/files/`` -~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: +If the user runs: .. code-block:: bash - $ kapow get + + $ curl -F -d myfield=foo http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/form/myfield + foo + ``/request/files//filename`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the name of the file uploaded through the incoming request. + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl -F -d myfile=@filename.txt http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/files/myfile/filename + filename.txt + ``/request/files//content`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contents of the file that is being uploaded in the incoming request. + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl -F -d myfile=@filename.txt http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/files/myfile/content + ...filename.txt contents... + ``/request/body`` ~~~~~~~~~~~~~~~~~ + +Raw contents of the incoming request HTTP body. + Sample usage: +If the user runs: + .. code-block:: bash - $ kapow get + + $ curl --data-raw foobar http://kapow.example:8080/ + +then, when handling the request: + +.. code-block:: bash + + $ kapow get /request/body + foobar + ``/response/status`` ~~~~~~~~~~~~~~~~~~~~ + +Contains the status code given in the user response. + Sample usage: +If during the request handling: + .. code-block:: bash - $ kapow get + + $ kapow set /response/status 418 + +then the response will have the status code ``418 I am a Teapot``. + ``/response/headers/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the header ``name`` in the user response. + Sample usage: +If during the request handling: + .. code-block:: bash - $ kapow get + + $ kapow set /response/headers/X-My-Header Foo + +then the response will contain an HTTP header named ``X-My-Header`` with +value ``Foo``. + ``/response/cookies/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contains the value of the cookie ``name`` that will be set to the user +response. + + Sample usage: +If during the request handling: + .. code-block:: bash - $ kapow get + + $ kapow set /response/cookies/MYCOOKIE Foo + +then the response will set the cookie ``MYCOOKIE`` to the user in +following requests. + ``/response/body`` ~~~~~~~~~~~~~~~~~~ + +Contains the value of the response HTTP body. + Sample usage: .. code-block:: bash - $ kapow get + + $ kapow set /response/body foobar + +then the response will contain ``foobar`` in the body. From b7efb3f109d39bcfd037f934658af63c6e264577 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 13:37:20 +0100 Subject: [PATCH 2/7] Documentation typos and improvements. Thanks Noel! --- docs/source/theory/interfaces.rst | 10 +++++----- docs/source/theory/request_life_cycle.rst | 13 +++++++------ docs/source/theory/resource_tree.rst | 4 ++-- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/source/theory/interfaces.rst b/docs/source/theory/interfaces.rst index d26ea87..d09c92d 100644 --- a/docs/source/theory/interfaces.rst +++ b/docs/source/theory/interfaces.rst @@ -9,7 +9,7 @@ User Interface The User HTTP interface is used to serve final user requests. -By default it binds to address `0.0.0.0` and port `8080`, but can be changed via +By default it binds to address ``0.0.0.0`` and port ``8080``, but can be changed via the ``--bind`` flag. @@ -19,15 +19,15 @@ Control Interface The Control HTTP interface is used by the command `kapow route` to administer the list of system routes. -By default it binds to address `127.0.0.1` and port `8081`, but can be changed +By default it binds to address ``127.0.0.1`` and port ``8081``, but can be changed via the ``--control-bind`` flag. Data Interface -------------- -The Data HTTP interface is used by the commands `kapow get` and `kapow -set` to exchange the data for a particular request. +The Data HTTP interface is used by the commands ``kapow get`` and ``kapow +set`` to exchange the data for a particular request. -By default it binds to address `127.0.0.1` and port `8082`, but can be changed +By default it binds to address ``127.0.0.1`` and port ``8082``, but can be changed via the ``--data-bind`` flag. diff --git a/docs/source/theory/request_life_cycle.rst b/docs/source/theory/request_life_cycle.rst index 0ca5643..086386a 100644 --- a/docs/source/theory/request_life_cycle.rst +++ b/docs/source/theory/request_life_cycle.rst @@ -14,15 +14,16 @@ answered by the User HTTP Interface. The default entrypoint is /bin/sh; we'll explain this workflow for now. - The spawned entrypoint is run with following variables added to its environment: -- KAPOW_HANDLER_ID -- KAPOW_DATAAPI_URL -- KAPOW_CONTROLAPI_URL + The spawned entrypoint is run with the following variables added to its environment: + + - KAPOW_HANDLER_ID + - KAPOW_DATAAPI_URL + - KAPOW_CONTROLAPI_URL #. During the lifetime of the shell, the request and response resources are available via these commands: -- kapow get /request/... -- kapow set /response/... + - kapow get /request/... + - kapow set /response/... TODO: link to resource tree diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index 4fcf91e..36ec0be 100644 --- a/docs/source/theory/resource_tree.rst +++ b/docs/source/theory/resource_tree.rst @@ -1,5 +1,5 @@ -The Resource Tree -================= +The `Kapow!` Resource Tree +========================== This is the model that Kapow! uses to expose the internals of the user request being serviced. From 664ddbc64166a4b63ef0cc29c3cdac8fa5fa56b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 13:43:21 +0100 Subject: [PATCH 3/7] Resource tree documentation cleanup --- docs/source/theory/resource_tree.rst | 43 ++++++++++++++-------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index 36ec0be..3200456 100644 --- a/docs/source/theory/resource_tree.rst +++ b/docs/source/theory/resource_tree.rst @@ -17,36 +17,35 @@ Overview .. code-block:: plain - / The root of the resource paths tree + / │ - ├─ request All information related to the HTTP request. Read-Only + ├─ request │ ├──── method Used HTTP Method (GET, POST) │ ├──── host Host part of the URL │ ├──── path Complete URL path (URL-unquoted) - │ ├──── matches Previously matched URL path parts - │ │ └──── - │ ├──── params URL parameters (after the "?" symbol) - │ │ └──── - │ ├──── headers HTTP request headers - │ │ └──── - │ ├──── cookies HTTP request cookie - │ │ └──── - │ ├──── form Form-urlencoded form fields (names only) + │ ├──── matches + │ │ └──── Previously matched URL path parts + │ ├──── params + │ │ └──── URL parameters (after the "?" symbol) + │ ├──── headers + │ │ └──── HTTP request headers + │ ├──── cookies + │ │ └──── HTTP request cookie + │ ├──── form │ │ └──── Value of the form field with name - │ ├──── files Files uploaded via multi-part form fields (names only) + │ ├──── files │ │ └──── - │ │ └──── filename Original file name - │ │ └──── content The file content + │ │ └──── filename Original file name of the file uploaded in the form field + │ │ └──── content The contents of the file uploaded in the form field │ └──── body HTTP request body │ - └─ response All information related to the HTTP request. Write-Only - ├──── status HTTP status code - ├──── headers HTTP response headers - │ └──── - ├──── cookies HTTP request cookie - │ └──── - ├──── body Response body. Mutually exclusive with response/stream - └──── stream Alias for /response/body + └─ response + ├──── status HTTP status code + ├──── headers + │ └──── HTTP response headers + ├──── cookies + │ └──── HTTP request cookie + └──── body Response body Resources --------- From ad1d0e8b0714ac24723b5478766f44653688646f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 13:45:42 +0100 Subject: [PATCH 4/7] Denoting the samples more clearly --- docs/source/theory/resource_tree.rst | 30 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index 3200456..eed1d67 100644 --- a/docs/source/theory/resource_tree.rst +++ b/docs/source/theory/resource_tree.rst @@ -55,7 +55,7 @@ Resources The HTTP method of the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -77,7 +77,7 @@ then, when handling the request: The ``Host`` header as defined in the HTTP/1.1 spec of the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -98,7 +98,7 @@ then, when handling the request: Contains the path substring of the URL. -Sample usage: +**Sample Usage** If the user runs: @@ -118,7 +118,7 @@ then, when handling the request: Contains the part of the URL captured by the pattern ``name``. -Sample usage: +**Sample Usage** For a route defined like this: @@ -144,7 +144,7 @@ then, when handling the request: Contains the value of the URL parameter ``name`` -Sample usage: +**Sample Usage** If the user runs: @@ -165,7 +165,7 @@ then, when handling the request: Contains the value of the HTTP header ``name`` of the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -186,7 +186,7 @@ then, when handling the request: Contains the value of the HTTP cookie ``name`` of the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -206,7 +206,7 @@ then, when handling the request: Contains the value of the field ``name`` of the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -227,7 +227,7 @@ then, when handling the request: Contains the name of the file uploaded through the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -248,7 +248,7 @@ then, when handling the request: Contents of the file that is being uploaded in the incoming request. -Sample usage: +**Sample Usage** If the user runs: @@ -269,7 +269,7 @@ then, when handling the request: Raw contents of the incoming request HTTP body. -Sample usage: +**Sample Usage** If the user runs: @@ -290,7 +290,7 @@ then, when handling the request: Contains the status code given in the user response. -Sample usage: +**Sample Usage** If during the request handling: @@ -306,7 +306,7 @@ then the response will have the status code ``418 I am a Teapot``. Contains the value of the header ``name`` in the user response. -Sample usage: +**Sample Usage** If during the request handling: @@ -325,7 +325,7 @@ Contains the value of the cookie ``name`` that will be set to the user response. -Sample usage: +**Sample Usage** If during the request handling: @@ -342,7 +342,7 @@ following requests. Contains the value of the response HTTP body. -Sample usage: +**Sample Usage** .. code-block:: bash From 63639eeaa9e39a3bb1d4c17144b11466d4f89490 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 13:52:45 +0100 Subject: [PATCH 5/7] More details about the request life cycle --- docs/source/theory/request_life_cycle.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/source/theory/request_life_cycle.rst b/docs/source/theory/request_life_cycle.rst index 086386a..9d4033e 100644 --- a/docs/source/theory/request_life_cycle.rst +++ b/docs/source/theory/request_life_cycle.rst @@ -8,7 +8,7 @@ answered by the User HTTP Interface. #. The request is matched against the route table -#. Kapow! provides a HANDLER_ID to identify this request +#. Kapow! provides a `HANDLER_ID` to identify this request #. Kapow! spawns the binary specified as entrypoint in the matching route @@ -16,15 +16,18 @@ answered by the User HTTP Interface. The spawned entrypoint is run with the following variables added to its environment: - - KAPOW_HANDLER_ID - - KAPOW_DATAAPI_URL - - KAPOW_CONTROLAPI_URL + - ``KAPOW_HANDLER_ID``: Containing the `HANDLER_ID` + - ``KAPOW_DATAAPI_URL``: With the URL of the `data interface` + - ``KAPOW_CONTROLAPI_URL``: With the URL of the `control interface` #. During the lifetime of the shell, the request and response resources are available via these commands: - - kapow get /request/... - - kapow set /response/... + - ``kapow get /request/...`` + - ``kapow set /response/...`` + + These commands use the aforementioned environment variables to read + data of the user request and to write the response. TODO: link to resource tree -#. When the shell dies, Kapow! finalizes the original request. +#. When the shell dies, Kapow! finalizes the original request From 2da8f7abd1612bf97d0ac8c4495d8450f7e53280 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roberto=20Abdelkader=20Mart=C3=ADnez=20P=C3=A9rez?= Date: Wed, 20 Nov 2019 14:18:21 +0100 Subject: [PATCH 6/7] Philosophy WIP --- docs/source/theory/philosophy.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/source/theory/philosophy.rst b/docs/source/theory/philosophy.rst index e69de29..a70e1a8 100644 --- a/docs/source/theory/philosophy.rst +++ b/docs/source/theory/philosophy.rst @@ -0,0 +1,29 @@ +Philosophy +========== + + +We Provide a Single Static Binary +--------------------------------- + +- Because it makes deployments easier. + + +Shell Agnostic +-------------- + +- Kapow! knows nothing about the shell you are using. +- It only spawn binaries. +- You can use anything you want that ends interacting with the `data + api`. +- This helps with multiplatform and with future higher level tools. + + +Not a Silver Bullet +------------------- + +You should not use Kapow! for projects with complex business logic. + +If you try to encode business logic in a shell script you will regret +**deeply**. + +Kapow! is for automating simple stuff. From e5e8da551e99c724e7c52c1f4e5ce89f50a2f481 Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Wed, 20 Nov 2019 14:30:28 +0100 Subject: [PATCH 7/7] docs/philosophy.rst: style fixes --- docs/source/theory/philosophy.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/theory/philosophy.rst b/docs/source/theory/philosophy.rst index a70e1a8..9303982 100644 --- a/docs/source/theory/philosophy.rst +++ b/docs/source/theory/philosophy.rst @@ -12,7 +12,7 @@ Shell Agnostic -------------- - Kapow! knows nothing about the shell you are using. -- It only spawn binaries. +- It only spawns executables. - You can use anything you want that ends interacting with the `data api`. - This helps with multiplatform and with future higher level tools. @@ -23,7 +23,7 @@ Not a Silver Bullet You should not use Kapow! for projects with complex business logic. -If you try to encode business logic in a shell script you will regret -**deeply**. +If you try to encode business logic in a shell script, you will **deeply** +regret it. Kapow! is for automating simple stuff.