callrun

package
v1.162.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

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

View Source
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.

View Source
const (
	VerdictRuns   = "runs"
	VerdictDenied = "denied"
	VerdictHeld   = "held"
)

The verdicts a call gets from its policies.

View Source
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.

View Source
const (
	RecentRan       = "ran"
	RecentFailed    = "failed"
	RecentHeld      = "held"
	RecentRefused   = "refused"
	RecentAllowance = "ran_on_allowance"
)

The outcomes a recent call is shown with.

View Source
const DefaultLinger = 100 * time.Millisecond

DefaultLinger is how long a watch run waits for others to join its write.

View Source
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.

func (APIShapes) CallShape

func (s APIShapes) CallShape(ctx context.Context, connection string, args map[string]any) Shape

CallShape is the call's operation, method, path and path parameters.

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

func (e *Evaluator) SetServer(s *mcp.Server)

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) Start

func (e *Evaluator) Start()

Start readies the evaluator to run handlers.

func (*Evaluator) Statement

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.

func (*Evaluator) Watch

func (e *Evaluator) Watch(ctx context.Context, c *callhandler.Call) []string

Watch queues a run of every watch that applies to a call that succeeded. Nothing here makes the call wait: resolving each watch's version reads through the cache, and the run is written by the queue.

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.

func (*Runtime) Start

func (r *Runtime) Start(ctx context.Context) error

Start reads the handlers, listens for changes, and starts the writer and the sweep. A failed read is logged: the index reads again in the background on the next call.

func (*Runtime) Stop

func (r *Runtime) Stop(context.Context) error

Stop ends the listener, the 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

type Shape struct {
	Operation, Method, Path string
	Params                  map[string]string
}

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 Sweeper

type Sweeper interface {
	Sweep(ctx context.Context, now time.Time) error
}

Sweeper removes what handlers no longer need (callhandler.Store).

type TransformError

type TransformError struct {
	Script string
	Err    error
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL