ドキュメント on 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

リクエストモデル#

3 つのプロトコルバージョンはすべて同じ API を共有します。コンストラクタでクライアントを作り、context・リクエスト・呼び出し側が所有する *client.Response を渡して Do を呼びます。

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 と異なる点は 2 つあります。

レスポンスは呼び出し側が所有します。 client.Response を 1 つ確保して Do に渡し、resp.Status（int）と resp.Body（[]byte）を読んだら、resp.Reset() を呼んで次のリクエストで再利用します。呼び出しごとにレスポンスオブジェクトが確保されることはなく、リクエストループでは 1 つの Response を全イテレーションで使い回せます。
リクエストは値であり、トランスポート内部へのポインタではありません。 client.GET(path) で GET リクエストを組み立てられます。細かく制御したい場合は client.Request{Method, Scheme, Authority, Path, BodyMode} を直接構築してください。

HTTP/2 での最初のリクエスト#

以下はリポジトリの examples/http2/main.go そのままです。公開されている HTTP/2 エンドポイントに GET を 1 回発行します。

HTTP/1.1

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

HTTP/1.1#

対象サーバーが HTTP/2 に対応していない場合、あるいはサーバーの HTTP/1.1 経路を狙って試験したい場合に HTTP/1.1 を使います。後者では、ALPN ネゴシエーションによって接続が h2 に格上げされるのを防ぐ必要があります。

HTTP/1.1 には HTTP/2・HTTP/3 と同じコンストラクタ群があります。

コンストラクタ	トランスポート	形態
`NewH1Client(addr, dialer, opts...)`	`TransportH1SingleConn`	接続 1 本、自動再ダイヤル。リクエストは直列。
`NewH1PoolClient(addr, dialer, pool, opts...)`	`TransportH1Pool`	最大 `MaxConnsPerHost` 本。この値がそのままリクエスト並行度。
`NewManagedH1Client(resolver, dialer, opts...)`	`TransportH1Managed`	Resolver + Selector によるサービスディスカバリ。解決したアドレスごとに HTTP/1.1 サブプールを展開。

HTTP/1.1 への固定#

プロトコルの固定には次の 2 点が必要です。

HTTP/1.1 トランスポート — 上記のいずれかのコンストラクタ、または client.ClientOptions の対応する Transport 値を指定する。
h2 を提示しないダイヤラ — 素の TCP ダイヤラ（&conn.PlaintextDialer{}）、または NextProtos に "http/1.1" だけを載せた TLS ダイヤラを使い、ハンドシェイク中にサーバーが 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) を使えば、同じ単一接続クライアントを 1 回の呼び出しで構築できます。リクエスト 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 も使いません。コンストラクタは 3 つあり、典型的な構成をカバーします。単一コネクション、ホストごとのプール、リゾルバ駆動の複数バックエンドです。いずれも *client.Client を返し、同じ Do / DoStream API で使えます。

単一コネクション#

client.NewSingleConnClient は 1 本のコネクションを保持し、切断時には自動で再ダイヤルします。以下は 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 も使いません。標準ライブラリ crypto/tls に依存するのは TLS 1.3 ハンドシェイクのみで、パケット保護、ロスリカバリ、輻輳制御、フロー制御はすべて 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 側と対になる 3 つのコンストラクタがあります。

機能と利点

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

機能と利点#

サポートマトリクス#

3 つのプロトコルバージョンはすべて同じリクエスト API を共有する: client.Do / client.DoStream と、呼び出し側が所有し再利用できる client.Response。圧縮も共通である: レスポンスは gzip、deflate、br、zstd の 4 つすべてがデコードされ(クライアントは accept-encoding: gzip, deflate, br, zstd を通知する)、Request.CompressBody でリクエストボディを圧縮できる — 後述の圧縮を参照。異なるのは、各トランスポートがプロトコルのどこまでを公開するかである。

プロトコル	実装	コンストラクタ	1 コネクションあたりの並行リクエスト	プーリング	サービスディスカバリ	主な機能
HTTP/1.1	フルスクラッチ	`NewH1Client`、`NewH1PoolClient`、`NewManagedH1Client`	不可 — 1 コネクションにつき同時に 1 交換のみ(パイプラインなし)	`NewH1PoolClient`(排他チェックアウト方式のプール: `MaxConnsPerHost` がそのままリクエスト並行数)	`NewManagedH1Client`(Resolver + Selector)	キープアライブによるコネクション再利用、リクエストボディはストリーミング可能(`Request.BodyReader`、長さが不明ならチャンク転送)だがレスポンスは常に `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` とリクエストトレーラ、フロー制御、動的 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`	可 — 1 本の 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 には他の 2 バージョンと同じコンストラクタ一式があるが、そのプールは性質が異なる。HTTP/1.1 には多重化がない: 1 本のコネクションではリクエストは厳密に直列になるため、プールなしではこのクライアントは HTTP/1.1 の負荷をそもそも生成できない。プールはコネクションを排他チェックアウトで貸し出す — 1 コネクションにつき同時に 1 交換 — ため、MaxConnsPerHost がそのままリクエスト並行数になり、MaxStreamsPerConn は適用されない。すべてのコネクションが使用中なら、リクエストはどれかが空くまで待つ(リクエストのコンテキストで打ち切られる)。コネクションはキープアライブで再利用される。Connection: close、死んだコネクション、交換エラーが起きたコネクションは破棄して再ダイヤルする。パイプラインは意図的に実装していない。ダイヤラーは ALPN トークン h2 を提供してはならない — 素の 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、その他の実績あるプロトコル実装を一切再利用していません。

実施済みの検証:

RFC のセクションに対応付けた約 200 件のコンフォーマンステスト（CI でゲート）。
ワイヤパーサのファジング。
独立した 3 種類の HTTP/3 サーバ実装（Caddy/quic-go、nginx、aioquic）との実 UDP 上での相互運用検証。
全テストスイートを Go の race detector 下で実行。

未実施 の検証: 第三者による正式なセキュリティ監査。テストとファジングは欠陥率を下げますが、フルスクラッチのプロトコルスタックに脆弱性が存在しないことを証明するものではありません。

本番投入の前に#

セキュリティが重要なシステムで、本ライブラリを net/http の単純な置き換えとして扱わないでください。デプロイ先が信頼できないピアや機微なデータを扱う場合、あるいはその他の理由でセキュリティクリティカルな場合は、採用する前に依存するコードパスを自分でレビューするか、プロジェクトが本番運用の実績を重ねるまで待ってください。

自分の管理下にあるインフラに対する負荷生成・テスト・ツール用途であれば、リスクプロファイルは低くなります。それが本ライブラリの主たる想定用途です。

脆弱性の報告#

セキュリティ上の問題を発見した場合は、SECURITY.md の手順に従って非公開で報告してください。脆弱性について公開の GitHub issue を立てないでください。