From: Amaury Denoyelle <adenoyelle@haproxy.com>
Date: Tue, 10 Jun 2025 14:36:54 +0000 (+0200)
Subject: MINOR: mux-quic: improve documentation for snd/rcv app-ops
X-Git-Tag: v3.3-dev2~71
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=93b904702f9f009537d3a7953f92e633dd6a1d60;p=thirdparty%2Fhaproxy.git

MINOR: mux-quic: improve documentation for snd/rcv app-ops

Complete document for rcv_buf/snd_buf operations. In particular, return
value is now explicitely defined. For H3 layer, associated functions
documentation is also extended.
---

diff --git a/include/haproxy/mux_quic-t.h b/include/haproxy/mux_quic-t.h
index fd03f861f..068f14eef 100644
--- a/include/haproxy/mux_quic-t.h
+++ b/include/haproxy/mux_quic-t.h
@@ -202,7 +202,7 @@ struct qcc_app_ops {
 	/* Initialize <qcs> stream app context or leave it to NULL if rejected. */
 	int (*attach)(struct qcs *qcs, void *conn_ctx);
 
-	/* Convert received HTTP payload to HTX. */
+	/* Convert received HTTP payload to HTX. Returns amount of decoded bytes from <b> or a negative error code. */
 	ssize_t (*rcv_buf)(struct qcs *qcs, struct buffer *b, int fin);
 
 	/* Convert HTX to HTTP payload for sending. */
diff --git a/src/h3.c b/src/h3.c
index 8304a6417..18baf8fba 100644
--- a/src/h3.c
+++ b/src/h3.c
@@ -1385,9 +1385,13 @@ static ssize_t h3_parse_settings_frm(struct h3c *h3c, const struct buffer *buf,
 /* Transcode HTTP/3 payload received in buffer <b> to HTX data for stream
  * <qcs>. If <fin> is set, it indicates that no more data will arrive after.
  *
- * Returns the count of consumed bytes or a negative error code. If 0 is
- * returned, stream data is incomplete, decoding should be call again later
- * with more content.
+ * It may be necessary to call this function with an empty input buffer to
+ * signal a standalone FIN.
+ *
+ * Returns the amount of decoded bytes from <b> or a negative error code. A
+ * null value can be returned even if input buffer is not empty, meaning that
+ * transcoding cannot be performed due to partial HTTP/3 content. Receive
+ * operation may be called later with newer data available.
  */
 static ssize_t h3_rcv_buf(struct qcs *qcs, struct buffer *b, int fin)
 {
@@ -1687,6 +1691,13 @@ static int h3_encode_header(struct buffer *buf,
 	return qpack_encode_header(buf, n, v_strip);
 }
 
+/* Convert a HTX status-line and associated headers stored into <htx> into a
+ * HTTP/3 HEADERS response frame. HTX blocks are removed up to end-of-trailer
+ * included.
+ *
+ * Returns the amount of consumed bytes from <htx> buffer or a negative error
+ * code.
+ */
 static int h3_resp_headers_send(struct qcs *qcs, struct htx *htx)
 {
 	int err;
@@ -1841,15 +1852,15 @@ static int h3_resp_headers_send(struct qcs *qcs, struct htx *htx)
 }
 
 /* Convert a series of HTX trailer blocks from <htx> buffer into <qcs> buffer
- * as a H3 HEADERS frame. H3 forbidden trailers are skipped. HTX trailer blocks
- * are removed from <htx> until EOT is found and itself removed.
+ * as a HTTP/3 HEADERS frame. Forbidden trailers are skipped. HTX trailer
+ * blocks are removed from <htx> up to end-of-trailer included.
  *
  * If only a EOT HTX block is present without trailer, no H3 frame is produced.
  * Caller is responsible to emit an empty QUIC STREAM frame to signal the end
  * of the stream.
  *
- * Returns the size of HTX blocks removed. A negative error code is returned in
- * case of a fatal error which should caused a connection closure.
+ * Returns the amount of consumed bytes from <htx> buffer or a negative error
+ * code.
  */
 static int h3_resp_trailers_send(struct qcs *qcs, struct htx *htx)
 {
@@ -2021,9 +2032,9 @@ static int h3_resp_trailers_send(struct qcs *qcs, struct htx *htx)
  * underlying HTX area via <buf> as this will be used if zero-copy can be
  * performed.
  *
- * Returns the total bytes of encoded HTTP/3 payload. This corresponds to the
- * total bytes of HTX block removed. A negative error code is returned in case
- * of a fatal error which should caused a connection closure.
+ * Returns the amount of consumed bytes from <htx> buffer, which corresponds to
+ * the length sum of encoded frames payload. A negative error code is returned
+ * in case of a fatal error which should caused a connection closure.
  */
 static int h3_resp_data_send(struct qcs *qcs, struct htx *htx,
                              struct buffer *buf, size_t count)
@@ -2148,6 +2159,14 @@ static int h3_resp_data_send(struct qcs *qcs, struct htx *htx,
 	return -1;
 }
 
+/* Transcode HTX data from <buf> of length <count> into HTTP/3 frame for <qcs>
+ * stream instance. Successfully transcoded HTX blocks are removed from input
+ * buffer.
+ *
+ * Returns the amount of consumed bytes from <buf>. In case of error,
+ * connection is flagged and transcoding is interrupted. The returned value is
+ * unchanged though.
+ */
 static size_t h3_snd_buf(struct qcs *qcs, struct buffer *buf, size_t count)
 {
 	size_t total = 0;
diff --git a/src/hq_interop.c b/src/hq_interop.c
index e4a8cc848..6a1ec2db0 100644
--- a/src/hq_interop.c
+++ b/src/hq_interop.c
@@ -12,6 +12,7 @@
 #include <haproxy/quic_utils.h>
 #include <haproxy/trace.h>
 
+/* Returns the amount of decoded bytes from <b> or a negative error code. */
 static ssize_t hq_interop_rcv_buf(struct qcs *qcs, struct buffer *b, int fin)
 {
 	struct htx *htx;
@@ -92,6 +93,7 @@ static ssize_t hq_interop_rcv_buf(struct qcs *qcs, struct buffer *b, int fin)
 	return b_data(b);
 }
 
+/* Returns the amount of consumed bytes from <buf>. */
 static size_t hq_interop_snd_buf(struct qcs *qcs, struct buffer *buf,
                                  size_t count)
 {