Documentation
¶
Overview ¶
Package httpclient provides a centralized HTTP client factory with unified configuration.
Index ¶
- Constants
- func ConfiguredTLS() *tls.Config
- func CurrentTransport(client *http.Client) (*http.Transport, bool)
- func NewAWSSDKClient(base *http.Client) *http.Client
- func NewClientWithTimeout(timeout time.Duration) *http.Client
- func NewDefaultHTTPClient() *http.Client
- func NewDownloadClient(timeout time.Duration) *http.Client
- func NewHTTPClient(config *ClientConfig) *http.Client
- func ParseProxyURL(raw string) (*url.URL, error)
- func RedactProxyURL(raw string) string
- func RestoreTLS(s TLSSnapshot)
- func SetConfiguredStreamIdleTimeout(seconds int)
- func SetConfiguredTLS(settings TLSSettings) error
- func SetConfiguredTimeouts(timeoutSeconds, responseHeaderTimeoutSeconds int)
- func StreamIdleTimeout() time.Duration
- type ClientConfig
- type TLSSettings
- type TLSSnapshot
Constants ¶
const DefaultStreamIdleTimeout = 300 * time.Second
DefaultStreamIdleTimeout is how long an upstream stream may stay silent, once its first bytes arrived, before it is treated as stalled. Healthy streams send tokens or keep-alive events far more often than this.
Variables ¶
This section is empty.
Functions ¶
func ConfiguredTLS ¶ added in v0.2.0
ConfiguredTLS returns a copy of the installed client TLS configuration, or nil when the gateway runs on system defaults. Callers that build their own transport (websocket dialers, SDK clients) should install it.
func CurrentTransport ¶ added in v0.2.0
CurrentTransport returns the *http.Transport a client created by this package currently sends through, so callers can inspect its settings such as the proxy function. It reports false for any other client.
func NewAWSSDKClient ¶ added in v0.2.0
NewAWSSDKClient returns a client for aws-sdk-go-v2's WithHTTPClient on base's transport, or on the shared default transport when base is nil, so a provider's outbound proxy and the gateway's TLS trust both apply. The SDK's own client follows only 307 and 308 redirects, because a 301/302 would replay a signed request; this client does the same, and like every client here it never follows a redirect to another origin.
func NewClientWithTimeout ¶ added in v0.2.0
NewClientWithTimeout returns a client on the shared transport settings (proxy, TLS trust, dial and keep-alive tuning) whose overall request and response-header timeouts are both bound to timeout. Auxiliary callers that send credentials, such as vector stores and embedding endpoints, use it so they inherit operator trust settings instead of building bare clients; like every client here it never follows a redirect to another origin.
func NewDefaultHTTPClient ¶
NewDefaultHTTPClient creates a new HTTP client with default configuration. This is a convenience function equivalent to NewHTTPClient(nil).
func NewDownloadClient ¶ added in v0.2.0
NewDownloadClient is NewClientWithTimeout with net/http's standard redirect policy: up to 10 hops, to any origin. Unauthenticated downloads such as the model catalog and the update check use it, because their hosts may redirect from http to https or to a separate file host. net/http still drops the Authorization and Cookie headers on a hop to another host.
func NewHTTPClient ¶
func NewHTTPClient(config *ClientConfig) *http.Client
NewHTTPClient creates a new HTTP client with the provided configuration. If config is nil, DefaultConfig() is used.
The client's transport follows the process-wide TLS trust installed with SetConfiguredTLS: a change or rollback applies to the next request on every client, so a client created while a later-rejected reload had its settings installed does not keep them.
func ParseProxyURL ¶ added in v0.1.96
ParseProxyURL validates an outbound proxy URL such as "http://proxy.internal:3128" or "socks5://user:pass@10.0.0.1:1080". The error message never echoes the URL, which may carry credentials.
func RedactProxyURL ¶ added in v0.1.96
RedactProxyURL returns a valid proxy URL with any password replaced by "xxxxx", for logs and admin views, and a fixed mask for anything else.
func RestoreTLS ¶ added in v0.2.0
func RestoreTLS(s TLSSnapshot)
RestoreTLS reinstalls a configuration captured by SnapshotTLS. Transports bound to that same configuration keep their connection pools.
func SetConfiguredStreamIdleTimeout ¶ added in v0.1.93
func SetConfiguredStreamIdleTimeout(seconds int)
SetConfiguredStreamIdleTimeout installs the config-file (`http:` block) stream idle timeout in seconds; 0 disables it. App startup calls this once before providers are constructed. HTTP_STREAM_IDLE_TIMEOUT still takes precedence.
func SetConfiguredTLS ¶ added in v0.2.0
func SetConfiguredTLS(settings TLSSettings) error
SetConfiguredTLS builds and installs the client TLS configuration used by every HTTP client this package creates, including clients that already exist: transports pick the change up on their next request. App startup calls it before any provider constructs a transport. It returns an error when a referenced file is missing, unreadable, or holds no usable certificate, so a typo in the path fails startup instead of silently trusting nothing extra.
Installing settings whose files hold the same bytes as the installed ones is a no-op, so a reload that changes nothing here keeps every pooled upstream connection.
func SetConfiguredTimeouts ¶
func SetConfiguredTimeouts(timeoutSeconds, responseHeaderTimeoutSeconds int)
SetConfiguredTimeouts installs the config-file (`http:` block) timeout defaults, in seconds. App startup calls this once before providers are constructed. The HTTP_TIMEOUT / HTTP_RESPONSE_HEADER_TIMEOUT env vars still take precedence, matching the project-wide env-over-YAML convention. Non-positive values clear the configured default.
func StreamIdleTimeout ¶ added in v0.1.93
StreamIdleTimeout resolves the stream idle timeout, highest precedence first: the HTTP_STREAM_IDLE_TIMEOUT env var (seconds or Go duration), the config-file value, then DefaultStreamIdleTimeout. Zero means disabled.
Types ¶
type ClientConfig ¶
type ClientConfig struct {
// MaxIdleConns controls the maximum number of idle (keep-alive) connections across all hosts
MaxIdleConns int
// MaxIdleConnsPerHost controls the maximum idle (keep-alive) connections to keep per-host
MaxIdleConnsPerHost int
// IdleConnTimeout is the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself
IdleConnTimeout time.Duration
// Timeout specifies a time limit for requests made by the client
Timeout time.Duration
// DialTimeout is the maximum amount of time a dial will wait for a connect to complete
DialTimeout time.Duration
// KeepAlive specifies the interval between keep-alive probes for an active network connection
KeepAlive time.Duration
// TLSHandshakeTimeout specifies the maximum amount of time to wait for a TLS handshake
TLSHandshakeTimeout time.Duration
// ResponseHeaderTimeout specifies the amount of time to wait for a server's response headers
ResponseHeaderTimeout time.Duration
// Proxy selects the outbound proxy for each request. Nil keeps the
// process-wide HTTP_PROXY / HTTPS_PROXY / NO_PROXY behaviour; a function
// returning nil sends that request directly.
Proxy func(*http.Request) (*url.URL, error)
}
ClientConfig holds configuration options for creating HTTP clients
func DefaultConfig ¶
func DefaultConfig() ClientConfig
DefaultConfig returns a ClientConfig with sensible defaults for API clients. Timeout values match OpenAI/Anthropic SDK defaults (10 minutes). Precedence for the two request timeouts, highest first:
- HTTP_TIMEOUT / HTTP_RESPONSE_HEADER_TIMEOUT env vars (seconds, or Go duration format)
- the config-file `http:` block installed via SetConfiguredTimeouts
- the built-in 600s default
type TLSSettings ¶ added in v0.2.0
type TLSSettings struct {
// CAFile is a PEM bundle appended to the system trust store. Use it for a
// private CA that signs local model servers or a TLS-intercepting proxy.
CAFile string
// ClientCertFile and ClientKeyFile present a client certificate (mTLS) to
// every upstream that asks for one. Both must be set together.
ClientCertFile string
ClientKeyFile string
// InsecureSkipVerify disables certificate verification entirely. It is
// meant for a lab, never for production; the gateway logs a warning.
InsecureSkipVerify bool
}
TLSSettings is the process-wide client TLS trust configuration for the outbound HTTPS clients built from this package: providers, the model catalog, the update check, MCP upstreams, vector stores, and embedding endpoints. Clients built elsewhere, such as the OTLP exporters and the PostgreSQL, MongoDB, and Redis drivers, keep their own TLS settings.
Everything is optional. With the zero value, connections trust the operating system's certificate store, which is what most deployments want.
type TLSSnapshot ¶ added in v0.2.0
type TLSSnapshot struct {
// contains filtered or unexported fields
}
TLSSnapshot is an opaque handle to the installed configuration, taken with SnapshotTLS and given back to RestoreTLS. A reload that fails after installing replacement settings uses it to put the serving generation's trust back. Because every transport re-checks the installed configuration per request, the rollback also reaches clients that were created while the rejected settings were installed.
func SnapshotTLS ¶ added in v0.2.0
func SnapshotTLS() TLSSnapshot
SnapshotTLS captures the currently installed configuration.
Source Files