Documentation
¶
Overview ¶
Package scripthandler is what starts a managed script (#2441, #2434, #2435): its handlers. A handler is one of a list of kinds, each keeping its own table: an endpoint (script_endpoints), a schedule (script_schedules) and a webhook source (script_webhook_handlers). A script may hold several handlers of each kind, and the read-only view script_handlers lists them all. The manage_script handler_* commands and the portal's handler routes carry out the same Service, so who may do what to which kind is decided in one place.
Form is not a kind: an endpoint whose script defines form_spec(req) and form_submit(req, values) is a form, and the view reports its type as form.
Index ¶
- Constants
- Variables
- func CallNamesOver(kits interface{ ... }) func(name string) (string, bool)
- func CheckTypes(types []string) error
- func Failed(err error) bool
- func Kinds() []string
- func Missing(err error) bool
- func Refused(err error) bool
- func Types() []string
- type ApprovalVersions
- func (a ApprovalVersions) ApproveFor(ctx context.Context, c Caller, sc *script.Script, version int) error
- func (a ApprovalVersions) Source(ctx context.Context, sc *script.Script, version int) (string, bool)
- func (a ApprovalVersions) State(ctx context.Context, sc *script.Script) (running int, approver string, waiting int)
- type CallStore
- type Caller
- type ConnectionStore
- type Filter
- type Handler
- type HandlerScriptChoice
- type HandlerScripts
- type Kind
- type Offer
- type Reader
- type ScheduleStore
- type Scripts
- type Service
- func (s *Service) CallName(name string) string
- func (s *Service) Check(ctx context.Context, sc *script.Script, source string) string
- func (s *Service) ConnectionHandlers(ctx context.Context, connection string, c Caller) ([]map[string]any, error)
- func (s *Service) Delete(ctx context.Context, id string, c Caller) (map[string]any, error)
- func (s *Service) Enable(ctx context.Context, id string, enabled bool, c Caller) (map[string]any, error)
- func (s *Service) Failures(ctx context.Context, id string, c Caller) ([]callhandler.Failure, error)
- func (s *Service) Get(ctx context.Context, id string, c Caller) (map[string]any, error)
- func (s *Service) HandlerScripts(ctx context.Context, kind, search string, c Caller) (HandlerScripts, error)
- func (s *Service) List(ctx context.Context, f Filter, c Caller) ([]Handler, int, error)
- func (s *Service) Offers(sc *script.Script, c Caller) []Offer
- func (s *Service) OrderTransforms(ctx context.Context, ids []string, c Caller) error
- func (s *Service) Resolve(ctx context.Context, id string, c Caller) (Handler, *script.Script, error)
- func (s *Service) SameSchedule(ctx context.Context, id, cron, timezone string, args map[string]any) (bool, error)
- func (s *Service) Set(ctx context.Context, req SetRequest) (map[string]any, error)
- func (s *Service) SourceNames(ctx context.Context, c Caller) ([]string, error)
- func (s *Service) TypesOf(ctx context.Context, scriptIDs []string) (map[string][]string, error)
- func (s *Service) VersionSaved(ctx context.Context, sc *script.Script, caller scriptsave.Caller)
- type SetRequest
- type SourceLister
- type SourceRule
- type VersionApprover
- type View
- type Webhooks
Constants ¶
const ( KindEndpoint = "endpoint" KindSchedule = "schedule" KindWebhook = "webhook" // The tool-call kinds (#2436, #2634, #2635): bound by an administrator // to a connection's calls, kept in call_handlers. KindPolicy = callhandler.KindPolicy KindTransform = callhandler.KindTransform KindWatch = callhandler.KindWatch // KindIntegration is an operation's script (#2659), chosen by an // administrator in Admin > Settings > Integrations, kept in // integration_bindings. KindIntegration = "integration" )
The kinds of handler.
const ( TypeForm = "form" TypeNone = "none" )
The types a handler list filters on: every kind, form (an endpoint on a form script), and none (a script with no handler).
const MaxListLimit = 500
MaxListLimit bounds one page of a handler list.
const MaxPerKind = 20
MaxPerKind is how many handlers of one kind a script may hold. Every handler can start runs, so the bound is what keeps one script from multiplying its own load: fifty schedules are fifty runs a minute.
Variables ¶
var ( // ErrNotFound is a handler, or a script, that does not exist. ErrNotFound = errors.New("not found") // ErrNotAllowed is a caller who may not do what they asked. ErrNotAllowed = errors.New("not allowed") // ErrInvalid is a request that names something wrongly. ErrInvalid = errors.New("invalid request") // ErrStore is a store that could not be read or written. ErrStore = errors.New("the handler store failed") )
The ways a handler operation is refused, which each surface reads by identity: an MCP error, or the HTTP status a portal route answers.
var ErrUnknownKind = errors.New("unknown handler kind")
ErrUnknownKind is a kind the platform does not register.
Functions ¶
func CallNamesOver ¶ added in v1.162.1
CallNamesOver is the CallNames of the live toolkits kits holds: the resolver every construction of the service sets (#2649).
func CheckTypes ¶
CheckTypes refuses a type a list cannot filter on.
Types ¶
type ApprovalVersions ¶
ApprovalVersions is the VersionApprover over the Approvals queue: a tool-call handler runs the highest version approved for call_handler, with the roles of the administrator who approved it.
func (ApprovalVersions) ApproveFor ¶
func (a ApprovalVersions) ApproveFor(ctx context.Context, c Caller, sc *script.Script, version int) error
ApproveFor records an administrator's approval of a version for handlers.
type CallStore ¶
type CallStore interface {
Insert(ctx context.Context, h *callhandler.Handler) error
Update(ctx context.Context, h *callhandler.Handler) error
Get(ctx context.Context, id string) (*callhandler.Handler, error)
ByScript(ctx context.Context, scriptID string) ([]callhandler.Handler, error)
SetEnabled(ctx context.Context, id string, enabled bool, by string) error
Delete(ctx context.Context, id string) error
Failures(ctx context.Context, handlerID string, limit int) ([]callhandler.Failure, error)
}
CallStore keeps tool-call handlers (callhandler.Store).
type Caller ¶
type Caller struct {
Email string
Admin bool
// Persona and Roles are the caller's: what a handler version an
// administrator approves runs with.
Persona string
Roles []string
}
Caller is who asks.
type ConnectionStore ¶
type ConnectionStore interface {
All(ctx context.Context) ([]callhandler.Handler, error)
Stats(ctx context.Context, connection string) (map[string]callhandler.Stat, error)
SetOrder(ctx context.Context, ids []string, by string) error
}
ConnectionStore lists and orders tool-call handlers by connection (callhandler.Store).
type Filter ¶
type Filter struct {
// Types narrows to handlers of these types (endpoint, form, schedule,
// webhook); none is a script-list type and matches no handler.
Types []string
ScriptIDs []string
// OwnerEmail narrows to the handlers of one person's scripts.
OwnerEmail string
Enabled *bool
// Search narrows to the handlers whose script name or target contains it.
Search string
Limit int
Offset int
}
Filter selects handlers. Every field narrows; a zero field does not. A nil ScriptIDs matches every script and an empty one none.
type Handler ¶
type Handler struct {
ID string `json:"id"`
Kind string `json:"kind"`
Type string `json:"type"`
ScriptID string `json:"script_id"`
ScriptName string `json:"script_name"`
OwnerEmail string `json:"owner_email"`
Target string `json:"target"`
Enabled bool `json:"enabled"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
}
Handler is one handler as every list reads it, from the script_handlers view: its kind, its type (the kind, or form for an endpoint on a form script), the script it starts and what it answers to.
type HandlerScriptChoice ¶ added in v1.162.1
type HandlerScriptChoice struct {
ID string `json:"id"`
Name string `json:"name"`
OwnerEmail string `json:"owner_email"`
// Version is the latest version, which defines the kind's entry.
Version int `json:"version"`
// Running is the version approved for handlers, 0 for none, and
// RunningDefines whether it defines the entry too.
Running int `json:"running_version"`
RunningDefines bool `json:"running_defines"`
}
HandlerScriptChoice is one script a tool-call handler of a kind can run.
type HandlerScripts ¶ added in v1.162.1
type HandlerScripts struct {
Kind string `json:"kind"`
Entry string `json:"entry"`
Scripts []HandlerScriptChoice `json:"scripts"`
// Looked is how many scripts were read to find them.
Looked int `json:"looked"`
}
HandlerScripts is what the Add handler dialog lists for a kind (#2650).
type Kind ¶
type Kind struct {
// Name is the kind's name: the kind argument and the view's kind column.
Name string
// Contract is the functions a script defines to hold a handler of this
// kind, as a refusal names them.
Contract string
// Check refuses a source a handler of this kind could not run, nil when
// it could. The save gate asks it of every handler the script holds.
Check func(source string) error
// Settings are the manage_script arguments the kind reads.
Settings []string
// Creator is who may create a handler of this kind.
Creator string
}
Kind is one kind of handler as the platform registers it.
type Offer ¶
type Offer struct {
Kind string `json:"kind"`
Allowed bool `json:"allowed"`
Reason string `json:"reason,omitempty"`
Contract string `json:"contract"`
}
Offer is one kind as adding a handler to a script offers it: whether the caller may add one, why not when they may not, and what the script must define.
type Reader ¶
type Reader interface {
List(ctx context.Context, f Filter) ([]Handler, int, error)
Get(ctx context.Context, id string) (Handler, error)
TypesOf(ctx context.Context, scriptIDs []string) (map[string][]string, error)
}
Reader reads the script_handlers view (View).
type ScheduleStore ¶
type ScheduleStore interface {
script.ScheduleStore
DeleteSchedule(ctx context.Context, id string) error
}
ScheduleStore keeps schedule handlers (scriptstore.Store): the schedule contract and the delete of one that produced no runs.
type Service ¶
type Service struct {
View Reader
Scripts Scripts
// Endpoints is the endpoint kind; nil on a deployment that cannot bind
// a script to an endpoint.
Endpoints *epcmd.Handler
Schedules ScheduleStore
Webhooks Webhooks
// Sources decides which webhook source a caller may name; nil refuses
// every source. SourceList lists them for a picker.
Sources SourceRule
SourceList SourceLister
// Now is the clock a new schedule's first fire is computed from.
Now func() time.Time
// Calls keeps the tool-call handlers (policy, transform, watch); nil on
// a deployment that cannot keep them. Versions approves their versions.
Calls CallStore
Versions VersionApprover
// Approvals is the queue a saved handler version is approved or asked
// for through; nil approves nothing.
Approvals *approval.Service
// OnCallChange is told when a tool-call handler changes, so this
// replica's index reads it for the next call; nil tells nothing.
OnCallChange func()
// CallNames is the name the calls of a connection carry, and whether
// name is a connection stored under another one (#2649,
// connid.Resolver.CallName); nil takes every name as its calls' own.
CallNames func(name string) (bound string, stored bool)
}
Service carries out every handler operation, for every surface.
func New ¶
func New(db *sql.DB, endpoints *epcmd.Handler, scripts Scripts, kits interface{ All() []registry.Toolkit }) *Service
New is the service over the platform's database, nil without one: there is nowhere to keep a handler. kits is the live toolkit registry a tool-call handler's connection name is resolved against (#2649); nil takes every name as its calls' own.
func (*Service) CallName ¶ added in v1.162.1
CallName is the name the calls of the connection name names carry, the one a tool-call handler matches: an MCP connection's connection_name for the instance it is stored under (#2649).
func (*Service) Check ¶
Check is the save gate's question of every handler the script holds (#2441): why a version with source could not serve one of them, "" when it could serve them all. It names the handler refused.
func (*Service) ConnectionHandlers ¶
func (s *Service) ConnectionHandlers(ctx context.Context, connection string, c Caller) ([]map[string]any, error)
ConnectionHandlers is every tool-call handler that applies to a connection, named by either of its names (#2649), as the connection's page lists it: policies, transforms in the order they run, then watches, each with its script, the version it runs and the one waiting, and its last day's counts. An administrator's only.
func (*Service) Delete ¶
Delete removes one handler. A schedule that produced runs is refused: it is disabled instead, because its runs name it.
func (*Service) Enable ¶
func (s *Service) Enable(ctx context.Context, id string, enabled bool, c Caller) (map[string]any, error)
Enable turns one handler on or off and returns it as Get does.
func (*Service) Failures ¶
Failures is a tool-call handler's newest failures: an administrator's only, ErrNotFound for anyone else, as if there were none to name.
func (*Service) HandlerScripts ¶ added in v1.162.1
func (s *Service) HandlerScripts(ctx context.Context, kind, search string, c Caller) (HandlerScripts, error)
HandlerScripts is the scripts a policy, transform or watch can be bound to: those that run (not libraries) whose latest version defines the kind's entry, matching search, at most 50, with the version each would run as handlers. An administrator's.
func (*Service) List ¶
List is one page of the handlers filter matches: every handler for an administrator, and the handlers of the caller's own scripts for anyone else.
func (*Service) Offers ¶
Offers is every kind as adding a handler to sc offers it to the caller. An integration is not offered: its script is chosen where the operation is.
func (*Service) OrderTransforms ¶
OrderTransforms sets the order a connection's transforms run in, ids first to last. An administrator's only.
func (*Service) Resolve ¶
func (s *Service) Resolve(ctx context.Context, id string, c Caller) (Handler, *script.Script, error)
Resolve is the handler with the id and its script, once the caller may act on the script's handlers.
func (*Service) SameSchedule ¶
func (s *Service) SameSchedule(ctx context.Context, id, cron, timezone string, args map[string]any) (bool, error)
SameSchedule reports whether the schedule handler id fires on the cadence and with the arguments given, as an import matches a bundle's schedule to one the script already holds.
func (*Service) Set ¶
Set creates or changes one of a script's handlers and returns it as handler_get reports it.
func (*Service) SourceNames ¶
SourceNames is the webhook sources the caller may run a script for: every one for an administrator, and anyone else the sources made for forms whose scripts they own.
func (*Service) VersionSaved ¶
VersionSaved is what a landed save of sc does to its tool-call handlers: with none it does nothing; otherwise an administrator's save approves the version and anyone else's files a request an administrator decides, the approved version running meanwhile. It is the save gate's HandlersSaved.
type SetRequest ¶
type SetRequest struct {
Caller
Script *script.Script
Kind string
Handler string
// Endpoint and TimeoutSeconds are an endpoint's settings.
Endpoint epcmd.Input
TimeoutSeconds int
// Cron, Timezone and Args are a schedule's.
Cron string
Timezone string
Args map[string]any
// EventSource is a webhook handler's.
EventSource string
// Call is a tool-call handler's match and settings (Args are its
// script's parameters); Approve approves the script's latest version
// for handlers as the administrator setting it.
Call callhandler.Patch
Approve bool
}
SetRequest is one handler_set: the script, the kind, the handler it changes ("" adds one, or for an endpoint finds it by name) and the kind's settings.
type SourceLister ¶
SourceLister lists the deployment's webhook sources (whsource.Store, read with no decryptor: only names and forms are read).
type SourceRule ¶
type SourceRule interface {
Check(ctx context.Context, source, callerEmail string, admin bool) error
}
SourceRule is who may run a script for which webhook source (sourcerule.Rule).
type VersionApprover ¶
type VersionApprover interface {
// ApproveFor records an administrator's approval of version (0 is the
// latest) of sc for its tool-call handlers, with their roles.
ApproveFor(ctx context.Context, c Caller, sc *script.Script, version int) error
// State is the version sc's handlers run, who approved it, and the
// newest version waiting for approval (0 for none).
State(ctx context.Context, sc *script.Script) (running int, approver string, waiting int)
// Source is the source of version of sc, false when it cannot be read.
Source(ctx context.Context, sc *script.Script, version int) (string, bool)
}
VersionApprover is what a tool-call handler's version approval is read and recorded through (approval.Service).
type View ¶
View reads the script_handlers view.
type Webhooks ¶
type Webhooks interface {
AddHandler(ctx context.Context, scriptID, source, actor string) (scriptevents.Handler, bool, error)
HandlerByID(ctx context.Context, id string) (scriptevents.Handler, error)
Handlers(ctx context.Context, filter scriptevents.HandlerFilter) ([]scriptevents.Handler, error)
EnableHandler(ctx context.Context, id string, enabled bool, actor string) error
DeleteHandler(ctx context.Context, id string) error
}
Webhooks keeps webhook handlers (scriptevents.PostgresStore).