poseidon-http-client

快速上手

Mon, 01 Jan 0001 00:00:00 +0000

快速上手#

poseidon-http-client 是一个 Go 语言的底层 HTTP 客户端。它从零实现了 HTTP/1.1、HTTP/2 和 HTTP/3——自带帧编解码、HPACK、QPACK 和 QUIC 协议栈——不依赖 net/http，也不依赖任何第三方协议库。它面向压测工具和需要直接控制连接、流和流量控制的场景。

安装#

要求 Go 1.25 或更高版本。

go get github.com/lodgvideon/poseidon-http-client

请求模型#

三个协议版本共用同一套 API。先用构造函数创建客户端，再调用 Do，传入 context、请求对象，以及一个由调用方持有的 *client.Response：

c, err := client.NewSingleConnClient(addr, dialer) // or any constructor above
defer c.Close()
resp := &client.Response{} // caller-owned, reusable
err = c.Do(ctx, client.GET("/path"), resp) // resp.Status, resp.Body
resp.Reset() // reuse for the next request

与 net/http 有两处不同：

响应对象由调用方持有。 你只分配一个 client.Response，传给 Do，读取 resp.Status（int）和 resp.Body（[]byte），然后调用 resp.Reset() 供下一次请求复用。每次调用不会分配新的响应对象——在请求循环中，一个 Response 可以贯穿所有迭代。
请求是值，不是指向传输层的指针。 client.GET(path) 构造一个 GET 请求。需要完全控制时，直接构造 client.Request{Method, Scheme, Authority, Path, BodyMode}。

第一个 HTTP/2 请求#

下面是仓库中的 examples/http2/main.go，原样未改。它向一个公开的 HTTP/2 端点发起一次 GET：

HTTP/1.1

Mon, 01 Jan 0001 00:00:00 +0000

HTTP/1.1#

当目标服务器不支持 HTTP/2，或者你想专门测试它的 HTTP/1.1 路径、必须阻止 ALPN 协商把连接升级到 h2 时，使用 HTTP/1.1。

HTTP/1.1 拥有与 HTTP/2、HTTP/3 相同的一套构造函数：

构造函数	Transport	形态
`NewH1Client(addr, dialer, opts...)`	`TransportH1SingleConn`	一条连接，自动重拨。请求串行执行。
`NewH1PoolClient(addr, dialer, pool, opts...)`	`TransportH1Pool`	最多 `MaxConnsPerHost` 条连接。这个数字就是请求并发度。
`NewManagedH1Client(resolver, dialer, opts...)`	`TransportH1Managed`	Resolver + Selector 服务发现；按地址各建一个 HTTP/1.1 子连接池分摊请求。

强制使用 HTTP/1.1#

固定协议需要两点：

一个 HTTP/1.1 transport——上表中的任一构造函数，或在 client.ClientOptions 中设置对应的 Transport 值。
一个不提供 h2 的 dialer：纯 TCP dialer （&conn.PlaintextDialer{}），或 NextProtos 只提供 "http/1.1" 的 TLS dialer，这样服务器在握手时无法选中 h2。

// Command http1-example issues a single HTTP/1.1 request with the poseidon
// client. HTTP/1.1 is reached by pinning the transport to TransportH1SingleConn
// and offering only the "http/1.1" ALPN token, so the connection never upgrades
// to HTTP/2.
//
//	go run ./examples/http1
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"time"

	"github.com/lodgvideon/poseidon-http-client/client"
	"github.com/lodgvideon/poseidon-http-client/conn"
)

func main() {
	c, err := client.NewClient(client.ClientOptions{
		Addr: "example.com:443",
		Transport: client.TransportH1SingleConn,
		ConnOpts: conn.ConnOptions{
			// Offer only http/1.1 so the server cannot select h2.
			Dialer: &conn.TLSDialer{Config: &tls.Config{
				ServerName: "example.com",
				NextProtos: []string{"http/1.1"},
			}},
		},
	})
	if err != nil {
		log.Fatalf("build client: %v", err)
	}
	defer func() { _ = c.Close() }()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	resp := &client.Response{}
	if err := c.Do(ctx, client.GET("/"), resp); err != nil {
		log.Fatalf("GET /: %v", err)
	}
	fmt.Printf("HTTP/1.1 %d — %d bytes\n", resp.Status, len(resp.Body))
}

client.NewH1Client(addr, dialer) 一行调用即可构建同样的单连接客户端。请求 API 与 HTTP/2、HTTP/3 使用的 Do / client.GET / client.Response 完全相同。因此在不同协议版本之间切换测试目标，只需换一个构造函数，不用重写代码。

HTTP/2

Mon, 01 Jan 0001 00:00:00 +0000

