Implement HTTP chunk encoding

A new function pointer, namely chunk, has been added to struct
http_response so that library users can generate their message bodies
dynamically.

1 files changed, 53 insertions, 10 deletions

diff --git a/doc/man7/libweb_http.7 b/doc/man7/libweb_http.7
index 63a68da..5c01549 100644
--- a/doc/man7/libweb_http.7
+++ b/doc/man7/libweb_http.7
@@ -1,4 +1,4 @@
-.TH LIBWEB_HTTP 7 2024-08-22 0.4.0 "libweb Library Reference"
+.TH LIBWEB_HTTP 7 2025-10-07 0.5.0 "libweb Library Reference"
 
 .SH NAME
 libweb_http \- libweb HTTP connection handling and utilities
@@ -562,12 +562,13 @@ struct http_response
     unsigned long long \fIn\fP;
     size_t \fIn_headers\fP;
     void (*\fIfree\fP)(void *);
-    void *\fIstep_args\fP;
+    void *\fIargs\fP;
+    int (*\fIchunk\fP)(void *\fIbuf\fP, size_t \fIn\fP, bool *\fIdone\fP, void *\fIuser\fP, void *\fIargs\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);
+        int (*\fIlength\fP)(unsigned long long \fIlen\fP, const struct http_cookie *\fIc\fP, struct http_response *\fIr\fP, void *\fIuser\fP, void *\fIargs\fP);
+        int (*\fIpayload\fP)(const struct http_payload *\fIp\fP, struct http_response *\fIr\fP, void *\fIuser\fP, void *\fIargs\fP);
     } \fIstep\fP;
 };
 .EE
@@ -604,10 +605,11 @@ defined by
 .I libweb
 shall select
 .I ro
-as the output payload if both
-.I f
-and
+as the output payload if
+.IR f ,
 .I free
+and
+.I chunk
 are null pointers, and
 .I n
 is non-zero.
@@ -619,9 +621,11 @@ is an opaque pointer to a buffer in memory, whose length is defined by
 .I libweb
 shall select
 .I rw
-as the output payload if both
+as the output payload if
+.I chunk
+and
 .I f
-is a null pointer and
+are null pointers,
 .I free
 is a valid pointer to a function that frees the memory used by
 .IR rw ,
@@ -639,6 +643,7 @@ client, whose length is defined by
 shall select
 .I f
 as the output payload if
+.IR chunk ,
 .IR ro ,
 .I rw
 and
@@ -676,6 +681,36 @@ is a valid pointer. Otherwise,
 .I free
 must be a null pointer.
 
+.I args
+is an opaque pointer to user-defined data, as consumed by
+.I chunk
+and
+.IR step .
+
+.I chunk
+allows library users to generate the response body dynamically,
+therefore relying on the
+.I Transfer-Encoding: chunked
+HTTP header.
+When used,
+.I chunk
+must point to a function that reads up to
+.I n
+bytes into a buffer provided by
+.IR libweb ,
+namely
+.IR buf .
+The function must return how many bytes were written into
+.IR buf ,
+and must be between zero and
+.IR n .
+In case of error, a negative integer must be returned.
+When no more chunks are to be sent, users must assign the flag
+pointed to by
+.I done
+to
+.IR true .
+
 .I step
 allows implementations to deal with responses asynchronously
 i.e., without blocking other clients.
@@ -688,6 +723,14 @@ must be assigned to a function that can generate it later.
 .I libweb
 shall then call this function immediately later,
 without blocking other clients.
+Do not confuse
+.I step
+with
+.IR chunk ,
+where
+.I chunk
+is meant for dynamically generated message bodies only, where the response
+HTTP status and headers have already been defined.
 
 Assigning
 .I step.length
@@ -857,7 +900,7 @@ applications no longer need to decode payload data by themselves.
 .BR http_decode_url (3).
 
 .SH COPYRIGHT
-Copyright (C) 2023-2024 libweb contributors
+Copyright (C) 2023-2025 libweb contributors
 .P
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU Affero General Public License as published by