quico 0.3.0 → 0.7.0

package/index.js

@@ -1,49 +1,71 @@
 /*
- * quico: HTTP/3 and QUIC implementation for Node.js
+ * quico: a full HTTP stack in JavaScript
  * Copyright 2025 colocohen
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at:
- *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * This file is part of the open-source project hosted at:
+ * Licensed under the Apache License, Version 2.0
  *     https://github.com/colocohen/quico
  */
 
+// ============================================================
+//  quico no longer imports node:http, node:https, node:http2 or node:tls.
+//
+//  Every protocol layer is here: HTTP/1.1 (h1.js), HTTP/2 (h2.js + hpack.js),
+//  HTTP/3 (h3.js + QUIC), and WebSocket. TLS comes from lemon-tls, also pure
+//  JavaScript. What remains from Node is the transport it alone can provide —
+//  node:net for TCP and node:dgram for UDP — plus node:crypto for primitives.
+//
+//  The point is not purity for its own sake. One stack, one set of semantics:
+//  the same IncomingMessage and ServerResponse reach the application whether a
+//  request arrived over QUIC, over TCP with h2, or over TCP with HTTP/1.1, so
+//  a framework written against node:http runs over all three without knowing.
+// ============================================================
+
 import { createServer } from './src/server.js';
 import { request, get } from './src/client.js';
 import { Agent, globalAgent } from './src/agent.js';
 import { IncomingMessage, ServerResponse, ClientRequest } from './src/streams.js';
 import { createSecureContext } from './src/tls_bridge.js';
-import { WebTransport } from './src/webtransport.js';
+import lemonTls from 'lemon-tls';
+
+// Encrypted Client Hello keys (RFC 9849) — LemonTLS's; for createServer's `ech`.
+const generateEchKey = lemonTls.generateEchKey;
+import { WebTransport, WebTransportError } from './src/webtransport.js';
+import { WebSocket } from './src/ws_client.js';
+import { connectUdp } from './src/connect_udp_client.js';
+import { WebSocketServer, upgradeWebSocket } from './src/ws_server.js';
+import { ja4h } from './src/ja4h.js';
+import { h2Fingerprint, h3Fingerprint, observeH2 } from './src/h2_fingerprint.js';
+import { profileRequest } from './src/client_profile.js';
+
+// Transport layers, for building something other than HTTP on top.
 import { createQuicServer } from './src/quic_server.js';
+import { createQuicClientSocket } from './src/quic_socket.js';
+import { createTcpListener } from './src/tcp_listener.js';
 
-export {
-  createServer,
-  request,
-  get,
-  Agent,
-  globalAgent,
-  IncomingMessage,
-  ServerResponse,
-  ClientRequest,
-  createSecureContext,
-  WebTransport,
-  createQuicServer
+// Protocol layers, for consumers that own their own sockets.
+import { createServer as createH1Server } from './src/h1_server.js';
+import { createServer as createH2Server } from './src/h2_server.js';
+import { createServer as createH3Server } from './src/h3_server.js';
+import { request as h1Request } from './src/h1_client.js';
+import { request as h2Request } from './src/h2_client.js';
+import { request as h3Request } from './src/h3_client.js';
+
+const api = {
+  createServer, request, get, Agent, globalAgent,
+  IncomingMessage, ServerResponse, ClientRequest,
+  connectUdp, createSecureContext, generateEchKey, WebTransport, WebTransportError, WebSocket, WebSocketServer, upgradeWebSocket,
+  ja4h, h2Fingerprint, h3Fingerprint, observeH2, profileRequest,
+  createQuicServer, createQuicClientSocket, createTcpListener,
+  createH1Server, createH2Server, createH3Server,
+  h1Request, h2Request, h3Request
 };
 
-export default {
-  createServer,
-  request,
-  get,
-  Agent,
-  globalAgent,
-  IncomingMessage,
-  ServerResponse,
-  ClientRequest,
-  createSecureContext,
-  WebTransport,
-  createQuicServer
+export {
+  createServer, request, get, Agent, globalAgent,
+  IncomingMessage, ServerResponse, ClientRequest,
+  connectUdp, createSecureContext, generateEchKey, WebTransport, WebTransportError, WebSocket, WebSocketServer, upgradeWebSocket,
+  ja4h, h2Fingerprint, h3Fingerprint, observeH2, profileRequest,
+  createQuicServer, createQuicClientSocket, createTcpListener,
+  createH1Server, createH2Server, createH3Server,
+  h1Request, h2Request, h3Request
 };
+export default api;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quico",
-  "version": "0.3.0",
+  "version": "0.7.0",
   "description": "A pure JavaScript implementation of QUIC, HTTP/3, QPACK, and WebTransport for Node.js",
   "type": "module",
   "main": "index.cjs",
@@ -77,7 +77,7 @@
     }
   ],
   "dependencies": {
-    "flat-ranges": "^2.0.0",
-    "lemon-tls": "^0.4.1"
+    "flat-ranges": "^2.2.0",
+    "lemon-tls": "^0.9.0"
   }
 }

