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
- Variables
- func ReadCookies(prefix string, names, values []string) map[string]string
- type Caller
- type Cookie
- type Executor
- type Preview
- type Request
- type Response
- type Runner
- func (r *Runner) Resolve(ctx context.Context, name string) (*Target, error)
- func (r *Runner) ResolveIn(ctx context.Context, name, env string) (*Target, error)
- func (r *Runner) Serve(ctx context.Context, t *Target, req Request) Response
- func (r *Runner) ServePreview(ctx context.Context, p Preview, req Request) (Response, error)
- func (r *Runner) SetCollector(c *epcollect.Collector)
- type Scripts
- type Target
Constants ¶
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.
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.
const MaxResponseBytes = 10 << 20
MaxResponseBytes bounds the body a handler answers with.
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.
const SlotWait = time.Second
SlotWait is how long a request waits for a free handler slot by default.
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 ¶
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
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 ¶ added in v1.160.0
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
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 ¶
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
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 ¶
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
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
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
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
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
PublicVersion is the version a public form serves a caller with no session, 0 for none.
func (*Target) ServesPublicly ¶ added in v1.153.2
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.