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

Merge remote-tracking branch 'origin/master'

Browse Source
This commit is contained in:
cr0hn
2019-11-20 15:18:09 +01:00
parent c6c0dd7c48 e5e8da551e
commit bd7cf16f0c
4 changed files with 279 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/theory/interfaces.rst
+5 -5
View File
@@ -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.
docs/source/theory/philosophy.rst
+29
View File
@@ -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
+12 -8
View File
@@ -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
docs/source/theory/resource_tree.rst
+233 -67
View File
@@ -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
│ │ └──── <name>
│ ├──── params URL parameters (after the "?" symbol)
│ │ └──── <name>
│ ├──── headers HTTP request headers
│ │ └──── <name>
│ ├──── cookies HTTP request cookie
│ │ └──── <name>
│ ├──── form Form-urlencoded form fields (names only)
│ ├──── matches
│ │ └──── <name> Previously matched URL path parts
│ ├──── params
│ │ └──── <name> URL parameters (after the "?" symbol)
│ ├──── headers
│ │ └──── <name> HTTP request headers
│ ├──── cookies
│ │ └──── <name> HTTP request cookie
│ ├──── 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
│ │ └──── content The file content
│ │ └──── filename Original file name of the file uploaded in the form field <name>
│ │ └──── 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
├──── status HTTP status code
├──── headers HTTP response headers
│ └──── <name>
├──── cookies HTTP request cookie
│ └──── <name>
├──── body Response body. Mutually exclusive with response/stream
└──── stream Alias for /response/body
└─ response
├──── status HTTP status code
├──── headers
│ └──── <name> HTTP response headers
├──── cookies
│ └──── <name> 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/<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>``
~~~~~~~~~~~~~~~~~~~~~~~~~
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/<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.