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

spec: Handler key tree examples.

Browse Source 
Co-authored-by: pancho horrillo <pedrofelipe.horrillo@bbva.com>
This commit is contained in:
Roberto Abdelkader Martínez Pérez
2019-05-22 12:14:24 +02:00
parent 7cee2fac83
commit 87dd0b2f6d
1 changed files with 81 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
spec/README.md
+81 -24
View File
@@ -38,7 +38,7 @@ There are some concepts in HTTP and the shell that **resemble each other**.
```
Any tool designed to give an HTTP interface to an existing shell command
**must map concepts of boths**. For example:
**must map concepts of boths**. For example:
- "GET parameters" to "Command line parameters"
- "Headers" to "Environment variables"
@@ -55,14 +55,14 @@ All the alternatives we found are **rigid** about how they match between HTTP
and shell concepts.
* [shell2http](https://github.com/msoap/shell2http): HTTP-server to execute
shell commands. Designed for development, prototyping or remote control.
shell commands. Designed for development, prototyping or remote control.
Settings through two command line arguments, path and shell command.
* [websocketd](https://github.com/joewalnes/websocketd): Turn any program that
uses STDIN/STDOUT into a WebSocket server. Like inetd, but for WebSockets.
uses STDIN/STDOUT into a WebSocket server. Like inetd, but for WebSockets.
* [webhook](https://github.com/adnanh/webhook): webhook is a lightweight
incoming webhook server to run shell commands.
* [gotty](https://github.com/yudai/gotty): GoTTY is a simple command line tool
that turns your CLI tools into web applications. (For interactive commands
that turns your CLI tools into web applications. (For interactive commands
only)
* [shell-microservice-exposer](https://github.com/jaimevalero/shell-microservice-exposer):
Expose your own scripts as a cool microservice API dockerizing it.
@@ -92,7 +92,7 @@ TODO: Small explanation and example.
## What?
We named it Kapow!. It is pronounceable, short and meaningless... like every
We named it Kapow!. It is pronounceable, short and meaningless... like every
good UNIX command ;-)
TODO: Definition
@@ -101,7 +101,7 @@ TODO: Intro to Architecture
# HTTP API
Kapow! server interacts with the outside world only through its HTTP API. Any
Kapow! server interacts with the outside world only through its HTTP API. Any
program making the correct HTTP request to a Kapow! server, can change its
behavior.
@@ -111,11 +111,11 @@ behavior.
* The API calls responses will have two distinct parts:
* The HTTP status code (e.g., 400, Bad Request). The target audience of this
information is the client code. The client can thus use this information to
information is the client code. The client can thus use this information to
control the program flow.
* The JSON-encoded message. The target audience in this case is the human
operating the client. The human can use this information to make a decision
on how to proceed.
* The JSON-encoded message. The target audience in this case is the human
operating the client. The human can use this information to make a
decision on how to proceed.
Let's illustrate these ideas with an example: TODO
@@ -123,7 +123,7 @@ Let's illustrate these ideas with an example: TODO
attained by the objects which have been addressed (requested, set or
deleted).
FIXME: consider what to do when deleting objects. Isn't it too much to
FIXME: consider what to do when deleting objects. Isn't it too much to
return the list of all deleted objects in such a request?
## API elements
@@ -135,7 +135,7 @@ TODO: Define servers' API
### Routes
Routes are the mechanism that allows Kapow! to find the correct program to
respond to an external event (e.g. an incomming HTTP request).
respond to an external event (e.g. an incomming HTTP request).
#### List routes
@@ -325,31 +325,88 @@ Each handler is identified by a `handler_id` and provide access to the
following keys:
```
/ The root of the keys tree
/ The root of the keys tree
│
├─ request All information related to the HTTP request. Read-Only
├─ request All information related to the HTTP request. Read-Only
│ ├──── method Used HTTP Method (GET, POST)
│ ├──── path Complete URL path.
│ ├──── match Previously matched URL path parts.
│ ├──── path Complete URL path (URL-unquoted)
│ ├──── matches Previously matched URL path parts
│ │ └──── <key>
│ ├──── param URL parameters (post ? symbol)
│ ├──── params URL parameters (post ? symbol)
│ │ └──── <key>
│ ├──── header HTTP request headers
│ ├──── headers HTTP request headers
│ │ └──── <key>
│ ├──── cookie HTTP request cookie
│ ├──── cookies HTTP request cookie
│ │ └──── <key>
│ ├──── form form-encoding body data
│ ├──── form form-urlencoded form fields
│ │ └──── <key>
│ └──── body HTTP request body
│
└─ response All information related to the HTTP request. Write-Only
└─ response All information related to the HTTP request. Write-Only
├──── status HTTP status code
├──── body Response body. Mutually exclusive with response/stream
├──── stream Chunk-encoded body. Streamed response. Mutually exclusive with response/body
└──── header HTTP response headers
├──── body Response body. Mutually exclusive with response/stream
├──── stream Chunk-encoded body. Streamed response. Mutually exclusive with response/body
└──── headers HTTP response headers
└──── <key>
```
#### Example Keys
1.
Scenario: Request URL is `http://localhost:8080/example?q=foo&r=bar`
Key: `/request/path`
Access: Read-Only
Returned Value: `/example?q=foo&r=bar`
Comment: That would provide read-only access to the request URL path.
2.
Scenario: Request URL is `http://localhost:8080/example?q=foo&r=bar`
Key: `/request/params/q`
Access: Read-Only
Returned Value: `foo`
Comment: That would provide read-only access to the request URL parameter `q`.
3.
Scenario: A POST request with a JSON body and the header `Content-Type` set to `application/json`.
Key: `/request/headers/Content-Type`
Access: Read-Only
Returned Value: `application/json`
Comment: That would provide read-only access to the value of the request header `Content-Type`.
4.
Scenario: A request generated by submitting this form:
```
<form method="post">
First name:<br>
<input type="text" name="firstname" value="Jane"><br>
Last name:<br>
<input type="text" name="lastname" value="Doe">
<input type="submit" value="Submit">
</form>
```
Key: `/request/form/firstname`
Access: Read-Only
Returned Value: `Jane`
Comment: That would provide read-only access to the value of the field `firstname` of the form.
5.
Scenario: A request is being attended.
Key: `/response/status`
Access: Write-Only
Acceptable Value: A 3-digit integer. Must match `[0-9]{3}`.
Default Value: 200
Comment: It is customary to use the HTTP status code as defined at [https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1](RFC2616).
6.
Scenario: A request is being attended.
Key: `/response/body`
Access: Write-Only
Acceptable Value: Any string of bytes.
Default Value: N/A
Comment: For media types other than `application/octet-stream` you should
specify the appropiate `Content-Type` header.
**Note**: Parameters under `request` are read-only and, conversely, parameters under
`response` are write-only.