Dark-Alex-17/kapow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: style fixes

Browse Source
This commit is contained in:
pancho horrillo
2019-12-11 02:32:52 +01:00
parent 37025211b1
commit 16639ba44b
6 changed files with 62 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/concepts/interfaces.rst
+7 -6
View File
@@ -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.
docs/source/concepts/philosophy.rst
+5 -5
View File
@@ -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.
docs/source/concepts/request_life_cycle.rst
+10 -6
View File
@@ -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::
docs/source/concepts/resource_tree.rst
+35 -34
View File
@@ -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
│ └──── <name> 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/<name>`` 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/<name>`` 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/<name>`` 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
docs/source/concepts/route_matching.rst
+1 -1
View File
@@ -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.
docs/source/concepts/routes.rst
+4 -5
View File
@@ -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::