Documentation
¶
Overview ¶
Package epcmd is the endpoint kind of script handler (#2171, #2441): setting, describing, listing, enabling, disabling and deleting a script's endpoint handlers, and form_preview. internal/platform/scripthandler carries out the handler_* commands and the portal's handler routes through it, after resolving the script by the rule every command resolves by; the input fields and their schema are spliced into manage_script's own.
Index ¶
- Constants
- Variables
- func MayWrite(req Request) error
- func Properties() map[string]any
- type Approvals
- type FormSources
- type Handler
- func (h *Handler) Choices(ctx context.Context, sc *script.Script) (map[string]any, error)
- func (h *Handler) Delete(ctx context.Context, req Request, b *epbinding.Binding) error
- func (h *Handler) Describe(ctx context.Context, sc *script.Script, b *epbinding.Binding) (map[string]any, error)
- func (h *Handler) Enable(ctx context.Context, req Request, b *epbinding.Binding, enabled bool) (map[string]any, error)
- func (h *Handler) List(ctx context.Context, req Request) (map[string]any, error)
- func (h *Handler) Preview(ctx context.Context, req Request) (map[string]any, error)
- func (h *Handler) Set(ctx context.Context, req Request) (map[string]any, error)
- func (h *Handler) SetForms(f FormSources)
- type Input
- type Request
Constants ¶
const CmdFormPreview = "form_preview"
CmdFormPreview opens a preview of a form for its owner (#2494).
const NoTrustedProxiesWarning = "This deployment trusts no proxy for a visitor's address (server.trusted_proxies is empty). " +
"Behind a load balancer or an ingress, every visitor then shares one address and one per-address limit. " +
"An administrator sets server.trusted_proxies to the ingress's address range."
NoTrustedProxiesWarning is what a binding with an ip_rate_limit is told on a deployment that trusts no proxy for a client's address (#2556).
Variables ¶
var ErrStore = errors.New("the endpoint store failed")
ErrStore marks a command that failed because a store could not be read or written, which is the platform's failure rather than the caller's.
Functions ¶
func MayWrite ¶ added in v1.161.0
MayWrite reports why the caller of req may not set, enable, disable or delete an endpoint handler of its script, nil when they may.
func Properties ¶
Properties is the schema fragment manage_script splices in for the fields of Input.
Types ¶
type Approvals ¶ added in v1.153.2
type Approvals interface {
Approved(ctx context.Context, scriptID, purpose string) int
RecordSelfApproval(ctx context.Context, actor approval.Actor, sc *script.Script, version int) error
}
Approvals is the part of the Approvals queue (internal/approval) a binding reads: the version approved for form_public, and an administrator's approval of the version they serve.
type FormSources ¶ added in v1.152.0
type FormSources interface {
Ensure(ctx context.Context, req epsource.SourceRequest) (epsource.SourceResult, error)
Find(ctx context.Context, scriptID string) (epsource.SourceResult, bool, error)
ConnectionChoices() []string
}
FormSources makes the webhook source a form stores its submissions in (epcollect.Maker).
type Handler ¶
type Handler struct {
Store epbinding.Store
// CheckUsable reports why a binding cannot name a bot check: none has
// the name, or it cannot be issued here (internal/botcheck).
CheckUsable func(ctx context.Context, name string) error
// BaseURL is the deployment's public address, empty when it has none.
BaseURL string
// ScriptName names a script a listing found by id; nil leaves names out.
ScriptName func(ctx context.Context, scriptID string) string
// Approvals says which version of a form is approved to be served to
// callers with no session (#2494); nil refuses making a form public.
Approvals Approvals
// Previews opens a form's preview (#2494); nil refuses form_preview.
Previews *eppreview.Previews
// PageAllowed reports why a script's endpoint cannot be a browser page
// (#2517); nil refuses every page.
PageAllowed func(ctx context.Context, scriptID string) error
// PageAddress is where a script's page answers, "" when it has none.
PageAddress func(ctx context.Context, scriptID string) string
// NoTrustedProxies is true when the deployment trusts no proxy for a
// client's address (server.trusted_proxies), which a binding setting
// ip_rate_limit is warned of (#2556).
NoTrustedProxies bool
// contains filtered or unexported fields
}
Handler carries the commands out.
func (*Handler) Choices ¶ added in v1.161.0
Choices is what adding an endpoint handler to sc offers: where its page would answer, and, for a form, the connections its submissions could be stored on, or the source they are stored in.
func (*Handler) Delete ¶ added in v1.161.0
Delete removes one of the script's endpoint handlers: /endpoints/<name> answers nothing from then on, and its failed and refused requests go with it. A form's webhook source, and the submissions stored in it, stay.
func (*Handler) Describe ¶ added in v1.161.0
func (h *Handler) Describe(ctx context.Context, sc *script.Script, b *epbinding.Binding) (map[string]any, error)
Describe is one endpoint handler as handler_get reports it: its settings, where its page answers, its recent failed requests and, for a form, where its submissions are stored.
func (*Handler) Enable ¶ added in v1.161.0
func (h *Handler) Enable(ctx context.Context, req Request, b *epbinding.Binding, enabled bool) (map[string]any, error)
Enable turns one of the script's endpoint handlers on or off. Turning a public form on by someone other than an administrator needs an approved version, as making it public does.
func (*Handler) List ¶ added in v1.161.0
List is one page of endpoint handlers: the caller's scripts' (req.Visible), or every one for an administrator.
func (*Handler) Preview ¶ added in v1.161.0
Preview opens a preview of the script's form for the caller (#2494): its owner or an administrator, of a saved version or the unsaved source sent. The link renders only for the person who opened it and expires within the hour.
func (*Handler) Set ¶ added in v1.161.0
Set creates or changes one of the script's endpoint handlers and returns it as manage_script reports it. The handler changed is the one named by req.Binding, else the script's handler with the name in req.Input, else the script's only one when no name is sent; any other name makes a new one.
func (*Handler) SetForms ¶ added in v1.152.0
func (h *Handler) SetForms(f FormSources)
SetForms is what makes a form's source from here on: the webhook sources, which are assembled after the endpoint commands.
type Input ¶
type Input struct {
Endpoint string `json:"endpoint,omitempty"`
Methods []string `json:"methods,omitempty"`
Path *string `json:"path,omitempty"`
AuthMode string `json:"auth_mode,omitempty"`
Callers []string `json:"callers,omitempty"`
BotCheck string `json:"bot_check,omitempty"`
CheckedMethods []string `json:"checked_methods,omitempty"`
MaxMemoryBytes int64 `json:"max_memory_bytes,omitempty"`
MaxBodyBytes int `json:"max_body_bytes,omitempty"`
AllowedOrigins []string `json:"allowed_origins,omitempty"`
RateLimit int `json:"rate_limit,omitempty"`
CallerRateLimit int `json:"caller_rate_limit,omitempty"`
// ResponseMode and PageCDNs make the endpoint a browser page (#2517).
ResponseMode string `json:"response_mode,omitempty"`
PageCDNs []string `json:"page_cdns,omitempty"`
// PageFrameOrigins, PageConnectOrigins and PageFormOrigins are what a
// page may frame, call and post to besides its own origin (#2554).
PageFrameOrigins []string `json:"page_frame_origins,omitempty"`
PageConnectOrigins []string `json:"page_connect_origins,omitempty"`
PageFormOrigins []string `json:"page_form_origins,omitempty"`
// IPRateLimit is one client address's requests a minute (#2556); nil
// keeps it, 0 removes it.
IPRateLimit *int `json:"ip_rate_limit,omitempty"`
// Connection and DecryptPersonas are a form's (#2178, #2179): the Trino
// connection its source's table is created on, and the personas a script
// run may decrypt its sensitive fields as (nil keeps them).
Connection string `json:"connection,omitempty"`
DecryptPersonas []string `json:"decrypt_personas,omitempty"`
// PreviewVersion is the saved version form_preview renders, 0 for the
// latest (#2494).
PreviewVersion int `json:"preview_version,omitempty"`
}
Input is the part of manage_script's input an endpoint handler reads. handler_set kind=endpoint also reads manage_script's timeout_seconds.
type Request ¶
type Request struct {
Input Input
// TimeoutSeconds is manage_script's timeout_seconds.
TimeoutSeconds int
// Script is the script whose handlers are acted on, nil for a listing
// that names none.
Script *script.Script
// Binding is the id of the binding a set replaces; empty finds it by the
// name in Input, or makes a new one.
Binding string
// MaxBindings is how many endpoint handlers one script may hold, 0 for
// no bound (#2441).
MaxBindings int
// Visible scopes a listing that names no script to the scripts the caller
// may see; nil for an administrator, whose listing is every binding.
Visible map[string]*script.Script
Admin bool
Actor string
// Limit is how many bindings a listing returns, bounded by the store.
Limit int
// Opener is who opens a form_preview, with the identity its drafts run
// as; Source is the unsaved source it renders, empty for a saved
// version (#2494).
Opener eppreview.Opener
Source string
}
Request is one operation on a script's endpoint handlers.