Documentation
¶
Overview ¶
Package httpf holds the HTTP glue a service needs on both sides of the wire.
Inbound, it writes handler responses that stay consistent with the service's OpenTelemetry tracing and structured logging: every outcome is recorded on the request span. Outbound, it builds the pooled, traced client a service calls other systems through.
Index ¶
- func HandleError(ctx context.Context, logger logging.Log, w http.ResponseWriter, ...)
- func NewPoolClient(options PoolOptions) *http.Client
- func NewPoolTransport(options PoolOptions) *http.Transport
- func SendJSONStatus[Data any](_ context.Context, w http.ResponseWriter, span trace.Span, status int, ...)
- type ErrMap
- type PoolOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleError ¶
func HandleError( ctx context.Context, logger logging.Log, w http.ResponseWriter, span trace.Span, errMap ErrMap, err error, )
HandleError writes a response for a failed handler. It records err on the span, matches it against errMap (with errors.Is) to pick a status, logs it, and writes the status text as the body. Unmatched errors default to 500 Internal Server Error.
func NewPoolClient ¶ added in v0.30.0
func NewPoolClient(options PoolOptions) *http.Client
NewPoolClient returns an HTTP client that adds three things to http.DefaultClient: a connection pool the caller sizes, otelhttp tracing that opens a span per request and carries the trace context to the far end, and no timeout, so a response that takes minutes to arrive survives.
Build one per process and inject it: sharing it is what makes the pool useful.
func NewPoolTransport ¶ added in v0.30.0
func NewPoolTransport(options PoolOptions) *http.Transport
NewPoolTransport returns the transport NewPoolClient runs on, untraced. Use it to read the pool settings back, or to wrap the transport before building a client.
func SendJSONStatus ¶ added in v0.26.0
func SendJSONStatus[Data any]( _ context.Context, w http.ResponseWriter, span trace.Span, status int, data Data, )
SendJSONStatus encodes data as JSON to w under status, and records the outcome on the span.
The status is a parameter rather than something the caller sends first, because net/http freezes the outbound header set when the status line goes out. A caller that writes the status first has its Content-Type discarded and answers text/plain; one that writes it afterwards gets a "superfluous WriteHeader" and keeps the 200. Owning both is the only order that answers JSON under a status other than 200.
An encoding failure is reported on the span. The status line is already sent by then, so the body may be truncated.
Types ¶
type ErrMap ¶
ErrMap maps sentinel errors to the HTTP status HandleError returns for them. A nil key sets the fallback status for unmatched errors; without one, they fall back to 500 Internal Server Error.
type PoolOptions ¶ added in v0.30.0
type PoolOptions struct {
// MaxIdleConns caps the idle connections kept across every host.
MaxIdleConns int
// MaxIdleConnsPerHost caps the idle connections kept for a single host. Set it to at least the
// number of concurrent requests made to that host: the standard library keeps two, and every
// call past that pays a fresh TLS handshake.
MaxIdleConnsPerHost int
}
PoolOptions sizes the connection pool NewPoolClient and NewPoolTransport build.
Source Files
Directories