eprun

package
v1.153.3 Latest Latest
Warning

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

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

Documentation

Overview

Package eprun runs a bound script inline on each request to its endpoint (#2172): handle(req) is called on the replica that received the request, in an in-memory MCP session presenting the roles its version's author held at the save, as a scheduled run presents them. Every platform call the handler makes is authorized, rate limited and audited as a script's. A request writes one audit row and its metrics, a failed one is kept for the script's owner to read, and no script_runs row is written.

The compiled module is kept per script version on each replica. Before a request runs, one read of when its binding and its script were last written (epbinding.Stamp) says whether what the replica holds is current, so the first request after a save, on any replica, runs the new version.

Index

Constants

View Source
const MaxConcurrent = 32

MaxConcurrent is how many requests a replica runs handlers for at once, across every endpoint. A request past it is answered 503 at once rather than held: a burst inside every endpoint's rate limit could otherwise hold as many executions as it sends, each with its own memory budget.

View Source
const MaxResponseBytes = 10 << 20

MaxResponseBytes bounds the body a handler answers with.

View Source
const PreviewPrefix = "_preview-"

PreviewPrefix opens the name a preview's form token is bound to. An endpoint's name never starts with "_" (epbinding), so a token a preview signed never opens at an endpoint, nor one an endpoint signed at a preview.

View Source
const SourceEndpoint = "endpoint"

SourceEndpoint is the audit source of the one row a request writes. The tool-call rows its handler's calls produce are the script source's, which is what every rule a script's calls answer to keys on.

Variables

This section is empty.

Functions

This section is empty.

Types

type Caller

type Caller struct {
	UserID   string
	Email    string
	AuthType string
	// Admin, Persona and APIKey are whether the caller is the administrator,
	// the persona their roles resolve to and the name of the API key the
	// request carried; an authenticated endpoint admits by them (#2259).
	Admin   bool
	Persona string
	APIKey  string
}

Caller is who sent a request to an authenticated endpoint.

type Executor added in v1.153.2

type Executor func(ctx context.Context, name string, args starlark.Tuple) (starlark.Value, error)

Executor calls one of a preview's functions as a draft of its script, under the identity of the person previewing it (internal/platform/scriptdraft): their persona authorizes every host call, and the draft's write barrier stops every write.

type Preview added in v1.153.2

type Preview struct {
	// ID is the preview's id; its form tokens are bound to PreviewPrefix+ID.
	ID      string
	Script  *script.Script
	Version int
	Source  string
	Exec    Executor
}

Preview is one form as its owner previews it (#2494): a saved version or an unsaved source, with no endpoint bound to it.

type Request

type Request struct {
	Method string
	Path   string
	Params map[string]string
	Query  map[string][]string
	Header http.Header
	Body   []byte
	// Caller is nil on a public or bot_check endpoint.
	Caller *Caller
}

Request is one request to an endpoint, as the HTTP surface read it.

type Response

type Response struct {
	Status int
	Header http.Header
	Body   []byte
}

Response is what the endpoint answers.

type Runner

type Runner struct {
	Bindings epbinding.Store
	Scripts  Scripts
	// Server is the assembled MCP server a request's session opens against.
	Server  *mcp.Server
	Audit   middleware.AuditLogger
	Metrics *observability.Metrics
	// Subjects resolves the subject the version's author authenticates as,
	// for where a request's managed resources land; nil leaves it empty.
	Subjects interface {
		ForRun(ctx context.Context, address, saved string) string
	}
	// Limits are a platform run's ceilings; a binding's timeout and memory
	// budget replace those two.
	Limits       scriptrun.PlatformLimits
	Destinations []script.Destination
	// Libraries is where the libraries a version loads are read from, given
	// the version; nil refuses every load.
	Libraries func(ctx context.Context, v *script.Version) (scriptlib.Source, error)
	// Tokens answers platform.mint_token and platform.verify_token, bound to
	// the endpoint a request reached (#2175); nil refuses them.
	Tokens *scripttoken.Issuer
	// FormKey signs a form's token (epform.Key, #2176); nil answers every
	// request to a form 503.
	FormKey []byte
	// Now is the clock a form's token is signed and checked by; nil is
	// time.Now.
	Now func() time.Time
	// contains filtered or unexported fields
}

Runner runs bound scripts.

func (*Runner) Resolve

func (r *Runner) Resolve(ctx context.Context, name string) (*Target, error)

Resolve is the endpoint a name serves, current as of this call. epbinding.ErrNotFound when no binding has the name.

func (*Runner) Serve

func (r *Runner) Serve(ctx context.Context, t *Target, req Request) Response

Serve runs t's handler for req and returns its response. It never fails: a request the script could not answer is answered with the status that says why, and recorded.

func (*Runner) ServePreview added in v1.153.2

func (r *Runner) ServePreview(ctx context.Context, p Preview, req Request) (Response, error)

ServePreview answers one request to a form's preview the way its endpoint would answer it, with three differences: form_spec and form_submit run as drafts under the previewer's identity; an accepted submission is answered and not stored, and its files are described to form_submit and not saved; and nothing is recorded, neither the endpoint's audit row and metrics nor a failed request. A failure is returned beside the response so the preview can show its author what went wrong, its sensitive values replaced.

func (*Runner) SetCollector added in v1.152.0

func (r *Runner) SetCollector(c *epcollect.Collector)

SetCollector is where accepted submissions are stored from here on: the webhook receiver, which is assembled after the runner. It is set before the routes are served.

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 the script a binding binds and its saved versions.

type Target

type Target struct {
	Binding *epbinding.Binding
	Script  *script.Script
	Version *script.Version

	// Form is whether the version defines form_spec and form_submit (#2176).
	Form bool
	// contains filtered or unexported fields
}

Target is one endpoint as a replica holds it: the binding, the script and version it runs, and the module compiled for that version.

func (*Target) For added in v1.153.2

func (t *Target) For(caller *Caller) *Target

For is the target a request from caller runs: on a public or bot_check form, a caller with no session gets the approved version (nil when none is), and a signed-in caller the version the script runs (#2494).

func (*Target) PublicVersion added in v1.153.2

func (t *Target) PublicVersion() int

PublicVersion is the version a public form serves a caller with no session, 0 for none.

func (*Target) ServesPublicly added in v1.153.2

func (t *Target) ServesPublicly() bool

ServesPublicly reports whether the target is a public or bot_check form, whose callers with no session are served its approved version. A binding with an approved version stays one when a later version is not a form: a form's owner cannot get a version approved and then serve a handler of their own publicly in its place.

Jump to

Keyboard shortcuts

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