Documentation
¶
Overview ¶
Package callrun runs the tool-call handlers (#2436, #2634, #2635): a policy's decide(call) before a call, a transform's transform(call, result) on what it returns, and a watch's queued run after it succeeds. A policy and a transform run inline, read-only and time-limited, on the version an administrator approved for handlers, with that administrator's roles; their own calls are not evaluated by handlers.
Index ¶
- Constants
- func CallMap(c *callhandler.Call, h *callhandler.Handler) map[string]any
- func LateMiddleware(get func() *Evaluator) mcp.Middleware
- func Rendering(c *callhandler.Call) string
- func RequestFor(c *callhandler.Call, v Verdict, calls int, reason string) approval.CallRequest
- func RuntimeMiddleware(get func() *Runtime) mcp.Middleware
- type APIOperations
- type APIShapes
- type Approvals
- type Evaluator
- func (e *Evaluator) BuildCall(ctx context.Context, pc *middleware.PlatformContext, tool string, ...) *callhandler.Call
- func (e *Evaluator) Decide(ctx context.Context, c *callhandler.Call, callID string, dry bool) Verdict
- func (e *Evaluator) HeldRequest(ctx context.Context, held approval.HeldCall) (approval.CallRequest, error)
- func (e *Evaluator) Middleware() mcp.Middleware
- func (e *Evaluator) RecentCalls(ctx context.Context, db *sql.DB, r *approval.Request) ([]RecentCall, error)
- func (e *Evaluator) SetServer(s *mcp.Server)
- func (e *Evaluator) Start()
- func (e *Evaluator) Statement(ctx context.Context, st callhandler.Statement) (calltransform.Transformer, error)
- func (e *Evaluator) Test(ctx context.Context, req callhandler.TestRequest) (map[string]any, error)
- func (e *Evaluator) Transform(ctx context.Context, c *callhandler.Call, transforms []callhandler.Handler, ...) (map[string]any, []audit.HandlerRun, error)
- func (e *Evaluator) Watch(ctx context.Context, c *callhandler.Call) []string
- type RecentCall
- type Runtime
- type Scripts
- type Shape
- type Shapes
- type Store
- type Sweeper
- type TransformError
- type Verdict
- type WatchQueue
Constants ¶
const ( OutcomeAllow = "allow" OutcomeDeny = "deny" OutcomeApprove = "require_approval" OutcomeError = "error" OutcomeTransformed = "transformed" OutcomeOriginal = "original" OutcomeQueued = "queued" OutcomeAllowance = "allowance" )
The outcomes a handler's run is recorded under, on the audit row and the test panel.
const ( VerdictRuns = "runs" VerdictDenied = "denied" VerdictHeld = "held" )
The verdicts a call gets from its policies.
const ( CodePolicyDenied = "policy_denied" CodeApprovalRequired = "approval_required" CodeApprovalFiled = "approval_filed" CodeProtectedColumn = "protected_column" CodeTransformFailed = "transform_failed" CategoryPolicyDenied = "policy_denied" CategoryApproval = "approval_required" CategoryProtected = "protected_column" CategoryTransform = "transform_failed" )
The codes and categories a call a handler stopped answers with.
const ( RecentRan = "ran" RecentFailed = "failed" RecentHeld = "held" RecentRefused = "refused" RecentAllowance = "ran_on_allowance" )
The outcomes a recent call is shown with.
const DefaultLinger = 100 * time.Millisecond
DefaultLinger is how long a watch run waits for others to join its write.
const DefaultMaxQueued = 100
DefaultMaxQueued is how many runs one watch may have waiting; past it a call is recorded as skipped, as a webhook handler's backlog is bounded.
Variables ¶
This section is empty.
Functions ¶
func CallMap ¶
func CallMap(c *callhandler.Call, h *callhandler.Handler) map[string]any
CallMap is c as a handler's script is given it, with h's reading of its items and whether it writes.
func LateMiddleware ¶
func LateMiddleware(get func() *Evaluator) mcp.Middleware
LateMiddleware is Middleware for an evaluator assembled after the chain is registered: get is read on each call, and a call before it answers runs as if no handler existed.
func Rendering ¶
func Rendering(c *callhandler.Call) string
Rendering is the platform's own reading of a call, which an approver reads: what it addresses, how many items it carries, and its body as sent.
func RequestFor ¶
func RequestFor(c *callhandler.Call, v Verdict, calls int, reason string) approval.CallRequest
RequestFor is the request a held call files: the call as sent, the platform's reading of it, and what its policies asked.
func RuntimeMiddleware ¶
func RuntimeMiddleware(get func() *Runtime) mcp.Middleware
RuntimeMiddleware is LateMiddleware over a runtime read on each call.
Types ¶
type APIOperations ¶
type APIOperations interface {
OperationKey(ctx context.Context, connection, method, path, operationID string) string
ResolveOperationRequest(ctx context.Context, connection, operationID, spec string, pathParams map[string]string) (method, path string, ok bool)
OperationTemplate(ctx context.Context, connection, method, path string) string
}
APIOperations is what the api gateway answers about a call on one of its connections, read from its arguments without sending it (apigateway.Toolkit).
type APIShapes ¶
type APIShapes struct{ API APIOperations }
APIShapes reads an api call's shape through the gateway (#2436): the catalog operation (its id, else "METHOD template", else ""), the method, the path with an operation_id's parameters filled in, and the path's parameters by name. It is what a tool-call handler is matched against and given, before any stored secret is filled.
type Approvals ¶
type Approvals interface {
HandlerRunAs(ctx context.Context, scriptID string) (approval.RunAs, bool)
SpendAllowance(ctx context.Context, requester, connection, operation string) (string, bool)
SubmitCall(ctx context.Context, actor approval.Actor, in approval.CallRequest) (*approval.Request, error)
}
Approvals is what a handler's version and a held call are approved through (approval.Service).
type Evaluator ¶
type Evaluator struct {
Index *callhandler.Index
Store Store
Scripts Scripts
Approvals Approvals
// Shapes reads an api call's operation, by toolkit kind; nil reads none.
Shapes func(kind string) Shapes
// Limits are the platform run limits a handler's run starts from.
Limits scriptrun.PlatformLimits
// Watches queues a watch's runs; nil queues none.
Watches *WatchQueue
// Protect checks a covered caller's SQL against the columns transforms
// protect; nil refuses any statement on a connection a protecting
// transform covers, which fails closed.
Protect func(ctx context.Context, connection, sql string, protected map[string]string) error
// contains filtered or unexported fields
}
Evaluator runs the tool-call handlers.
func (*Evaluator) BuildCall ¶
func (e *Evaluator) BuildCall(ctx context.Context, pc *middleware.PlatformContext, tool string, args map[string]any) *callhandler.Call
BuildCall is what a handler is matched against and given for a tool call: its tool, connection and operation, its arguments as the caller sent them (a stored secret still a placeholder), its body read as the value it holds whether sent as an object or a string of JSON, and who calls.
func (*Evaluator) Decide ¶
func (e *Evaluator) Decide(ctx context.Context, c *callhandler.Call, callID string, dry bool) Verdict
Decide runs every policy that applies to c and combines what they decided: a deny beats a hold beats an allow. A held call an approved allowance covers runs, spending one call of it. A call that does not run counts against nobody. dry is the test panel's: nothing is counted, spent or recorded.
func (*Evaluator) HeldRequest ¶
func (e *Evaluator) HeldRequest(ctx context.Context, held approval.HeldCall) (approval.CallRequest, error)
HeldRequest is the request manage_approval submit files for a call the person was told is held: the policies are asked again, without counting, so the request names what held it and the platform's reading of the call. A call no policy holds is refused: it runs as it is, or no approval would change that it is refused.
func (*Evaluator) Middleware ¶
func (e *Evaluator) Middleware() mcp.Middleware
Middleware is the tools/call layer the handlers run in: inside authorization and the gates, inner to the result layers, so a policy only ever sees a call the caller's persona may make, and the result budget, call reference and enrichment see what the caller gets. A call no handler applies to pays one lookup in memory.
func (*Evaluator) RecentCalls ¶
func (e *Evaluator) RecentCalls(ctx context.Context, db *sql.DB, r *approval.Request) ([]RecentCall, error)
RecentCalls are the requester's calls of a call request's operation on its connection in the last day, from the audit record, each read as the handlers read it: its operation and its item count. A request that is not a call's has none.
func (*Evaluator) SetServer ¶
SetServer is the assembled MCP server a handler's run opens its session against; the server is built after the evaluator, so it is set late.
func (*Evaluator) Statement ¶
func (e *Evaluator) Statement(ctx context.Context, st callhandler.Statement) (calltransform.Transformer, error)
Statement puts a script's application database statement through the handlers (scriptsession.AppDBHandlers): the policies on its connection decide it, without anyone to ask, so a hold refuses it naming what holds it; a transform covering the run refuses a statement using a column it protects and changes the rows it returns. A statement no handler covers has no transformer.
func (*Evaluator) Test ¶
func (e *Evaluator) Test(ctx context.Context, req callhandler.TestRequest) (map[string]any, error)
Test is the test panel's answer for a call (#2436): every handler on the connection that would apply, in the order they run, what each would do, and the outcome the real call would get. The upstream is never called and no count or allowance is spent; a handler's own reads run.
func (*Evaluator) Transform ¶
func (e *Evaluator) Transform(ctx context.Context, c *callhandler.Call, transforms []callhandler.Handler, result map[string]any, dry bool) (map[string]any, []audit.HandlerRun, error)
Transform runs transforms over result in order and returns what the caller gets. A transform that fails fails the call, naming it, unless it chose to return what it was given. dry is the test panel's: nothing is recorded.
type RecentCall ¶
type RecentCall struct {
At time.Time `json:"at"`
Items int `json:"items"`
Outcome string `json:"outcome" example:"held"`
}
RecentCall is one of a requester's calls an approver reads beside a held call's request (#2437): when it was made, how many items it carried, and what came of it. Never its arguments.
type Runtime ¶
type Runtime struct {
Evaluator *Evaluator
DSN string
Sweeper Sweeper
// contains filtered or unexported fields
}
Runtime is the tool-call handlers' lifecycle on one replica: the index read before the first call and again on every change any replica announces, the watch writer, and the sweep.
type Scripts ¶
type Scripts interface {
GetByID(ctx context.Context, id string) (*script.Script, error)
GetVersion(ctx context.Context, scriptID string, version int) (*script.Version, error)
}
Scripts reads a handler's script and the version that runs.
type Shape ¶
Shape is what an api call addresses: its catalog operation, method, path and path parameters.
type Shapes ¶
type Shapes interface {
CallShape(ctx context.Context, connection string, args map[string]any) Shape
}
Shapes reads what an api call addresses (APIShapes).
type Store ¶
type Store interface {
Count(ctx context.Context, t callhandler.Tally) (int, error)
Release(ctx context.Context, callID string) error
RecordFailure(ctx context.Context, f callhandler.Failure) error
}
Store is where counts and failures are kept (callhandler.Store).
type TransformError ¶
TransformError is a transform that failed a call (#2634): its script, and what went wrong, which the caller is told.
func (*TransformError) Error ¶
func (e *TransformError) Error() string
func (*TransformError) Unwrap ¶
func (e *TransformError) Unwrap() error
type Verdict ¶
type Verdict struct {
Outcome string
// Reason and Handler are a refusal's: the deny's reason and the script
// that said it.
Reason string
Handler string
// Approvers and Asks are a hold's: who may approve it, merged across the
// policies that held it, and what each said.
Approvers []string
Asks []approval.HandlerAsk
// AllowanceID is the approved allowance a held call ran on.
AllowanceID string
Runs []audit.HandlerRun
}
Verdict is what a call's policies decided.
type WatchQueue ¶
type WatchQueue struct {
DB *sql.DB
MaxQueued int
// Linger is how long the writer waits after a run arrives for more to
// join its write (DefaultLinger): a burst of matched calls is then one
// transaction and one wake of the workers rather than one per call, so
// the writes compete less with the calls themselves. 0 writes at once.
Linger time.Duration
// contains filtered or unexported fields
}
WatchQueue writes the runs watches are owed off the request path (#2635): a matched call that succeeded hands its runs here and answers at once, and one writer stores them. A replica lost between the answer and the write loses the runs as it loses the call's audit row, which the audit writer buffers the same way.
func NewWatchQueue ¶
func NewWatchQueue(db *sql.DB, maxQueued int) *WatchQueue
NewWatchQueue is the queue over db, nil without one.
func (*WatchQueue) Run ¶
func (q *WatchQueue) Run(ctx context.Context)
Run writes queued runs until ctx ends: each wake drains what has queued, up to batchSize, into one transaction, and tells each script's workers once, so a burst of matched calls is a few writes rather than one per call.