@currentspace / http3

针对Node.js 24+的HTTP/3、HTTP/2和原始QUIC服务器/客户端包，由Rust + quache提供支持。

功能

• HTTP/3服务器和客户端通过QUIC/UDP
• HTTP/2在同一侦听器上通过TLS/TCP回退
• 原始QUIC：双向流，数据报，会话恢复，自定义ALPN
• 运行时选择: auto， fast， portable，或者 wasm
• 平台原生I/O: kqueue (macOS), io_uring （Linux快速路径）， poll （Linux可移植路径）
• WASM运行时(runtimeMode: 'wasm')用于HTTP/3和原始QUIC客户端，加上a 仅节点WASM服务器-没有本机 .node 需要插件，并确认 在真正的Cloudflare workerd中运行
• 获取/ SSE EventSource适配器
• 通过表达兼容性 @currentspace/http3/express

安装

npm install @currentspace/http3

版本 1.0.0 增加了自动WASM回退，有限制的大写入，外观 运行时元数据，以及Linux和Intel macOS的本机包。早些时候 当本地插件不可用时，安装需要显式WASM。

保持可选的依赖项为本机性能启用。如果是本地插件 不能加载，默认值 auto 模式选择绑定的WASM运行时并发出 WARN_HTTP3_RUNTIME_FALLBACK． 根包包含JavaScript、声明、 WASM和CLI；它不捆绑本机二进制文件、文档或示例。

所有六个本机目标都使用匹配的1.0.0 sidecars。没有安装时间 编译器回退。看到 docs/SUPPORT_MATRIX.md.

快速服务器示例

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({ port: 443 }); // Dual-stack ::, all interfaces.

地方发展

在0.9.7 +, npx @currentspace/http3 dev-cert --out .certs --trust 创建一个约束 localhost CA，显式安装本地信任，并颁发证书。从一个 构建的源代码检出使用 node bin/http3.cjs dev-cert --out .certs --trust. 使用 key.pem/cert.pem 在服务器上设置 NODE_EXTRA_CA_CERTS=/absolute/path/.certs/ca.pem 启动Node客户端之前. 此库的本机/WASM客户端需要一个显式的 ca 选项。

Chrome还需要 --origin-to-force-quic-on=localhost:1 用于本地可信QUIC。 未使用的端口启用local-root异常；应用程序仍然 通过Alt-Svc协商H3。监听器默认为双堆栈 :: (所有 接口)，所以localhost工作在IPv4和IPv6上。看到 本地发展指南 要删除信任，请使用服务器 配置、浏览器启动命令和仅环回绑定。

快速客户端示例

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

流式传输和取消

H3请求和响应主体在本机和 WASM运行时。暂停一个读者最终会给对方带来反压力；其他流 在连接上可以继续。QUIC接收窗口和传输队列是 与Node的可读高水位标志分开。

使用 pipeline() 或者等待 drain 当 write() 返回 false． 写 回调, drain, finish 描述本地写许可，而不是收据或 对等体的确认。销毁未完成的客户端流将取消它 远程并拒绝挂起的写；正常的双工完成不会重置它。

运行时模式

每个支持quic的API都接受：

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

返回的客户端会话和服务器对象公开 runtimeInfo, auto 回退还会发出带有代码的进程警告 WARN_HTTP3_RUNTIME_FALLBACK. 返回的Node facade createNodeServerFactory.

auto 更喜欢原生的，保留Linux fast → portable 回退时 Io_uring不可用。如果绑定本身无法加载， auto 与 默认的 warn-and-fallback 策略在构造原生状态之前选择WASM。 该警告标识操作系统、体系结构、Linux libc和加载程序失败。 runtimeInfo.reasonCode 是 native-binding-unavailable 对于这种情况。 显式的 fast/portable，或者 auto 与 fallbackPolicy: 'error'，而不是失败 与 ERR_HTTP3_RUNTIME_UNSUPPORTED． 显式WASM从不探测本机加载。

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

看到 docs/RUNTIME_MODES.md 对于部署矩阵， 功能需求、Docker指南、拓扑策略和原始端点 合同。

客户端拓扑现在在实现中是显式的：

• 原始QUIC快速客户端每个绑定族共享一个worker和一个本地UDP端口
• H3快速客户端每个绑定族共享一个worker和一个本地UDP端口
• macOS可移植模式保持相同的共享客户机-worker所有权模型 最高的 kqueue
• QUIC和H3服务器仍然是每个端口一个工作人员的架构

