feat(client): multiplex HTTP/2 requests and clear connections

client/connection.lisp

@@ -21,6 +21,7 @@
   max-connection-age
   clock-function
   lock
+  (generation 0)
   (clear-callbacks nil)
   (entries nil))
 
@@ -227,19 +228,22 @@ be used concurrently from multiple threads."
               (remove oldest entries :test #'eq))
         (%pool-close pool (%http-pooled-connection-stream oldest))))))
 
-(defun %pool-retain (pool key stream opened-at last-used)
+(defun %pool-retain (pool key stream opened-at last-used generation)
   (let ((max-idle (%http-connection-pool-max-idle pool)))
-    (if (zerop max-idle)
-        (%pool-close pool stream)
-        (progn
-          (when (>= (length (%http-connection-pool-entries pool)) max-idle)
-            (%pool-evict-oldest pool))
-          (push (%make-http-pooled-connection
-                 :key key
-                 :stream stream
-                 :opened-at opened-at
-                 :last-used last-used)
-                (%http-connection-pool-entries pool)))))
+    (cond
+      ((/= generation (%http-connection-pool-generation pool))
+       (%pool-close pool stream))
+      ((zerop max-idle)
+       (%pool-close pool stream))
+      (t
+       (when (>= (length (%http-connection-pool-entries pool)) max-idle)
+         (%pool-evict-oldest pool))
+       (push (%make-http-pooled-connection
+              :key key
+              :stream stream
+              :opened-at opened-at
+              :last-used last-used)
+             (%http-connection-pool-entries pool)))))
   pool)
 
 (defun %pool-open (pool request &key timeout deadline proxy-plan proxy)
@@ -270,12 +274,13 @@ be used concurrently from multiple threads."
           (%http-connection-pool-max-connection-age pool))))
 
 (defun http-connection-pool-clear (pool)
-  "Close and remove every idle connection in POOL, returning its count."
+  "Close idle entries in POOL and invoke its clear callbacks. Return the number of idle entries removed."
   (%pool-ensure-pool pool)
   (let ((entries nil)
         (callbacks nil)
         (callback-error nil))
     (%with-client-lock ((%http-connection-pool-lock pool))
+      (incf (%http-connection-pool-generation pool))
       (setf entries (%http-connection-pool-entries pool)
             callbacks (copy-list
                        (%http-connection-pool-clear-callbacks pool))
@@ -315,17 +320,19 @@ be used concurrently from multiple threads."
                      :cause condition))))
          (stream nil)
          (opened-at nil)
