Documentation
¶
Overview ¶
Package broker is the trusted host-mediated HTTP boundary for provider agents. Provider code never dials the network; it hands the host a structured request from an already-admitted plan action, and the broker re-derives the exact action, resource, origin, headers, and credentials from host-owned context before any bytes leave the machine. Provider descriptors are treated as adversarial: the action, resource, read-only intent, and origin the provider claims are all ignored in favor of what the host planned.
The broker never retries. It reports one of NOT_SENT, SENT_OUTCOME_UNKNOWN, or RESPONSE_RECEIVED so the coordinator can recover honestly, and it filters every response through the manifest response policy so secret-bearing fields are captured or suppressed rather than forwarded.
Index ¶
Constants ¶
const DefaultMaxRequestDuration = 10 * time.Minute
DefaultMaxRequestDuration bounds a round trip when no budget deadline is set. It is generous enough for a long model generation yet finite, so a stalled stream releases the session instead of blocking on it forever.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Checkpointer ¶
type Checkpointer interface {
Latest(ctx context.Context, operation *providerv0.OperationIdentity) (*providerv0.ActionCheckpoint, error)
}
Checkpointer reports the durable recovery checkpoint the coordinator persisted for an operation. The durable store itself is out of scope (F3); the broker depends only on this read-side to enforce checkpoint-before-send ordering.
type Config ¶
type Config struct {
Manifest *manifest.Manifest
Action *providerv0.PlanAction
Binding *providerv0.BindingAddress
Budget *providerv0.RequestBudget
ReadOnly bool
Vault *credentials.Vault
Sink responsepolicy.Sink
Checkpoints Checkpointer
Resolver *net.Resolver
Deadlines urlguard.Deadlines
UserAgent string
// Cassette, when set, records or replays this session's responses. Replay
// never touches the network; record stores only filtered safe responses.
Cassette *cassette.Cassette
// OnStreamEvent, when set, receives each filtered event of a streamed (SSE)
// response in order, as it is delivered live or replayed, before Execute
// returns. It is how a caller gets live tokens instead of only the fully
// buffered ordered set. A non-nil error from it fails the delivery closed.
OnStreamEvent func(*providerv0.FilteredEvent) error
// MaxRequestDuration bounds one round trip — including reading a streamed
// body — when the budget carries no absolute deadline. It exists so a slow or
// stalled stream cannot hold the session open indefinitely. Zero selects
// DefaultMaxRequestDuration.
MaxRequestDuration time.Duration
// ClientFor overrides guarded client construction. Production leaves it nil
// to use the SSRF-hardened urlguard client; tests inject a client bound to a
// local server.
ClientFor func(urlguard.Origin, urlguard.Resolution) *http.Client
// Now overrides the clock for deterministic tests.
Now func() time.Time
}
Config binds one broker session to exactly one admitted plan action. Every field is host-owned; the provider cannot override any of it.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is the per-action broker context. A session serializes its requests: budget, capture-gate, and delivery are inherently sequential, so Execute holds a session lock for the duration of each call.
func (*Session) Execute ¶
func (s *Session) Execute(ctx context.Context, request *providerv0.ExecuteRequestRequest) (*providerv0.ExecuteRequestResponse, error)
Execute runs one admitted broker request. It returns a filtered response and, on any admission or filtering failure, a non-nil error the coordinator treats as a hard stop. Original response bytes are never forwarded.
Source Files