epcmd

package
v1.161.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source
const CmdFormPreview = "form_preview"

CmdFormPreview opens a preview of a form for its owner (#2494).

View Source
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

View Source
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

func MayWrite(req Request) error

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

func Properties() map[string]any

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

func (h *Handler) Choices(ctx context.Context, sc *script.Script) (map[string]any, error)

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

func (h *Handler) Delete(ctx context.Context, req Request, b *epbinding.Binding) error

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

func (h *Handler) List(ctx context.Context, req Request) (map[string]any, error)

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

func (h *Handler) Preview(ctx context.Context, req Request) (map[string]any, error)

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

func (h *Handler) Set(ctx context.Context, req Request) (map[string]any, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL