Improve multiple incoming header set handling (#640)

Queue incoming header sets with STAILQ so informational responses and 
final responses are delivered in order.  Add an on_hset_in callback for                             
applications that want to collect each decoded header set as it arrives,
including both IETF QUIC and gQUIC paths.

Keep DATA read behavior unchanged when header sets are pending, document
retry behavior for overlapping header sends, and update http_client to
consume header sets through the new callback.  Also recognize HTTP/1.x
informational reason phrases, including 100 Continue and 103 Early Hints,
and extend tests for FIFO delivery and informational responses.

Author: dtikhonov

bin/http_client.c

@@ -765,11 +765,44 @@ maybe_perform_priority_actions (struct lsquic_stream *stream,
 }
 
 
+static void
+http_client_process_hset (lsquic_stream_t *stream, lsquic_stream_ctx_t *st_h)
+{
+    struct hset *hset;
+
+    hset = lsquic_stream_get_hset(stream);
+    if (!hset)
+    {
+        LSQ_ERROR("could not get header set from stream");
+        exit(2);
+    }
+    if (!(st_h->sh_flags & PROCESSED_HEADERS))
+    {
+        /* Internal helper (not in lsquic.h); example-only timing. */
+        st_h->sh_ttfb = lsquic_time_now();
+        update_sample_stats(&s_stat_ttfb, st_h->sh_ttfb - st_h->sh_created);
+        st_h->sh_flags |= PROCESSED_HEADERS;
+    }
+    if (s_discard_response)
+        LSQ_DEBUG("discard response: do not dump headers");
+    else
+        hset_dump(hset, stdout);
+    hset_destroy(hset);
+}
+
+
+static void
+http_client_on_hset_in (lsquic_stream_t *stream, lsquic_stream_ctx_t *st_h)
+{
+    if (g_header_bypass)
+        http_client_process_hset(stream, st_h);
+}
+
+
 static void
 http_client_on_read (lsquic_stream_t *stream, lsquic_stream_ctx_t *st_h)
 {
     struct http_client_ctx *const client_ctx = st_h->client_ctx;
-    struct hset *hset;
     ssize_t nread;
     unsigned old_prio, new_prio;
     unsigned char buf[0x200];
@@ -781,23 +814,7 @@ http_client_on_read (lsquic_stream_t *stream, lsquic_stream_ctx_t *st_h)
     do
     {
         if (g_header_bypass && !(st_h->sh_flags & PROCESSED_HEADERS))
-        {
-            hset = lsquic_stream_get_hset(stream);
-            if (!hset)
-            {
-                LSQ_ERROR("could not get header set from stream");
-                exit(2);
-            }
-            /* Internal helper (not in lsquic.h); example-only timing. */
-            st_h->sh_ttfb = lsquic_time_now();
-            update_sample_stats(&s_stat_ttfb, st_h->sh_ttfb - st_h->sh_created);
-            if (s_discard_response)
-                LSQ_DEBUG("discard response: do not dump headers");
-            else
-                hset_dump(hset, stdout);
-            hset_destroy(hset);
-            st_h->sh_flags |= PROCESSED_HEADERS;
-        }
+            http_client_process_hset(stream, st_h);
         else if (nread = (s_discard_response
                             ? lsquic_stream_readf(stream, discard, st_h)
                             : lsquic_stream_read(stream, buf,
@@ -955,6 +972,7 @@ static struct lsquic_stream_if http_client_if = {
     .on_write               = http_client_on_write,
     .on_close               = http_client_on_close,
     .on_hsk_done            = http_client_on_hsk_done,
+    .on_hset_in             = http_client_on_hset_in,
 };
 
 

docs/apiref.rst

@@ -1396,6 +1396,21 @@ the engine to communicate with the user code:
 
         This callback is optional.
 
+    .. member:: void (*on_hset_in)  (lsquic_stream_t *s, lsquic_stream_ctx_t *h)
+
+        This callback is called when a decoded HTTP header set becomes
+        available on a stream.  It is only used when the optional header set
+        interface (:member:`lsquic_engine_api.ea_hsi_if`) is specified.
+
+        The application can call :func:`lsquic_stream_get_hset()` from this
+        callback to take ownership of the header set.  This is useful for
+        HTTP/3 responses that contain more than one header set, such as one or
+        more informational responses followed by the final response.
+
+        This callback is optional.  If it is not specified, header sets can
+        still be collected during the next :member:`lsquic_stream_if.on_read`
+        callback.
+
     .. member:: ssize_t (*on_dg_write)(lsquic_conn_t *c, void *buf, size_t buf_sz)
 
         Called when datagram is ready to be written.  Write at most
@@ -1819,6 +1834,20 @@ more information.
 
         0 on success or -1 on error.
 
+    LSQUIC does not maintain a user-visible queue of header sets for this
+    function.  A stream can have at most one encoded header block pending in
+    the stream object.  If a previous call to this function produced a header
+    block that could not be written out completely, a subsequent call made
+    before that pending block is flushed fails with ``-1`` and sets ``errno``
+    to ``EAGAIN``.
+
+    This is intentional: queuing multiple outbound header sets internally
+    would create a second buffering layer with unclear ownership and resource
+    limits.  Applications that send more than one header set on a stream, for
+    example an informational response followed by the final response, should
+    serialize those calls and retry after LSQUIC has flushed the previous
+    header block.
+
 Receiving HTTP Headers
 ----------------------
 
@@ -1904,6 +1933,10 @@ fields yourself.  In that case, the header set must be "read" from the stream vi
     ``hsi_create_header_set()`` callback.  After this call, the ownership of
     the header set is transferred to the caller.
 
+    When :member:`lsquic_stream_if.on_hset_in` is specified, the application
+    can call this function from that callback.  Otherwise, call this function
+    from :member:`lsquic_stream_if.on_read` before reading stream data.
+
     This call must precede calls to :func:`lsquic_stream_read()`,
     :func:`lsquic_stream_readv()`, and :func:`lsquic_stream_readf()`.
 

docs/tutorial.rst

@@ -333,7 +333,10 @@ this tutorial, it is good to know that they are available.
 - Callbacks to control memory allocation for outgoing packets.  These are useful when sending packets using a custom library.  For example, when all packets must be in contiguous memory.
 - Callbacks to observe connection ID lifecycle.  These are useful in multi-process applications.
 - Callbacks that provide access to a shared-memory hash.  This is also used in multi-process applications.
-- HTTP header set processing.  These callbacks may be used in HTTP mode for HTTP/3 and Google QUIC.
+- HTTP header set processing.  These callbacks may be used in HTTP mode for
+  HTTP/3 and Google QUIC.  The optional ``on_hset_in`` stream callback
+  notifies the application when a decoded header set is ready to be collected
+  using :func:`lsquic_stream_get_hset()`.
 
 Please refer to :ref:`apiref-engine-settings` for details.
 
@@ -365,6 +368,7 @@ The optional callbacks are used to observe some events in the connection lifecyc
       void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s);
       void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token,
       void (*on_sess_resume_info)(lsquic_conn_t *c, const unsigned char *, size_t);
+      void (*on_hset_in)  (lsquic_stream_t *s, lsquic_stream_ctx_t *h);
   };
 
 On new connection

include/lsquic.h

@@ -236,6 +236,11 @@ struct lsquic_stream_if {
     void (*on_conncloseframe_received)(lsquic_conn_t *c,
                                        int app_error, uint64_t error_code,
                                        const char *reason, int reason_len);
+    /**
+     * Optional callback is called when a new header set becomes available.
+     * The user may pick it off immediately using lsquic_stream_get_hset().
+     */
+    void (*on_hset_in)  (lsquic_stream_t *s, lsquic_stream_ctx_t *h);
 };
 
 struct ssl_ctx_st;

src/liblsquic/lsquic_full_conn.c

@@ -4108,7 +4108,6 @@ synthesize_push_request (struct full_conn *conn, void *hset,
     if (lsquic_http1x_if == conn->fc_enpub->enp_hsi_if)
         uh->uh_flags    |= UH_H1H;
     uh->uh_hset          = hset;
-    uh->uh_next          = NULL;
 
     return uh;
 }

src/liblsquic/lsquic_full_conn_ietf.c

@@ -4166,7 +4166,6 @@ ietf_full_conn_ci_push_stream (struct lsquic_conn *lconn, void *hset,
     uh->uh_exclusive     = 0;
     uh->uh_flags         = UH_FIN;
     uh->uh_hset          = hset;
-    uh->uh_next          = NULL;
 
     memset(promise, 0, sizeof(*promise));
     promise->pp_refcnt = 1; /* This function itself keeps a reference */
@@ -10099,4 +10098,3 @@ static const struct lsquic_stream_if unicla_if =
 static const struct lsquic_stream_if *unicla_if_ptr = &unicla_if;
 
 typedef char dcid_elem_fits_in_128_bytes[sizeof(struct dcid_elem) <= 128 ? 1 : - 1];
-

src/liblsquic/lsquic_headers.h

@@ -2,6 +2,8 @@
 #ifndef LSQUIC_HEADERS_H
 #define LSQUIC_HEADERS_H 1
 
+#include <sys/queue.h>
+
 /* When ea_hsi_if is not specified, the headers are converted to a C string
  * that contains HTTP/1.x-like header structure.
  */
@@ -36,8 +38,8 @@ struct uncompressed_headers
                            UH_H1H  = (1 << 2),  /* uh_hset points to http1x_headers */
     }                      uh_flags:8;
     void                  *uh_hset;
-    struct uncompressed_headers
-                          *uh_next;
+    STAILQ_ENTRY(uncompressed_headers)
+                           uh_next;
 };
 
 #endif

src/liblsquic/lsquic_http1x_if.c

@@ -192,6 +192,7 @@ code_str_to_reason (const char code_str[HTTP_CODE_LEN])
     #define HTTP_REASON_CODE(code, reason) [code - 100] = reason
         HTTP_REASON_CODE(100, "Continue"),
         HTTP_REASON_CODE(101, "Switching Protocols"),
+        HTTP_REASON_CODE(103, "Early Hints"),
         HTTP_REASON_CODE(200, "OK"),
         HTTP_REASON_CODE(201, "Created"),
         HTTP_REASON_CODE(202, "Accepted"),
@@ -240,7 +241,7 @@ code_str_to_reason (const char code_str[HTTP_CODE_LEN])
     memcpy(code_buf, code_str, HTTP_CODE_LEN);
     code_buf[HTTP_CODE_LEN] = '\0';
     code = strtol(code_buf, NULL, 10) - 100;
-    if (code > 0 && code < (long) (sizeof(http_reason_phrases) /
+    if (code >= 0 && code < (long) (sizeof(http_reason_phrases) /
                                         sizeof(http_reason_phrases[0])))
         return http_reason_phrases[code];
     else