libweb_http.7: Update according to status quo

1 files changed, 137 insertions, 60 deletions

diff --git a/doc/man7/libweb_http.7 b/doc/man7/libweb_http.7
index 6fc8d12..ef67bff 100644
--- a/doc/man7/libweb_http.7
+++ b/doc/man7/libweb_http.7
@@ -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),