eprun

package
v1.164.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 37 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 (
	// CookiePrefixSecure is the prefix over https: a __Host- cookie has no
	// Domain, Path=/ and Secure, so no sibling origin can set it.
	CookiePrefixSecure = "__Host-app-"
	// CookiePrefixPlain is the prefix over http, where __Host- is refused.
	CookiePrefixPlain = "app-"

	// MaxCookieNameLen, MaxCookieValueBytes, MaxCookiesSet and MaxCookiesRead
	// bound what a handler sets and reads; MaxCookieAge is the browsers' own
	// cap, 400 days.
	MaxCookieNameLen    = 32
	MaxCookieValueBytes = 1024
	MaxCookiesSet       = 10
	MaxCookiesRead      = 20
	MaxCookieAge        = 400 * 24 * 60 * 60

	// SameSiteLax is a cookie's default; SameSiteStrict the other it may be.
	// None is refused: an application cookie is never sent cross-site.
	SameSiteLax    = "Lax"
	SameSiteStrict = "Strict"
)

Application cookies (#2555): a handler on an application's own address reads req["cookies"] and sets cookies by returning "cookies". The platform writes each under a fixed prefix and strips it on the way in, so a handler only ever sees and sets cookies with that prefix: the platform's own cookies (page_viewer, page_state, a portal session) are out of its reach under any casing, since a name is matched exactly.

View Source
const MaxConcurrent = 32

MaxConcurrent is how many requests a replica runs handlers for at once, across every endpoint: a burst inside every endpoint's rate limit could otherwise hold as many executions as it sends, each with its own memory budget. A request past it waits up to SlotWait for a handler to finish, holding no execution while it waits, and is answered 503 with Retry-After only when none does (#2682): a stall of a few hundred milliseconds under a steady load put more than 32 requests in flight at once, and the requests past them were refused though a slot came free a moment later.

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 SlotWait = time.Second

SlotWait is how long a request waits for a free handler slot by default.

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

View Source
var ErrNoEnvironment = errors.New("the endpoint has no such environment")

ErrNoEnvironment is a request to an environment the endpoint's application does not have, or that runs no release holding its script.

Functions

func ReadCookies added in v1.160.0

func ReadCookies(prefix string, names, values []string) map[string]string

ReadCookies is the application cookies on a request, the prefix taken off, at most MaxCookiesRead of them, the first in name order. Only a name that starts with prefix exactly is the application's.

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 Cookie struct {
	Name  string
	Value string
	// MaxAge is nil for a session cookie, 0 to delete the cookie, and
	// otherwise its lifetime in seconds.
	MaxAge   *int
	SameSite string
}

Cookie is one application cookie a handler sets.

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
	// CSPNonce is the nonce a page's inline scripts carry, read as
	// req["csp_nonce"]; empty on anything but a page (#2517).
	CSPNonce string
	// Cookies are the application's cookies, prefix taken off (#2555): empty
	// on the platform's own address and on a cross-site write.
	Cookies map[string]string
	// ClientIP is the client's address as the trusted-proxy resolver reads
	// it, req["client_ip"] (#2556).
	ClientIP string
	// Asset is the asset whose page called the endpoint through an
	// mcp:endpoint reference (#2457), recorded in the request's audit row;
	// empty for any other request.
	Asset string
}

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
	// Cookies are the application cookies the handler set (#2555), written
	// by the HTTP surface on an application's own address and nowhere else.
	Cookies []Cookie
	// Secret says the answer may hold one of the platform's tokens: a form's
	// signed spec token, or anything after the run called platform.mint_token
	// or platform.decrypt. It is never sent compressed (#2655).
	Secret bool
}

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
	// SlotWait is how long a request past MaxConcurrent waits for a slot;
	// zero is the package's SlotWait.
	SlotWait time.Duration
	// Environments resolves an application endpoint's environment, the
	// version it runs there and its variables (#2696); nil serves every
	// endpoint outside any environment.
	Environments appenv.Resolver
	// 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 in its application's last environment, current as of this call. epbinding.ErrNotFound when no binding has the name.

func (*Runner) ResolveIn added in v1.164.0

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

ResolveIn is the endpoint a name serves in env, "" for its application's last (#2696): the version that environment's release pins, with its variables read for this request. An endpoint whose script no application holds answers only for "", and env must be one its application has with a release holding the script; ErrNoEnvironment otherwise.

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

	// Environment and Variables are the application environment this
	// request runs in and its variables (#2696), empty outside one.
	Environment string
	// 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) ApplicationID added in v1.155.0

func (t *Target) ApplicationID() string

ApplicationID is the application the endpoint's script is a part of, "" for none, read with this request's stamp.

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