Documentation
¶
Overview ¶
Package httpclient provides a named HTTP client registry and factory.
Clients are configured once (via ClientSpec) and built by the Registry, which applies global concerns (fixture transports, shared default transport) consistently to every client it produces — whether named or inline.
The package does not define a new interface for consuming HTTP; it produces standard *http.Client instances.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BearerTransport ¶
type BearerTransport struct {
Token string
Base http.RoundTripper
}
BearerTransport injects a static Authorization: Bearer header into every request.
func (*BearerTransport) RoundTrip ¶
RoundTrip implements http.RoundTripper.
type CertSource ¶
type CertSource interface {
// Certificate returns the current client cert+key for TLS handshake.
Certificate() (tls.Certificate, error)
}
CertSource provides client certificates for mTLS. Implementations may read from files, Vault, K8s secrets, etc.
type ClientName ¶
type ClientName string
ClientName identifies a named HTTP client in configuration.
type ClientSpec ¶
type ClientSpec struct {
Timeout time.Duration
CertSource CertSource // nil = share default transport
TransportMiddleware TransportMiddleware // nil = no wrapping
RootCAPath string // PEM-encoded CA cert file to trust
}
ClientSpec holds resolved parameters for building an *http.Client. It is the runtime equivalent of the configuration-level HTTPClientSpec, with durations parsed and abstractions instantiated.
type FileCertSource ¶
FileCertSource loads a client certificate and key from disk paths.
func NewFileCertSource ¶
func NewFileCertSource(certPath, keyPath string) *FileCertSource
NewFileCertSource creates a FileCertSource that reads from the given paths.
func (*FileCertSource) Certificate ¶
func (s *FileCertSource) Certificate() (tls.Certificate, error)
Certificate implements CertSource.
type HTTPClientObserver ¶
type HTTPClientObserver interface {
// RequestStarted is called when an outbound HTTP request begins.
// clientName is the [ClientName] from the registry (empty for inline clients).
// Returns a potentially modified context and a probe to track the request.
RequestStarted(ctx context.Context, clientName string, method string, host string) (context.Context, RequestProbe)
}
HTTPClientObserver observes outbound HTTP client requests made via the Registry. Implementations should embed NoOpHTTPClientObserver for forward compatibility with new methods added to this interface.
type HeadersTransport ¶
type HeadersTransport struct {
Headers map[string]string
Base http.RoundTripper
}
HeadersTransport injects a fixed set of headers into every request.
func (*HeadersTransport) RoundTrip ¶
RoundTrip implements http.RoundTripper.
type NoOpHTTPClientObserver ¶
type NoOpHTTPClientObserver struct{}
NoOpHTTPClientObserver is a no-op implementation for forward compatibility and testing.
func (NoOpHTTPClientObserver) RequestStarted ¶
func (NoOpHTTPClientObserver) RequestStarted(ctx context.Context, _ string, _ string, _ string) (context.Context, RequestProbe)
RequestStarted returns the context unchanged and a no-op probe.
type NoOpRequestProbe ¶
type NoOpRequestProbe struct{}
NoOpRequestProbe is a no-op implementation for forward compatibility.
func (NoOpRequestProbe) ConnectionReused ¶
func (NoOpRequestProbe) ConnectionReused(bool)
func (NoOpRequestProbe) End ¶
func (NoOpRequestProbe) End()
func (NoOpRequestProbe) Error ¶
func (NoOpRequestProbe) Error(error)
func (NoOpRequestProbe) ProtocolVersion ¶
func (NoOpRequestProbe) ProtocolVersion(string)
func (NoOpRequestProbe) StatusCode ¶
func (NoOpRequestProbe) StatusCode(int)
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry builds, stores, and provides named HTTP clients. It is also the factory for inline (anonymous) clients, ensuring global concerns like fixture transports are applied uniformly.
func NewRegistry ¶
func NewRegistry(fixtureTransport http.RoundTripper, opts ...RegistryOption) *Registry
NewRegistry creates a Registry. If fixtureTransport is non-nil, it overrides the base transport for every client built by this registry (hermetic mode).
func (*Registry) Build ¶
func (r *Registry) Build(spec ClientSpec) (*http.Client, error)
Build creates an anonymous *http.Client from the given spec, applying all global concerns (fixture transport, etc.). The client is NOT stored in the registry. Use this for inline-defined clients.
func (*Registry) Get ¶
func (r *Registry) Get(name ClientName) (*http.Client, error)
Get retrieves a named client. Returns an error if not found.
func (*Registry) Register ¶
func (r *Registry) Register(name ClientName, spec ClientSpec) (*http.Client, error)
Register builds a client from spec, stores it by name, and returns it. Returns an error if the name is already registered or the spec is invalid.
type RegistryOption ¶
type RegistryOption func(*registryConfig)
RegistryOption configures optional parameters for NewRegistry.
func WithObserver ¶
func WithObserver(obs HTTPClientObserver) RegistryOption
WithObserver sets the observer used to instrument outbound HTTP requests. If not provided, no instrumentation is applied.
type RequestProbe ¶
type RequestProbe interface {
// StatusCode records the HTTP response status code.
StatusCode(code int)
// Error records a transport-level error (timeout, connection refused, etc.).
Error(err error)
// ConnectionReused records whether the underlying TCP connection was
// reused (true) or newly established (false). Called from an
// httptrace.ClientTrace.GotConn callback during the round-trip.
ConnectionReused(reused bool)
// ProtocolVersion records the negotiated HTTP protocol version
// (e.g. "HTTP/1.1", "HTTP/2.0") from the response. Only called on
// successful round-trips; omitted on transport-level errors.
ProtocolVersion(proto string)
// End signals the request is complete (for timing). Called via defer.
End()
}
RequestProbe tracks a single outbound HTTP request. Implementations should embed NoOpRequestProbe for forward compatibility.
type TransportMiddleware ¶
type TransportMiddleware func(base http.RoundTripper) http.RoundTripper
TransportMiddleware wraps a base RoundTripper, returning a decorated one. Used to compose concerns like authentication atop a resolved base transport.
Source Files