Fix design issues with async responses, add async example

struct http_response did not provide users any void * that could be used
to maintain a state between calls to an asynchronous HTTP response.
On the other hand, the user pointer could not be used for this purpose,
since it is shared among all HTTP clients for a given struct handler
instance.

Moreover, the length callback was still not supporting this feature,
which in fact might be required by some users. Implementing this was
particularly challenging, as this broke the current assumption that
all bytes on a call to http_read were being processed.

Now, since a client request can only be partially processed because of
the length callback, http_read must take this into account so that the
remaining bytes are still available for future calls, before reading
again from the file descriptor.

1 files changed, 44 insertions, 6 deletions

diff --git a/doc/man7/libweb_http.7 b/doc/man7/libweb_http.7
index c3bec8b..a8e315d 100644
--- a/doc/man7/libweb_http.7
+++ b/doc/man7/libweb_http.7
@@ -562,7 +562,13 @@ struct http_response
     unsigned long long \fIn\fP;
     size_t \fIn_headers\fP;
     void (*\fIfree\fP)(void *);
-    int (*\fIstep\fP)(const struct http_payload *, struct http_response *, void *);
+    void *\fIstep_args\fP;
+
+    union http_step
+    {
+        int (*\fIlength\fP)(unsigned long long \fIlen\fP, const struct http_cookie *\fIc\fP, struct http_response *\fIr\fP, void *\fIuser\fP, void *\fIstep_args\fP);
+        int (*\fIpayload\fP)(const struct http_payload *\fIp\fP, struct http_response *\fIr\fP, void *\fIuser\fP, void *\fIstep_args\fP);
+    } \fIstep\fP;
 };
 .EE
 .in
@@ -671,22 +677,54 @@ is a valid pointer. Otherwise,
 must be a null pointer.
 
 .I step
-allows implementations to generate a response in a non-blocking manner.
-When a response is not immediately available when a payload is received,
+allows implementations to deal with responses asynchronously
+i.e., without blocking other clients.
+For example, this can be useful to
+generate a response in a non-blocking manner.
+In other words, when a response is not immediately available
+when a payload is received,
 .I step
 must be assigned to a function that can generate it later.
 .I libweb
 shall then call this function immediately later,
 without blocking other clients.
+
 Assigning
-.I step
+.I step.length
+or
+.I step.payload
 to a null pointer falls back to the default behaviour
 i.e., a response is returned immediately.
 Note that a non-null
-.I step
-shall always take priority, thus ignoring any other information inside the
+.I step.length
+or
+.I step.payload
+shall always take priority,
+.B thus ignoring any other information inside the
 .I "struct http_response"
 instance.
+.I step
+can be configured under the following situations:
+
+.IP \(bu 2
+Inside the
+.I length
+callback defined by the
+.I struct http_cfg
+instance. In this case,
+.I step.length
+must be assigned to a function to be later called by
+.IR libweb .
+
+.IP \(bu 2
+Inside the
+.I payload
+callback defined by the
+.I struct http_cfg
+instance. In this case,
+.I step.payload
+must be assigned to a function to be later called by
+.IR libweb .
 
 .SS Transport Layer Security (TLS)
 By design,