quico 0.1.1 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">QUICO</h1>
 <p align="center">
-  <em>🚀 JavaScript implementation of QUIC, HTTP/3, QPACK & WebTransport for Node.js</em>
+  <em>Pure JavaScript implementation of QUIC, HTTP/3, QPACK &amp; WebTransport for Node.js</em>
 </p>
 
 <p align="center">
@@ -17,112 +17,350 @@
 
 ---
 
-> **⚠️ Project status: _Active development_.**  
-> APIs may change without notice until we reach v1.0.  
-> Use at your own risk and please report issues!
+> **⚠️ Project status: Active development.**
+> APIs may change before v1.0. Use at your own risk and please report issues!
 
-## ✨ Features
-- **Pure JS QUIC**: Initial & 1-RTT packets, connection ID management, ACK & flow-control.
-- **TLS 1.3 handshake** in JavaScript (no OpenSSL binding).
-- **HTTP/3** control stream, request/response, server push, GOAWAY.
-- **WebTransport** streams & datagrams (RFC 9298) — tested with Chrome Canary.
-- **QPACK** encoder/decoder with custom Huffman table support.
-- Fully self-contained—no native addons, no external OpenSSL.
+---
+
+
+## Table of Contents
+1. [What is QUIC / HTTP/3?](#-what-is-quic--http3)
+2. [Why QUICO?](#-why-quico)
+3. [Quick Start](#-quick-start)
+4. [Features](#-features)
+5. [Node.js API Compatibility](#-nodejs-api-compatibility)
+6. [WebTransport](#-webtransport)
+7. [Testing](#-testing)
+8. [Project Structure](#-project-structure)
+9. [Roadmap](#-roadmap)
+10. [Sponsors](#-sponsors)
+11. [Contact](#-contact)
+12. [License](#-license)
+
+
+## ⚡ What is QUIC / HTTP/3?
+
+**QUIC** is the future of Internet transport protocols. Created at Google and standardized by the IETF, QUIC powers **HTTP/3** and is already deployed at scale by the world’s largest platforms. It was specifically designed to overcome the limitations of TCP and deliver a faster, smoother, and more resilient web.
+
+Key advantages of QUIC include:
+
+- **Eliminating bottlenecks**: With TCP, data must arrive strictly in order. If a single packet is lost or delayed, all subsequent packets are blocked until it arrives — a phenomenon called **head-of-line blocking**. QUIC removes this bottleneck by running over UDP, so each package arrives on its own and avoids dependence on delayed pieces of data.
+
+- **UDP efficiency**: By running over UDP, QUIC bypasses decades of kernel-level constraints, enabling lightning-fast performance even on constrained devices such as smartphones, IoT hardware, or edge gateways.
+
+- **Security by default**: TLS 1.3 is built directly into the protocol. Every connection is encrypted — no exceptions, no downgrade paths.
+
+- **Seamless mobility**: Connections remain stable as devices move across networks (e.g., Wi-Fi → 4G/5G) or switch IP addresses, without breaking the session.
+
+- **Lower latency**: QUIC merges the transport and TLS handshake into fewer round-trips, significantly reducing connection setup time.
+
+- **Smarter congestion control**: Advanced congestion control algorithms (such as BBR) continuously measure bandwidth, round-trip time, and loss in real time. They dynamically adjust to real-world network conditions.
 
-## 📦 Installation
+
+QUIC combines **UDP speed, TCP reliability, mandatory TLS security, and adaptive multiplexing** into one powerful transport layer.
+
+**HTTP/3** (h3 in short) is the layer on top of QUIC. This is the evolution of the web’s application layer. Instead of riding over TCP, HTTP/3 maps HTTP requests and responses directly onto QUIC streams.
+HTTP/3 is also himself dramatically reduces overhead and improves efficiency - thats bring faster page loads and real-time applications that scale across the modern web.
+
+
+
+## 🧠 Why QUICO?
+
+Node.js is the backbone of countless modern web applications, but it currently lacks a native QUIC implementation. Supporting QUIC inside Node.js requires **deep access to TLS internals** that Node's existing TLS APIs don't expose. Beyond that, QUIC demands a **highly complex architecture** — intricate state machines, packet schedulers, and congestion control mechanisms.
+
+**QUICO** brings this missing capability directly into the **Node.js ecosystem**. It is a from-scratch JavaScript implementation of QUIC, HTTP/3 and WebTransport, built without relying on OpenSSL or native code. At its core, it uses [LemonTLS](https://github.com/colocohen/lemon-tls) — a pure JavaScript TLS 1.3 library built by the same author — to provide the cryptographic layer that QUIC requires. Together, QUICO and LemonTLS form a complete, fully auditable JavaScript networking stack from UDP to HTTP/3.
+
+**What this means for you:**
+
+- **`npm install` and go** — no build tools, no platform-specific binaries, no gyp
+- **Works everywhere Node.js runs** — Linux, macOS, Windows, ARM, Docker, edge
+- **Debuggable top to bottom** — every packet, every frame, every byte is JavaScript you can step through
+
+
+## 📦 Quick Start
 
 ```bash
 npm install quico
 ```
 
-## 🏃 Quick start
+### Server
+
+```js
+import quico from 'quico';
+import fs from 'node:fs';
+
+const server = quico.createServer({
+  key: fs.readFileSync('server.key'),
+  cert: fs.readFileSync('server.crt')
+}, (req, res) => {
+  res.writeHead(200, { 'content-type': 'text/plain' });
+  res.end('Hello from HTTP/3!');
+});
+
+server.listen(4433, () => {
+  console.log('HTTP/3 server on https://localhost:4433');
+});
+```
+
+### Client
+
+```js
+import quico from 'quico';
 
-### Step 1: Generate a self-signed certificate
+quico.request('https://www.google.com/', (res) => {
+  console.log('Status:', res.statusCode);       // 200
+  console.log('Protocol:', res.httpVersion);     // "3.0"
+  res.on('data', (chunk) => process.stdout.write(chunk));
+});
+```
 
-To test QUICO locally, you’ll need a TLS certificate.  
-Generate one using OpenSSL:
+> 📂 For more examples, see [`examples/`](./examples)
 
-```bash
-mkdir certs
-openssl req -x509 -newkey rsa:2048 -nodes -keyout certs/localhost.key -out certs/localhost.crt -days 365
+
+## ✨ Features
+
+### HTTP/3 Server & Client
+- Full request/response cycle over QUIC
+- QPACK header compression with static and dynamic tables
+- Standard Node.js API: `req.headers`, `res.writeHead()`, `res.end()`
+- Multiple requests per connection (stream multiplexing)
+- Automatic `Alt-Svc` header for HTTP/3 protocol discovery
+- H3 → H2 → H1 fallback when QUIC isn't available
+- Tested against Google, Cloudflare, Facebook, Microsoft and nginx QUIC servers
+
+### WebTransport
+- Client and server implementation
+- Bidirectional and unidirectional streams (Node.js Duplex + WHATWG Streams API)
+- Unreliable datagrams (RFC 9297)
+- Natural API: `req.on('stream')`, `res.sendDatagram()`, `res.writeHead(200)` to accept
+
+### QUIC Transport
+- Full TLS 1.3 handshake via LemonTLS (no OpenSSL)
+- Initial, Handshake, and 1-RTT packet handling
+- Connection ID management
+- ACK processing and flow control
+- Key updates (key phase bit rotation)
+- HelloRetryRequest support (P-256, P-384, X25519)
+- AES-128-GCM and AES-256-GCM cipher suites
+- Handshake timeout
+
+
+## 🔗 Node.js API Compatibility
+
+One of the core design goals of QUICO is to provide a **familiar API**. If you already know `node:https`, working with QUICO should feel natural — `createServer`, `request`, `req`, `res` all work the same way.
+
+This means existing frameworks work out of the box:
+
+```js
+import express from 'express';
+import quico from 'quico';
+
+const app = express();
+app.get('/', (req, res) => res.json({ protocol: req.httpVersion }));
+
+quico.createServer({ key: KEY, cert: CERT }, app).listen(4433);
+// → { "protocol": "3.0" }
 ```
 
-### Step 2: Create a basic HTTP/3 server
+For multi-domain setups, QUICO supports `SNICallback` just like `node:https`:
 
 ```js
-const fs = require('fs');
-const quico = require('quico');
+import quico from 'quico';
+import tls from 'lemon-tls';
 
 const server = quico.createServer({
   SNICallback: function (servername, cb) {
-    cb(null, {
-      key: fs.readFileSync('certs/localhost.key'),
-      cert: fs.readFileSync('certs/localhost.crt')
-    });
+    cb(null, tls.createSecureContext({
+      key: fs.readFileSync('certs/' + servername + '.key'),
+      cert: fs.readFileSync('certs/' + servername + '.crt')
+    }));
   }
-}, function (req, res) {
-  const data = new TextEncoder().encode('Hello World from HTTP/3 on Node.js!');
-  res.writeHead(200, {
-    'Content-Type': 'text/html; charset=utf-8',
-    'Content-Length': data.byteLength
-  });
-  res.end(data);
+}, (req, res) => {
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+  res.end('Hello World from HTTP/3 on Node.js!');
 });
 
-server.listen(4433, function () {
+server.listen(4433, () => {
   console.log('🚀 QUIC server running on https://localhost:4433');
 });
 ```
 
-> ✅ You must launch Chrome with `--enable-quic` and `--origin-to-force-quic-on=localhost:4433`  
-> 📂 For more examples, see [`examples/`](./examples)
 
-## 🛣 Roadmap
+## 🚀 WebTransport
 
-The following roadmap reflects the current and planned status of the QUICO project.  
-✅ = Completed 🔄 = In progress ⏳ = Planned ❌ = Not planned
+### Server
 
-### ✅ Completed
-| Status | Item |
-|:------:|------|
-| ✅ | QUIC: Initial / Handshake / 1-RTT |
-| ✅ | TLS 1.3 handshake & key schedule |
-| ✅ | HTTP/3: control streams & basic requests |
-| ✅ | QPACK: static & dynamic table |
+```js
+import quico from 'quico';
+
+quico.createServer({ key: KEY, cert: CERT }, (req, res) => {
+  if (req.headers[':protocol'] === 'webtransport') {
+    // Accept the WebTransport session
+    res.writeHead(200);
+
+    // Bidirectional streams from the client
+    req.on('stream', (stream) => {
+      stream.on('data', (chunk) => {
+        stream.write(chunk); // echo back
+      });
+      stream.on('end', () => stream.end());
+    });
+
+    // Unreliable datagrams
+    req.on('datagram', (data) => {
+      res.sendDatagram(data); // echo back
+    });
+
+    // Server can also create streams
+    const push = res.createBidirectionalStream();
+    push.write('server says hello');
+    push.end();
+  } else {
+    // Regular HTTP/3 request
+    res.end('Hello HTTP/3!');
+  }
+}).listen(4433);
+```
+
+### Client (Node.js)
+
+```js
+import { WebTransport } from 'quico';
+
+const wt = new WebTransport('https://localhost:4433/echo');
+await wt.ready;
+
+// Bidirectional stream
+const stream = await wt.createBidirectionalStream();
+stream.write('hello');
+stream.on('data', (chunk) => console.log('echo:', chunk.toString()));
+stream.end();
+
+// Unidirectional stream
+const uni = await wt.createUnidirectionalStream();
+uni.write('fire and forget');
+uni.end();
+
+// Datagrams (unreliable)
+wt.sendDatagram(Buffer.from('ping'));
+wt.on('datagram', (data) => console.log('pong:', data.toString()));
+
+wt.close();
+```
+
+### Client (Browser)
+
+```js
+const wt = new WebTransport('https://yourserver.com:4433/live');
+await wt.ready;
+
+// Send via WHATWG Streams API
+const writer = wt.datagrams.writable.getWriter();
+await writer.write(new TextEncoder().encode('Hello QUIC'));
+
+// Receive
+const reader = wt.datagrams.readable.getReader();
+const { value } = await reader.read();
+console.log('Received:', new TextDecoder().decode(value));
+```
+
+
+## 🧪 Testing
+
+QUIC requires TLS 1.3. Self-signed RSA certificates usually fail with QUIC clients and browsers. For local development, [mkcert](https://github.com/FiloSottile/mkcert) is the easiest option — it generates locally-trusted ECDSA certificates automatically.
+
+This project supports ALPN `"h3"` only (not draft variants like `h3-29`). You must explicitly force h3 when testing with Chrome.
+
+**Chrome:**
+```bash
+chrome --enable-quic --quic-version=h3 --ignore-certificate-errors --origin-to-force-quic-on=localhost:4433
+```
+
+**curl:**
+```bash
+curl --http3 https://localhost:4433 --insecure
+```
+
+**Integration tests:**
+```bash
+node examples/test_integration.js          # HTTP/3 client + server — 19 tests
+node examples/test_wt_server.js            # WebTransport server echo (QUICO ↔ QUICO)
+node examples/test_webtransport.js URL     # WebTransport client against any server
+```
+
+
+## 📁 Project Structure
+
+```
+quico/
+├── index.js               — Public API exports
+└── src/
+    ├── server.js            — Unified server (drop-in for node:https)
+    ├── client.js            — Unified client with H3 → H2 → H1 fallback
+    ├── agent.js             — Connection pooling and Alt-Svc protocol cache
+    ├── streams.js           — IncomingMessage, ServerResponse, ClientRequest
+    ├── h3.js                — HTTP/3 framing, QPACK, WebTransport detection
+    ├── h3_server.js         — HTTP/3 + WebTransport server
+    ├── h3_client.js         — HTTP/3 client (DNS, UDP, QUIC, H3 pipeline)
+    ├── quic_connection.js   — QUIC state machine, burst scheduler, flow control
+    ├── transport.js         — Packet parsing, frame encoding/decoding
+    ├── crypto.js            — AEAD encryption, header protection, key derivation
+    ├── tls_bridge.js        — LemonTLS integration, transport parameters
+    └── webtransport.js      — WebTransport client + stream classes
+```
+
+
+## 🛣 Roadmap
+
+### ✅ Done
+- QUIC v1 transport (RFC 9000) — Initial, Handshake, 1-RTT
+- TLS 1.3 via LemonTLS — X25519, P-256, P-384, AES-128/256-GCM
+- HTTP/3 server and client (RFC 9114)
+- QPACK header compression with static and dynamic tables (RFC 9204)
+- WebTransport client and server — bidi/uni streams + datagrams (RFC 9297)
+- Node.js `https`-style API compatibility — `createServer`, `request`, `get`
+- Express / Fastify / Koa middleware support
+- Connection reuse and multiplexing
+- HelloRetryRequest — client and server
+- Key updates (key phase rotation)
+- Interop with Google, Cloudflare, Facebook, Microsoft, nginx
+- Handshake timeout
 
 ### 🔄 In Progress
-| Status | Item | Notes |
-|:------:|------|-------|
-| 🔄 | QPACK: Huffman encoding/decoding | Custom table support partially working |
-| 🔄 | WebTransport: unidirectional & bidirectional streams | Stream interface WIP |
-| 🔄 | HTTP/3: GOAWAY & request cancellation | Partial control flow support |
-| 🔄 | Integration with Node.js `https`-style API | Goal: seamless compatibility |
-| 🔄 | Project modularization & internal refactoring | To improve maintainability |
+- Loss detection and PTO timers (RFC 9002)
+- Congestion control (BBR / CUBIC)
+- 0-RTT and session resumption
+- Debug log cleanup (`QUICO_DEBUG` environment flag)
 
 ### ⏳ Planned
-| Status | Item | Notes |
-|:------:|------|-------|
-| ⏳ | QUIC: 0-RTT support | Will follow key update & early data support |
-| ⏳ | WebTransport: datagram support | Based on RFC 9298 |
-| ⏳ | QUIC: proper connection teardown | CLOSE frame, idle timeout |
-| ⏳ | QUIC: keep-alive & PING frames | For long-lived connections |
-| ⏳ | QUIC: flow control & congestion (BBR / CUBIC) | Needs metrics and simulation |
-| ⏳ | QUIC: session resumption & connection migration | For mobile/roaming support |
-| ⏳ | End-to-end test suite against Chromium | Automate using testh3 and Puppeteer |
-| ⏳ | Benchmarks, performance analysis & tuning | Resource usage, latency, throughput |
-| ⏳ | Fuzz testing and protocol robustness checks | To improve security and reliability |
-| ⏳ | Developer documentation & API reference | For better onboarding |
-| ⏳ | TypeScript typings | Type safety for IDE support |
-
-_Note: QUICO is a work-in-progress project aiming to provide a full JavaScript implementation of QUIC + HTTP/3. Community contributions are welcome!_
-
-_Please ⭐ star the repo to follow progress!_
+- Connection migration (PATH_CHALLENGE / PATH_RESPONSE)
+- ChaCha20-Poly1305 cipher suite (0x1303)
+- GOAWAY and graceful shutdown
+- Stream priority (RFC 9218)
+- TypeScript type definitions
+- Performance benchmarks
+- Fuzz testing
+
+_Community contributions are welcome! Please ⭐ star the repo to follow progress._
+
 
 ## 🙏 Sponsors
 
 QUICO is an evenings-and-weekends project.  
 Support development via **GitHub Sponsors** or simply share the project.
 
+
+
+## 💬 Contact
+
+For feedback, ideas, or contributions,  
+contact directly at:  
+📧 **support@quicojs.dev**
+
+For security-related issues, please see [SECURITY.md](./SECURITY.md).
+
+
+
 ## 📜 License
 
 **Apache License 2.0**

package/index.cjs

@@ -0,0 +1,45 @@
+/*
+ * quico — CommonJS entry point
+ *
+ * Since quico is ESM-only internally, CommonJS users
+ * must await .ready before calling any API:
+ *
+ *   const quico = require('quico');
+ *   await quico.ready;
+ *   const server = quico.createServer({ ... }, handler);
+ *
+ * Or in one step:
+ *
+ *   const quico = await require('quico').ready;
+ *   const server = quico.createServer({ ... }, handler);
+ */
+
+let _mod;
+
+const proxy = new Proxy({}, {
+  get(target, key) {
+    // .ready must be accessible before module loads
+    if (key === 'ready') return target.ready;
+    // Prevent Promise auto-unwrapping when proxy is returned from async
+    if (key === 'then') return undefined;
+    if (!_mod) throw new Error(
+      'quico: module not loaded yet. Use "const quico = await require(\'quico\').ready" first.'
+    );
+    return _mod[key];
+  }
+});
+
+// Kick off async ESM import — sets .ready on proxy target
+proxy.ready = import('./index.js').then(function (m) {
+  // Merge default export (createServer, request, etc.)
+  // with named exports (WebTransport, etc.)
+  _mod = Object.assign({}, m.default);
+  for (var key in m) {
+    if (key !== 'default' && key !== '__esModule') {
+      _mod[key] = m[key];
+    }
+  }
+  return proxy;
+});
+
+module.exports = proxy;

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 };