使用内置基准测试来检查运行时选择和内部选择 反应堆计数器:

npm run bench:quic -- --profile smoke
npm run bench:h3 -- --profile smoke

WASM运行时

runtimeMode: 'wasm' 运行HTTP/3和原始QUIC客户端和Node服务器 wasm32-wasip1 构建相同的quiche + BoringSSL协议核心，没有 本地的 .node 插件:

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

const session = await connectAsync('example.com:443', { runtimeMode: 'wasm' });

大节点流写入，包括 res.end(buffer)，在限定范围内被允许 WASM下的切片。继续尊重可写反压；并发工作 仍然共享有限的WASM堆。本机写入保留其现有路径。

消费者测量2026-10-30，在macOS arm64 / Node 26.13上使用0.9.9 使用本机客户机，在WASM下发现大约5,060-5,270个请求/s 10,500-12,300本机可移植，用于并发50的1,000个小型get。流 32 MiB的下载速度为91-93 MiB/s，而不是836-933 MiB/s。这些描述了那些 其他主机上的工作负载，而不是性能保证。使用本机包 throughput-sensitive部署;WASM保持开发和较小的工作负载 无需插件即可使用。

服务器端(Http3SecureServer.listen() / QuicServer.listen())也 支持 runtimeMode: 'wasm',节点只。客户端构建另外有 已在真正的Cloudflare workerd中运行验证-参见 examples/workerd-client;唯一的 真正的workerd部署的剩余障碍是Workers没有出站 UDP客户端套接字APIcloudflare / workerd # 4463）。

看到 docs/WASM_RUNTIME.md 获取完整的使用指南 和当前Node/workerd支持矩阵 docs/WASM_CLIENT_PLAN.md 对于设计。

原始快速mTLS

• 原始QUIC客户端可以通过稳定的公开使用mTLS cert 和 key 选项 connectQuic() 和 connectQuicAsync().
• 原始QUIC服务器支持显式客户端证书策略 clientAuth，默认为 require 当一个验证 ca 配置。
• 原始的QUIC服务器会话公开经过验证的对等证书，因此应用程序可以检查或使用Node的精确客户端证书 X509Certificate API。

看到 CHANGELOG.md 查阅发行说明及 docs/RELEASE_EVIDENCE.md 对于当前 发布审计分类账和注意事项。

快速快速服务器

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');

快速客户端

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()));

兼容性的表面

实验 节点风格的服务器工厂,介绍了 在0.9.4中，支持fasttify集成。版本0.9.5添加了兼容性修复 由 js自定义服务器示例.

• @currentspace/http3 -规范API。
• @currentspace/http3/parity -用于迁移的http2风格别名。
• @currentspace/http3/h3 —HTTP/3扩展命名空间。

包根也导出 createNodeServerFactory 和 createExpressHandler． 子路径声明使用 typesVersions 对于遗留 打印稿 moduleResolution: "node";现代Node16/NodeNext/捆绑器解析 继续使用 exports． 不需要环境模块声明。

从0.9.7开始，本机和WASM H3请求体是流控制的：缓慢的或 暂停处理程序保留客户端。一个4 MiB的上传可以通过慢速流 具有默认值的处理程序 maxBufferedRequestBytes: 1024 * 1024 (1 MiB)。 此选项限制传输流中缓冲的未读字节，包括数据 阅读暂停时已经在飞行；这不是一个总的上传大小限制。 超过上限会重置流，但大型流上传通常不会 需要更高的值。框架车身尺寸限制仍然适用。看到 请求缓冲.

示例

• 原始API示例
• 快速适配器示例
• Hono serveFetch() 例子
• Next.js自定义服务器与HTTP/3和快速刷新
• 基于HTTP/3的netjs
• Next.js和NestJS与Express在一个进程中 (0.9.6 +)

从这里开始

• 快速入门
• 运行时模式和部署矩阵
• WASM运行时指南
• 支持矩阵
• 配置选项参考
• 错误处理指南
• 更新日志

部署与操作

• QUIC指南
• 生产文档索引
• HTTP/2奇偶矩阵
• ECS / Fargate部署
• AWS NLB QUIC直通
• 跨实例的会话票证密钥

贡献者和维护者

• 测试策略
• 贡献指南
• 发放证据分类账
• 释放runbook