Help us shape the future of Go! Take the 2026 Go Developer Survey

httpserver

package
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package httpserver serves HTTP ingress and egress points for the protocol engine. Both share one handler that forwards, records, replays, and reports as the engine decides.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewReverseProxy

func NewReverseProxy(ctx context.Context, target *netaddr.Endpoint, transport http.RoundTripper, discard bool) (*httputil.ReverseProxy, error)

NewReverseProxy forwards requests to a backend target with trusted forwarding headers. A discarding proxy logs failures as candidate failures and writes no response.

func Serve

func Serve(ctx context.Context, config Config, bindings []Binding, lifecycle Lifecycle) error

Serve runs every binding until the context is cancelled or any server fails, then shuts all of them down before draining work that outlives requests.

func Supports added in v0.35.0

func Supports() []state.Support

Supports returns the kinds of IO the HTTP server proxies, described for an agent that sorts a service's code into them.

Types

type Binding

type Binding struct {
	// contains filtered or unexported fields
}

Binding pairs a listener with the handler that serves its connections.

func NewBinding

func NewBinding(listener net.Listener, handler http.Handler) Binding

NewBinding serves connections accepted by listener with handler.

type Config

type Config struct {
	// TransportConfig holds the limits shared with the backend transport.
	TransportConfig `embed:""`
	// MaxConnections limits concurrent client connections.
	MaxConnections int `default:"512" help:"Maximum concurrent client connections."`
	// ReadHeaderTimeout limits the duration spent reading request headers.
	ReadHeaderTimeout time.Duration `default:"10s" help:"Maximum duration for reading request headers."`
	// IdleTimeout limits how long an idle client connection remains open.
	IdleTimeout time.Duration `default:"1m" help:"Maximum idle client connection duration."`
	// ShutdownTimeout limits graceful server shutdown.
	ShutdownTimeout time.Duration `default:"10s" help:"Maximum graceful shutdown duration."`
	// ComparisonMaxBodyBytes limits each captured request or response body.
	ComparisonMaxBodyBytes int `default:"1048576" help:"Maximum captured body bytes per request or response."`
	// Candidates limits candidate admission.
	Candidates proxy.CandidatesConfig `embed:""`
	// Descriptors supplies static protobuf descriptors. Ingress adds any reflected ones.
	Descriptors descriptors.Config `embed:""`
}

Config contains the configuration shared by ingress and egress.

func NewConfig

func NewConfig() Config

NewConfig returns the default server configuration.

func (Config) Validate

func (c Config) Validate() error

Validate checks that every limit is positive.

type DescriptorLoader

type DescriptorLoader interface {
	Load(ctx context.Context, endpoint string) (*descriptorpb.FileDescriptorSet, error)
}

DescriptorLoader loads a backend's protobuf descriptor set.

type Egress

type Egress struct {
	// contains filtered or unexported fields
}

Egress serves reference and candidate traffic on separate listeners. Candidate requests never reach a dependency under any condition.

func NewEgress

func NewEgress(
	ctx context.Context,
	config EgressConfig,
	engineConfig protocol.Config,
	transport http.RoundTripper,
) (*Egress, error)

NewEgress constructs an egress proxy and the engine it owns.

func (*Egress) Candidates added in v0.30.0

func (e *Egress) Candidates() *proxy.Candidates

Candidates reports the egress candidate quarantine state.

func (*Egress) Serve

func (e *Egress) Serve(ctx context.Context, reference net.Listener, candidate net.Listener, probes net.Listener) error

Serve accepts reference, candidate, and health traffic until the context is cancelled or a server fails. Readiness turns true once the servers start.

type EgressConfig

type EgressConfig struct {
	// ReferenceListen receives reference traffic, which is always forwarded.
	ReferenceListen string `default:"127.0.0.1:50060" help:"Reference listener address: host:port, or unix:<path|@abstract> for a unix socket."`
	// CandidateListen receives candidate traffic. It must stay local: a loopback
	// IP or a unix socket.
	CandidateListen string `` /* 129-byte string literal not displayed */
	// HealthListen serves liveness and readiness. Probes need their own listener,
	// because any path on the traffic listeners may belong to a dependency.
	HealthListen string `default:"127.0.0.1:50062" help:"Health listener address for /livez and /readyz: host:port, or unix:<path|@abstract>."`
	// Destinations maps each request host to its upstream URL, using the backend
	// URL forms that ingress accepts.
	Destinations map[string]string `` /* 210-byte string literal not displayed */
	// RecordingBufferBytes limits recorded reference responses across all requests.
	RecordingBufferBytes int `default:"33554432" help:"Maximum reference response bytes recorded across all requests."`
	// Config holds the configuration shared with ingress.
	Config `embed:""`
}

EgressConfig contains the command-line configuration for an egress proxy.

func NewEgressConfig

func NewEgressConfig() EgressConfig

NewEgressConfig returns the default egress configuration.

func (EgressConfig) Validate

func (c EgressConfig) Validate() error

Validate checks that the egress has usable resource limits.

type Ingress

type Ingress struct {
	// contains filtered or unexported fields
}

Ingress mirrors each inbound request to the reference and candidate services. Reference responses never wait for candidate comparison.

func NewIngress

func NewIngress(
	ctx context.Context,
	config IngressConfig,
	engineConfig protocol.Config,
	transport http.RoundTripper,
	loader Option[DescriptorLoader],
	migration Option[state.State],
) (*Ingress, error)

