From e77bd93693a74ce872d4c13fb45537c34518d84f Mon Sep 17 00:00:00 2001 From: Xavier Del Campo Romero Date: Mon, 6 Oct 2025 23:01:42 +0200 Subject: 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. --- doc/man7/libweb_http.7 | 63 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 53 insertions(+), 10 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3