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/philosophy.rst b/docs/source/theory/philosophy.rst index e69de29..9303982 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 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. + + +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 **deeply** +regret it. + +Kapow! is for automating simple stuff. diff --git a/docs/source/theory/request_life_cycle.rst b/docs/source/theory/request_life_cycle.rst index 0ca5643..9d4033e 100644 --- a/docs/source/theory/request_life_cycle.rst +++ b/docs/source/theory/request_life_cycle.rst @@ -8,22 +8,26 @@ 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 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``: 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 diff --git a/docs/source/theory/resource_tree.rst b/docs/source/theory/resource_tree.rst index 7c9cb88..eed1d67 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. @@ -17,169 +17,335 @@ 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 --------- ``/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: +**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. +**Sample Usage** -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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +Contains the value of the field ``name`` of the incoming request. + +**Sample Usage** + +If the user runs: .. code-block:: bash - $ kapow get -``/request/files/`` -~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + $ curl -F -d myfield=foo http://kapow.example:8080/ + +then, when handling the request: .. code-block:: bash - $ kapow get + + $ kapow get /request/form/myfield + foo + ``/request/files//filename`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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`` ~~~~~~~~~~~~~~~~~ -Sample usage: + +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`` ~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample usage: + +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`` ~~~~~~~~~~~~~~~~~~ -Sample usage: + +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.