package/src/agent.js

@@ -13,6 +13,61 @@
  */
 
 import { EventEmitter } from 'node:events';
+import { createHash } from 'node:crypto';
+import lemonTls from 'lemon-tls';
+
+
+// ============================================================
+//  Which connections a request may share — node:https.Agent's getName
+//
+//  A pooled connection was looked up by host and port alone. One opened with
+//  rejectUnauthorized: false — to a server whose certificate was never
+//  checked — then carried the next request to that origin that does check,
+//  and that request went over an unverified connection without a word; one
+//  verified against a private `ca` served a request that trusts only the
+//  public roots. node:https puts what decides a connection's TLS into the
+//  pool's name (getName): ca, cert, key, rejectUnauthorized, servername.
+//  So does this, for every pool — the agent's HTTP/3 connections, the HTTP/2
+//  sessions and HTTP/1.1 sockets, and their TLS sessions — the values
+//  hashed, not spelled out, so a key or a CA bundle is not in a map key.
+//
+//  A request with a client certificate shared no connection at all, since
+//  the name could not tell one certificate from another; now it shares those
+//  opened with the same one, as in Node.
+// ============================================================
+
+function digestOf(v) {
+  if (v === undefined || v === null || v === '') return '';
+  var h = createHash('sha256');
+  (Array.isArray(v) ? v : [v]).forEach(function (x) {
+    h.update(typeof x === 'string' || Buffer.isBuffer(x) || x instanceof Uint8Array ? x : String(x));
+    h.update('\0');
+  });
+  return h.digest('hex').slice(0, 16);
+}
+
+/** The TLS identity part of a pool name: '' for a cleartext connection. */
+// Sessions kept per origin (see _takeSession).
+var ECH_RETRY_TTL = 24 * 3600 * 1000;   // ms: how long a server's retry_configs are used for
+var TICKETS_PER_ORIGIN = 4;
+
+function tlsIdentity(options) {
+  options = options || {};
+  // With ECH, its own connections: a request asking for its name to be
+  // hidden does not ride one opened without (or with another server's keys).
+  // With other key-exchange groups (ecdhCurve, as node:https names it), its
+  // own connections too: one asking for post-quantum does not ride a
+  // classical one.
+  var curve = options.ecdhCurve == null ? '' : String(options.ecdhCurve).trim().toUpperCase().replace(/[\s,]+/g, ':');
+  // And with other signature schemes (sigalgs): the certificate a server
+  // presents can depend on them (an ML-DSA one, asked for first).
+  var sigalgs = options.sigalgs == null ? '' : String(options.sigalgs).trim().toUpperCase().replace(/[\s,]+/g, ':');
+  return [options.servername || '', options.rejectUnauthorized === false ? 'noverify' : 'verify',
+          digestOf(options.ca), digestOf(options.cert), digestOf(options.key)].join(':') +
+         (options.ech ? ':ech:' + digestOf(options.ech) : '') +
+         (sigalgs ? ':sigalgs:' + sigalgs : '') +
+         (curve && curve !== 'AUTO' ? ':curve:' + curve : '');
+}
 
 
 // ============================================================
