Headroom Rust透明代理：HTTP/1.1、HTTP/2、SSE与WebSocket全协议支持指南

Headroom Rust透明代理HTTP/1.1、HTTP/2、SSE与WebSocket全协议支持指南【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom如果你正在为 AI 编程代理寻找省 Token 的方案Headroom 是一个值得关注的开源项目它在工具输出、日志、文件与 RAG 分片进入 LLM 之前完成压缩JSON 类数据可省 60–95% Token编码代理场景省 15–20%且答案质量不变。而真正让它可以零代码改动接入的关键就是Rust 实现的透明反向代理它对 HTTP/1.1、HTTP/2、SSE 流式响应和 WebSocket 四种通信形态全协议支持端用户无感运维可平滑切换。本文带你快速看懂它的工作原理与部署要点。什么是透明代理模式为什么值得用Headroom 提供 4 种接入方式库compress(messages)、MCP 服务器、Agent 包装headroom wrap claude以及代理模式。代理模式是门槛最低的你的 Agent / 应用 ──HTTP/1.1、HTTP/2、SSE、WS──▶ Headroom Rust 代理 ──▶ LLM 提供商 (Claude Code、Cursor、Codex、LangChain…) (压缩 可观测) (Anthropic/OpenAI/Bedrock…)你只需把请求指向代理端口不改一行代码任意语言都适用。Rust 代理crates/headroom-proxy/基于axumreqwest构建默认监听0.0.0.0:8787把所有请求转发给--upstream指定的上游可以是 Python 代理也可以是 LLM 端点。它被设计为字节管道不压缩的请求原样通过缓存前缀字节不变避免破坏提供商的 KV 缓存。透明转发的工作原理字节级直通与智能拦截核心逻辑在 crates/headroom-proxy/src/proxy.rs 中HTTP/1.1 与 HTTP/2 双协议协商上游客户端同时开启http2特性通过 TLS 的 ALPN 自动协商客户端是 1.1 就按 1.1 走支持 HTTP/2 的服务端自动升级全程无感知路由分发健康检查/healthz、Prometheus 指标/metrics等保留路径被本地拦截/v1/messages、/v1/chat/completions、/v1/responses以及 Bedrock/Vertex 端点命中专属处理器其余路径全部落入 catch-all 转发器按需缓冲只有开启压缩、且是POST JSON 的 LLM 端点才缓冲请求体做压缩分析其他请求走纯流式转发不占内存Header 策略自动添加X-Forwarded-For/Proto、请求 ID可选重写Host头并剥离内部x-headroom-*头防止内部标记泄漏到上游。关键设计是无静默降级请求体超过缓冲上限时直接返回 413 并打结构化日志而不是悄悄截断。SSE 流式解析字节级状态机LLM 的流式输出走 SSEServer-Sent Events。Headroom 在 crates/headroom-proxy/src/sse/framing.rs 中实现了字节级分帧器配合三套提供商状态机状态机处理对象文件AnthropicStreamStatemessage_start/thinking_delta/signature_delta/citations_deltasse/anthropic.rsChunkStateChat Completions 分块、工具调用、[DONE]sse/openai_chat.rsResponseStateResponses API 乱序完成按 id 而非位置sse/openai_responses.rs它解决了 Python 时代几类经典 bugUTF-8 多字节字符被 TCP 分包截断按完整事件解码不按块解码、ping心跳与[DONE]哨兵处理、工具调用 id 被后续分块覆盖等。状态机与字节直通并行运行——客户端第一时间拿到原始字节遥测在旁路完成不阻塞流。官方用 10 万组随机字节的属性测试保证解析器永不 panic。WebSocket 双向泵升级检测与协议转换对于 WebSocket 流量如 Codex 的实时会话代理在 crates/headroom-proxy/src/websocket.rs 中实现catch-all 处理器检测Upgrade: websocketConnection: upgrade头命中后交给ws_handler自动把上游 URL 的 scheme 从http重写为ws或https→wss转发Authorization、Sec-WebSocket-Protocol等业务头完成子协议协商建立双向消息泵客户端帧与上游帧互相搬运直到任一端关闭并保留x-request-id关联日志。也就是说一个端口同时服务 REST 请求、SSE 长连接和 WebSocket 全双工通信无需额外网关。健康检查与优雅停机生产级可观测透明代理也必须是可靠的。crates/headroom-proxy/src/main.rs 提供了完整的运维能力双健康端点/healthz检查自身/healthz/upstream探测上游可达性方便编排系统做就绪门控Prometheus 指标/metrics暴露压缩比、缓存命中、透传字节完整性等计数器见 crates/headroom-proxy/src/observability/prometheus.rs优雅停机收到 SIGTERM/SIGINT 后停止接新请求等待在途流式请求排空默认 30s 超时再退出结构化日志全链路 JSON 日志 request_id贯穿便于排查。快速部署三步完成切换Rust 代理的完整运维手册见 RUST_DEV.md切换流程非常轻# 1. 构建并查看帮助 make build-proxy ./target/release/headroom-proxy --help # 2. 指向你的上游如现有 Python 代理在公开端口启动 ./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 # 3. 验证透传 curl -si http://127.0.0.1:8787/healthz curl -si http://127.0.0.1:8787/v1/models常用配置项环境变量可覆盖配置默认值说明--listen0.0.0.0:8787对外监听地址--upstream必填转发目标地址--upstream-timeout600s请求总超时为长流式预留--max-body-bytes100MB缓冲上限流式不受限--graceful-shutdown-timeout30s停机排空等待时间回滚同样简单停掉 Rust 代理、把上游服务重新绑回 8787 即可。部署后打开 Dashboard就能实时看到每个请求的 Token 节省总结一套代理四种协议全覆盖Headroom 的 Rust 透明代理把省 Token这件事做到了无感全协议HTTP/1.1、HTTP/2、SSE、WebSocket 一个端口通吃安全直通字节级透传保证缓存前缀稳定压缩路径带完整性告警生产可用健康检查、Prometheus 指标、优雅停机、结构化日志齐备渐进演进Bedrock SigV4 签名、Vertex ADC 令牌等原生云路由已在 crates/headroom-proxy/src/bedrock/ 与 crates/headroom-proxy/src/vertex/ 中落地。如果你希望在不改代码的前提下让编码代理立刻省 15–20% Tokenheadroom proxy --port 8787就是最快的上手路径。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考