From 5ee8353cba9a3ca035ba078ffae109f1742a7d9f Mon Sep 17 00:00:00 2001 From: pancho horrillo Date: Wed, 20 Nov 2019 12:54:29 +0100 Subject: [PATCH] WIP on docs/theory 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/theory/interfaces.rst | 12 +- docs/source/theory/request_life_cycle.rst | 22 +++ docs/source/theory/resource_tree.rst | 181 ++++++++++++++++++++++ 3 files changed, 212 insertions(+), 3 deletions(-) diff --git a/docs/source/theory/interfaces.rst b/docs/source/theory/interfaces.rst index c28dc72..d26ea87 100644 --- a/docs/source/theory/interfaces.rst +++ b/docs/source/theory/interfaces.rst @@ -1,12 +1,16 @@ Kapow! HTTP Interfaces ====================== +`kapow server` sets up three HTTP server interfaces, each with a distinct and +clear purpose. + User Interface -------------- The User HTTP interface is used to serve final user requests. -By default is bind to address `0.0.0.0` and port `8080`. +By default it binds to address `0.0.0.0` and port `8080`, but can be changed via +the ``--bind`` flag. Control Interface @@ -15,7 +19,8 @@ Control Interface The Control HTTP interface is used by the command `kapow route` to administer the list of system routes. -By default is bind to address `127.0.0.1` and port `8081`. +By default it binds to address `127.0.0.1` and port `8081`, but can be changed +via the ``--control-bind`` flag. Data Interface @@ -24,4 +29,5 @@ Data Interface The Data HTTP interface is used by the commands `kapow get` and `kapow set` to exchange the data for a particular request. -By default is bind to address `127.0.0.1` and port `8082`. +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 a874759..0ca5643 100644 --- a/docs/source/theory/request_life_cycle.rst +++ b/docs/source/theory/request_life_cycle.rst @@ -4,4 +4,26 @@ Request Life Cycle This section describes the sequence of events happening for each request answered by the User HTTP Interface. +#. The user makes a request to the User HTTP Interface +#. The request is matched against the route table + +#. 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 + +#. During the lifetime of the shell, the request and response resources are available via these commands: + +- kapow get /request/... +- kapow set /response/... + +TODO: link to resource tree + +#. 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 3aea6f2..7c9cb88 100644 --- a/docs/source/theory/resource_tree.rst +++ b/docs/source/theory/resource_tree.rst @@ -1,4 +1,185 @@ The Resource Tree ================= +This is the model that Kapow! uses to expose the internals of the user request +being serviced. + +We use this tree to get access to any data that comes in the request, +as well as to compose the response. + +We access the resource tree easily with the ``kapow set`` and ``kapow get`` +subcommands. + + +Overview +-------- + +.. code-block:: plain + + / The root of the resource paths tree + │ + ├─ request All information related to the HTTP request. Read-Only + │ ├──── 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) + │ │ └──── Value of the form field with name + │ ├──── files Files uploaded via multi-part form fields (names only) + │ │ └──── + │ │ └──── filename Original file name + │ │ └──── content The file content + │ └──── 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 + +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 + + +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: + +.. code-block:: bash + # GET http://url.example/foo/bar?q=1 + $ kapow get /request/path + /foo/bar + +``/request/matches/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/params/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/headers/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/cookies/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/form/`` +~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/files/`` +~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/files//filename`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/files//content`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/request/body`` +~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/response/status`` +~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/response/headers/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/response/cookies/`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get + +``/response/body`` +~~~~~~~~~~~~~~~~~~ +Sample usage: + +.. code-block:: bash + $ kapow get