libweb_http.7: Update according to status quo
This commit is contained in:
parent
f9a305fe4d
commit
edc855f93b
GPG Key ID:
84FF3612A9BF43F2
|
|
@ -19,14 +19,23 @@ server implementation, the following features are supported:
|
|||
.IP \(bu 2
|
||||
.BR GET .
|
||||
.IP \(bu 2
|
||||
.BR POST .
|
||||
.BR HEAD .
|
||||
.IP \(bu 2
|
||||
.BR PUT .
|
||||
.IP \(bu 2
|
||||
.BR POST .
|
||||
.IR multipart/form-data -encoded
|
||||
data. An optional payload size limit can be defined (see section
|
||||
.BR "HTTP server configuration" ).
|
||||
data is also supported.
|
||||
.IP \(bu 2
|
||||
Cookies.
|
||||
|
||||
An optional payload size limit can be defined for
|
||||
.B PUT
|
||||
and
|
||||
.B POST
|
||||
requests (see section
|
||||
.BR "HTTP server configuration" ).
|
||||
|
||||
.SS Utility functions
|
||||
The functions listed below are meant for library users:
|
||||
|
||||
|
|
@ -154,13 +163,20 @@ returned.
|
|||
is a function pointer called by
|
||||
.I libweb
|
||||
when an incoming HTTP request from a client requires to store one or
|
||||
more files on the server, encoded as
|
||||
.IR multipart/form-data .
|
||||
more files on the server.
|
||||
In the case of a
|
||||
.B POST
|
||||
request,
|
||||
.I len
|
||||
defines the length of the
|
||||
.IR multipart/form-data
|
||||
(see section
|
||||
.BR "Content-Length design limitations for multipart/form-data" ).
|
||||
In the case of a
|
||||
.B PUT
|
||||
request,
|
||||
.I len
|
||||
defines the length of the file body.
|
||||
.I c
|
||||
is a read-only pointer to a
|
||||
.I "struct http_cookie"
|
||||
|
|
@ -230,12 +246,13 @@ struct http_payload
|
|||
union
|
||||
{
|
||||
struct http_post \fIpost\fP;
|
||||
} \fIu\fP;
|
||||
struct http_put \fIput\fP;
|
||||
} u;
|
||||
|
||||
const struct http_arg *\fIargs\fP;
|
||||
size_t \fIn_args\fP;
|
||||
size_t \fIn_args\fP, \fIn_headers\fP;
|
||||
const struct http_header *\fIheaders\fP;
|
||||
size_t \fIn_headers\fP;
|
||||
bool \fIexpect_continue\fP;
|
||||
};
|
||||
.EE
|
||||
.in
|
||||
|
|
@ -263,9 +280,13 @@ defines a tagged union with operation-specific data. For example,
|
|||
refers to data sent by a client on a
|
||||
.B POST
|
||||
request (see section
|
||||
.BR "HTTP POST payload" ).
|
||||
Also, see section
|
||||
.BR "Future supported HTTP/1.1 operations" .
|
||||
.BR "HTTP POST payload" ),
|
||||
whereas
|
||||
.I put
|
||||
refers to data sent by a client on a
|
||||
.B PUT
|
||||
request (see section
|
||||
.BR "HTTP PUT payload" ).
|
||||
|
||||
.I args
|
||||
defines a list of key-value pairs containing URL parameters. Its length
|
||||
|
|
@ -277,6 +298,21 @@ defines a list of key-value pairs containing header fields. Its length
|
|||
is defined by
|
||||
.IR n_headers .
|
||||
|
||||
.I expect_continue
|
||||
shall be set to
|
||||
.I true
|
||||
if an
|
||||
.B "Expect: 100-continue"
|
||||
HTTP header is received,
|
||||
.I false
|
||||
otherwise (see section
|
||||
.BR "Expect: 100-continue handling" ).
|
||||
This field is only relevant for
|
||||
.B PUT
|
||||
or
|
||||
.B POST
|
||||
requests.
|
||||
|
||||
.SS HTTP POST payload
|
||||
|
||||
As opposed to payload-less HTTP/1.1 operations, such as
|
||||
|
|
@ -284,7 +320,7 @@ As opposed to payload-less HTTP/1.1 operations, such as
|
|||
.B POST
|
||||
operations might or might not include payload data. Moreover, such
|
||||
payload can be encoded in two different ways, which
|
||||
.I slcl
|
||||
.I libweb
|
||||
handles differently:
|
||||
|
||||
.IP \(bu 2
|
||||
|
|
@ -309,7 +345,7 @@ member
|
|||
.IR tmpdir .
|
||||
|
||||
This information is contained into a
|
||||
.B "struct http_post"
|
||||
.I struct http_post
|
||||
object, defined as:
|
||||
|
||||
.PP
|
||||
|
|
@ -317,7 +353,6 @@ object, defined as:
|
|||
.EX
|
||||
struct http_post
|
||||
{
|
||||
bool \fIexpect_continue\fP;
|
||||
const char *\fIdata\fP;
|
||||
size_t \fInfiles\fP, \fInpairs\fP;
|
||||
|
||||
|
|
@ -335,19 +370,6 @@ struct http_post
|
|||
.in
|
||||
.PP
|
||||
|
||||
.I expect_continue
|
||||
shall be set to
|
||||
.I true
|
||||
if an
|
||||
.B "Expect: 100-continue"
|
||||
HTTP header is received,
|
||||
.I false
|
||||
otherwise (see
|
||||
section
|
||||
.B Handling of 100-continue requests
|
||||
in
|
||||
.BR BUGS ).
|
||||
|
||||
When
|
||||
.IR application/x-www-form-urlencoded -data
|
||||
is included,
|
||||
|
|
@ -391,6 +413,94 @@ If no name-value pairs are defined,
|
|||
.I pairs
|
||||
shall be a null pointer.
|
||||
|
||||
.SS HTTP PUT payload
|
||||
|
||||
For
|
||||
.B PUT
|
||||
requests, and as opposed to
|
||||
.B POST
|
||||
requests,
|
||||
.I libweb
|
||||
shall always store the request body into a temporary file, defined by
|
||||
.I struct http_put
|
||||
member
|
||||
.IR tmpname .
|
||||
|
||||
This information is contained into a
|
||||
.I struct http_put
|
||||
object, defined as:
|
||||
|
||||
.PP
|
||||
.in +4n
|
||||
.EX
|
||||
struct http_put
|
||||
{
|
||||
const char *tmpname;
|
||||
};
|
||||
.EE
|
||||
.in
|
||||
.PP
|
||||
|
||||
.SS Expect: 100-continue handling
|
||||
|
||||
As opposed to other HTTP headers, the
|
||||
.B Expect: 100-continue
|
||||
HTTP header requires the server to respond before the request body is
|
||||
sent by the client. Typically, this is meant to allow the server to
|
||||
check the request resource and headers beforehand, without waiting to
|
||||
receive the request body, which can be long. This is usual for resource
|
||||
uploads, as typically done with
|
||||
.BR PUT
|
||||
requests.
|
||||
|
||||
Therefore, when this header is received,
|
||||
.I libweb
|
||||
shall trigger the user-defined callback as defined by
|
||||
.I struct http_cfg
|
||||
member
|
||||
.I payload
|
||||
at least once. Then, users are expected to check this flag and act
|
||||
accordingly.
|
||||
|
||||
The example below shows a user-defined callback that replies with
|
||||
.I HTTP_STATUS_CONTINUE
|
||||
when
|
||||
.I struct http_payload
|
||||
member
|
||||
.I expect_continue
|
||||
is set:
|
||||
|
||||
.PP
|
||||
.in +4n
|
||||
.EX
|
||||
static int on_payload(const struct http_payload *const p,
|
||||
struct http_response *const r, void *const user)
|
||||
{
|
||||
if (p->expect_continue)
|
||||
{
|
||||
*r = (const struct http_response)
|
||||
{
|
||||
.status = HTTP_STATUS_CONTINUE
|
||||
};
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* Handle request body. */
|
||||
}
|
||||
.EE
|
||||
.in
|
||||
.PP
|
||||
|
||||
Then, once the request body is received,
|
||||
.I libweb
|
||||
shall trigger the callback again with
|
||||
.I struct http_payload
|
||||
member
|
||||
.I expect_continue
|
||||
assigned to
|
||||
.IR false .
|
||||
|
||||
.SS HTTP responses
|
||||
|
||||
Some function pointers used by
|
||||
|
|
@ -579,22 +689,6 @@ can rely on, and therefore is the value passed to the
|
|||
function pointer in
|
||||
.IR "struct http_cfg" .
|
||||
|
||||
.SH BUGS
|
||||
.SS Handling of 100-continue requests
|
||||
|
||||
The handling of
|
||||
.B 100-continue
|
||||
requests is not done correctly:
|
||||
.I libweb
|
||||
calls the function pointed to by
|
||||
.I "struct http_cfg"
|
||||
member
|
||||
.I payload
|
||||
as soon as it encounters the
|
||||
.B Expected:
|
||||
header. However, a response should only be sent to the client once all
|
||||
headers are processed.
|
||||
|
||||
.SH FUTURE DIRECTIONS
|
||||
.SS Limitations on the number of HTTP cookies
|
||||
So far,
|
||||
|
|
@ -630,23 +724,6 @@ member
|
|||
with an array of structures containing key-value pairs, so that
|
||||
applications no longer need to decode payload data by themselves.
|
||||
|
||||
.SS Future supported HTTP/1.1 operations
|
||||
So far,
|
||||
.I struct http_payload
|
||||
defines
|
||||
.I u
|
||||
as a union that only holds one possible data type. While this might
|
||||
look counterintuitive, this is because
|
||||
.B POST
|
||||
is the only HTTP/1.1 operation
|
||||
.I libweb
|
||||
supports that requires to store a payload. However, future versions of
|
||||
this library might extend its support for other HTTP/1.1 operations
|
||||
that could require to store a payload, while keeping the memory
|
||||
footprint for
|
||||
.I struct http_payload
|
||||
small.
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR handler_alloc (3),
|
||||
.BR http_alloc (3),
|
||||
|
|
|
|||
Loading…
Reference in New Issue