README
¶
httpclient
A hardened, framework-free *http.Client factory for Go — secure TLS defaults, a downgrade-proof redirect policy, and the go/transit retry / circuit-breaker / auth middleware
Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Docs: httpclient.go.phpboyscout.uk
gitlab.com/phpboyscout/go/httpclient builds a secure-by-default *http.Client: a TLS
1.2 floor with curated cipher suites (from go/tls),
sane connection limits and timeouts, and a redirect policy that refuses HTTPS→HTTP
downgrades. Layer on the client middleware from
go/transit — retry with backoff, circuit breaking,
host-pinned credentials, request logging — through simple options.
It is the client half of the transport stack extracted from go-tool-base: a service or library that only makes outbound HTTP calls gets the hardened client and its middleware without ever linking the server stack (controls, authn, gateway) or the gRPC SDK.
Install
go get gitlab.com/phpboyscout/go/httpclient
Quick start
package main
import (
"time"
"gitlab.com/phpboyscout/go/httpclient"
transithttp "gitlab.com/phpboyscout/go/transit/http"
)
func main() {
client := httpclient.NewClient(
httpclient.WithTimeout(10*time.Second),
httpclient.WithRetry(transithttp.DefaultRetryConfig()), // retry transient failures
httpclient.WithClientMiddleware(transithttp.NewClientChain( // per-request middleware
transithttp.WithBearerToken("…"),
)),
)
resp, err := client.Get("https://api.internal/things")
_ = resp
_ = err
}
Design
- Framework-free. Depends only on
go/tls,go/transitandcockroachdb/errors(plus transit's OTel/redact transitive deps). Adepfootprint_test.goguard forbids go-tool-base, the server stack (controls/authn/gateway), the gRPC SDK, Viper/Cobra/ Charm and the cloud SDKs. - Secure by default. Hardened TLS, connection limits, and a
CheckRedirectthat caps redirects and rejects HTTPS→HTTP downgrades — you opt out, not in. - Middleware is transit's. Retry, circuit breaking, auth and logging are the
go/transitclient round-trippers; this module just wires them intoNewClient.
Compatibility
go/transit and go/tls versions are pinned and kept in lockstep with
go-tool-base. Grouped Renovate updates
keep them aligned.
Documentation
Guides and the factory model: httpclient.go.phpboyscout.uk. API reference: pkg.go.dev.
License
See LICENSE.
Documentation
¶
Overview ¶
Package httpclient is a hardened, framework-free *http.Client factory. It wires the shared client middleware from gitlab.com/phpboyscout/go/transit (retry, circuit breaking, auth, logging) and the hardened TLS defaults from gitlab.com/phpboyscout/go/tls onto the standard library net/http client, with a secure-by-default posture: TLS 1.2 floor, curated connection limits and timeouts, and a redirect policy that refuses HTTPS→HTTP downgrades.
It is the client half of the transport stack extracted from go-tool-base — a consumer that only makes outbound HTTP calls never inherits the server stack (controls, authn, gateway).
Index ¶
- func NewClient(opts ...ClientOption) *http.Client
- func NewTransport(tlsCfg *tls.Config) *http.Transport
- type ClientOption
- func WithCertPool(pool *x509.CertPool) ClientOption
- func WithClientMiddleware(chain transithttp.ClientChain) ClientOption
- func WithMaxRedirects(n int) ClientOption
- func WithRetry(cfg transithttp.RetryConfig) ClientOption
- func WithTLSConfig(cfg *tls.Config) ClientOption
- func WithTimeout(d time.Duration) ClientOption
- func WithTransport(rt http.RoundTripper) ClientOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewClient ¶
func NewClient(opts ...ClientOption) *http.Client
NewClient returns an *http.Client with security-focused defaults: TLS 1.2 minimum, curated cipher suites, timeouts, connection limits, and redirect policy that rejects HTTPS-to-HTTP downgrades.
Types ¶
type ClientOption ¶
type ClientOption func(*clientConfig)
ClientOption configures the secure HTTP client.
func WithCertPool ¶
func WithCertPool(pool *x509.CertPool) ClientOption
WithCertPool sets the root CA pool used to verify server certificates, preserving the hardened default TLS configuration (cipher suites, minimum version, curve preferences). Use this to trust certificates that are not in the system roots, such as a private CA or self-signed cert. Build the pool with tls.CertPool. Applying WithTLSConfig after this option replaces the pool along with the rest of the TLS configuration.
func WithClientMiddleware ¶
func WithClientMiddleware(chain transithttp.ClientChain) ClientOption
WithClientMiddleware applies a transit client middleware chain to the client's transport. The chain wraps the transport after retry (if configured) so that retry operates on the raw transport, not on logged/authed requests.
func WithMaxRedirects ¶
func WithMaxRedirects(n int) ClientOption
WithMaxRedirects sets the maximum number of redirects to follow. Default: 10. Set to 0 to disable redirect following entirely.
func WithRetry ¶
func WithRetry(cfg transithttp.RetryConfig) ClientOption
WithRetry enables automatic retry with exponential backoff for transient failures, using the retry transport from gitlab.com/phpboyscout/go/transit.
func WithTLSConfig ¶
func WithTLSConfig(cfg *tls.Config) ClientOption
WithTLSConfig overrides the default TLS configuration. The caller is responsible for ensuring the provided config meets security requirements.
func WithTimeout ¶
func WithTimeout(d time.Duration) ClientOption
WithTimeout sets the overall request timeout. Default: 30s.
func WithTransport ¶
func WithTransport(rt http.RoundTripper) ClientOption
WithTransport overrides the entire HTTP transport. When set, transport-level options (TLS config, connection limits) are ignored.
Source Files