NewIngress constructs an ingress proxy and the engine it owns. loader is required only for reflection; with a migration state, only migrated routes are mirrored.

func (*Ingress) Candidates added in v0.30.0

func (i *Ingress) Candidates() *proxy.Candidates

Candidates reports the ingress candidate quarantine state.

func (*Ingress) Serve

func (i *Ingress) Serve(ctx context.Context, listener net.Listener) error

Serve accepts ingress traffic until the context is cancelled or the server fails. Readiness remains false until the comparison schema is configured.

func (*Ingress) ServeHTTP

func (i *Ingress) ServeHTTP(writer http.ResponseWriter, request *http.Request)

ServeHTTP serves health checks or mirrors a request to both backends.

func (*Ingress) Shutdown

func (i *Ingress) Shutdown(ctx context.Context) error

Shutdown stops accepting candidate work and waits for active mirrors to finish. Ingress owns its engine, so it also shuts the engine down.

type IngressConfig

type IngressConfig struct {
	// Listen is the address for the ingress HTTP server. A "unix:" prefix binds a
	// unix socket, either an absolute path or an abstract name beginning with "@".
	Listen string `default:"127.0.0.1:50050" help:"Ingress server address: host:port, or unix:<path|@abstract> for a unix socket."`
	// Reference is the authoritative backend URL, using http, https, or h2c over
	// TCP, or http+unix/h2c+unix over a unix socket.
	Reference string `required:"" help:"Reference backend URL: http, https, h2c, or http+unix:<socket> / h2c+unix:<socket>."`
	// Candidate is the mirrored backend URL. It must stay local: a loopback IP or
	// a unix socket, using http, https, or h2c.
	Candidate string `required:"" help:"Candidate backend URL on a loopback IP or unix socket: http, https, h2c, http+unix, or h2c+unix."`
	// CandidateTimeout limits the duration of a candidate request.
	CandidateTimeout time.Duration `default:"30s" help:"Maximum duration of a candidate request."`
	// Reflection loads and compares both backends' descriptors at startup.
	Reflection bool `default:"true" negatable:"" help:"Load backend descriptors with gRPC reflection and require them to match."`
	// ReflectionTimeout limits the startup descriptor comparison.
	ReflectionTimeout time.Duration `default:"10s" help:"Maximum duration of the startup gRPC reflection check."`
	// CandidateBufferBytes limits queued request data across all candidates.
	CandidateBufferBytes int `default:"1048576" help:"Maximum request bytes buffered across candidates before quarantine."`
	// Config holds the configuration shared with egress.
	Config `embed:""`
}

IngressConfig contains the command-line configuration for an ingress proxy.

func NewIngressConfig

func NewIngressConfig() IngressConfig

NewIngressConfig returns the default ingress configuration.

func (IngressConfig) ListenNetworkAddress

func (c IngressConfig) ListenNetworkAddress() (network string, address string)

ListenNetworkAddress reports the network and address for the ingress listener.

func (IngressConfig) Validate

func (c IngressConfig) Validate() error

Validate checks that the ingress has usable resource limits.

type Lifecycle

type Lifecycle struct {
	// contains filtered or unexported fields
}

Lifecycle holds the proxy-specific steps that Serve runs around its servers.

func NewLifecycle

func NewLifecycle(start func(ctx context.Context), stop func(), drain func(ctx context.Context) error) Lifecycle

NewLifecycle runs start once every listener accepts connections, stop before servers shut down, and drain after they have stopped.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport forwards HTTP/1, encrypted HTTP/2, and unencrypted HTTP/2 requests.

func NewTransport

func NewTransport(config TransportConfig) *Transport

NewTransport constructs transports for HTTP/1, encrypted HTTP/2, and h2c.

func (*Transport) CloseIdleConnections

func (t *Transport) CloseIdleConnections()

CloseIdleConnections closes idle connections held by every underlying transport.

func (*Transport) ForBackend

func (t *Transport) ForBackend(target *netaddr.Endpoint) http.RoundTripper

ForBackend selects the transport for a backend, dialing its unix socket when the backend uses one.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(request *http.Request) (*http.Response, error)

RoundTrip sends HTTP requests without deriving backend protocol from the client.

type TransportConfig added in v0.39.0

type TransportConfig struct {
	// MaxInFlightRequests limits concurrent proxied requests.
	MaxInFlightRequests int `default:"256" help:"Maximum concurrent proxied requests."`
	// MaxHeaderBytes limits the size of request and response headers.
	MaxHeaderBytes int `default:"65536" help:"Maximum request header size in bytes."`
}

TransportConfig contains the limits the backend transport shares with the servers.

Directories

Path Synopsis
Package codec decodes gRPC, Connect, and bare protobuf payloads to JSON.
Package codec decodes gRPC, Connect, and bare protobuf payloads to JSON.
Package message decodes HTTP requests and responses into engine messages.
Package message decodes HTTP requests and responses into engine messages.
middleware
health
Package health provides HTTP liveness and readiness middleware.
Package health provides HTTP liveness and readiness middleware.
logging
Package logging provides structured HTTP request logging middleware.
Package logging provides structured HTTP request logging middleware.
Package route matches HTTP requests against net/http.ServeMux patterns.
Package route matches HTTP requests against net/http.ServeMux patterns.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL