Documentation
¶
Overview ¶
Package epbinding is an endpoint's binding (#2171): the HTTP route a managed script answers at /endpoints/{name}/..., who may call it, and the limits each request runs under. It holds the record, its validation, the store contract and the matching of a request path against the binding's template; the store is internal/endpoint/epstore and the request surface internal/endpoint/ephttp.
Index ¶
- Constants
- Variables
- func Callable(source string) error
- type Binding
- func (b Binding) Admits(c Caller) bool
- func (b Binding) Answers(method string) bool
- func (b Binding) Checks(method string) bool
- func (b Binding) Match(rest string) (map[string]string, bool)
- func (b Binding) PagePolicy(nonce string) string
- func (b Binding) URLPath() string
- func (b Binding) Validate() error
- type Caller
- type Failure
- type Filter
- type Request
- type Stamp
- type Store
Constants ¶
const ( AuthAuthenticated = "authenticated" AuthPublic = "public" AuthBotCheck = "bot_check" )
Access modes (#2259). An authenticated endpoint answers a platform API key or a browser session among its callers; a public one answers anyone with no check; a bot_check one answers anyone who passes the bot check it names.
const ( CallersAll = "*" CallerPersona = "persona:" CallerAPIKey = "api_key:" )
Callers an authenticated endpoint names: every authenticated caller, the callers whose persona is the named one, or the named API key.
const ( ResponseAPI = "api" ResponsePage = "page" )
Response modes (#2517). An api endpoint's answer is held to the sandbox policy wherever it is served; a page endpoint's is served as a working browser page on its application's own origin.
const ( DefaultTimeoutSeconds = 10 MaxTimeoutSeconds = 60 DefaultMaxMemoryBytes int64 = 64 << 20 MinMaxMemoryBytes int64 = 1 << 20 MaxMaxMemoryBytes int64 = 1 << 30 DefaultMaxBodyBytes = 1 << 20 MaxMaxBodyBytes = 10 << 20 DefaultRateLimit = 600 DefaultCallerRateLimit = 120 MaxRateLimit = 100000 )
Limits a binding is held to, and the values one that names none gets.
const FailureRetention = 7 * 24 * time.Hour
FailureRetention is how long a failed request is kept.
const PathPrefix = "/endpoints/"
PathPrefix is where every endpoint is served: /endpoints/{name}/...
Variables ¶
var ( // ErrNotFound reports a script with no binding, or a name no binding has. ErrNotFound = errors.New("this script is not bound to an endpoint") // ErrNameTaken reports a name another script's binding already has. ErrNameTaken = errors.New("another script's endpoint has this name") // ErrNotAllowed reports a caller who may not create or change a binding: // an administrator binds any script, and a form's owner binds their own // form (#2494). The error wrapping it says which rule refused. ErrNotAllowed = errors.New("the endpoint binding was refused") // ErrNoSuchCheck reports a binding naming a bot check that does not // exist. ErrNoSuchCheck = errors.New("no bot check has this name; an administrator configures them under Admin > Settings > Bot checks") )
Errors a binding is refused or looked up with.
var AuthModes = []string{AuthAuthenticated, AuthPublic, AuthBotCheck}
AuthModes is every access mode, in the order they are offered.
var Methods = []string{"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"}
Methods is every HTTP method a binding may answer.
var ResponseModes = []string{ResponseAPI, ResponsePage}
ResponseModes is every response mode.
Functions ¶
func Callable ¶
Callable refuses a source an endpoint cannot call: one that defines neither a top-level handle(req) taking one parameter nor a form's form_spec(req) and form_submit(req, values) (#2176). It is asked when a script is bound and when a bound script is saved (internal/platform/scriptsave).
Types ¶
type Binding ¶
type Binding struct {
ID string `json:"id"`
ScriptID string `json:"script_id"`
// Name is the endpoint's segment of /endpoints/{name}, unique across the
// deployment.
Name string `json:"name" example:"order-lookup"`
// Methods are the HTTP methods it answers.
Methods []string `json:"methods" example:"GET"`
// Path is the template under /endpoints/{name}: "" for the name alone,
// "/{id}" for one parameter a request reads as req.params["id"].
Path string `json:"path" example:"/{id}"`
// AuthMode is authenticated, public or bot_check.
AuthMode string `json:"auth_mode" example:"authenticated"`
// Callers is who an authenticated endpoint admits besides the
// administrator: "*" for every authenticated caller, "persona:<name>" and
// "api_key:<name>". Empty admits no one but the administrator.
Callers []string `json:"callers" example:"persona:analyst"`
// BotCheck is the named bot check a bot_check endpoint requires.
BotCheck string `json:"bot_check,omitempty" example:"default"`
// CheckedMethods are the methods a bot_check endpoint checks, empty for
// every method it answers; HEAD is checked where GET is.
CheckedMethods []string `json:"checked_methods"`
// TimeoutSeconds, MaxMemoryBytes and MaxBodyBytes bound one request.
TimeoutSeconds int `json:"timeout_seconds"`
MaxMemoryBytes int64 `json:"max_memory_bytes"`
MaxBodyBytes int `json:"max_body_bytes"`
// AllowedOrigins are the browser origins a cross-origin request may come
// from; empty answers no preflight.
AllowedOrigins []string `json:"allowed_origins"`
// ResponseMode is api, or page for an endpoint that serves a browser page
// on its application's own origin (#2517).
ResponseMode string `json:"response_mode" example:"api"`
// PageCDNs are the https origins a page may load scripts, styles, images
// and fonts from besides its own.
PageCDNs []string `json:"page_cdns"`
// PageFrameOrigins, PageConnectOrigins and PageFormOrigins are the https
// origins a page may frame, call from its scripts and post its forms to,
// besides its own (#2554).
PageFrameOrigins []string `json:"page_frame_origins"`
PageConnectOrigins []string `json:"page_connect_origins"`
PageFormOrigins []string `json:"page_form_origins"`
// RateLimit is the endpoint's requests per minute on each replica, and
// CallerRateLimit one signed-in caller's.
RateLimit int `json:"rate_limit"`
CallerRateLimit int `json:"caller_rate_limit"`
// IPRateLimit is one client address's requests per minute on each
// replica, 0 for no such limit (#2556).
IPRateLimit int `json:"ip_rate_limit"`
Enabled bool `json:"enabled"`
CreatedBy string `json:"created_by,omitempty"`
UpdatedBy string `json:"updated_by,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Binding is one script's endpoint.
func Build ¶
Build is the binding req sets on sc over prev, which is nil for a script not bound yet. It refuses a library, which nothing calls, and everything Validate refuses.
func (Binding) Admits ¶ added in v1.152.0
Admits reports whether an authenticated endpoint admits c: the administrator always, anyone else when the callers list names them.
func (Binding) Answers ¶
Answers reports whether the binding answers method. HEAD is answered wherever GET is.
func (Binding) Checks ¶ added in v1.152.0
Checks reports whether a request with method must pass the binding's bot check.
func (Binding) Match ¶
Match reports whether rest, the part of a request path after /endpoints/{name} or the page origin's root, is the binding's template, and the parameter values it carries. rest is the decoded path, as the platform's router and the page origin's request both hold it: a segment is not decoded again, so %25 in an address reaches a handler as the % it stands for, and a doubly encoded dot never turns into "..".
A segment is matched only when it is a name a handler can use: not empty, not "." or "..", and holding no backslash or control character. A catch-all takes the remaining segments under the same rule, joined with "/", so what it hands a handler is always a clean relative path.
func (Binding) PagePolicy ¶ added in v1.155.0
PagePolicy is the content policy a page answer is sent under: its own origin and listed CDNs, inline script only under this response's nonce, framing only by the binding's allowed origins, and the sites it may frame, call and post to besides its own (#2554). Every value in it passed validatePage, and nonce is the base64 the serving layer generated. A binding that lists no frame, connect or form origin answers exactly the policy it did before they existed.
type Caller ¶ added in v1.152.0
type Caller struct {
// Admin is whether the caller is the platform's administrator, whom every
// authenticated endpoint admits whatever its callers say: an
// administrator is unrestricted on every surface.
Admin bool
// Persona is the persona the caller's roles resolve to, empty when none.
Persona string
// APIKey is the name of the API key the request carried, empty for a
// browser session.
APIKey string
}
Caller is who sent a request to an authenticated endpoint, as the binding's callers list is matched against it.
type Failure ¶
type Failure struct {
ID string `json:"id"`
EndpointID string `json:"endpoint_id"`
Version int `json:"version"`
Method string `json:"method"`
Status int `json:"status"`
Error string `json:"error"`
DurationMS int64 `json:"duration_ms"`
CreatedAt time.Time `json:"created_at"`
}
Failure is one request that failed, kept for the script's owner to read.
type Filter ¶
Filter narrows a listing. A non-nil empty ScriptIDs matches nothing. An empty AuthMode and a nil Enabled match every binding. Limit is a page's size, bounded by the store, and Offset how many to pass over (#2251).
type Request ¶
type Request struct {
Name string
Methods []string
Path *string
AuthMode string
// Callers, BotCheck and CheckedMethods are nil or empty to keep what the
// binding had; a change of mode clears what the old mode named.
Callers []string
BotCheck string
CheckedMethods []string
TimeoutSeconds int
MaxMemoryBytes int64
MaxBodyBytes int
AllowedOrigins []string
RateLimit int
CallerRateLimit int
Enabled *bool
// ResponseMode is empty to keep what the binding had; PageCDNs and the
// other page lists nil to keep them.
ResponseMode string
PageCDNs []string
PageFrameOrigins []string
PageConnectOrigins []string
PageFormOrigins []string
// IPRateLimit is nil to keep what the binding had, 0 for no limit.
IPRateLimit *int
Actor string
}
Request is a binding set on a script. A nil field keeps what the binding had, or takes the default on a new one.
type Stamp ¶
type Stamp struct {
Binding time.Time
Script time.Time
// ApprovedVersion is the highest version approved for form_public, 0
// for none.
ApprovedVersion int
// Application is the id of the application the script is a part of and
// AppConnection the connection that application's schema is on, both ""
// for none (#2539). Read with the stamp, so a request learns the run role
// its statements log in as with no query of its own.
Application, AppConnection string
}
Stamp is when a binding and its script were last written, and the version of a form approved to be served to callers with no session (#2494). Every write of a script row moves its updated_at, a new version included, and an approval moves ApprovedVersion, so two equal stamps mean nothing a request runs has changed.
type Store ¶
type Store interface {
// Set creates or replaces sc's binding, keyed by its script; a name
// another script's binding has is ErrNameTaken.
Set(ctx context.Context, b *Binding) error
// Get is a script's binding, ErrNotFound when it has none.
Get(ctx context.Context, scriptID string) (*Binding, error)
// GetByName is the binding a name serves, ErrNotFound when none does.
GetByName(ctx context.Context, name string) (*Binding, error)
// List is one page of the bindings filter matches, by name, and how
// many it matches in all.
List(ctx context.Context, filter Filter) (page []Binding, total int, err error)
// SetEnabled turns a script's binding on or off.
SetEnabled(ctx context.Context, scriptID string, enabled bool, actor string) error
// RecordFailure keeps one failed request.
RecordFailure(ctx context.Context, f Failure) error
// Failures is an endpoint's most recent failed requests, newest first.
Failures(ctx context.Context, endpointID string, limit int) ([]Failure, error)
// SweepFailures deletes the failures recorded before cutoff.
SweepFailures(ctx context.Context, cutoff time.Time) (int64, error)
// Stamp is when the binding a name serves, and the script it binds, were
// last written: one read that tells a replica whether what it compiled
// for the name is still current. ErrNotFound when no binding has it.
Stamp(ctx context.Context, name string) (Stamp, error)
}
Store keeps bindings and the failed requests they answered.