+         (generation nil)
          (retained-p nil))
     (handler-case
         (with-http-deadline
          (absolute-deadline timeout
                             :inherited deadline
                             :clock-function #'%pool-monotonic-time)
          (let ((entry
-                (unless *client-preopened-http-stream*
-                  (%with-client-lock ((%http-connection-pool-lock pool))
-                                     (%pool-purge-expired pool)
-                                     (%pool-take pool key)))))
+                (%with-client-lock ((%http-connection-pool-lock pool))
+                  (setf generation (%http-connection-pool-generation pool))
+                  (unless *client-preopened-http-stream*
+                    (%pool-purge-expired pool)
+                    (%pool-take pool key)))))
            (cond
             (*client-preopened-http-stream*
              (setf stream (prog1 *client-preopened-http-stream*
@@ -349,7 +356,7 @@ be used concurrently from multiple threads."
                  (error '%http-client-alpn-handoff
                         :stream opened-stream))
                 ((or (null negotiated-alpn)
-    (equal negotiated-alpn "http/1.1"))
+                     (equal negotiated-alpn "http/1.1"))
                  nil)
                 (t
                  (%pool-protocol-error
@@ -376,24 +383,25 @@ be used concurrently from multiple threads."
              (if reusable-p
                  (progn
                    (%with-client-lock ((%http-connection-pool-lock pool))
-                                      (%pool-retain pool key stream opened-at (%pool-now pool)))
+                     (%pool-retain pool key stream opened-at (%pool-now pool)
+                                   generation))
                    (setf retained-p t))
-               (%pool-close pool stream))
+                 (%pool-close pool stream))
              (setf stream nil)
              response)))
       (%http-client-alpn-handoff (condition)
-                                 (error condition))
+        (error condition))
       (http-error (condition)
-                  (unless retained-p
-                    (%pool-close pool stream))
-                  (error condition))
+        (unless retained-p
+          (%pool-close pool stream))
+        (error condition))
       (error (condition)
-             (unless retained-p
-               (%pool-close pool stream))
-             (error 'http-connection-error
-                    :message "The pooled HTTP exchange signaled an error."
-                    :operation :transport
-                    :cause condition)))))
+        (unless retained-p
+          (%pool-close pool stream))
+        (error 'http-connection-error
+               :message "The pooled HTTP exchange signaled an error."
+               :operation :transport
+               :cause condition)))))
 
 (defun http-connection-pool-send
     (pool request &key key timeout deadline max-header-bytes max-fields max-body-bytes

client/data.lisp

@@ -328,6 +328,7 @@ character in that range is a decimal digit, apart from an optional sign when
   ;; plus :ALTERNATIVE-SERVICE.
   http3-transport-function
   connection-pool
+  clear-connections-function
   (default-headers nil)
   cookie-jar
   cookie-partition-key

docs/src/project/changelog.md

@@ -14,6 +14,15 @@ historical release behavior, not the current API contract; see the
   See the
   [WebSocket and SSE migration guide](migration.md#websocket-and-sse-api-migration).
 
+### HTTP/2
+
+- report malformed PING frames received while awaiting an acknowledgement as
+  `http-protocol-error` with `:http2-client` operation and the received frame
+  as detail.
+- document `:http2-read` detail for DATA on a never-opened HTTP/2 client stream:
+  the stream ID while another request is in progress and has not failed,
+  otherwise a list with `0` (the DATA frame type) followed by the stream ID.
+
 ## 0.4.1
 
 - require certificate-chain, hostname, and trust verification by default on

docs/src/reference/api.md

@@ -442,6 +442,10 @@ The condition type for malformed or contradictory protocol data.
 ### `http-protocol-error-detail`
 
 Return structured protocol detail.
+For `:http2-read` errors caused by DATA on a client stream that has never been
+opened, the detail is the stream ID when another request on the connection is
+still in progress and has not failed; otherwise it is a two-element list with
+`0` (the DATA frame type) first and the stream ID second.
 
 ### `http-invalid-uri`
 
@@ -557,6 +561,9 @@ per decoded header or trailer section is 256.
 
 `cancel-http2-stream` emits `RST_STREAM` for an opened client stream.
 `ping-http2-connection` sends a PING and waits for the matching acknowledgement.
+If it receives a malformed PING while waiting, it signals
+`HTTP-PROTOCOL-ERROR` with operation `:http2-client` and the received frame as
+detail.
 `send-http2-priority-update` emits an RFC 9218 priority update.
 `send-http2-goaway` and its convenience alias
 `graceful-shutdown-http2-connection` make the connection drain without
@@ -612,9 +619,16 @@ also clamps peer HPACK table settings to 4096 bytes by default through
 `&key open-connection max-connections idle-timeout max-connection-age
 clock-function on-evict on-transient-close`. `max-connections` defaults to `8`
 and limits retained cache entries; request-scoped connections do not count
-toward that limit. On SBCL, the manager synchronizes its entry state for
-concurrent callers and leases each retained connection to at most one manager
-call at a time.
+toward that limit, so the total number of open connections can exceed it. On
+SBCL, the manager synchronizes its entry state for concurrent callers. Ordinary
+single-request calls with the same key can share one retained connection; its
+scheduler assigns distinct stream IDs and observes the peer's concurrent-stream
+and flow-control limits. A batch call holds an exclusive lease on its selected
+connection. A concurrent call that cannot share an active entry uses a
+request-scoped connection.
+There is no separate cap on total open connections. Enforcing one would require
+the manager to define how concurrent calls wait or fail when all sockets are in
+use, so `max-connections` remains a retained-cache limit.
 By default, the cache key includes the request scheme, host, port, proxy plan,
 and proxy.
 Supplying `connection-key` to a send function replaces that default; keys are
@@ -626,11 +640,10 @@ Each invocation passes `:timeout` and `:deadline`; proxy-routed requests also
 pass `:proxy-plan` and `:proxy`. Caller-supplied `open-connection`,
 `clock-function`, `on-evict`, and `on-transient-close` functions may run
 concurrently with manager calls, so they must synchronize any shared state
-they use. A request for a key whose retained connection is busy uses a
-request-scoped connection. For a different key, the manager can create a
-retained entry while below the cap, or evict the least-recently-used idle
-entry at capacity. If the cache is full and every retained entry is active,
-it uses a request-scoped connection.
+they use. For a different key, the manager can create a retained entry while
+below the cap, or evict the least-recently-used idle entry at capacity. If the
+cache is full and every retained entry is active, a request for another key
+uses a request-scoped connection.
 
 `idle-timeout`, `max-connection-age`, and `on-evict` default to `nil`. Idle
 expiry is based on the time since the last completed manager call; maximum age
@@ -667,7 +680,17 @@ session multiplexes the streams.
 `make-http2-connection-manager-transport` adapts a manager to the high-level
 client transport protocol. The two send functions and the function returned by
 `make-http2-connection-manager-transport` each accept and forward the per-section
-`max-fields` limit.
+`max-fields` limit. Per-request `max-header-bytes`, `max-fields`, and
+`max-body-bytes` values can tighten the selected connection's limits; they
+cannot raise them.
+
+While dispatching received response frames, malformed headers and body-limit
+violations fail the connection and every active request on it. RFC 9113
+§5.4.1 permits treating a stream error as a connection error. A per-request
+timeout, callback error, explicit stream cancellation, or peer `RST_STREAM`
+uses the stream-level handling path. If writing a required `RST_STREAM` fails,
+the connection also fails.
+
 `clear-http2-connection-manager` is idempotent. It retires
 all retained connections without closing the manager and returns it on success.
 A call whose connection was still opening when clear began may finish using