Документация on poseidon-http-client

Начало работы

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

Начало работы#

poseidon-http-client — низкоуровневый HTTP-клиент для Go. Он реализует HTTP/1.1, HTTP/2 и HTTP/3 с нуля — собственный фрейминг, HPACK, QPACK и QUIC-стек — без net/http и без сторонних протокольных библиотек. Клиент рассчитан на генераторы нагрузки и инструменты, которым нужен прямой контроль над соединениями, стримами и flow control.

Установка#

Требуется Go 1.25 или новее.

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

Модель запроса#

Все три версии протокола используют один и тот же API. Клиент создаётся конструктором, затем вызывается Do с контекстом, запросом и принадлежащим вызывающему коду *client.Response:

HTTP/1.1

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

HTTP/1.1#

Используйте HTTP/1.1, когда целевой сервер не поддерживает HTTP/2, или когда нужно проверить именно его HTTP/1.1-путь и не дать ALPN-переговорам поднять соединение до h2.

У HTTP/1.1 тот же набор конструкторов, что у HTTP/2 и HTTP/3:

Конструктор	Транспорт	Схема
`NewH1Client(addr, dialer, opts...)`	`TransportH1SingleConn`	Одно соединение, автоматическое переподключение. Запросы выполняются последовательно.
`NewH1PoolClient(addr, dialer, pool, opts...)`	`TransportH1Pool`	До `MaxConnsPerHost` соединений. Это число и есть конкурентность запросов.
`NewManagedH1Client(resolver, dialer, opts...)`	`TransportH1Managed`	Service discovery через Resolver + Selector; на каждый адрес — свой HTTP/1.1-подпул.

Принудительный HTTP/1.1#

Протокол фиксируют две вещи:

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. Три конструктора покрывают типовые топологии: одно соединение, пул на хост или набор бэкендов, управляемый резолвером. Все три возвращают *client.Client с одним и тем же API Do / DoStream.

Одно соединение#

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); защита пакетов, восстановление после потерь, управление перегрузкой и flow control — код poseidon.

API запросов — те же Do / DoStream, что и в HTTP/2. client.Request и client.Response не меняются при смене транспорта; перевод нагрузочного теста с H2 на H3 — это замена конструктора.

Возможности и преимущества

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 сжимает тела запросов — см. Сжатие ниже. Различается лишь то, какую часть протокола открывает каждый транспорт.

Протокол	Реализация	Конструкторы	Параллельные запросы в одном соединении	Пул соединений	Service discovery	Ключевые возможности
HTTP/1.1	С нуля	`NewH1Client`, `NewH1PoolClient`, `NewManagedH1Client`	Нет — один обмен на соединение в каждый момент (без pipelining)	`NewH1PoolClient` (пул с эксклюзивной выдачей: `MaxConnsPerHost` и есть параллелизм запросов)	`NewManagedH1Client` (Resolver + Selector)	Keep-alive и переиспользование соединений; тела запросов передаются потоком (`Request.BodyReader`, chunked, если длина заранее неизвестна), но ответы всегда буферизуются в `Response.Body` — `DoStream` и `BodyStream` возвращают ошибку; цель ALPN-фолбэка: `TransportALPN` автоматически выбирает HTTP/1.1, если сервер не предлагает h2
HTTP/2	RFC 7540 + HPACK (RFC 7541), с нуля	`NewSingleConnClient`, `NewPoolClient`, `NewManagedClient`	Да — мультиплексирование потоков, ограниченное `MAX_CONCURRENT_STREAMS`	`NewPoolClient` (пул на хост, выбор наименее загруженного соединения, вытеснение простаивающих)	`NewManagedClient` (Resolver + Selector)	`DoStream` и трейлеры запроса; управление потоком (flow control); динамические SETTINGS; корректное завершение по GOAWAY; PING keepalive; server push (PUSH_PROMISE); приоритеты запросов; extended CONNECT (RFC 8441, WebSockets поверх H2); 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 в обоих направлениях (кодирование и декодирование); все AEAD-шифры TLS 1.3 (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 не применяется. Запрос, заставший все соединения занятыми, ждёт освобождения одного из них — ожидание ограничено контекстом запроса. Соединения поддерживаются живыми и переиспользуются; Connection: close, мёртвое соединение или ошибка обмена приводят к сбросу соединения и повторному подключению. Pipelining сознательно не реализован. Диалер не должен предлагать ALPN-токен h2 — используйте обычный TCP-диалер или TLS-диалер, у которого в NextProtos только "http/1.1".

Отказ от ответственности

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

Отказ от ответственности#

poseidon-http-client — молодая библиотека. Это её первый релиз. Прочитайте эту страницу, прежде чем на неё полагаться.

Без гарантий#

Библиотека распространяется под лицензией MIT и предоставляется как есть, без каких-либо гарантий. Вы используете её на свой страх и риск. Точные условия — в файле LICENSE.

Критичный для безопасности код без стороннего аудита#

Библиотека реализует с нуля протоколы, критичные для безопасности: транспорт QUIC (RFC 9000/9001/9002), защиту записей TLS 1.3 для QUIC, HPACK (RFC 7541) и QPACK (RFC 9204). На этих путях она не использует net/http, quic-go или какую-либо другую устоявшуюся реализацию протоколов.