scripthandler

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: 26 Imported by: 0

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

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

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

View Source
const MaxListLimit = 500

MaxListLimit bounds one page of a handler list.

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

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

View Source
var ErrUnknownKind = errors.New("unknown handler kind")

ErrUnknownKind is a kind the platform does not register.

Functions

func CallNamesOver added in v1.162.1

func CallNamesOver(kits interface{ All() []registry.Toolkit }) func(name string) (string, bool)

CallNamesOver is the CallNames of the live toolkits kits holds: the resolver every construction of the service sets (#2649).

func CheckTypes

func CheckTypes(types []string) error

CheckTypes refuses a type a list cannot filter on.

func Failed

func Failed(err error) bool

Failed reports whether err is the platform's failure rather than the caller's.

func Kinds

func Kinds() []string

Kinds is the name of every registered kind, in list order.

func Missing

func Missing(err error) bool

Missing reports whether err is a handler or script that does not exist.

func Refused

func Refused(err error) bool

Refused reports whether err is a caller not allowed to do what they asked, by any kind's rule.

func Types

func Types() []string

Types is every type a handler list filters on, in list order.

Types

type ApprovalVersions

type ApprovalVersions struct {
	Approvals *approval.Service
}

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.

func (ApprovalVersions) Source added in v1.162.1

func (a ApprovalVersions) Source(ctx context.Context, sc *script.Script, version int) (string, bool)

Source is the source of version of sc, false when it cannot be read.

func (ApprovalVersions) State

func (a ApprovalVersions) State(ctx context.Context, sc *script.Script) (running int, approver string, waiting int)

State is the version sc's handlers run, who approved it, and the version waiting.

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.

func KindOf

func KindOf(name string) (Kind, bool)

KindOf is the registered kind with the name.

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 Scripts

type Scripts interface {
	GetByID(ctx context.Context, id string) (*script.Script, error)
}

Scripts reads a script by id, nil and nil for none.

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

func (s *Service) CallName(name string) string

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

func (s *Service) Check(ctx context.Context, sc *script.Script, source string) string

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

func (s *Service) Delete(ctx context.Context, id string, c Caller) (map[string]any, error)

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

func (s *Service) Failures(ctx context.Context, id string, c Caller) ([]callhandler.Failure, error)

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

func (s *Service) Get(ctx context.Context, id string, c Caller) (map[string]any, error)

Get is one handler, as its kind describes it.

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

func (s *Service) List(ctx context.Context, f Filter, c Caller) ([]Handler, int, error)

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

func (s *Service) Offers(sc *script.Script, c Caller) []Offer

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

func (s *Service) OrderTransforms(ctx context.Context, ids []string, c Caller) error

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

func (s *Service) Set(ctx context.Context, req SetRequest) (map[string]any, error)

Set creates or changes one of a script's handlers and returns it as handler_get reports it.

func (*Service) SourceNames

func (s *Service) SourceNames(ctx context.Context, c Caller) ([]string, error)

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

func (s *Service) TypesOf(ctx context.Context, scriptIDs []string) (map[string][]string, error)

TypesOf is each script's handler types; a script with none is absent.

func (*Service) VersionSaved

func (s *Service) VersionSaved(ctx context.Context, sc *script.Script, caller scriptsave.Caller)

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

type SourceLister interface {
	List(ctx context.Context) ([]whsource.Source, error)
}

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

type View struct{ DB *sql.DB }

View reads the script_handlers view.

func (View) Get

func (v View) Get(ctx context.Context, id string) (Handler, error)

Get is one handler, ErrNotFound when none has the id.

func (View) List

func (v View) List(ctx context.Context, f Filter) ([]Handler, int, error)

List is one page of the handlers filter matches, by script name, and how many it matches in all.

func (View) TypesOf

func (v View) TypesOf(ctx context.Context, scriptIDs []string) (map[string][]string, error)

TypesOf is each script's handler types, sorted and once each; a script with no handler is absent.

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

Jump to

Keyboard shortcuts

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