quico 0.1.3 → 0.3.0

package/index.d.ts

@@ -0,0 +1,158 @@
+/*
+ * quico — TypeScript declarations
+ * Pure JavaScript QUIC, HTTP/3, QPACK & WebTransport for Node.js
+ */
+
+/// <reference types="node" />
+
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Duplex, Readable, Writable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+
+// ============================================================
+//  Server
+// ============================================================
+
+type RequestHandler = (req: QuicoIncomingMessage, res: QuicoServerResponse) => void;
+
+interface ServerOptions {
+  key?: string | Buffer;
+  cert?: string | Buffer;
+  ca?: string | Buffer;
+  SNICallback?: (servername: string, cb: (err: Error | null, ctx: any) => void) => void;
+  maxConnections?: number;
+}
+
+interface QuicoServer extends EventEmitter {
+  listen(port: number, callback?: () => void): this;
+  listen(port: number, host: string, callback?: () => void): this;
+  close(callback?: () => void): void;
+  on(event: 'request', listener: RequestHandler): this;
+  on(event: 'listening', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+interface QuicoIncomingMessage extends IncomingMessage {
+  /** QUIC stream ID */
+  streamId?: number;
+
+  // WebTransport events (available after res.writeHead(200) on WT sessions)
+  on(event: 'stream', listener: (stream: Duplex) => void): this;
+  on(event: 'unidirectionalStream', listener: (stream: Readable) => void): this;
+  on(event: 'datagram', listener: (data: Buffer) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+interface QuicoServerResponse extends ServerResponse {
+  // WebTransport methods (available after res.writeHead(200) on WT sessions)
+  sendDatagram?(data: Buffer | Uint8Array | string): void;
+  createBidirectionalStream?(): Duplex;
+  createUnidirectionalStream?(): Writable;
+}
+
+
+// ============================================================
+//  Client
+// ============================================================
+
+interface RequestOptions {
+  hostname?: string;
+  host?: string;
+  port?: number;
+  path?: string;
+  method?: string;
+  headers?: Record<string, string | string[]>;
+  agent?: QuicoAgent;
+  rejectUnauthorized?: boolean;
+  timeout?: number;
+}
+
+interface QuicoClientRequest extends Writable {
+  on(event: 'response', listener: (res: QuicoIncomingMessage) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'timeout', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+  end(data?: string | Buffer): this;
+  abort(): void;
+  setTimeout(ms: number, callback?: () => void): this;
+}
+
+
+// ============================================================
+//  Agent
+// ============================================================
+
+interface QuicoAgent {
+  destroy(): void;
+}
+
+
+// ============================================================
+//  WebTransport
+// ============================================================
+
+interface WebTransportOptions {
+  /** Skip certificate verification (default: true for self-signed) */
+  rejectUnauthorized?: boolean;
+}
+
+declare class WebTransport extends EventEmitter {
+  constructor(url: string, options?: WebTransportOptions);
+
+  /** Resolves when the WebTransport session is established */
+  readonly ready: Promise<void>;
+  /** Current state: 'connecting' | 'connected' | 'closed' */
+  readonly state: string;
+  /** The URL of the WebTransport session */
+  readonly url: string;
+
+  /** WHATWG-style datagram interface */
+  readonly datagrams: {
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly writable: WritableStream<Uint8Array>;
+  };
+
+  /** Create a bidirectional stream (Node.js Duplex + WHATWG .readable/.writable) */
+  createBidirectionalStream(): Promise<Duplex & {
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly writable: WritableStream<Uint8Array>;
+  }>;
+
+  /** Create a unidirectional stream for writing */
+  createUnidirectionalStream(): Promise<Writable>;
+
+  /** Send an unreliable datagram */
+  sendDatagram(data: Buffer | Uint8Array): void;
+
+  /** Close the WebTransport session */
+  close(info?: { closeCode?: number; reason?: string }): void;
+
+  on(event: 'datagram', listener: (data: Buffer) => void): this;
+  on(event: 'close', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+
+// ============================================================
+//  Main module
+// ============================================================
+
+declare const quico: {
+  createServer(options: ServerOptions, handler?: RequestHandler): QuicoServer;
+
+  request(url: string | URL, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+  request(url: string | URL, options: RequestOptions, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+  request(options: RequestOptions, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+
+  get(url: string | URL, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+  get(url: string | URL, options: RequestOptions, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+  get(options: RequestOptions, callback?: (res: QuicoIncomingMessage) => void): QuicoClientRequest;
+
+  globalAgent: QuicoAgent;
+};
+
+export default quico;
+export { WebTransport };
+export { QuicoServer, QuicoIncomingMessage, QuicoServerResponse, QuicoClientRequest, QuicoAgent };
+export { ServerOptions, RequestOptions, RequestHandler, WebTransportOptions };

package/index.js

@@ -1,23 +1,49 @@
-/*
- * quico: HTTP/3 and QUIC implementation for Node.js
- * 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:
- *     https://github.com/colocohen/quico
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- */
-
-import { createServer } from './h3_server.js';
-
-export { createServer };
-
-export default { createServer };
+/*
+ * quico: HTTP/3 and QUIC implementation for Node.js
+ * 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:
+ *     https://github.com/colocohen/quico
+ */
+
+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 { createQuicServer } from './src/quic_server.js';
+
+export {
+  createServer,
+  request,
+  get,
+  Agent,
+  globalAgent,
+  IncomingMessage,
+  ServerResponse,
+  ClientRequest,
+  createSecureContext,
+  WebTransport,
+  createQuicServer
+};
+
+export default {
+  createServer,
+  request,
+  get,
+  Agent,
+  globalAgent,
+  IncomingMessage,
+  ServerResponse,
+  ClientRequest,
+  createSecureContext,
+  WebTransport,
+  createQuicServer
+};

package/package.json

@@ -1,60 +1,83 @@
-{
-  "name": "quico",
-  "version": "0.1.3",
-  "description": "A pure JavaScript implementation of QUIC, HTTP/3, QPACK, and WebTransport for Node.js",
-  "main": "index.js",
-  "type": "module",
-  "keywords": [
-    "quic",
-    "http3",
-    "http",
-    "https",
-    "h3",
-    "quic-node",
-    "http3-node",
-    "quic-server",
-    "http3-server",
-    "h3-node",
-    "webtransport",
-    "websocket",
-    "datagram",
-    "udp",
-    "qpack",
-    "tls",
-    "tls1.3",
-    "tls13",
-    "nodejs",
-    "backend",
-    "real-time",
-    "low-latency",
-    "transport",
-    "http-server",
-    "socketio"
-  ],
-  "author": "colocohen",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/colocohen/quico.git"
-  },
-  "bugs": {
-    "url": "https://github.com/colocohen/quico/issues"
-  },
-  "homepage": "https://github.com/colocohen/quico#readme",
-  "funding": [
-    {
-      "type": "github",
-      "url": "https://github.com/sponsors/colocohen"
-    },
-    {
-      "type": "opencollective",
-      "url": "https://opencollective.com/quico-node"
-    }
-  ],
-  "dependencies": {
-    "@noble/curves": "^2.0.1",
-    "@noble/hashes": "^2.0.1",
-    "flat-ranges": "^1.0.2",
-    "lemon-tls": "^0.1.1"
-  }
-}
+{
+  "name": "quico",
+  "version": "0.3.0",
+  "description": "A pure JavaScript implementation of QUIC, HTTP/3, QPACK, and WebTransport for Node.js",
+  "type": "module",
+  "main": "index.cjs",
+  "module": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "quic",
+    "http3",
+    "http",
+    "https",
+    "h3",
+    "quic-node",
+    "http3-node",
+    "quic-server",
+    "quic-client",
+    "http3-server",
+    "http3-client",
+    "h3-node",
+    "webtransport",
+    "websocket",
+    "datagram",
+    "udp",
+    "qpack",
+    "tls",
+    "tls1.3",
+    "tls13",
+    "nodejs",
+    "backend",
+    "real-time",
+    "low-latency",
+    "transport",
+    "http-server",
+    "socketio"
+  ],
+  "author": {
+    "name": "colocohen",
+    "email": "support@quicojs.dev"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/colocohen/quico.git"
+  },
+  "bugs": {
+    "email": "support@quicojs.dev",
+    "url": "https://github.com/colocohen/quico/issues"
+  },
+  "homepage": "https://github.com/colocohen/quico#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/colocohen"
+    },
+    {
+      "type": "opencollective",
+      "url": "https://opencollective.com/quicojs"
+    }
+  ],
+  "dependencies": {
+    "flat-ranges": "^2.0.0",
+    "lemon-tls": "^0.4.1"
+  }
+}

package/src/agent.js

@@ -0,0 +1,283 @@
+/*
+ * quico: HTTP/3 and QUIC implementation for Node.js
+ * 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:
+ *     https://github.com/colocohen/quico
+ */
+
+import { EventEmitter } from 'node:events';
+
+
+// ============================================================
+//  Agent — connection pooling + protocol discovery
+//
+//  Mirrors node:https.Agent API surface.
+//  Caches which protocol works per host so subsequent requests
+//  skip the discovery step.
+//
+//  Options:
+//    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
+// ============================================================
+
+class Agent extends EventEmitter {
+
+  constructor(options) {
+    super();
+
+    options = options || {};
+
+    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;
+
+    // Protocol flags (defaults for all requests through this agent)
+    this.http2 = options.http2 !== false;
+    this.http1 = options.http1 !== false;
+
+    // H3 connect timeout before falling back (ms)
+    this.h3Timeout = options.h3Timeout || 3000;
+
+    // Protocol cache:  "host:port" → { protocol, ts, altSvcMaxAge }
+    //   protocol: 'h3' | 'h2' | 'https'
+    this._protocolCache = {};
+
+    // Active QUIC connections: "host:port" → QUICConnection
+    // Allows multiplexing multiple requests over one QUIC connection
+    this._h3Pool = {};
+
+    // Active HTTP/2 sessions: "host:port" → http2.ClientHttp2Session
+    this._h2Pool = {};
+
+    // Request count per host (for maxSockets enforcement)
+    this._activeCounts = {};
+
+    // Sweep interval — clean stale pool entries
+    this._sweepTimer = setInterval(() => this._sweep(), 15000);
+    if (this._sweepTimer.unref) this._sweepTimer.unref();
+  }
+
+
+  // ============================================================
+  //  Protocol cache
+  // ============================================================
+
+  /**
+   * Get cached protocol for a host, or null if unknown.
+   */
+  getProtocol(host, port) {
+    var key = host + ':' + (port || 443);
+    var entry = this._protocolCache[key];
+    if (!entry) return null;
+
+    // Check expiry (Alt-Svc max-age, default 24h)
+    var maxAge = entry.altSvcMaxAge || 86400000;
+    if (Date.now() - entry.ts > maxAge) {
+      delete this._protocolCache[key];
+      return null;
+    }
+
+    return entry.protocol;
+  }
+
+  /**
+   * Record which protocol works for a host.
+   */
+  setProtocol(host, port, protocol, altSvcMaxAge) {
+    var key = host + ':' + (port || 443);
+    this._protocolCache[key] = {
+      protocol: protocol,
+      ts: Date.now(),
+      altSvcMaxAge: altSvcMaxAge || 86400000
+    };
+  }
+
+
+  // ============================================================
+  //  Alt-Svc header parsing
+  // ============================================================
+
+  /**
+   * Parse Alt-Svc header from an HTTP/1.1 or HTTP/2 response.
+   * If it advertises h3, cache it for future requests.
+   *
+   * Examples:
+   *   Alt-Svc: h3=":443"; ma=86400
+   *   Alt-Svc: h3=":443", h3-29=":443"
+   */
+  parseAltSvc(host, port, altSvcValue) {
+    if (!altSvcValue || altSvcValue === 'clear') {
+      var key = host + ':' + (port || 443);
+      delete this._protocolCache[key];
+      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;
+      }
+    }
+  }
+
+
+  // ============================================================
+  //  H3 connection pool
+  //  Stores { quic, h3, udpSocket, _nextStreamId } objects
+  //  from h3_client.js for multiplexing.
+  // ============================================================
+
+  getH3Connection(host, port) {
+    var key = host + ':' + (port || 443);
+    var conn = this._h3Pool[key];
+    if (!conn) return null;
+    var state = conn.quic ? conn.quic.state : 'closed';
+    if (state === 'closed' || state === 'draining' || state === 'closing') {
+      delete this._h3Pool[key];
+      return null;
+    }
+    return conn;
+  }
+
+  setH3Connection(host, port, conn) {
+    var key = host + ':' + (port || 443);
+    this._h3Pool[key] = conn;
+    if (conn.quic) {
+      conn.quic.on('close', () => {
+        if (this._h3Pool[key] === conn) delete this._h3Pool[key];
+      });
+    }
+    // RFC 9114 §5.2: once the peer sends GOAWAY it won't accept new requests, so
+    // stop reusing this connection for new ones. In-flight requests keep running
+    // on it; they just won't be joined by new requests (which open a fresh conn).
+    if (conn.h3 && typeof conn.h3.on === 'function') {
+      conn.h3.on('goaway', () => {
+        if (this._h3Pool[key] === conn) delete this._h3Pool[key];
+      });
+    }
+  }
+
+
+  // ============================================================
+  //  H2 session pool
+  // ============================================================
+
+  getH2Session(host, port) {
+    var key = host + ':' + (port || 443);
+    var session = this._h2Pool[key];
+    if (!session) return null;
+    if (session.closed || session.destroyed) {
+      delete this._h2Pool[key];
+      return null;
+    }
+    return session;
+  }
+
+  setH2Session(host, port, session) {
+    var key = host + ':' + (port || 443);
+    this._h2Pool[key] = session;
+    session.on('close', () => {
+      if (this._h2Pool[key] === session) delete this._h2Pool[key];
+    });
+    session.on('error', () => {
+      if (this._h2Pool[key] === session) delete this._h2Pool[key];
+    });
+  }
+
+
+  // ============================================================
+  //  Active request tracking
+  // ============================================================
+
+  canCreateSocket(host, port) {
+    var key = host + ':' + (port || 443);
+    return (this._activeCounts[key] || 0) < this.maxSockets;
+  }
+
+  trackRequest(host, port) {
+    var key = host + ':' + (port || 443);
+    this._activeCounts[key] = (this._activeCounts[key] || 0) + 1;
+  }
+
+  releaseRequest(host, port) {
+    var key = host + ':' + (port || 443);
+    if (this._activeCounts[key]) {
+      this._activeCounts[key]--;
+      if (this._activeCounts[key] <= 0) delete this._activeCounts[key];
+    }
+  }
+
+
+  // ============================================================
+  //  Sweep stale entries
+  // ============================================================
+
+  _sweep() {
+    var now = Date.now();
+
+    for (var key in this._protocolCache) {
+      var entry = this._protocolCache[key];
+      var maxAge = entry.altSvcMaxAge || 86400000;
+      if (now - entry.ts > maxAge) delete this._protocolCache[key];
+    }
+
+    for (var key in this._h3Pool) {
+      var conn = this._h3Pool[key];
+      var state = conn.quic ? conn.quic.state : 'closed';
+      if (state === 'closed' || state === 'draining') delete this._h3Pool[key];
+    }
+
+    for (var key in this._h2Pool) {
+      var session = this._h2Pool[key];
+      if (session.closed || session.destroyed) delete this._h2Pool[key];
+    }
+  }
+
+  destroy() {
+    if (this._sweepTimer) { clearInterval(this._sweepTimer); this._sweepTimer = null; }
+
+    for (var key in this._h3Pool) {
+      try { this._h3Pool[key].quic.close(0, 'agent destroy'); } catch (e) {}
+    }
+    this._h3Pool = {};
+
+    for (var key in this._h2Pool) {
+      try { this._h2Pool[key].close(); } catch (e) {}
+    }
+    this._h2Pool = {};
+
+    this._protocolCache = {};
+    this._activeCounts = {};
+  }
+}
+
+
+var globalAgent = new Agent();
+
+export { Agent, globalAgent };