Merge remote-tracking branch 'origin/master'

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
+The Data HTTP interface is used by the commands ``kapow get`` and ``kapow
-set` to exchange the data for a particular request.
+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.

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.

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:
+   The spawned entrypoint is run with the following variables added to its environment:
-- KAPOW_HANDLER_ID
+
-- KAPOW_DATAAPI_URL
+   - ``KAPOW_HANDLER_ID``: Containing the `HANDLER_ID`
-- KAPOW_CONTROLAPI_URL
+   - ``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 get /request/...``
-- kapow set /response/...
+   - ``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

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
+    │  ├──── matches
-    │  │     └──── <name>
+    │  │     └──── <name>           Previously matched URL path parts
-    │  ├──── params                 URL parameters (after the "?" symbol)
+    │  ├──── params
-    │  │     └──── <name>
+    │  │     └──── <name>           URL parameters (after the "?" symbol)
-    │  ├──── headers                HTTP request headers
+    │  ├──── headers
-    │  │     └──── <name>
+    │  │     └──── <name>           HTTP request headers
-    │  ├──── cookies                HTTP request cookie
+    │  ├──── cookies
-    │  │     └──── <name>
+    │  │     └──── <name>           HTTP request cookie
-    │  ├──── form                   Form-urlencoded form fields (names only)
+    │  ├──── form
     │  │     └──── <name>           Value of the form field with name <name>
-    │  ├──── files                  Files uploaded via multi-part form fields (names only)
+    │  ├──── files
     │  │     └──── <name>
-    │  │           └──── filename   Original file name
+    │  │           └──── filename   Original file name of the file uploaded in the form field <name>
-    │  │           └──── content    The file content
+    │  │           └──── content    The contents of the file uploaded in the form field <name>
     │  └──── body                   HTTP request body
     │
-    └─ response                     All information related to the HTTP request.  Write-Only
+    └─ response
-      ├──── status                 HTTP status code
+      ├──── status                  HTTP status code
-      ├──── headers                HTTP response headers
+      ├──── headers
-      │     └──── <name>
+      │     └──── <name>            HTTP response headers
-      ├──── cookies                HTTP request cookie
+      ├──── cookies
-      │     └──── <name>
+      │     └──── <name>            HTTP request cookie
-      ├──── body                   Response body.  Mutually exclusive with response/stream
+      └──── body                    Response body
-      └──── stream                 Alias for /response/body
 
 Resources
 ---------
 
 ``/request/method``
 ~~~~~~~~~~~~~~~~~~~
+
 The HTTP method of the incoming request.
 
-Sample usage:
+**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.
 
+**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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
+   $ curl -F -d myfield=foo http://kapow.example:8080/
-~~~~~~~~~~~~~~~~~~~~~~~~~
+
-Sample usage:
+then, when handling the request:
 
 .. code-block:: bash
-   $ kapow get
+
+   $ kapow get /request/form/myfield
+   foo
+
 
 ``/request/files/<name>/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/<name>/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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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/<name>``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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.