eprun

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: 36 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 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

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