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 ¶
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 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.
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 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
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
}
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 ¶
Resolve is the endpoint a name serves, current as of this call. epbinding.ErrNotFound when no binding has the name.
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
// 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.