GitHub - currentspace/http3

HTTP/3, HTTP/2, and raw QUIC server/client package for Node.js 24+, powered by Rust + quiche. Features

HTTP/3 server and client over QUIC/UDP HTTP/2 fallback over TLS/TCP on the same listener Raw QUIC: bidirectional streams, datagrams, session resumption, custom ALPN Explicit runtime selection: fast, portable, or auto Platform-native I/O: kqueue (macOS), io_uring (Linux fast path), poll (Linux portable path) fetch/SSE/EventSource adapters Express compatibility via @currentspace/http3/express

Install npm install @currentspace/http3 Prebuilt native binaries are currently published for Linux x64/arm64 (glibc) and macOS arm64. Other platforms may fall back to local native compilation; see docs/SUPPORT_MATRIX.md. Quick server example import { createSecureServer } from '@currentspace/http3';

const server = createSecureServer({ key: process.env.TLS_KEY_PEM, cert: process.env.TLS_CERT_PEM, }, (stream, headers) => { stream.respond({ ':status': '200', 'content-type': 'text/plain' }); stream.end(`hello ${String(headers[':path'] ?? '/')}`); });

server.listen(443, '0.0.0.0'); Quick client example import { connectAsync } from '@currentspace/http3';

const session = await connectAsync('example.com:443'); const stream = session.request({ ':method': 'GET', ':path': '/', ':authority': 'example.com', ':scheme': 'https', }, { endStream: true }); Runtime modes Every QUIC-capable API accepts:

runtimeMode: 'auto' | 'fast' | 'portable' fallbackPolicy: 'error' | 'warn-and-fallback' onRuntimeEvent(info)

Returned client sessions and server objects expose runtimeInfo, and auto fallback also emits a process warning with code WARN_HTTP3_RUNTIME_FALLBACK.

import { connectQuicAsync } from '@currentspace/http3';

const session = await connectQuicAsync('https://sfu:9080', { alpn: ['sfu-repl'], rejectUnauthorized: false, runtimeMode: 'auto', fallbackPolicy: 'warn-and-fallback', });

console.log(session.runtimeInfo); See docs/RUNTIME_MODES.md for the deployment matrix, capability requirements, Docker guidance, topology policy, and the raw endpoint contract. Client topology is now explicit in the implementation:

raw QUIC fast clients share one worker and one local UDP port per bind family H3 fast clients share one worker and one local UDP port per bind family macOS portable mode keeps the same shared client-worker ownership model on top of kqueue QUIC and H3 servers remain one-worker-per-port architectures

Use the built-in benchmarks to inspect both runtime selection and internal reactor counters: npm run bench:quic -- --profile smoke npm run bench:h3 -- --profile smoke New In 0.6.0

Raw QUIC clients can now use mTLS through the stable public cert and key options on connectQuic() and connectQuicAsync(). Raw QUIC servers now support explicit client certificate policy with clientAuth, defaulting to require when a verification ca is configured. Raw QUIC server sessions now expose the verified peer certificate so applications can inspect or pin exact client certificates with Node's X509Certificate API.

See CHANGELOG.md for the 0.6.0 release notes and docs/RELEASE_EVIDENCE.md for the supporting audit ledger and caveats behind this release. Quick QUIC server import { createQuicServer } from '@currentspace/http3';

const server = createQuicServer({ key: process.env.TLS_KEY_PEM, cert: process.env.

TLS_CERT_PEM, });

server.on('session', (session) => { session.on('stream', (stream) => { stream.pipe(stream); // echo }); });

await server.listen(4433, '0.0.0.0'); Quick QUIC client import { connectQuicAsync } from '@currentspace/http3';

const session = await connectQuicAsync('127.0.0.1:4433', { rejectUnauthorized: false, });

const stream = session.openStream(); stream.end(Buffer.from('hello QUIC'));

const chunks: Buffer[] = []; stream.on('data', (c) => chunks.push(c)); stream.on('end', () => console.log(Buffer.concat(chunks).toString())); Compatibility surfaces

@currentspace/http3 - canonical API. @currentspace/http3/parity - http2-style aliases for migrations. @currentspace/http3/h3 - HTTP/3-specific extension namespace.

Examples

Raw API example Express adapter example Hono serveFetch() example

Start Here

Quickstart Runtime modes and deployment matrix Support matrix Configuration options reference Error handling guide Changelog

Deployment and Operations

QUIC guide Production docs index HTTP/2 parity matrix ECS/Fargate deployment AWS NLB QUIC passthrough Session ticket keys across instances

Contributors and Maintainers

Test strategy Contributing guide Release evidence ledger Release runbook