Documentation on poseidon-http-client

Getting started

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

Getting started#

poseidon-http-client is a low-level HTTP client for Go. It implements HTTP/1.1, HTTP/2, and HTTP/3 from scratch — its own framing, HPACK, QPACK, and QUIC stack — with no net/http and no third-party protocol libraries. It is built for load generators and tools that need direct control over connections, streams, and flow control.

Install#

Requires Go 1.25 or newer.

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

The request model#

All three protocol versions share the same API. You build a client with a constructor, then call Do with a context, a request, and a caller-owned *client.Response:

HTTP/1.1

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

HTTP/1.1#

Use HTTP/1.1 when the target server does not speak HTTP/2, or when you want to test its HTTP/1.1 path specifically and must prevent the ALPN negotiation from upgrading the connection to h2.

HTTP/1.1 has the same constructor set as HTTP/2 and HTTP/3:

Constructor	Transport	Shape
`NewH1Client(addr, dialer, opts...)`	`TransportH1SingleConn`	One connection, auto-redial. Requests are serialized.
`NewH1PoolClient(addr, dialer, pool, opts...)`	`TransportH1Pool`	Up to `MaxConnsPerHost` connections. That number is the request concurrency.
`NewManagedH1Client(resolver, dialer, opts...)`	`TransportH1Managed`	Resolver + Selector service discovery; a per-address HTTP/1.1 sub-pool fans out.

Forcing HTTP/1.1#

Two things pin the protocol:

HTTP/2

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

HTTP/2#

The HTTP/2 client implements RFC 7540 and HPACK (RFC 7541) from scratch — no net/http, no golang.org/x/net/http2. Three constructors cover the common topologies: one connection, a per-host pool, or a resolver-driven set of backends. All three return a *client.Client with the same Do / DoStream API.

Single connection#

client.NewSingleConnClient holds one connection and redials automatically when it drops. This is 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 is caller-owned: allocate it once, call resp.Reset() between requests. client.GET(path) is shorthand; build a client.Request{Method, Scheme, Authority, Path, BodyMode} directly for full control.

HTTP/3

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

HTTP/3#

The HTTP/3 client (RFC 9114) runs over a QUIC stack (RFC 9000/9001/9002) and QPACK codec (RFC 9204) implemented in this repository — no quic-go, no cgo. Only the TLS 1.3 handshake itself comes from the standard library crypto/tls; packet protection, loss recovery, congestion control, and flow control are poseidon code.

The request API is the same Do / DoStream you use with HTTP/2. A client.Request and client.Response do not change between transports; switching a load test from H2 to H3 is a constructor change.

Features & advantages

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

Features & advantages#

Support matrix#

All three protocol versions share the same request API: client.Do / client.DoStream with a caller-owned, reusable client.Response. Compression is shared too: responses are decoded for all of gzip, deflate, br, and zstd (the client advertises accept-encoding: gzip, deflate, br, zstd), and Request.CompressBody compresses request bodies — see Compression below. What differs is how much of the protocol each transport exposes.

Protocol	Implementation	Constructors	Concurrent requests per connection	Pooling	Service discovery	Notable capabilities
HTTP/1.1	From scratch	`NewH1Client`, `NewH1PoolClient`, `NewManagedH1Client`	No — one exchange per connection at a time (no pipelining)	`NewH1PoolClient` (exclusive-checkout pool: `MaxConnsPerHost` is the request concurrency)	`NewManagedH1Client` (Resolver + Selector)	Keep-alive connection reuse; request bodies stream (`Request.BodyReader`, chunked when length is unknown) but responses are always buffered into `Response.Body` — `DoStream` and `BodyStream` return an error; ALPN fallback target: `TransportALPN` selects HTTP/1.1 automatically when a server does not offer h2
HTTP/2	RFC 7540 + HPACK (RFC 7541), from scratch	`NewSingleConnClient`, `NewPoolClient`, `NewManagedClient`	Yes — stream multiplexing, gated by `MAX_CONCURRENT_STREAMS`	`NewPoolClient` (per-host pool, least-loaded stream pick, idle eviction)	`NewManagedClient` (Resolver + Selector)	`DoStream` and request trailers; flow control; dynamic SETTINGS; GOAWAY drain; PING keepalive; server push (PUSH_PROMISE); request priority; extended CONNECT (RFC 8441, WebSockets over H2); CONTINUATION; HTTP CONNECT proxy dialers; h2c prior knowledge
HTTP/3	RFC 9114 + QUIC (RFC 9000/9001/9002) + QPACK (RFC 9204), from scratch	`NewH3Client`, `NewH3PoolClient`, `NewManagedH3Client`	Yes — concurrent in-flight requests over one QUIC connection	`NewH3PoolClient` (multi-connection pool)	`NewManagedH3Client`	`DoStream`; dynamic QPACK in both directions (encode + decode); all TLS 1.3 AEADs (AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305); congestion control NewReno by default, opt-in BBR; on Linux: GSO batched send, GRO batched receive, bounded ACK coalescing

HTTP/1.1 has the same constructor set as the other two versions, but its pool is different in kind. HTTP/1.1 has no multiplexing: a single connection means strictly serial requests, so without a pool the client cannot generate HTTP/1.1 load at all. The pool hands out connections by exclusive checkout — one exchange per connection at a time — which makes MaxConnsPerHost the request concurrency; MaxStreamsPerConn does not apply. A request that finds every connection busy waits for one to free, bounded by the request context. Connections are kept alive and reused; a Connection: close, a dead connection, or an exchange error discards the connection and redials. Pipelining is deliberately not implemented. The dialer must not offer the h2 ALPN token — use a plain TCP dialer, or a TLS dialer whose NextProtos is only "http/1.1".

Disclaimer

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

Disclaimer#

poseidon-http-client is young software. This is its first release. Read this page before depending on it.

No warranty#

The library is licensed under MIT and is provided as is, without warranty of any kind. You use it at your own risk. See the LICENSE file for the exact terms.

Security-sensitive code, no third-party audit#

This library implements security-sensitive protocols from scratch: the QUIC transport (RFC 9000/9001/9002), TLS 1.3 record protection for QUIC, HPACK (RFC 7541), and QPACK (RFC 9204). It does not reuse net/http, quic-go, or any other established protocol implementation for these paths.