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 access the resource tree easily with the kapow set
and kapow get
subcommands.
/
│
├─ request
│ ├──── method HTTP Method used (GET, POST)
│ ├──── host Host part of the URL
│ ├──── version HTTP version of the request
│ ├──── path Complete URL path (URL-unquoted)
│ ├──── remote IP address of client
│ ├──── 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
│ │ └──── <name>
│ │ └──── 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
│
|─ ssl
│ └──── client
│ └──── i
│ └──── dn Subject's DN common name coming ina request through SSL with mTLS
│─ route
│ └──── id Id of the route that matched this request.
│
|─ server
│ └──── log Log to server stderr
│ └──── <prefix> Optional prefix to the message
│
└─ response
├──── status HTTP status code
├──── headers
│ └──── <name> HTTP response headers
├──── cookies
│ └──── <name> HTTP request cookie
└──── body Response body
The HTTP method of the incoming request.
If the user runs:
$ curl -X POST http://kapow.example:8080
then, when handling the request:
$ kapow get /request/method
POST
The Host
header as defined in the HTTP/1.1 spec of the incoming request.
If the user runs:
$ curl http://kapow.example:8080
then, when handling the request:
$ kapow get /request/host
kapow.example
The HTTP version of the incoming request.
If the user runs:
$ curl --http1.0 http://kapow.example:8080
then, when handling the request:
$ kapow get /request/version
HTTP/1.0
Contains the path substring of the URL.
If the user runs:
$ curl http://kapow.example:8080/foo/bar?qux=1
then, when handling the request:
$ kapow get /request/path
/foo/bar
The IP address of the host making the incoming request.
If the user runs:
$ curl http://kapow.example:8080
then, when handling the request:
$ kapow get /request/remote
192.168.100.156
Contains the part of the URL captured by the pattern name
.
For a route defined like this:
$ kapow route add /foo/{mymatch}/bar
if the user runs:
$ curl http://kapow.example:8080/foo/1234/bar
then, when handling the request:
$ kapow get /request/matches/mymatch
1234
Contains the value of the URL parameter name
Note
In the reference implementation only the first parameter's value can be accessed in the case of multiple values coming in the request.
If the user runs:
$ curl http://kapow.example:8080/foo?myparam=bar
then, when handling the request:
$ kapow get /request/params/myparam
bar
Contains the value of the HTTP header name
of the incoming request.
Note
In the reference implementation only the first header's value can be accessed in the case of multiple values coming in the request.
If the user runs:
$ curl -H X-My-Header=Bar http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/headers/X-My-Header
Bar
Contains the value of the HTTP cookie name
of the incoming request.
If the user runs:
$ curl --cookie MYCOOKIE=Bar http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/cookies/MYCOOKIE
Bar
Contains the value of the field name
of the incoming request.
Note
In the reference implementation there are some caveats:
- Only the first form field's value can be accessed in the case of multiple values coming in the request.
- In order to get access to the form data a correct 'Content-Type' header must be present in the request ('application/x-www-form-urlencoded' or 'multipart/form-data')
If the user runs:
$ curl -F -d myfield=foo http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/form/myfield
foo
Contains the name of the file uploaded through the incoming request.
Note
In the reference implementation to get access to the multipart data a correct Content-Type header must be present in the request (multipart/form-data or multipart/mixed).
If the user runs:
$ curl -F 'myfile=@filename.txt' http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/files/myfile/filename
filename.txt
Contents of the file that is being uploaded in the incoming request.
Note
In the reference implementation to get access to the multipart data a correct Content-Type header must be present in the request (multipart/form-data or multipart/mixed).
If the user runs:
$ curl -F 'myfile=@filename.txt' http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/files/myfile/content
...filename.txt contents...
Raw contents of the incoming request HTTP body.
If the user runs:
$ curl --data-raw foobar http://kapow.example:8080/
then, when handling the request:
$ kapow get /request/body
foobar
The IP address of the host making the incoming request.
If the user runs:
$ curl --cacert path/to/CAfile --cert path/to/clientcredentials http://kapow.example:8080
using a client certificate with DN=subject@example.net then, when handling the request:
$ kapow get /ssl/client/i/dn
subject@example.net
The ID of the original route that matched this request..
If the user runs:
$ curl http://kapow.example:8080/
then, when handling the request:
$ kapow get /route/id
ecd5d63f-f28b-11ea-ac55-ec21e5089c1f
Allows logging to Kapow!'s server stderr:
$ kapow set /server/log/my_banana_peeler 'banana too slippery!'
... meanwhile, in the server...
2020/12/18 11:15:49.437642 620846c6-4122-11eb-abeb-002b671b12f9 my_banana_peeler: banana too slippery!
Note that the '/my_banana_peeler' part is an optional arbitrary prefix, and can be omitted.
Contains the status code given in the user response.
Note
In the reference implementation there are some caveats:
- The status code value must be between 100 and 999.
- There is no way of writing reason phrase in the status line of the response.
If during the request handling:
$ kapow set /response/status 418
then the response will have the status code 418 I am a Teapot
.
Contains the value of the header name
in the user response.
Note
At this moment header values are only appended, there is no way of reset the values once set.
If during the request handling:
$ kapow set /response/headers/X-My-Header Foo
then the response will contain an HTTP header named X-My-Header
with value Foo
.
Contains the value of the cookie name
that will be set to the user response.
If during the request handling:
$ kapow set /response/cookies/MYCOOKIE Foo
then the response will set the cookie MYCOOKIE
to the user in following requests.
Contains the value of the response HTTP body.
If during the request handling:
$ kapow set /response/body foobar
then the response will contain foobar
in the body.