HTTP/2#

HTTP/2 客户端从零实现 RFC 7540 与 HPACK（RFC 7541）——不依赖 net/http，也不依赖 golang.org/x/net/http2。三个构造函数覆盖常见的连接拓扑：单连接、按主机的连接池、由 resolver 驱动的多后端。三者返回的都是 *client.Client，共用同一套 Do / DoStream API。

单连接#

client.NewSingleConnClient 持有一条连接，断开后自动重拨。以下是 examples/http2/main.go：

// Command http2-example issues a single HTTP/2 GET with the poseidon client.
// TransportSingleConn (the default) negotiates h2 over TLS and reuses one
// connection with automatic redial.
//
//	go run ./examples/http2
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"time"

	"github.com/lodgvideon/poseidon-http-client/client"
	"github.com/lodgvideon/poseidon-http-client/conn"
)

func main() {
	c, err := client.NewSingleConnClient(
		"www.cloudflare.com:443",
		&conn.TLSDialer{Config: &tls.Config{
			ServerName: "www.cloudflare.com",
			NextProtos: []string{"h2"},
		}},
	)
	if err != nil {
		log.Fatalf("build client: %v", err)
	}
	defer func() { _ = c.Close() }()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Response is caller-owned and reusable; Reset() clears it between requests.
	resp := &client.Response{}
	if err := c.Do(ctx, client.GET("/"), resp); err != nil {
		log.Fatalf("GET /: %v", err)
	}
	fmt.Printf("HTTP/2 %d — %d bytes\n", resp.Status, len(resp.Body))
}

Response 由调用方持有：分配一次，请求之间调用 resp.Reset() 复用。client.GET(path) 是简写；需要完全控制时直接构造 client.Request{Method, Scheme, Authority, Path, BodyMode}。

HTTP/3

Mon, 01 Jan 0001 00:00:00 +0000

HTTP/3#

HTTP/3 客户端（RFC 9114）运行在本仓库自行实现的 QUIC 协议栈（RFC 9000/9001/9002）和 QPACK 编解码器（RFC 9204）之上——不依赖 quic-go，不使用 cgo。只有 TLS 1.3 握手本身来自标准库 crypto/tls；数据包保护、丢包恢复、拥塞控制和流量控制均为 poseidon 自己的代码。

请求 API 与 HTTP/2 完全相同，仍是 Do / DoStream。client.Request 和 client.Response 在不同传输层之间没有任何区别；把一个压测从 H2 切换到 H3，只需换一个构造函数。

示例#

examples/http3/main.go：

// Command http3-example issues a single HTTP/3 GET over QUIC with the poseidon
// client, and shows how to opt into BBR congestion control.
//
//	go run ./examples/http3
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"time"

	"github.com/lodgvideon/poseidon-http-client/client"
	"github.com/lodgvideon/poseidon-http-client/quic"
)

func main() {
	// The simple path: one QUIC connection, buffered response.
	//
	//	c, err := client.NewH3Client("www.cloudflare.com:443",
	//	 &tls.Config{ServerName: "www.cloudflare.com"})
	//
	// Below uses NewClient so we can also select BBR congestion control.
	c, err := client.NewClient(client.ClientOptions{
		Addr: "www.cloudflare.com:443",
		Transport: client.TransportH3,
		TLSConfig: &tls.Config{ServerName: "www.cloudflare.com"},
		H3ConnOptions: []quic.ConnOption{
			quic.WithCongestionControl(quic.CCBBR), // default is NewReno
		},
	})
	if err != nil {
		log.Fatalf("build client: %v", err)
	}
	defer func() { _ = c.Close() }()

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	resp := &client.Response{}
	if err := c.Do(ctx, client.GET("/"), resp); err != nil {
		log.Fatalf("GET /: %v", err)
	}
	fmt.Printf("HTTP/3 %d — %d bytes\n", resp.Status, len(resp.Body))
}

构造函数#

三个构造函数，与 HTTP/2 的一一对应：

功能与优势

Mon, 01 Jan 0001 00:00:00 +0000

功能与优势#

支持矩阵#

三个协议版本共用同一套请求 API：client.Do / client.DoStream，配合由调用方持有、可复用的 client.Response。压缩能力同样共享：响应端对 gzip、deflate、br、zstd 四种编码都能解码（客户端通告 accept-encoding: gzip, deflate, br, zstd），请求端可用 Request.CompressBody 压缩请求体 —— 见下文压缩。不同之处在于各传输层暴露了多少协议能力。

