Processing data sent to a custom handler
POST Method
Preliminaries
This note provides supplementary information about the server's implementation of the standard HTTP POST method to process data sent to the server for special handling.
The POST
method is the protocol used by HTML forms to accept data for processing. It is the only method other than GET
that is directly supported via HTML.
POST
is dissimilar from PUT
and PATCH
in that the request's :path
pseudo-header identifies a module to be used as a data handler. By way of constrast, the other two method's :path
pseudo-header identifies the resource that is the target of the update.
In many programming paradigms the :path
is both the data handler and the target resource. This is often termed a post-back. The RWSERVE software does not restrict POST
methods one way or the other, so using post-backs is allowed, but not required.
When used in either an AJAX call, or with an HTTP <form method='POST'>, a software developer must write a custom module that will carry out the request to process the data, and the webmaster must configure a dynamic route with *methods=POST
which references that module.
Request/response handlers
The server's request/response cycle for POST
requests is fulfilled using this sequence of handlers:
Request Handler | Optional | Configurable | |
---|---|---|---|
1 | Server Name Indication | no | no |
2 | Hosts | no | yes |
3 | IP Access | yes | yes |
4 | Resource Masks | yes | yes |
5 | Raw Path | no | no |
6 | Cookies | no | no |
7 | Forbidden | yes | yes |
8 | Cross Origin | yes | yes |
9 | RBAC | yes | yes |
10 | Content Length | no | no |
11 | Content Decoding | no | no |
12 | WWW Form Data | no | no |
13 | Multipart Form Data | no | no |
Dynamic Handler | Optional | Configurable | |
14 | Router | yes | yes |
Response Handler | Optional | Configurable | |
15 | Content Length | no | no |
16 | Status Codes | no | yes |
Status codes
Successful responses are finalized by the dynamic module with any of these status codes:
200
"OK" when the response contains a payload and these response headers:content-type
,content-length
and optionallycontent-encoding
.204
"No Content" when the response has no payload.207
"Multi Status" with a payload that has individual status codes for each part of the multipart request.303
"See Other" when the processing is successful and the browser should issue a follow-onGET
request to the URI declared in the response'slocation
header.307
"Temporary Redirect" when the processing is successful and the browser should issue a follow-onPOST
request to the URI declared in the response'slocation
header.
Content length
POST
requests must contain a content-length
header. If not present, the request will fail with a status code of 411
and an information header of rw-content-length-missing
.
The maximum size of a file to be uploaded is limited by the server to the size configured in restrictions/content-length-limit
. If the file is too large, the request will fail with a status code of 413
and an information header of rw-content-length-limit
.
Content encoding
POST
requests may be uploaded in compressed form if the request includes an acceptable content-encoding
header with a value of 'br'
, 'gzip'
or 'deflate'
. The uploaded request body will be decompressed and made available to plugin work orders in uncompressed form.
The request will fail with status code 406
if the Content Encoding module is not enabled or if the encoding value is not acceptable. An rw-content-decoding
information header is added to this type of unsuccessful response.
Reference
For reference purposes, refer to IETF RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content section 4.3.3 for the basic protocol expected of HTTP POST
requests.