@@ -26,6 +81,19 @@ import { EventEmitter } from 'node:events';
 //    http2: true (default) — allow HTTP/2 in fallback chain
 //    http1: true (default) — allow HTTP/1.1 in fallback chain
 //    h3Timeout: 3000       — ms before falling back from H3
+//
+//  and node:http.Agent's, with Node's meanings. They govern HTTP/1.1, the one
+//  version that needs a socket per request; HTTP/2 and HTTP/3 multiplex every
+//  request to an origin over one connection, which the agent always keeps.
+//    keepAlive: true       — keep a socket for the next request (Node's
+//                            globalAgent default; `new http.Agent()` is false)
+//    keepAliveMsecs: 1000  — TCP keep-alive initial delay on kept sockets
+//    maxSockets: 256       — sockets per origin at once; more requests wait
+//    maxFreeSockets: 256   — idle sockets kept per origin
+//    timeout               — how long an idle socket is kept (5000 when unset,
+//                            as node:https.globalAgent)
+//    maxCachedSessions: 100 — TLS sessions kept to resume with, as
+//                            node:https.Agent's; 0 keeps none
 // ============================================================
 
 class Agent extends EventEmitter {
@@ -38,8 +106,8 @@ class Agent extends EventEmitter {
     this.keepAlive = options.keepAlive !== false;
     this.keepAliveMsecs = options.keepAliveMsecs || 1000;
     this.maxSockets = options.maxSockets || 256;
-    this.maxFreeSockets = options.maxFreeSockets || 32;
-    this.timeout = options.timeout || 30000;
+    this.maxFreeSockets = options.maxFreeSockets != null ? options.maxFreeSockets : 256;
+    this.timeout = options.timeout;   // unset: idle sockets kept 5 s (see agentH1Pool)
 
     // Protocol flags (defaults for all requests through this agent)
     this.http2 = options.http2 !== false;
@@ -48,14 +116,47 @@ class Agent extends EventEmitter {
     // H3 connect timeout before falling back (ms)
     this.h3Timeout = options.h3Timeout || 3000;
 
+    // The key-exchange groups its requests offer, unless a request names its
+    // own (tls.connect's ecdhCurve; 'X25519MLKEM768:X25519' for the
+    // post-quantum hybrid). Checked here, as tls.connect checks it.
+    if (options.ecdhCurve != null) lemonTls.parseEcdhCurve(options.ecdhCurve);
+    this.ecdhCurve = options.ecdhCurve != null ? options.ecdhCurve : undefined;
+    // The signature schemes they offer (tls.connect's sigalgs; 'mldsa65:…'
+    // first asks a server holding an ML-DSA certificate for it).
+    if (options.sigalgs != null) lemonTls.parseSigalgs(options.sigalgs);
+    this.sigalgs = options.sigalgs != null ? options.sigalgs : undefined;
+
+    // TLS sessions to resume with, as node:https.Agent keeps them: the
+    // latest per origin, the oldest dropped past maxCachedSessions.
+    this.maxCachedSessions = options.maxCachedSessions != null ? options.maxCachedSessions : 100;
+    if (!(Number.isInteger(this.maxCachedSessions) && this.maxCachedSessions >= 0))
+      throw new TypeError('maxCachedSessions must be a non-negative integer, got ' + options.maxCachedSessions);
+    this._sessionCache = new Map();
+    this._tokenCache = new Map();   // NEW_TOKEN tokens (_takeToken)
+    this._echCache = new Map();     // ECH keys a server sent on rejecting (_getEchRetry)
+
     // Protocol cache:  "host:port" → { protocol, ts, altSvcMaxAge }
     //   protocol: 'h3' | 'h2' | 'https'
     this._protocolCache = {};
 
+    // Alt-Svc advertisements: "host:port" (the origin) → { port, expires, brokenUntil }
+    this._altSvc = {};
+
     // Active QUIC connections: "host:port" → QUICConnection
     // Allows multiplexing multiple requests over one QUIC connection
     this._h3Pool = {};
 
+    // Connections still being ESTABLISHED: "host:port" → [waiter callbacks].
+    // Without this third state the pool only knows "have one" / "don't", so N
+    // requests issued in the same tick each see an empty pool and open N
+    // separate QUIC connections to the same origin — N handshakes, N
+    // congestion controllers, zero multiplexing (the QUIC interop runner's
+    // http3 test flags exactly this: "Expected exactly 1 handshake. Got: 3").
+    // The first request to miss the pool becomes the lead and creates the
+    // entry; requests arriving before it finishes park a callback here and
+    // are replayed once the lead settles.
+    this._h3Pending = {};
+
     // Active HTTP/2 sessions: "host:port" → http2.ClientHttp2Session
     this._h2Pool = {};
 
@@ -104,45 +205,209 @@ class Agent extends EventEmitter {
 
 
   // ============================================================
-  //  Alt-Svc header parsing
+  //  Alt-Svc (RFC 7838): where else an origin can be reached
+  //
+  //  An HTTP/1.1 or HTTP/2 response saying `Alt-Svc: h3=":443"; ma=86400`
+  //  tells us the same origin is also served over HTTP/3, on that port, for
+  //  the next `ma` seconds. That is what lets a client move to HTTP/3 at all.
+  //
+  //  Kept apart from the protocol cache on purpose. The two answer different
+  //  questions — "what worked here last time" and "what does the origin
+  //  advertise" — and when they shared one entry, the request that carried
+  //  the Alt-Svc header recorded its own protocol ('h2') a line later,
+  //  overwriting the advertisement: a client never moved to HTTP/3 through
+  //  Alt-Svc. An advertisement for another port was stored under that port,
+  //  where no lookup for the origin ever looked.
+  //
+  //  Keyed by origin. Only alternatives on the same host are used: one on
+  //  another host would need the connection to be authenticated for the
+  //  origin, not for the host it goes to (RFC 7838 §2.1), which the HTTP/3
+  //  client does not do.
   // ============================================================
 
   /**
-   * Parse Alt-Svc header from an HTTP/1.1 or HTTP/2 response.
-   * If it advertises h3, cache it for future requests.
-   *
-   * Examples:
+   * Record what an origin advertises. `value` is the Alt-Svc header.
    *   Alt-Svc: h3=":443"; ma=86400
-   *   Alt-Svc: h3=":443", h3-29=":443"
+   *   Alt-Svc: h3=":8443", h3-29=":8443"
+   *   Alt-Svc: clear
    */
-  parseAltSvc(host, port, altSvcValue) {
-    if (!altSvcValue || altSvcValue === 'clear') {
-      var key = host + ':' + (port || 443);
-      delete this._protocolCache[key];
+  parseAltSvc(host, port, value) {
+    var key = host + ':' + (port || 443);
+    if (!value) return;
+    if (String(value).trim() === 'clear') { delete this._altSvc[key]; return; }
+
+    var entries = String(value).split(',');
+    for (var i = 0; i < entries.length; i++) {
+      var match = entries[i].trim().match(/^h3="([^"]*)"(.*)$/);   // RFC 9114 h3 only, not drafts
+      if (!match) continue;
+      var authority = match[1];
+      var colonIdx = authority.lastIndexOf(':');
+      if (colonIdx < 0) continue;
+      var altHost = authority.substring(0, colonIdx);
+      var altPort = parseInt(authority.substring(colonIdx + 1), 10);
+      if (!(altPort > 0 && altPort < 65536)) continue;
+      if (altHost && altHost.toLowerCase() !== String(host).toLowerCase()) continue;
+      var maMatch = (match[2] || '').match(/(?:^|;)\s*ma=(\d+)/);
+      var maxAge = maMatch ? parseInt(maMatch[1], 10) * 1000 : 86400000;   // default 24h (§3.1)
+      var prev = this._altSvc[key];
+      this._altSvc[key] = {
+        port: altPort,
+        expires: Date.now() + maxAge,
+        // A fresh advertisement does not clear a recent failure of the same
+        // alternative: the origin keeps advertising it on every response.
+        brokenUntil: prev && prev.port === altPort ? prev.brokenUntil : 0
+      };
       return;
     }
+  }
 
-    var entries = altSvcValue.split(',');
-    for (var i = 0; i < entries.length; i++) {
-      var entry = entries[i].trim();
-      var match = entry.match(/^h3(?:-\d+)?="([^"]*)"(.*)$/);
-      if (match) {
-        var authority = match[1];
-        var params = match[2] || '';
-
-        var maMatch = params.match(/ma=(\d+)/);
-        var maxAge = maMatch ? parseInt(maMatch[1]) * 1000 : 86400000;
-
-        var h3Port = port;
-        var colonIdx = authority.lastIndexOf(':');
-        if (colonIdx >= 0) {
-          var parsed = parseInt(authority.substring(colonIdx + 1));
-          if (!isNaN(parsed)) h3Port = parsed;
-        }
-
-        this.setProtocol(host, h3Port, 'h3', maxAge);
-        return;
-      }
+  /** The HTTP/3 alternative to use for an origin now: { port }, or null. */
+  getAltSvc(host, port) {
+    var key = host + ':' + (port || 443);
+    var alt = this._altSvc[key];
+    if (!alt) return null;
+    var now = Date.now();
+    if (now > alt.expires) { delete this._altSvc[key]; return null; }
+    if (now < alt.brokenUntil) return null;
+    return { port: alt.port };
+  }
+
+  /**
+   * The alternative failed: don't try it again for a while (RFC 7838 §2.4
+   * lets a client mark an alternative broken). Five minutes, as browsers do
+   * for a first failure; requests in the meantime go straight to the
+   * origin's own protocol.
+   */
+  markAltSvcBroken(host, port) {
+    var alt = this._altSvc[host + ':' + (port || 443)];
+    if (alt) alt.brokenUntil = Date.now() + 5 * 60 * 1000;
+  }
+
+
+  // ============================================================
+  //  TLS sessions (node:https.Agent's _getSession / _cacheSession /
+  //  _evictSession)
+  //
+  //  Every connection used to start with a full handshake — certificate
+  //  chain, signature, its verification — though the server had sent a
+  //  ticket to skip all that next time; node:https.Agent resumes. And the
+  //  ticket is where a QUICO server keeps what it learned about the path
+  //  (Careful Resume, quic_connection.js): without resumption a returning
+  //  client was a stranger again, its transfer starting from the initial
+  //  window.
+  //
+  //  The key says which connections a session may serve: the transport (a
+  //  ticket from TLS over TCP is not offered to QUIC, RFC 9001 §4.6.1 keeps
+  //  them apart), and the pool name (tlsIdentity above) — a session from a
+  //  connection that did not verify the server, or verified it against
+  //  another `ca`, is not offered to one that does (lemon-tls checks that
+  //  too, from the session).
+  // ============================================================
+
+  _sessionKey(transport, host, port, options) {
+    return transport + ':' + host + ':' + (port || 443) + ':' + tlsIdentity(options);
+  }
+
+  /** node:https.Agent's getName: what the agent keys a connection by. */
+  getName(options) {
+    options = options || {};
+    return (options.hostname || options.host || 'localhost') + ':' + (options.port || 443) + ':' + tlsIdentity(options);
+  }
+
+  // Each origin's sessions — the tickets its server sent, up to
+  // TICKETS_PER_ORIGIN, newest last — and each used ONCE (RFC 8446 §C.4: a
+  // ticket offered twice links the two connections, and its 0-RTT is
+  // refused as a replay). The latest alone was kept and offered to every
+  // connection: two at once resumed with the same ticket, and the second's
+  // early data was always refused. A QUICO server sends two per full
+  // handshake, as OpenSSL and BoringSSL do. Expired ones are not offered
+  // (lemon-tls sessionInfo). maxCachedSessions bounds the origins.
+
+  /** The newest session for `key`, left in the cache (to look at). */
+  _getSession(key) {
+    var list = this._sessionCache.get(key);
+    return list && list.length ? list[list.length - 1] : undefined;
+  }
+
+  /** The newest unexpired session for `key`, taken: a new connection's. */
+  _takeSession(key) {
+    var list = this._sessionCache.get(key);
+    var now = Date.now();
+    while (list && list.length) {
+      var s = list.pop();
+      var info = lemonTls.sessionInfo ? lemonTls.sessionInfo(s) : null;
+      if (info && info.expiresAt != null && info.expiresAt <= now) continue;
+      if (!list.length) this._sessionCache.delete(key);
+      return s;
+    }
+    this._sessionCache.delete(key);
+    return undefined;
+  }
+
+  _cacheSession(key, session) {
+    if (this.maxCachedSessions === 0 || !session) return;
+    var list = this._sessionCache.get(key) || [];
+    this._sessionCache.delete(key);              // the newest origin goes last
+    list.push(session);
+    while (list.length > TICKETS_PER_ORIGIN) list.shift();
+    this._sessionCache.set(key, list);
+    while (this._sessionCache.size > this.maxCachedSessions) {
+      this._sessionCache.delete(this._sessionCache.keys().next().value);
+    }
+  }
+
+  _evictSession(key) {
+    this._sessionCache.delete(key);
+  }
+
+  // ECH keys a server sent when it rejected the ones the caller had
+  // (retry_configs, RFC 9849 §6.1.6), kept for the next connections (§6.1.8:
+  // "Clients MAY use information learned from a rejected ECH for future
+  // connections"): a server that rotated its keys was asked with the old
+  // ones on every connection until the caller's DNS caught up — rejected,
+  // retried, a round trip lost each time. Kept under what PSKs are (§6.1.8:
+  // "the same lifetime and scope restrictions"): the key is the session key
+  // of the config the caller gave (the same source), the origin, the TLS
+  // identity; a day at most (ECH_RETRY_TTL); none with maxCachedSessions 0;
+  // bounded by it. A caller that gives another config — its DNS updated —
+  // finds nothing kept for it.
+  _getEchRetry(key) {
+    var e = this._echCache.get(key);
+    if (!e) return null;
+    if (Date.now() - e.at > ECH_RETRY_TTL) { this._echCache.delete(key); return null; }
+    return e.configs;
+  }
+
+  _cacheEchRetry(key, configs) {
+    if (this.maxCachedSessions === 0 || !configs) return;
+    this._echCache.delete(key);
+    this._echCache.set(key, { configs: configs, at: Date.now() });
+    while (this._echCache.size > this.maxCachedSessions) {
+      this._echCache.delete(this._echCache.keys().next().value);
+    }
+  }
+
+  _evictEchRetry(key) {
+    this._echCache.delete(key);
+  }
+
+  // NEW_TOKEN tokens (RFC 9000 §8.1.3), per server: the latest one a QUIC
+  // connection to it was given, for the next connection's Initial — which
+  // then needs no proof of address, so the server's whole first flight goes
+  // out in one round trip. Each is used once (§8.1.3: a reused token links
+  // the connections that carry it), and the server gives another each time.
+  _takeToken(key) {
+    var t = this._tokenCache.get(key);
+    this._tokenCache.delete(key);
+    return t;
+  }
+
+  _cacheToken(key, token) {
+    if (this.maxCachedSessions === 0 || !token) return;
+    this._tokenCache.delete(key);
+    this._tokenCache.set(key, token);
+    while (this._tokenCache.size > this.maxCachedSessions) {
+      this._tokenCache.delete(this._tokenCache.keys().next().value);
     }
   }
 
@@ -158,13 +423,51 @@ class Agent extends EventEmitter {
     var conn = this._h3Pool[key];
     if (!conn) return null;
     var state = conn.quic ? conn.quic.state : 'closed';
-    if (state === 'closed' || state === 'draining' || state === 'closing') {
+    // GOAWAY'd (RFC 9114 §5.2) — the event below can come before the
+    // connection is pooled, so asked here too.
+    if (state === 'closed' || state === 'draining' || state === 'closing' || conn.goingAway) {
       delete this._h3Pool[key];
       return null;
     }
     return conn;
   }
 
+  /**
+   * Coalesce concurrent connection attempts to one origin.
+   *
+   * Returns false if the caller is the LEAD: no connection exists and nobody
+   * else is establishing one. The lead MUST eventually call
+   * resolveH3Pending(host, port, connOrNull) — on success, failure, or
+   * abandonment — or every later request to this origin parks forever.
+   *
+   * Returns true if the caller was parked as a follower; `cb` fires (with no
+   * arguments) once the lead settles, and the caller should simply retry its
+   * pool lookup: on success the connection is already registered, and on
+   * failure the retry becomes the next lead — serial retry, no thundering
+   * herd.
+   */
+  joinH3Pending(host, port, cb) {
+    var key = host + ':' + (port || 443);
+    if (this._h3Pending[key]) {
+      this._h3Pending[key].push(cb);
+      return true;
+    }
+    this._h3Pending[key] = [];
+    return false;
+  }
+
+  /** Lead's settlement. Registers the connection (if any) BEFORE waking the
+   *  waiters, so their retried pool lookups succeed synchronously. */
+  resolveH3Pending(host, port, conn) {
+    var key = host + ':' + (port || 443);
+    var waiters = this._h3Pending[key] || [];
+    delete this._h3Pending[key];
+    if (conn) this.setH3Connection(host, port, conn);
+    for (var i = 0; i < waiters.length; i++) {
+      try { waiters[i](); } catch (e) { /* a waiter's failure is its own */ }
+    }
+  }
+
   setH3Connection(host, port, conn) {
     var key = host + ':' + (port || 443);
     this._h3Pool[key] = conn;
@@ -247,6 +550,10 @@ class Agent extends EventEmitter {
       if (now - entry.ts > maxAge) delete this._protocolCache[key];
     }
 
+    for (var key in this._altSvc) {
+      if (now > this._altSvc[key].expires) delete this._altSvc[key];
+    }
+
     for (var key in this._h3Pool) {
       var conn = this._h3Pool[key];
       var state = conn.quic ? conn.quic.state : 'closed';
@@ -262,8 +569,20 @@ class Agent extends EventEmitter {
   destroy() {
     if (this._sweepTimer) { clearInterval(this._sweepTimer); this._sweepTimer = null; }
 
+    // Wake anyone parked on an in-flight connection attempt; their retried
+    // pool lookup will find nothing and proceed (or fail) on its own.
+    for (var key in this._h3Pending) {
+      var waiters = this._h3Pending[key];
+      delete this._h3Pending[key];
+      for (var i = 0; i < waiters.length; i++) {
+        try { waiters[i](); } catch (e) {}
+      }
+    }
+    this._h3Pending = {};
+
     for (var key in this._h3Pool) {
-      try { this._h3Pool[key].quic.close(0, 'agent destroy'); } catch (e) {}
+      // Pooled connections are HTTP/3 — close with H3_NO_ERROR (RFC 9114 §5.2).
+      try { this._h3Pool[key].quic.close(0x0100, 'agent destroy', true); } catch (e) {}
     }
     this._h3Pool = {};
 
@@ -272,12 +591,21 @@ class Agent extends EventEmitter {
     }
     this._h2Pool = {};
 
+    // The pools client.js keeps on the agent for HTTP/2 sessions and HTTP/1.1
+    // sockets. destroy() left them open: a destroyed agent kept its sockets.
+    if (this._h2ClientPool) { try { this._h2ClientPool.destroy(); } catch (e) {} this._h2ClientPool = null; }
+    if (this._h1ClientPool) { try { this._h1ClientPool.destroy(); } catch (e) {} this._h1ClientPool = null; }
+
     this._protocolCache = {};
+    this._altSvc = {};
     this._activeCounts = {};
+    this._sessionCache.clear();
+    this._tokenCache.clear();
+    this._echCache.clear();
   }
 }
 
 
 var globalAgent = new Agent();
 
-export { Agent, globalAgent };
+export { Agent, globalAgent, tlsIdentity };