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.
- ResponseHeaderTimeout is likewise unset because non-streaming LLM calls legitimately spend minutes before the first response byte.
- 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 ¶
- Variables
- 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 ¶
This section is empty.
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 ¶
This section is empty.
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
// 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
}
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.
Source Files