robaho httpserver

本文档为中文版。英文使用文档见 README.en.md。 This README is in Chinese; see README.en.md for English.

零依赖的 JDK com.sun.net.httpserver.HttpServer 规范替代实现，专为 JDK 25 + 虚拟线程 设计。

• HTTP/1.1：完整实现，支持 keep-alive、pipelining、chunked、trailer
• HTTP/2：RFC 9113 合规（h2c + ALPN），含 HPACK Huffman 编解码、流控、多路复用
• WebSocket：基于 nanohttpd 修改的 RFC 6455 实现
• 代理：ProxyHandler 支持 HTTP 转发与 CONNECT 隧道
• 虚拟线程原生：默认执行器即虚拟线程，全链路无 monitor 锁（ReentrantLock/CAS），ScopedValue（JDK 25）
• 零依赖：仅 200KB jar，无任何第三方库

• 比 JDK 内置实现快 10 倍以上（TechEmpower 基准，同硬件同 JDK）
• 比 Jetty http2 快 3 倍、http1 快 5 倍（h2load 基准）
• 单机回环实测：h1 ~31k RPS、h2 多路复用 ~28k RPS、单流上传 ~110MB/s（8 核 macOS，小响应）
• h2 路径垃圾分配比优化前减少 73%（GC 停顿 4 倍减少）

<dependency>
  <groupId>io.github.robaho</groupId>
  <artifactId>httpserver</artifactId>
  <version>使用徽章中的版本号（去掉前缀 v）</version>
</dependency>

要求 JDK 25+。

JDK 会自动使用 robaho.net.httpserver.DefaultHttpServerProvider 替代内置实现（jar 在 classpath/module path 上即可）。如有多个 provider，用系统属性指定：

-Dcom.sun.net.httpserver.HttpServerProvider=robaho.net.httpserver.DefaultHttpServerProvider

也可以直接实例化：DefaultHttpServerProvider.java

import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.util.concurrent.Executors;

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpHandler;
import com.sun.net.httpserver.HttpServer;

public class Test {
    static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
        server.createContext("/", new MyHandler());
        // 虚拟线程执行器（默认已是虚拟线程，可省略）
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        server.start();
    }

    static class MyHandler implements HttpHandler {
        @Override
        public void handle(HttpExchange exchange) throws IOException {
            byte[] bytes = "This is the response".getBytes();
            var contentLength = bytes.length == 0 ? -1 : bytes.length;
            try (OutputStream os = exchange.getResponseBody()) {
                exchange.sendResponseHeaders(200, contentLength);
                os.write(bytes);
            }
        }
    }
}

用于基本测试（下载、echo、hello）：

mvn -q compile test-compile exec:java -Dexec.mainClass=SimpleFileServer -Dexec.classpathScope=test

静态文件响应走 extras.Sendfile，普通 h1 连接上由内核 FileChannel.transferTo 直通 socket——文件字节不经过用户态拷贝，handler 线程零参与：

// handler 内：
Sendfile.serve(exchange, path, "application/octet-stream");
// 或等价地：exchange.setAttribute(Sendfile.ATTRIBUTE, path) 后
// sendResponseHeaders(200, Files.size(path))，再 close 响应流

约束：声明的 Content-Length 必须等于文件大小（serve 自动计算）；声明后 handler 不得再写响应体。h2 与 TLS 连接自动回退为常规流式发送（h2 的 DATA 帧封装无法直通 socket），语义不变。

继承 WebSocketHandler 并注册端点：

HttpHandler h = new EchoWebSocketHandler();
HttpContext c = server.createContext("/ws", h);

更多示例见 websocket 测试目录。底层 API 来自 nanohttpd。

使用 Java System Logger。

设置 robaho.net.httpserver.EnableStats=true 后，/__stats 端点返回实时统计：

$ curl http://localhost:8080/__stats
Active Connections: 2049
Requests Since: 2669256
Requests/sec: 73719
Total Handler Exceptions: 0
...

"Since" 统计在每次拉取时重置，"Total" 统计累计。

以下参数均通过 JVM 系统属性（-D）设置，在服务器启动时一次性读取。

以下配方均在 8 核 macOS / JDK 25 / 本库 33k rps 负载下实测验证：

1. 紧凑对象头（分配密集场景，零代码）：

java -XX:+UseCompactObjectHeaders ...

本库每请求分配已压到 ~2KB，对象头 12B→8B 对小对象（String、ArrayList 节点）再省约 10% 脚印，等效减少 young GC 频率。测试套件默认在该模式下运行。

