diff --git a/docs/source/concepts/interfaces.rst b/docs/source/concepts/interfaces.rst index 6b5d2d3..eace43c 100644 --- a/docs/source/concepts/interfaces.rst +++ b/docs/source/concepts/interfaces.rst @@ -4,13 +4,14 @@ `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 it binds to address ``0.0.0.0`` and port ``8080``, but can be changed via -the ``--bind`` flag. +By default it binds to address ``0.0.0.0`` and port ``8080``, but that can be +changed via the ``--bind`` flag. Control Interface @@ -19,8 +20,8 @@ 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 -via the ``--control-bind`` flag. +By default it binds to address ``127.0.0.1`` and port ``8081``, but that can be +changed via the ``--control-bind`` flag. Data Interface @@ -29,5 +30,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 it binds to address ``127.0.0.1`` and port ``8082``, but can be changed -via the ``--data-bind`` flag. +By default it binds to address ``127.0.0.1`` and port ``8082``, but that can be +changed via the ``--data-bind`` flag. diff --git a/docs/source/concepts/philosophy.rst b/docs/source/concepts/philosophy.rst index 7eb4c0b..bd98b27 100644 --- a/docs/source/concepts/philosophy.rst +++ b/docs/source/concepts/philosophy.rst @@ -7,17 +7,17 @@ Single Static Binary - Deployment is then as simple as it gets. -- Docker-friendly. +- ``Docker``-friendly. Shell Agnostic -------------- -- *Kapow!* knows nothing, and makes no assumptions, about the shell you are using. - It only spawns executables. +- *Kapow!*, like John Snow, knows nothing, and makes no assumptions about the + shell you are using. It only spawns executables. - You are free to implement a client to the Data API directly if you are so - inclined. The spec provides all the necessary details. + inclined. The spec provides all the necessary details. Not a Silver Bullet @@ -26,6 +26,6 @@ Not a Silver Bullet You should not use *Kapow!* if your project requires complex business logic. If you try to encode business logic in a shell script, you will **deeply** -regret it. +regret it soon enough. *Kapow!* is designed for automating simple stuff. diff --git a/docs/source/concepts/request_life_cycle.rst b/docs/source/concepts/request_life_cycle.rst index 7e8810b..3b3de99 100644 --- a/docs/source/concepts/request_life_cycle.rst +++ b/docs/source/concepts/request_life_cycle.rst @@ -12,18 +12,19 @@ answered by the `User HTTP Interface`. The user makes a request to the `User HTTP Interface`. -- The request is matched against the route table +- The request is matched against the route table. - ``kapow`` provides a `HANDLER_ID` to identify this request and don't mix it with other requests that could be running concurrently. + 2. spawn -------- ``kapow`` spawns the executable specified as entrypoint in the matching route. -The default entrypoint is ``/bin/sh``; we'll explain this workflow for now. +The default entrypoint is ``/bin/sh``; let's focus on this workflow. The spawned entrypoint is run with the following variables added to its environment: @@ -32,6 +33,7 @@ environment: - ``KAPOW_DATAAPI_URL``: With the URL of the `Data HTTP Interface` - ``KAPOW_CONTROLAPI_URL``: With the URL of the `Control HTTP Interface` + 3. ``kapow set /response/body banana`` -------------------------------------- @@ -43,18 +45,20 @@ available via these commands: - ``kapow set /response/...`` These commands use the aforementioned environment variables to read data -from the user request and to write the response. They accept data -either as arguments or from ``stdin``. +from the user request and to write the response. They accept data either as +arguments or from ``stdin``. + 4. exit ------- -The shell dies. +The shell dies. Long live the shell! + 5. response ----------- -``kapow`` finalizes the original request. +``kapow`` finalizes the original request. Enjoy your banana now. .. todo:: diff --git a/docs/source/concepts/resource_tree.rst b/docs/source/concepts/resource_tree.rst index 94b31d2..9fb1947 100644 --- a/docs/source/concepts/resource_tree.rst +++ b/docs/source/concepts/resource_tree.rst @@ -4,9 +4,8 @@ The *Kapow!* 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 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. @@ -47,6 +46,7 @@ Overview │ └──── HTTP request cookie └──── body Response body + Resources --------- @@ -59,13 +59,13 @@ The HTTP method of the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl -X POST http://kapow.example:8080 then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/method POST @@ -74,20 +74,19 @@ then, when handling the request: ``/request/host`` Resource ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``Host`` header as defined in the HTTP/1.1 spec of the incoming -request. +The ``Host`` header as defined in the HTTP/1.1 spec of the incoming request. **Sample Usage** If the user runs: -.. code-block:: bash +.. code-block:: console $ curl http://kapow.example:8080 then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/host kapow.example @@ -102,17 +101,18 @@ Contains the path substring of the URL. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl http://kapow.example:8080/foo/bar?qux=1 then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/path /foo/bar + ``/request/matches/`` Resource ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -122,23 +122,24 @@ Contains the part of the URL captured by the pattern ``name``. For a route defined like this: -.. code-block:: bash +.. code-block:: console $ kapow route add /foo/{mymatch}/bar if the user runs: -.. code-block:: bash +.. code-block:: console $ curl http://kapow.example:8080/foo/1234/bar then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/matches/mymatch 1234 + ``/request/params/`` Resource ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -148,13 +149,13 @@ Contains the value of the URL parameter ``name`` If the user runs: -.. code-block:: bash +.. code-block:: console $ curl http://kapow.example:8080/foo?myparam=bar then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/params/myparam myparam @@ -169,13 +170,13 @@ Contains the value of the HTTP header ``name`` of the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl -H X-My-Header=Bar http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/headers/X-My-Header Bar @@ -190,17 +191,18 @@ Contains the value of the HTTP cookie ``name`` of the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console - $ curl --cookie "MYCOOKIE=Bar" http://kapow.example:8080/ + $ curl --cookie MYCOOKIE=Bar http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/cookies/MYCOOKIE Bar + ``/request/form/`` Resource ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -210,13 +212,13 @@ Contains the value of the field ``name`` of the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl -F -d myfield=foo http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/form/myfield foo @@ -231,13 +233,13 @@ Contains the name of the file uploaded through the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl -F -d myfile=@filename.txt http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/files/myfile/filename filename.txt @@ -252,13 +254,13 @@ Contents of the file that is being uploaded in the incoming request. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl -F -d myfile=@filename.txt http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/files/myfile/content ...filename.txt contents... @@ -273,13 +275,13 @@ Raw contents of the incoming request HTTP body. If the user runs: -.. code-block:: bash +.. code-block:: console $ curl --data-raw foobar http://kapow.example:8080/ then, when handling the request: -.. code-block:: bash +.. code-block:: console $ kapow get /request/body foobar @@ -294,7 +296,7 @@ Contains the status code given in the user response. If during the request handling: -.. code-block:: bash +.. code-block:: console $ kapow set /response/status 418 @@ -310,7 +312,7 @@ Contains the value of the header ``name`` in the user response. If during the request handling: -.. code-block:: bash +.. code-block:: console $ kapow set /response/headers/X-My-Header Foo @@ -324,12 +326,11 @@ value ``Foo``. 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 +.. code-block:: console $ kapow set /response/cookies/MYCOOKIE Foo @@ -346,7 +347,7 @@ Contains the value of the response HTTP body. If during the request handling: -.. code-block:: bash +.. code-block:: console $ kapow set /response/body foobar diff --git a/docs/source/concepts/route_matching.rst b/docs/source/concepts/route_matching.rst index dd3562d..bd1e9c7 100644 --- a/docs/source/concepts/route_matching.rst +++ b/docs/source/concepts/route_matching.rst @@ -10,5 +10,5 @@ to. 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. +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/concepts/routes.rst b/docs/source/concepts/routes.rst index 66f3f84..bde105f 100644 --- a/docs/source/concepts/routes.rst +++ b/docs/source/concepts/routes.rst @@ -6,10 +6,9 @@ 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 +.. code-block:: console $ kapow route add \ -X POST \ @@ -40,7 +39,7 @@ 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. + In the future the user will be able to specify a custom value. ``method`` Route Element @@ -48,7 +47,7 @@ Uniquely identifies each route. It is used for instance by ``kapow route remove Specifies the HTTP method for the route to match the incoming request. -The route shown above will only match a ``POST`` request. +Note that the route shown above will only match a ``POST`` request. ``url_pattern`` Route Element @@ -71,7 +70,7 @@ https://github.com/gorilla/mux#examples 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. +which is an incomplete recipe. It is then completed by the `command` element. .. todo::