协议	实现	构造函数	单连接并发请求	连接池	服务发现	主要能力
HTTP/1.1	从零实现	`NewH1Client`、`NewH1PoolClient`、`NewManagedH1Client`	否 —— 每条连接同一时刻只承载一个交换（无 pipelining）	`NewH1PoolClient`（独占借出式连接池：`MaxConnsPerHost` 即请求并发数）	`NewManagedH1Client`（Resolver + Selector）	Keep-alive 连接复用；请求体可流式发送（`Request.BodyReader`，长度未知时用 chunked），但响应总是缓冲进 `Response.Body` —— `DoStream` 和 `BodyStream` 返回错误；作为 ALPN 回退目标：服务端不提供 h2 时，`TransportALPN` 自动选择 HTTP/1.1
HTTP/2	RFC 7540 + HPACK（RFC 7541），从零实现	`NewSingleConnClient`、`NewPoolClient`、`NewManagedClient`	是 —— 流多路复用，受 `MAX_CONCURRENT_STREAMS` 限制	`NewPoolClient`（按主机建池、选取负载最低的流、空闲连接回收）	`NewManagedClient`（Resolver + Selector）	`DoStream` 与请求 trailer；流量控制；动态 SETTINGS；GOAWAY 排空；PING 保活；服务端推送（PUSH_PROMISE）；请求优先级；扩展 CONNECT（RFC 8441，基于 H2 的 WebSocket）；CONTINUATION；HTTP CONNECT 代理拨号器；h2c prior knowledge
HTTP/3	RFC 9114 + QUIC（RFC 9000/9001/9002）+ QPACK（RFC 9204），从零实现	`NewH3Client`、`NewH3PoolClient`、`NewManagedH3Client`	是 —— 单条 QUIC 连接上并发在途请求	`NewH3PoolClient`（多连接池）	`NewManagedH3Client`	`DoStream`；双向动态 QPACK（编码 + 解码）；全部 TLS 1.3 AEAD（AES-128-GCM、AES-256-GCM、ChaCha20-Poly1305）；拥塞控制默认 NewReno，可选启用 BBR；Linux 上支持 GSO 批量发送、GRO 批量接收、有界 ACK 合并

HTTP/1.1 与另外两个协议版本拥有同样的构造函数组合，但它的连接池在性质上不同。HTTP/1.1 没有多路复用：单条连接意味着请求严格串行，所以没有连接池时客户端根本无法产生 HTTP/1.1 负载。连接池以独占借出的方式分发连接 —— 每条连接同一时刻只承载一个交换 —— 因此 MaxConnsPerHost 就是请求并发数；MaxStreamsPerConn 不适用。请求发现所有连接都在忙时，会等待其中一条空出，等待受请求 context 约束。连接保持存活并被复用；遇到 Connection: close、连接失效或交换出错时，该连接被丢弃并重新拨号。Pipelining 是有意不实现的。拨号器不得提供 h2 ALPN 令牌 —— 使用纯 TCP 拨号器，或 NextProtos 只含 "http/1.1" 的 TLS 拨号器。

免责声明

Mon, 01 Jan 0001 00:00:00 +0000

免责声明#

poseidon-http-client 是一个年轻的项目，这是它的首个正式版本。在依赖它之前，请先读完本页。

无担保#

本库以 MIT 许可证发布，按现状（as is）提供，不附带任何形式的担保。使用风险由你自行承担。具体条款见 LICENSE 文件。

安全敏感代码，未经第三方审计#

本库从零实现了多个安全敏感协议：QUIC 传输层（RFC 9000/9001/9002）、QUIC 的 TLS 1.3 记录保护、HPACK（RFC 7541）以及 QPACK（RFC 9204）。这些路径均不复用 net/http、quic-go 或任何其他成熟的协议实现。

已经做了什么：

约 200 个按 RFC 章节对应的一致性测试，在 CI 中强制执行。
对线路格式解析器进行了模糊测试（fuzzing）。
与三个相互独立的 HTTP/3 服务端实现（Caddy/quic-go、nginx、aioquic）在真实 UDP 上完成了互操作验证。
完整测试套件在 Go 竞态检测器（race detector）下运行。

没有做什么：正式的第三方安全审计。测试与模糊测试能降低缺陷率，但无法证明一个从零实现的协议栈不存在漏洞。

用于生产环境之前#

不要把本库当作 net/http 在安全关键系统中的直接替代品。如果你的部署需要面对不受信任的对端、处理敏感数据，或在其他方面属于安全关键场景，请在采用之前自行审查你所依赖的代码路径——或者等项目积累更多生产环境使用记录之后再考虑。

如果用于对你自己掌控的基础设施做负载生成、测试和工具开发，风险要低得多。这正是本库设计的主要使用场景。

报告安全漏洞#

如果你发现安全问题，请按 SECURITY.md 中的说明私下报告。不要为安全漏洞开公开的 GitHub issue。