Documentation
¶
Overview ¶
Package chain provides the SEP-compliant interceptor chain orchestrator. It discovers interceptors from MCP servers via "interceptors/list" and invokes them via "interceptor/invoke", implementing trust-boundary-aware execution ordering.
Execution Model ¶
Chain.Execute filters registered interceptors by event and phase, separates them into validators and mutators, and runs them in the SEP-defined order:
Request phase (untrusted → trusted):
Validate (parallel) → Mutate (sequential)
Response phase (trusted → untrusted):
Mutate (sequential) → Validate (parallel)
Usage ¶
A Chain is created with NewChain and populated by adding MCP servers via Chain.AddMCPServer:
chain := chain.NewChain()
chain.AddMCPServer(ctx, clientSession)
mcpServer.AddReceivingMiddleware(
gomiddleware.Middleware(chain),
)
For convenience, [extension.Extension.LocalChain] creates a chain pre-configured with a local in-process MCP server:
chain, err := ext.LocalChain(ctx, mcpServer)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AbortInfo ¶
type AbortInfo struct {
Interceptor string `json:"interceptor"`
Reason string `json:"reason"`
Type AbortType `json:"type"`
Phase string `json:"phase,omitempty"` // phase at which the abort occurred
}
AbortInfo describes where and why a chain was aborted.
type AbortType ¶
type AbortType string
AbortType classifies the reason an interceptor chain was aborted.
type Chain ¶
type Chain struct {
// contains filtered or unexported fields
}
Chain is the SEP-compliant interceptor chain orchestrator. It holds ChainEntry objects (interceptor descriptors + MCP server connections), discovers interceptors via interceptors/list, and invokes them via interceptor/invoke on the appropriate server.
func NewChain ¶
func NewChain(opts ...ChainOption) *Chain
NewChain creates a new Chain with optional configuration.
func (*Chain) AddMCPServer ¶
AddMCPServer discovers interceptors from an MCP server via interceptors/list and adds entries for each. The client session's transport determines how interceptor/invoke calls are made (in-memory, stdio, HTTP, etc.).
func (*Chain) Execute ¶
func (c *Chain) Execute(ctx context.Context, params *ExecutionParams) (*ExecutionResult, error)
Execute runs the chain for a given event and phase per the SEP execution model:
- Filter entries by event + phase
- Separate into validators and mutators
- Sort mutators by priorityHint (ascending, alphabetical tiebreak)
- Request phase: validate (parallel) then mutate (sequential)
- Response phase: mutate (sequential) then validate (parallel)
- Call interceptor/invoke via CallCustom for each entry
- For mutators: pass mutated payload from previous to next
- Handle abort, timeout, fail-open
type ChainEntry ¶
type ChainEntry struct {
Interceptor interceptors.InterceptorInfo
Server *mcp.ClientSession
}
ChainEntry pairs an interceptor descriptor with the MCP client session that hosts it.
type ChainOption ¶
type ChainOption func(*Chain)
ChainOption configures a Chain.
func WithChainLogger ¶
func WithChainLogger(l *slog.Logger) ChainOption
WithChainLogger sets the logger for chain execution. If not set, slog.Default() is used.
type ChainStatus ¶
type ChainStatus string
ChainStatus describes the outcome of a full interceptor chain execution.
const ( ChainSuccess ChainStatus = "success" ChainValidationFailed ChainStatus = "validation_failed" ChainMutationFailed ChainStatus = "mutation_failed" ChainTimeout ChainStatus = "timeout" )
type ExecutionParams ¶
type ExecutionParams struct {
Event string `json:"event"`
Phase interceptors.InterceptionPhase `json:"phase"`
Payload json.RawMessage `json:"payload"`
Interceptors []string `json:"interceptors,omitempty"` // optional: restrict to named interceptors
Config map[string]map[string]any `json:"config,omitempty"` // optional: per-interceptor config
TimeoutMs int64 `json:"timeoutMs,omitempty"`
Context *interceptors.InvocationContext `json:"context,omitempty"`
}
ExecutionParams configures a chain execution run. These are SDK-level types used by Chain.Execute, not wire-protocol types.
type ExecutionResult ¶
type ExecutionResult struct {
Status ChainStatus `json:"status"`
Event string `json:"event"`
Phase interceptors.InterceptionPhase `json:"phase"`
Results []interceptors.InvokeResult `json:"results"`
FinalPayload json.RawMessage `json:"finalPayload,omitempty"`
ValidationSummary ValidationSummary `json:"validationSummary"`
TotalDurationMs int64 `json:"totalDurationMs"`
AbortedAt []AbortInfo `json:"abortedAt,omitempty"`
}
ExecutionResult aggregates results from executing the full interceptor chain via interceptor/invoke RPCs.
type ValidationSummary ¶
type ValidationSummary struct {
Errors int `json:"errors"`
Warnings int `json:"warnings"`
Infos int `json:"infos"`
}
ValidationSummary counts validation outcomes.
Source Files