Documentation
¶
Overview ¶
Package httpx is the shared HTTP plumbing for provider adapters: a tuned transport, JSON request/response execution, SSE stream setup, an SSRF guard, and Retry-After parsing.
Design notes, mirrored from the package design doc:
- No http.Client.Timeout is ever set: it would cap the total time to read a response body and kill long streams. Callers bound requests with context deadlines instead.
- A streaming request is bounded in two places instead, and both live here rather than in an http.Client option so a bring-your-own client gets them too. Config.ResponseHeaderTimeout caps the wait for response headers, and Config.StreamIdleTimeout bounds the silence between reads on the body. Neither bounds the response's total duration, and a non-streaming call keeps no bound at all: it legitimately generates for minutes before its headers arrive. Without them a peer that accepts a request and then goes quiet parks the caller forever, and a caller parked on a read reports no error for any recovery layer to act on.
- The transport runs its own liveness checks, so a peer that stops answering is reported rather than parked: an HTTP/2 ping after a stretch of silence, a close when the ping goes unanswered, and explicit TCP keep-alive probes for a path that drops the connection's state.
- Every request carries a User-Agent naming this client and its build, so a gateway's logs can attribute the traffic. Config.UserAgent replaces that value, and a declared value that is empty sends no User-Agent header at all. An adapter or Config.Header entry that sets the header wins over both.
- By default the client refuses plain HTTP and connections to private, loopback, link-local, or unspecified addresses (SSRF guard). Local endpoints opt out via Config.
Index ¶
- Constants
- Variables
- func DefaultUserAgent() string
- type Client
- func (c *Client) GetJSON(ctx context.Context, path string, headers http.Header, out any, ...) ([]byte, error)
- func (c *Client) MaxStreamLineSize() int
- func (c *Client) PostJSON(ctx context.Context, path string, headers http.Header, body, out any, ...) ([]byte, error)
- func (c *Client) PostMultipart(ctx context.Context, path string, headers http.Header, fields []FormField, ...) ([]byte, error)
- func (c *Client) PostMultipartStream(ctx context.Context, path string, headers http.Header, fields []FormField, ...) (io.ReadCloser, error)
- func (c *Client) PostStream(ctx context.Context, path string, headers http.Header, body any, ...) (io.ReadCloser, error)
- type Config
- type ErrorDecoder
- type FormField
- type FormFile
Constants ¶
const ( // DefaultSendPingTimeout is how long an HTTP/2 connection may receive no // frame at all before the client pings it. DefaultSendPingTimeout = 30 * time.Second // DefaultPingTimeout closes an HTTP/2 connection whose ping goes // unanswered. DefaultPingTimeout = 10 * time.Second // DefaultTCPKeepAliveIdle is how long a connection may sit idle before the // kernel sends its first keep-alive probe. DefaultTCPKeepAliveIdle = 30 * time.Second // DefaultTCPKeepAliveInterval is the gap between those probes. DefaultTCPKeepAliveInterval = 10 * time.Second // DefaultTCPKeepAliveCount is how many probes may go unanswered before the // kernel drops the connection. DefaultTCPKeepAliveCount = 3 )
Liveness settings for the built-in transport. They exist so a peer that stops answering, or a path that forgets the connection, is reported as an error within about a minute rather than parking the caller until the operating system gives up, which on the common defaults runs to minutes.
const DefaultResponseHeaderTimeout = 10 * time.Minute
DefaultResponseHeaderTimeout caps how long a streaming call waits for its response headers unless Config.ResponseHeaderTimeout sets a bound of its own. A streaming peer returns headers in seconds — measured against a live gateway, in under four — so the bound only fires on a request the peer has parked without answering at all. Non-streaming calls keep no bound: they legitimately generate for minutes before their headers arrive.
const DefaultStreamIdleTimeout = ai.DefaultStreamIdleTimeout
DefaultStreamIdleTimeout bounds the silence between reads on a streaming response body unless Config.StreamIdleTimeout sets one of its own. It sits far above any provider's legitimate pause — measured against a live gateway, the longest silence was 4.5s to the first byte and 1.2s between chunks — so it only fires on a stream that has genuinely stopped delivering.
It is ai.DefaultStreamIdleTimeout, so the transport and any caller deriving policy from the bound share one number.
Variables ¶
var ErrPrivateAddress = errors.New("dial to private, loopback, or link-local address blocked (enable the allow-private-IPs option for local endpoints)")
ErrPrivateAddress is returned (wrapped) when the SSRF guard blocks a dial to a non-public address.
Functions ¶
func DefaultUserAgent ¶ added in v0.1.9
func DefaultUserAgent() string
DefaultUserAgent names this client and its build on every request, so a gateway's logs can attribute the traffic to pips instead of to an anonymous HTTP client. A build that carries no version reports "pips" alone.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client executes JSON and SSE requests against one provider endpoint. It is built once per adapter instance and is safe for concurrent use.
func New ¶
New builds a Client from cfg, falling back to defaultBaseURL when cfg.BaseURL is empty. Construction never fails; configuration errors surface on the first request.
func (*Client) GetJSON ¶
func (c *Client) GetJSON(ctx context.Context, path string, headers http.Header, out any, decodeErr ErrorDecoder) ([]byte, error)
GetJSON executes a GET request and decodes the 2xx response body into out. Non-2xx responses are passed to decodeErr. Task-based provider APIs use it to poll a previously submitted job.
func (*Client) MaxStreamLineSize ¶
MaxStreamLineSize exposes the configured SSE line ceiling for adapters.
func (*Client) PostJSON ¶
func (c *Client) PostJSON(ctx context.Context, path string, headers http.Header, body, out any, decodeErr ErrorDecoder) ([]byte, error)
PostJSON executes a JSON POST and decodes the 2xx response body into out. It returns the raw response bytes for Response.Raw. Non-2xx responses are passed to decodeErr.
func (*Client) PostMultipart ¶
func (c *Client) PostMultipart(ctx context.Context, path string, headers http.Header, fields []FormField, files []FormFile, out any, decodeErr ErrorDecoder) ([]byte, error)
PostMultipart executes a multipart/form-data POST and decodes the 2xx response body into out. The body is buffered in memory before sending so it can be replayed for retries; the caller bounds the payload size. Non-2xx responses are passed to decodeErr.
func (*Client) PostMultipartStream ¶
func (c *Client) PostMultipartStream(ctx context.Context, path string, headers http.Header, fields []FormField, files []FormFile, decodeErr ErrorDecoder) (io.ReadCloser, error)
PostMultipartStream executes a multipart/form-data POST expecting an SSE response and returns the response body ready for the sse package. Like Client.PostMultipart, the body is buffered in memory before sending. Non-2xx responses are fully read and passed to decodeErr.
func (*Client) PostStream ¶
func (c *Client) PostStream(ctx context.Context, path string, headers http.Header, body any, decodeErr ErrorDecoder) (io.ReadCloser, error)
PostStream executes a JSON POST expecting an SSE response and returns the response body ready for the sse package. Non-2xx responses are fully read and passed to decodeErr, so stream setup failures carry provider error details.
type Config ¶
type Config struct {
// APIKey is the provider credential. How it is sent (bearer header,
// x-api-key, x-goog-api-key) is up to the adapter's Authorize hook.
APIKey string
// BaseURL overrides the provider's default endpoint. It should include
// any version prefix (for example "https://api.openai.com/v1").
BaseURL string
// HTTPClient replaces the built-in client entirely. The bring-your-own
// client is used as-is: transport tuning and the SSRF dial guard are the
// owner's responsibility. Scheme checks still apply.
HTTPClient *http.Client
// Header is applied to every request. Adapter-set headers are written
// first, so Header entries override them on key collision.
Header http.Header
// UserAgent replaces the User-Agent every request carries. Nil sends
// DefaultUserAgent, an empty value sends no User-Agent header at all, and
// any other value is sent verbatim. A Header entry or an adapter-set
// User-Agent wins over all three.
UserAgent *string
// AllowHTTP permits plain-HTTP base URLs (local inference servers).
AllowHTTP bool
// AllowPrivateIPs disables the SSRF dial guard (local inference servers).
AllowPrivateIPs bool
// MaxStreamLineSize caps a single SSE line; zero selects the sse package
// default (1 MiB).
MaxStreamLineSize int
// StreamIdleTimeout bounds the silence between reads on a streaming
// response body; zero or negative selects DefaultStreamIdleTimeout. It
// applies to every streaming call, including one made through HTTPClient:
// the bound is not expressible as an http.Client option, so a bring-your-own
// client cannot supply it and this field stays the override.
StreamIdleTimeout time.Duration
// ResponseHeaderTimeout caps the wait for response headers on a streaming
// call; zero or negative selects DefaultResponseHeaderTimeout. Like the idle
// bound it is not expressible as an http.Client option, so a bring-your-own
// HTTPClient gets it too.
ResponseHeaderTimeout time.Duration
}
Config carries the transport-level options every provider constructor accepts. Provider option funcs write into it.
type ErrorDecoder ¶
ErrorDecoder turns a non-2xx response into an error. Adapters parse their provider's error body shape and build an *ai.Error; retryAfter is the parsed Retry-After header (zero when absent).
type FormField ¶
type FormField struct {
// Name is the multipart part name.
Name string
// Value is the field's text value.
Value string
}
FormField is one text field of a multipart/form-data request.
type FormFile ¶
type FormFile struct {
// Field is the multipart part name (for example "image[]").
Field string
// Name is the filename recorded in the part's Content-Disposition.
Name string
// ContentType is the part's media type. Empty omits the part header.
ContentType string
// Data is the part's body.
Data []byte
}
FormFile is one binary part of a multipart/form-data request. Part names and filenames are generated by the adapter, never copied from caller input.