2. 闲时内存主动归还（长连接服务空闲时把内存还给系统）：

java -Xms64m -Xmx256m -XX:G1PeriodicGCInterval=30000 ...

默认配置下 JVM 闲置后不主动归还（Xms=Xmx 时 G1 永不 uncommit），物理内存回落依赖操作系统内核对冷页的异步压缩，实测需要约 5 分钟。开启周期 GC 后，实测闲置 ~30 秒即触发 G1 Periodic Collection（37M→8M，committed 收缩回 Xms 下限，RSS 从 123MB 降到 96MB）。适合跑在计费按 RSS、或与其他进程共址的容器里；吞吐负载下周期 GC 会被高分配率自然抑制，无副作用。

3. 分代 ZGC（停顿敏感部署的可选项）：

java -XX:+UseZGC -XX:+ZGenerational ...

实测与 G1 对比：吞吐 33.1k vs 33.4k rps（-0.6%）、p99 8.26ms 持平、服务端 CPU 持平、负载期零可测 GC 停顿（G1 为 0.7-5ms/次）。G1 默认停顿已足够小；仅在 P99 有硬性 SLA 且对亚毫秒停顿敏感时选 ZGC。

4. AOT 缓存（JDK 24+ Leyden，缩短冷启动，面向 CLI/短生命周期进程）：

# 1) 训练运行（classpath 必须全部是 JAR，非空目录会被 CDS 拒绝）：
java -XX:AOTMode=record -XX:AOTCacheOutput=app.aot -cp app.jar:... Main
# 2) 生成缓存：
java -XX:AOTMode=create -XX:AOTConfiguration=app.aot.config -XX:AOTCacheOutput=app.aot
# 3) 正式启动：
java -XX:AOTCache=app.aot -cp app.jar:... Main

训练进程需正常退出（System.exit）才会落盘 config；训练时带一轮真实流量可预热方法编译。实测本库示例服务冷启动 ~150ms → ~111ms（-25%）；应用类越多收益越大。

5. h1 密集 + 低连接数场景的平台线程模式（省 CPU 而非提吞吐）：

server.setExecutor(Executors.newCachedThreadPool(
    Thread.ofPlatform().name("conn-", 0).factory()));

实测 64/256/1024 连接下吞吐与虚拟线程持平（瓶颈在链路时延），但服务端 CPU 从 1.55 核降到 1.05 核（-32%——省去了 VT 调度器 + Read-Poller 唤醒机制，两者合计约 27% 执行采样 + 11% poller CPU）。注意：该执行器同时服务于 h2 流分发，h2 多路复用场景勿用（每流一个平台线程会毁掉多路复用）。连接数上万时回退虚拟线程（平台线程栈内存 ~16KB+ 栈预留 1MB/线程）。

HTTP/2 连接级发送窗口（服务端→客户端方向）初始为 65535 字节（协议默认），只能由客户端通过 WINDOW_UPDATE 增长，服务端无法代为扩大。大响应或多路复用下载场景下，客户端收满 64KB 后服务端写线程会等待窗口信用回流，吞吐受窗口往返次数限制（实测：默认窗口下 640KB 多路复用响应需约 10 次窗口往返）。

自研 h2 客户端若追求高吞吐，建议：

• 连接建立早期主动发送一次大的连接级 WINDOW_UPDATE（如 1~16MB），浏览器均如此
• 收到 DATA 后及时归还信用（收即还，而非攒到消息结束），避免服务端写线程等待
• 流级窗口同理，可通过 SETTINGS 帧通告更大的 INITIAL_WINDOW_SIZE

服务端侧对应的调优项为 http2InitialWindowSize（流级接收窗口，影响上传吞吐）与 http2ConnectionWindowSize（连接级接收窗口）。

• 几乎所有 JDK 原有测试均已包含（全部 TestNG 套件通过（当前 214 项，见 CI））
• 额外的代理、WebSocket、HTTP/2 合规测试
• HTTP/2 通过 h2spec 全部规范测试

• 异步迟到读取请求头返回空表：handler 从未调用 getRequestHeaders() 的交换，其请求头视图按需惰性物化；若应用代码在响应完成且连接已服务下一请求之后才首次读取该视图，得到的是空 Headers（而非 JDK 实现的过期快照）。任何时点在 handler 内正常读取（含异步 handler 在 doFilter 返回前获取引用）行为与 JDK 完全一致。此差异杜绝了跨请求头泄漏，是安全性取舍。