Documentation
¶
Index ¶
- Constants
- Variables
- func AuthorizeWebsocketTurn(ctx context.Context, payload []byte) ([]byte, error)
- func BindExecutionResource(opts Options, closer io.Closer) error
- func DownstreamWebsocket(ctx context.Context) bool
- func IsConfiguredTLSHandshakeTimeoutError(err error) bool
- func IsUpstreamWebsocketReplayRequired(err error) bool
- func IsUpstreamWebsocketTurnError(err error) bool
- func LocalWebsocketTurnExecuted(ctx context.Context) bool
- func MarkLocalWebsocketTurn(ctx context.Context)
- func MarkUpstreamAttempt(ctx context.Context)
- func NewConfiguredTLSHandshakeTimeoutError(cause error) error
- func NewUpstreamWebsocketReplayRequiredError() error
- func NotifyWebsocketInputLoss(ctx context.Context)
- func RequestProxyURL(ctx context.Context) string
- func RequiredUpstreamWebsocket(ctx context.Context) bool
- func ResetLocalWebsocketTurn(ctx context.Context)
- func ResponseFormatOrSource(opts Options) sdktranslator.Format
- func UpstreamAttempted(ctx context.Context) bool
- func WebsocketAuthEnabled(ctx context.Context, authID string) bool
- func WebsocketInputFromContext(ctx context.Context) <-chan WebsocketInput
- func WebsocketInputLossError(ctx context.Context) error
- func WebsocketInputPredatesLoss(ctx context.Context) bool
- func WithDownstreamWebsocket(ctx context.Context) context.Context
- func WithLocalWebsocketTurnTracker(ctx context.Context) context.Context
- func WithRequestProxyURL(ctx context.Context, proxyURL string) context.Context
- func WithRequiredUpstreamWebsocket(ctx context.Context) context.Context
- func WithUpstreamAttemptTracker(ctx context.Context) context.Context
- func WithWebsocketAuthCheck(ctx context.Context, check func(string) bool) context.Context
- func WithWebsocketInput(ctx context.Context, input <-chan WebsocketInput) context.Context
- func WithWebsocketInputEpoch(ctx context.Context, epoch *atomic.Uint64, messageEpoch uint64) context.Context
- func WithWebsocketTurnAuthorizer(ctx context.Context, authorize func([]byte) ([]byte, error)) context.Context
- func WithoutRequestProxyURL(ctx context.Context) context.Context
- type ConfiguredTLSHandshakeTimeoutError
- type ExecutionLifecycle
- type Options
- type Request
- type RequestAfterAuthInterceptRequest
- type RequestAfterAuthInterceptResponse
- type RequestAfterAuthInterceptor
- type RequestBeforeAuthInterceptor
- type RequestScopedError
- type RequestTerminatedError
- type Response
- type StatusError
- type StreamChunk
- type StreamResult
- type StreamTruncatedError
- type TransientRateLimitError
- type UpstreamWebsocketReplayRequiredError
- type UpstreamWebsocketTurnError
- type WebSocketResponseEvent
- type WebSocketResponseObserver
- type WebsocketInput
Constants ¶
const ( // PinnedAuthMetadataKey locks execution to a specific auth ID. PinnedAuthMetadataKey = "pinned_auth_id" // SelectionIDMetadataKey stores the per-selection ID generated for a plugin scheduler pick. SelectionIDMetadataKey = "selection_id" // SelectedAuthMetadataKey stores the auth ID selected by the scheduler. SelectedAuthMetadataKey = "selected_auth_id" // SelectedAuthCallbackMetadataKey carries an optional callback invoked with the selected auth ID. SelectedAuthCallbackMetadataKey = "selected_auth_callback" // SelectedAuthIndexMetadataKey stores the stable index of the auth selected by the scheduler. SelectedAuthIndexMetadataKey = "selected_auth_index" // SelectedAuthIndexCallbackMetadataKey carries an optional callback invoked with the selected auth index. SelectedAuthIndexCallbackMetadataKey = "selected_auth_index_callback" // FinalizedResponseFormatCallbackMetadataKey carries an optional callback invoked with the effective response_format after payload rules. FinalizedResponseFormatCallbackMetadataKey = "finalized_response_format_callback" // ExecutionSessionMetadataKey identifies a long-lived downstream execution session. ExecutionSessionMetadataKey = "execution_session_id" // DerivedSessionIDMetadataKey stores a stable session identity inferred from request context. // It may be used to derive a provider session identity. DerivedSessionIDMetadataKey = "derived_session_id" // LCPAffinitySessionIDMetadataKey stores an LCP-only routing identity. Executors // must not use it as a provider conversation or execution-session identity. The // current phase also keeps it out of SessionTree topology until downstream wiring exists. LCPAffinitySessionIDMetadataKey = "lcp_affinity_session_id" // CanonicalSessionIDMetadataKey stores the single unified session identity reconciled // across explicit harness headers, body fields, execution sessions, LCP inference, // and fallback context derivation for unified debugging and cross-subsystem tracing. CanonicalSessionIDMetadataKey = "canonical_session_id" // ParentSessionIDMetadataKey stores the parent session identity for hierarchical sessions and forks. // For top-level Merkle LCP forks, it represents the deterministic Merkle prefix hash at the divergence point. ParentSessionIDMetadataKey = "parent_session_id" // IsForkMetadataKey indicates whether the request represents a conversational branch or fork. IsForkMetadataKey = "is_fork" // IsCompactionMetadataKey indicates whether the request represents a context compaction continuation. IsCompactionMetadataKey = "is_compaction" // NodeKindMetadataKey indicates the session DAG topology kind ("compaction", "fork", or "trunk"). NodeKindMetadataKey = "node_kind" // LCPTailFingerprintsMetadataKey stores the actual trailing turn fingerprints for context compaction matching. LCPTailFingerprintsMetadataKey = "lcp_tail_fingerprints" // LCPEnvironmentDigestMetadataKey stores the environment digest across all system and developer instructions. LCPEnvironmentDigestMetadataKey = "lcp_environment_digest" // LCPAccessGenerationMetadataKey stores the monotonic access generation when an LCP entry was touched or bound. LCPAccessGenerationMetadataKey = "lcp_access_generation" // LCPFingerprintMetadataKey stores bounded request-scoped turn fingerprints so // SessionAffinitySelector.OnResult can avoid reparsing the original payload. LCPFingerprintMetadataKey = "lcp_fingerprints" // LCPMinPrefixLengthMetadataKey stores the minimum eligible prefix boundary for // the bounded LCP fingerprint sequence. LCPMinPrefixLengthMetadataKey = "lcp_min_prefix_length" // CallerScopeMetadataKey isolates inferred session identities between downstream callers. CallerScopeMetadataKey = "caller_scope" // SessionAffinityProviderMetadataKey carries the affinity selection namespace // (provider string, e.g. the literal "mixed" pool key) used by SessionAffinitySelector.Pick, // so OnResult keys the session cache identically to how selection read it. SessionAffinityProviderMetadataKey = "session_affinity_provider" // SessionAffinityModelMetadataKey carries the model used during session affinity selection. SessionAffinityModelMetadataKey = "session_affinity_model" )
const AuthSelectionModelMetadataKey = "auth_selection_model"
AuthSelectionModelMetadataKey overrides the model used only for auth selection.
const DisallowFreeAuthMetadataKey = "disallow_free_auth"
DisallowFreeAuthMetadataKey instructs auth selection to skip known free-tier credentials.
const GenerateMetadataKey = "generate"
GenerateMetadataKey stores whether the client requested actual generation for usage logs. Missing or true means generation is enabled; only an explicit false disables generation.
const ReasoningEffortMetadataKey = "reasoning_effort"
ReasoningEffortMetadataKey stores the client-requested reasoning effort for usage logs.
const RequestPathMetadataKey = "request_path"
RequestPathMetadataKey stores the inbound HTTP request path (e.g. "/v1/images/generations") in Options.Metadata. It is optional and may be absent for non-HTTP executions.
const RequestedModelMetadataKey = "requested_model"
RequestedModelMetadataKey stores the client-requested model name in Options.Metadata.
const ServiceTierMetadataKey = "service_tier"
ServiceTierMetadataKey stores the client-requested service tier for usage logs.
Variables ¶
var ErrNoActiveUpstreamWebsocket = errors.New("no active upstream websocket for response.interrupt")
ErrNoActiveUpstreamWebsocket means response.interrupt has no live upstream socket.
var ErrUpstreamWebsocketInterruptRejected = errors.New("response.interrupt does not target the active upstream response")
ErrUpstreamWebsocketInterruptRejected means a live upstream socket owns the current turn, but response.interrupt does not target its running response (unknown id, or that response already finished). Handlers must reject the frame outright and must not fall back to local cancellation, which would cancel a healthy websocket turn.
Functions ¶
func AuthorizeWebsocketTurn ¶ added in v8.0.39
func BindExecutionResource ¶
BindExecutionResource binds a closer to the execution lifecycle.
func DownstreamWebsocket ¶
DownstreamWebsocket reports whether the current request originates from a downstream websocket connection.
func IsConfiguredTLSHandshakeTimeoutError ¶ added in v8.0.29
IsConfiguredTLSHandshakeTimeoutError reports whether err is exclusively explained by configured TLS handshake deadlines.
Every context.Canceled or context.DeadlineExceeded occurrence in the error tree must be contained in a ConfiguredTLSHandshakeTimeoutError subtree, and at least one configured timeout subtree must itself contain a deadline. A caller-owned cancellation or deadline anywhere outside such a subtree therefore wins, including when it is combined with a configured timeout through errors.Join. Matching error text is never sufficient on its own.
func IsUpstreamWebsocketReplayRequired ¶
IsUpstreamWebsocketReplayRequired reports whether err is the internal replay signal.
func IsUpstreamWebsocketTurnError ¶ added in v8.0.45
IsUpstreamWebsocketTurnError reports whether err is a recoverable upstream websocket loss.
func LocalWebsocketTurnExecuted ¶ added in v8.0.64
LocalWebsocketTurnExecuted reports whether the current downstream websocket turn was fulfilled locally rather than on an upstream websocket.
func MarkLocalWebsocketTurn ¶ added in v8.0.64
MarkLocalWebsocketTurn records that the current downstream websocket turn was answered locally without creating an upstream websocket response.
func MarkUpstreamAttempt ¶
MarkUpstreamAttempt records that the provider execution reached an upstream transport boundary.
func NewConfiguredTLSHandshakeTimeoutError ¶ added in v8.0.29
NewConfiguredTLSHandshakeTimeoutError wraps the handshake failure that resulted from an internally configured TLS handshake deadline.
func NewUpstreamWebsocketReplayRequiredError ¶
func NewUpstreamWebsocketReplayRequiredError() error
NewUpstreamWebsocketReplayRequiredError creates a request-scoped replay signal.
func NotifyWebsocketInputLoss ¶ added in v8.0.45
NotifyWebsocketInputLoss advances the session's loss epoch if present.
func RequestProxyURL ¶
RequestProxyURL returns the execution-scoped proxy override, or empty when unset.
func RequiredUpstreamWebsocket ¶
RequiredUpstreamWebsocket reports whether falling back to an HTTP upstream would lose request context.
func ResetLocalWebsocketTurn ¶ added in v8.0.64
ResetLocalWebsocketTurn clears the local websocket turn marker before a new auth attempt.
func ResponseFormatOrSource ¶
func ResponseFormatOrSource(opts Options) sdktranslator.Format
ResponseFormatOrSource returns the response target format for an execution.
func UpstreamAttempted ¶
UpstreamAttempted reports whether the tracked provider execution reached an upstream transport boundary.
func WebsocketInputFromContext ¶
func WebsocketInputFromContext(ctx context.Context) <-chan WebsocketInput
func WebsocketInputLossError ¶ added in v8.0.45
WebsocketInputLossError returns the turn error for a downstream websocket frame whose input epoch predates the latest upstream connection loss.
func WebsocketInputPredatesLoss ¶ added in v8.0.45
WebsocketInputPredatesLoss reports whether the current turn's input was read before an upstream websocket loss.
func WithDownstreamWebsocket ¶
WithDownstreamWebsocket marks the current request as coming from a downstream websocket connection.
func WithLocalWebsocketTurnTracker ¶ added in v8.0.64
WithLocalWebsocketTurnTracker installs a tracker that records when a downstream websocket turn was fulfilled locally over HTTP rather than establishing or owning an upstream websocket response.
func WithRequestProxyURL ¶
WithRequestProxyURL replaces the execution-scoped proxy override. An empty proxy clears any override inherited from the parent context.
func WithRequiredUpstreamWebsocket ¶
WithRequiredUpstreamWebsocket marks a request whose incremental context is valid only on the current upstream websocket.
func WithUpstreamAttemptTracker ¶
WithUpstreamAttemptTracker installs a fresh tracker for one provider execution attempt.
func WithWebsocketAuthCheck ¶
func WithWebsocketInput ¶
func WithWebsocketInput(ctx context.Context, input <-chan WebsocketInput) context.Context
func WithWebsocketInputEpoch ¶ added in v8.0.45
func WithWebsocketInputEpoch(ctx context.Context, epoch *atomic.Uint64, messageEpoch uint64) context.Context
WithWebsocketInputEpoch attaches the session's loss epoch counter and the current message's read epoch so executors can advance the epoch on upstream loss and reject messages that were read before an upstream loss.
func WithWebsocketTurnAuthorizer ¶ added in v8.0.39
func WithWebsocketTurnAuthorizer(ctx context.Context, authorize func([]byte) ([]byte, error)) context.Context
WithWebsocketTurnAuthorizer supplies a per-turn frontend access check for follow-up response.create and response.append frames on a duplex socket. Returning a non-empty error payload rejects the turn while keeping the socket open.
Types ¶
type ConfiguredTLSHandshakeTimeoutError ¶ added in v8.0.29
type ConfiguredTLSHandshakeTimeoutError struct {
// contains filtered or unexported fields
}
ConfiguredTLSHandshakeTimeoutError identifies a TLS handshake failure caused by an internally configured establishment bound rather than by the caller's request context. Transports construct it only after they have established that the parent context was still live and their own handshake child context expired.
The concrete type is deliberately shared through this neutral executor package so both transport helpers and auth retry classification can recognize it without importing each other or trusting error text.
func (*ConfiguredTLSHandshakeTimeoutError) Error ¶ added in v8.0.29
func (e *ConfiguredTLSHandshakeTimeoutError) Error() string
func (*ConfiguredTLSHandshakeTimeoutError) Unwrap ¶ added in v8.0.29
func (e *ConfiguredTLSHandshakeTimeoutError) Unwrap() error
Unwrap preserves the original handshake error chain, including context.DeadlineExceeded, for diagnostics and errors.Is checks.
type ExecutionLifecycle ¶
ExecutionLifecycle owns resources associated with an execution attempt.
type Options ¶
type Options struct {
// Stream toggles streaming mode.
Stream bool
// Alt carries optional alternate format hint (e.g. SSE JSON key).
Alt string
// Headers are forwarded to the provider request builder.
Headers http.Header
// Query contains optional query string parameters.
Query url.Values
// OriginalRequest preserves the inbound request bytes prior to translation.
OriginalRequest []byte
// SourceFormat identifies the inbound schema.
SourceFormat sdktranslator.Format
// ResponseFormat identifies the downstream response schema.
// Empty means responses should use SourceFormat for backward compatibility.
ResponseFormat sdktranslator.Format
// Metadata carries extra execution hints shared across selection and executors.
Metadata map[string]any
// RequestBeforeAuthInterceptor runs before after-auth interception on bound follow-up turns.
RequestBeforeAuthInterceptor RequestBeforeAuthInterceptor
// RequestAfterAuthInterceptor runs after credential selection and before executor translation.
RequestAfterAuthInterceptor RequestAfterAuthInterceptor
// WebSocketResponseObserver receives upstream WebSocket response events during execution.
WebSocketResponseObserver WebSocketResponseObserver
// ExecutionLifecycle owns Home-dispatched execution resources. Executors must not add it to request metadata.
ExecutionLifecycle ExecutionLifecycle
// ProxyURL overrides the credential and global proxy for this execution only.
// Credential refresh and token exchange must ignore it.
ProxyURL string
// KeepTopLevelEffort tells SIWC request-body rules to keep the resolved
// top-level reasoning.effort when configuration_update items are collapsed.
KeepTopLevelEffort bool
}
Options controls execution behavior for both streaming and non-streaming calls.
func (*Options) EnsureMetadata ¶
EnsureMetadata initializes and returns Metadata, ensuring it is non-nil.
type Request ¶
type Request struct {
// Model is the upstream model identifier after translation.
Model string
// Payload is the provider specific JSON payload.
Payload []byte
// Format represents the provider payload schema.
Format sdktranslator.Format
// Metadata carries optional provider specific execution hints.
Metadata map[string]any
}
Request encapsulates the translated payload that will be sent to a provider executor.
type RequestAfterAuthInterceptRequest ¶
type RequestAfterAuthInterceptRequest struct {
// SourceFormat is the original client protocol format.
SourceFormat sdktranslator.Format
// ToFormat is the selected upstream protocol format.
ToFormat sdktranslator.Format
// Model is the selected upstream model for this attempt.
Model string
// RequestedModel is the client-requested model before alias/model-pool rewriting.
RequestedModel string
// Stream reports whether the request expects streaming output.
Stream bool
// Headers contains the current upstream request headers.
Headers http.Header
// Body contains the current request payload. Treat it as read-only; modifications must be returned in RequestAfterAuthInterceptResponse.Body.
Body []byte
// Metadata is a best-effort cloned context snapshot. Treat it as read-only and JSON-like.
Metadata map[string]any
}
RequestAfterAuthInterceptRequest describes a selected-auth request before executor translation.
type RequestAfterAuthInterceptResponse ¶
type RequestAfterAuthInterceptResponse struct {
// Path optionally overrides the inbound request path in Options.Metadata[RequestPathMetadataKey].
Path string
// Headers replaces matching current request headers and preserves headers not mentioned here.
Headers http.Header
// Body replaces the current request body only when non-empty.
Body []byte
// ClearHeaders explicitly removes current request headers before Headers is applied.
ClearHeaders []string
// Terminate prevents the selected executor from receiving the request.
Terminate bool
// StatusCode is the downstream HTTP status used when Terminate is true.
StatusCode int
// ResponseHeaders contains downstream response headers used when Terminate is true.
ResponseHeaders http.Header
// ResponseBody contains the downstream response body used when Terminate is true.
ResponseBody []byte
}
RequestAfterAuthInterceptResponse returns selected-auth request modifications.
type RequestAfterAuthInterceptor ¶
type RequestAfterAuthInterceptor func(context.Context, RequestAfterAuthInterceptRequest) RequestAfterAuthInterceptResponse
RequestAfterAuthInterceptor rewrites a request after credential selection and before executor translation.
type RequestBeforeAuthInterceptor ¶ added in v8.0.47
type RequestBeforeAuthInterceptor func(context.Context, RequestAfterAuthInterceptRequest) RequestAfterAuthInterceptResponse
RequestBeforeAuthInterceptor rewrites a follow-up request on a bound session before after-auth interception.
type RequestScopedError ¶
RequestScopedError identifies a failure tied to the current request rather than the selected credential. Auth managers should not retry these errors across credentials or change credential availability because of them.
type RequestTerminatedError ¶
RequestTerminatedError carries a plugin-defined downstream response without executing upstream.
func (*RequestTerminatedError) Error ¶
func (e *RequestTerminatedError) Error() string
func (*RequestTerminatedError) ResponseBody ¶
func (e *RequestTerminatedError) ResponseBody() []byte
ResponseBody returns a copy of the plugin-defined downstream body.
func (*RequestTerminatedError) ResponseHeaders ¶
func (e *RequestTerminatedError) ResponseHeaders() http.Header
ResponseHeaders returns a copy of the plugin-defined downstream headers.
func (*RequestTerminatedError) StatusCode ¶
func (e *RequestTerminatedError) StatusCode() int
StatusCode returns the plugin-defined downstream HTTP status.
type Response ¶
type Response struct {
// Payload is the provider response in the executor format.
Payload []byte
// Incomplete reports that the upstream execution terminated in an incomplete state
// (e.g., response.incomplete) even if translated into a normal non-stream payload.
Incomplete bool
// Metadata exposes optional structured data for translators.
Metadata map[string]any
// Headers carries upstream HTTP response headers for passthrough to clients.
Headers http.Header
}
Response wraps either a full provider response or metadata for streaming flows.
type StatusError ¶
StatusError represents an error that carries an HTTP-like status code. Provider executors should implement this when possible to enable better auth state updates on failures (e.g., 401/402/429).
type StreamChunk ¶
type StreamChunk struct {
// Payload is the raw provider chunk payload.
Payload []byte
// Incomplete reports that the upstream stream ended in an incomplete terminal state
// (e.g., response.incomplete) even if protocol translation mapped it to a normal chunk.
Incomplete bool
// Err reports any terminal error encountered while producing chunks.
Err error
}
StreamChunk represents a single streaming payload unit emitted by provider executors.
type StreamResult ¶
type StreamResult struct {
// Headers carries upstream HTTP response headers from the initial connection.
Headers http.Header
// Chunks is the channel of streaming payload units.
Chunks <-chan StreamChunk
}
StreamResult wraps the streaming response, providing both the chunk channel and the upstream HTTP response headers captured before streaming begins.
type StreamTruncatedError ¶ added in v8.0.44
StreamTruncatedError identifies a locally synthesized failure for an accepted upstream stream that ended without its terminal frame. The upstream generation was already submitted, so auth managers must not cool the credential or replay the request on another credential because of it.
type TransientRateLimitError ¶ added in v8.0.45
TransientRateLimitError identifies a transient per-model capacity or admission rejection (for example a Codex turn_rate_limit_exceeded 429). The credential's plan quota is not exhausted, so auth managers must not record quota exhaustion or advance the quota exponential backoff for it. The rejecting model may still cool until any provider RetryAfter hint.
type UpstreamWebsocketReplayRequiredError ¶
type UpstreamWebsocketReplayRequiredError struct{}
UpstreamWebsocketReplayRequiredError indicates that an incremental request cannot safely continue because its upstream websocket is no longer reusable.
func (*UpstreamWebsocketReplayRequiredError) Error ¶
func (*UpstreamWebsocketReplayRequiredError) Error() string
func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped ¶
func (*UpstreamWebsocketReplayRequiredError) IsRequestScoped() bool
func (*UpstreamWebsocketReplayRequiredError) StatusCode ¶
func (*UpstreamWebsocketReplayRequiredError) StatusCode() int
type UpstreamWebsocketTurnError ¶ added in v8.0.45
type UpstreamWebsocketTurnError struct {
Cause error
// FullContextRequired marks a continuation (previous_response_id, append) that refers to
// the lost socket: nothing was sent, the client resends the full input.
FullContextRequired bool
// NotSent marks an operation that was never written upstream.
NotSent bool
EventID string
// Idle marks a loss with no running turn: only Abandoned is reported, if anything.
Idle bool
// Abandoned lists the other operations that lose their outcome with this turn.
Abandoned []*UpstreamWebsocketTurnError
}
UpstreamWebsocketTurnError ends one downstream websocket turn after the upstream websocket was lost. The downstream socket stays open and the turn is never replayed. Cause is kept for logging and is never sent to the client.
func (*UpstreamWebsocketTurnError) Error ¶ added in v8.0.45
func (e *UpstreamWebsocketTurnError) Error() string
func (*UpstreamWebsocketTurnError) IsRequestScoped ¶ added in v8.0.45
func (*UpstreamWebsocketTurnError) IsRequestScoped() bool
func (*UpstreamWebsocketTurnError) StatusCode ¶ added in v8.0.45
func (e *UpstreamWebsocketTurnError) StatusCode() int
func (*UpstreamWebsocketTurnError) Unwrap ¶ added in v8.0.45
func (e *UpstreamWebsocketTurnError) Unwrap() error
type WebSocketResponseEvent ¶
type WebSocketResponseEvent struct {
RequestID string
TraceID string
SourceFormat string
Model string
RequestedModel string
Provider string
AuthID string
AuthLabel string
AuthType string
EventType string
Payload []byte
Metadata map[string]any
}
WebSocketResponseEvent describes an upstream WebSocket response event received during execution.
type WebSocketResponseObserver ¶
type WebSocketResponseObserver func(context.Context, WebSocketResponseEvent)
WebSocketResponseObserver receives upstream WebSocket response events during execution.
type WebsocketInput ¶
type WebsocketInput struct {
Payload []byte
Err error
// Epoch is the downstream input epoch at read time; a loss advances it.
Epoch uint64
}
WebsocketInput is a frame from the single downstream reader. Err terminates the connection; Payload is owned by the receiver and must not be replayed.