ephttp

package
v1.162.2 Latest Latest
Warning

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

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

Documentation

Overview

Package ephttp is the HTTP surface of endpoints (#2174): every request to /endpoints/{name}/... and the bot check a bot_check one is answered behind (/botcheck/challenge and /botcheck/solver.js).

An authenticated endpoint answers a platform API key or a browser session its callers list names, and the identity the platform found is what the handler reads as req.caller; it never comes from the request body. A public endpoint answers anyone. A bot_check endpoint answers a request carrying an answer to the bot check it names in the X-Bot-Check header, or one with none to a method it does not check (#2259).

These routes answer their own cross-origin requests from each binding's allowed origins; the platform's CORS layer leaves them alone. A binding's ip_rate_limit counts each client address (#2556), read through the trusted-proxy resolver, so a forged X-Forwarded-For escapes nothing; the other limits count the endpoint and an authenticated caller.

Index

Constants

View Source
const (
	// PathPrefix is every endpoint's prefix; a request's path is
	// /endpoints/{name} and what follows it.
	PathPrefix = "/endpoints/"
	// BotCheckPrefix is the bot check's routes.
	BotCheckPrefix = "/botcheck/"
)

The routes.

View Source
const HeaderBotCheck = "X-Bot-Check"

HeaderBotCheck carries a public request's bot check answer.

Variables

View Source
var ErrForbidden = errors.New("the request's credential was refused")

ErrForbidden is what Authenticate returns for a credential that was presented and refused for a reason other than its absence (a browser session without its CSRF token), which is answered 403 rather than 401.

Functions

This section is empty.

Types

type Checker

type Checker interface {
	Issue(ctx context.Context, check, endpoint string) (botcheck.Challenge, error)
	Verify(ctx context.Context, check, endpoint, answer string) error
}

Checker issues and verifies the named bot checks.

type Handler

type Handler struct {
	Runner  Runner
	Checker Checker
	// Authenticate is who sent the request: a browser session or an API key,
	// with the persona its roles resolve to and the key's name.
	// Nil caller and nil error is nobody.
	Authenticate func(r *http.Request) (*eprun.Caller, error)
	// Refused counts a request refused before its handler ran, by endpoint
	// and reason (#2208). Nil counts nothing.
	Refused func(endpointID, reason string)
	// ViewerKey opens the viewer token an authenticated form embedded in an
	// asset is sent with (epform.ViewerKey, #2177); nil honors none.
	ViewerKey []byte
	// SiteOrigins are the origins of the sites an application holds (#2518),
	// which its public and bot_check endpoints answer without listing them;
	// nil adds none.
	SiteOrigins func(ctx context.Context, applicationID string) []string
	// Clients reads a request's client address with server.trusted_proxies
	// (#2556); nil trusts no proxy and reads the peer's address.
	Clients *ratelimit.Resolver
	// contains filtered or unexported fields
}

Handler answers the routes.

func (*Handler) Mount

func (h *Handler) Mount(mux *http.ServeMux)

Mount registers the routes on mux.

func (*Handler) Raw added in v1.161.0

func (h *Handler) Raw(next http.Handler) http.Handler

Raw serves a request under /endpoints/ whose path has an empty or a dot segment from the path as sent, so the endpoint's router answers it as it does on a page origin: such a segment matches nothing and is answered 404 without the handler running. A ServeMux would first redirect it to the cleaned path and then run the handler there (#2628). Every other request goes to next.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP answers one request to an endpoint.

func (*Handler) ServePage added in v1.155.0

func (h *Handler) ServePage(w http.ResponseWriter, r *http.Request, route PageRoute)

ServePage answers one request on an application's page origin. An endpoint of another application answers as if it did not exist.

type PageRoute added in v1.155.0

type PageRoute struct {
	Application string
	Name        string
	Rest        string
	// Nonce is this response's inline-script nonce.
	Nonce string
	// Caller is who the page origin's viewer cookie names; nil and nil is
	// nobody. Neither a portal session nor an API key is read there.
	Caller func(r *http.Request) (*eprun.Caller, error)
	// SignIn sends a browser with no viewer to sign in, for a page.
	SignIn func(w http.ResponseWriter, r *http.Request)
	// CookiePrefix is what the application's cookies are written under on
	// this origin (#2555): eprun.CookiePrefixSecure over https,
	// eprun.CookiePrefixPlain over http, "" where a handler reads and sets
	// none. Secure says the origin is https.
	CookiePrefix string
	Secure       bool
	// CookiesWithheld is true for a request that changes something and does
	// not prove it came from this origin: it reaches the handler with no
	// cookies, so a forged request from another site carries no session.
	CookiesWithheld bool
}

PageRoute is a request to an application's endpoint on its page origin (#2517): the endpoint, the application it must belong to, and the identity that origin carries in place of the portal's.

type Runner

type Runner interface {
	Resolve(ctx context.Context, name string) (*eprun.Target, error)
	Serve(ctx context.Context, t *eprun.Target, req eprun.Request) eprun.Response
}

Runner is what serves a resolved endpoint.

Jump to

Keyboard shortcuts

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