Documentation
¶
Overview ¶
Package transport is a generic, connection-bound HTTP client for the inference seam. It composes an transport.Endpoint (connection identity), an route.Router (request routing), an codec.Codec (request encoding + response decoding), an OPTIONAL codec.StreamDecoder (streaming), and an auth.Authenticator (credentials) into an inference.Client. It owns HTTP mechanics only: it does not hardcode a method, a chat path, a Content-Type, a streaming Accept header, or a stream framing such as SSE — the Router supplies method+URL+route headers, the encoder supplies the body and its headers, and the StreamDecoder owns wire framing.
Index ¶
- Constants
- type Client
- func (c *Client) Invoke(ctx context.Context, req inference.Request) (*inference.Response, error)
- func (c *Client) InvokeWithAuth(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*inference.Response, error)
- func (c *Client) InvokeWithAuthorizer(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*inference.Response, error)
- func (c *Client) Stream(ctx context.Context, req inference.Request) (*stream.StreamReader[content.Chunk], error)
- func (c *Client) StreamWithAuth(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*stream.StreamReader[content.Chunk], error)
- func (c *Client) StreamWithAuthorizer(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*stream.StreamReader[content.Chunk], error)
- type Endpoint
- type Option
- type RequestBuildError
- type UnsupportedStreamingError
Constants ¶
const ( // MaxResponseBodyBytes bounds an atomic successful Invoke response before // handing it to a codec. Streaming bodies remain owned by their decoder. MaxResponseBodyBytes = 16 << 20 // MaxErrorResponseBodyBytes bounds transient non-2xx parsing. The body is // never retained by failure.APIError. MaxErrorResponseBodyBytes = 64 << 10 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a connection-bound inference.Client: one Codec x one Endpoint x one Router x one Authenticator, with an optional StreamDecoder. It performs the same ordered pre-I/O guards for both Invoke and Stream — binding check, then Model.Validate — then routes, encodes, authorizes, and executes, mapping transport failures to *failure.NetworkError and non-2xx responses to *failure.APIError.
func New ¶
func New(ep Endpoint, router route.Router, cdc codec.Codec, authenticator auth.Authenticator, opts ...Option) *Client
New constructs a Client bound to ep, routing with router, encoding/decoding with codec, authenticating with auth. It is the source-compatible wrapper around NewWithAuth. If codec also satisfies codec.StreamDecoder (i.e. is a StreamingCodec), it becomes the stream decoder automatically; otherwise streaming fails before I/O with *UnsupportedStreamingError unless WithStreamDecoder supplies one. router, codec, and auth are required: a nil is a programmer error (the explicit "no credentials" value is auth.None()), so New panics rather than sending unrouted, unencoded, or silently unauthenticated requests.
func NewWithAuth ¶
NewWithAuth constructs a connection-bound client for call-scoped authorization. The optional arguments may contain a default httpauth.Authorizer (for compatibility with callers that still invoke Invoke/Stream directly) and/or Option values. With no default authorizer, use InvokeWithAuth or StreamWithAuth for every request. The variadic shape keeps this additive constructor compatible with both forms during the migration; invalid arguments panic like the legacy constructor's nil checks.
func NewWithAuthorizer ¶
func NewWithAuthorizer(ep Endpoint, router route.Router, cdc codec.Codec, authorizer httpauth.Authorizer, opts ...Option) *Client
NewWithAuthorizer is the typed constructor spelling for new code that wants a legacy default in addition to call-scoped methods.
func (*Client) Invoke ¶
Invoke sends a non-streaming request using the legacy constructor's default authorizer. New credential-backed callers should use InvokeWithAuth so a lease is applied to this concrete request attempt.
func (*Client) InvokeWithAuth ¶
func (c *Client) InvokeWithAuth(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*inference.Response, error)
InvokeWithAuth sends one non-streaming request with a call-scoped authorizer. The request is built from scratch before authorization, so no header or body from a previous attempt can accumulate on this attempt.
func (*Client) InvokeWithAuthorizer ¶
func (c *Client) InvokeWithAuthorizer(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*inference.Response, error)
InvokeWithAuthorizer is a descriptive alias for InvokeWithAuth.
func (*Client) Stream ¶
func (c *Client) Stream(ctx context.Context, req inference.Request) (*stream.StreamReader[content.Chunk], error)
Stream sends a streaming request using the legacy constructor's default authorizer. New credential-backed callers should use StreamWithAuth.
func (*Client) StreamWithAuth ¶
func (c *Client) StreamWithAuth(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*stream.StreamReader[content.Chunk], error)
StreamWithAuth sends one streaming request with a call-scoped authorizer. Error responses are bounded and sanitized before returning.
func (*Client) StreamWithAuthorizer ¶
func (c *Client) StreamWithAuthorizer(ctx context.Context, req inference.Request, authorizer httpauth.Authorizer) (*stream.StreamReader[content.Chunk], error)
StreamWithAuthorizer is a descriptive alias for StreamWithAuth.
type Endpoint ¶
type Endpoint struct {
BaseURL string
Provider model.ProviderName
APIFormat model.APIFormat
}
Endpoint is explicit client-binding metadata for one connection.
type Option ¶
type Option func(*Client)
Option customizes a Client at construction.
func WithInvokeTimeout ¶
WithInvokeTimeout overrides Invoke's whole-request timeout (default defaultInvokeTimeout). It has no effect on Stream, which never carries a whole-request timeout. A non-positive d is a no-op — the default (or a prior WithInvokeTimeout) is left in place — since a zero or negative timeout would mean "never time out" or "always time out", neither of which this option is meant to express.
func WithRoundTripper ¶
func WithRoundTripper(rt http.RoundTripper) Option
WithRoundTripper installs the exact caller-supplied RoundTripper on both the invoke and stream HTTP clients. The caller retains ownership: this option neither clones nor closes the RoundTripper, and the value must be safe for concurrent use by both clients. It must also enforce the caller's desired TLS verification policy itself; supplying this option replaces the library-created transport (and therefore its dialing, pooling, and TLS defaults) rather than wrapping it.
A nil RoundTripper panics during option construction so a caller cannot silently fall back to the process-wide default transport.
func WithStreamDecoder ¶
func WithStreamDecoder(sd codec.StreamDecoder) Option
WithStreamDecoder sets or overrides the Client's StreamDecoder. Use it to enable streaming for a plain Codec, or to route streaming through a caller-supplied decoder (e.g. an NDJSON- or custom-framer-backed decoder) different from the codec's own.
func WithTLSRootCAs ¶
WithTLSRootCAs installs a cloned, non-empty trust pool on the library-owned invoke and stream transports. It does not replace dialing, proxy, TLS minimum-version, pooling, timeout, or redirect policy. The caller must populate the pool with the roots it intends to trust before construction. If WithRoundTripper is also supplied, that caller-owned transport remains in use and is responsible for its own TLS verification policy.
type RequestBuildError ¶
type RequestBuildError struct {
Err error
}
RequestBuildError is a failure to CONSTRUCT the outbound request — a router that cannot build a route, or a malformed method/URL. It is a request-configuration error, kept strictly distinct from *failure.NetworkError (reserved for hc.Do transport failures) so errors.As never misclassifies a config bug as a transport fault. Unwrap exposes the underlying cause (e.g. a route.MissingModelError or a net/http error).
func (*RequestBuildError) Error ¶
func (e *RequestBuildError) Error() string
func (*RequestBuildError) Unwrap ¶
func (e *RequestBuildError) Unwrap() error
type UnsupportedStreamingError ¶
UnsupportedStreamingError is returned by Stream, before any I/O, when the Client has no StreamDecoder (the codec is a plain Codec, not a StreamingCodec, and no decoder was injected). Fail-closed and typed so callers can errors.As it. APIFormat records the bound endpoint's format for diagnosis.
func (*UnsupportedStreamingError) Error ¶
func (e *UnsupportedStreamingError) Error() string
Source Files