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 ¶
const ( // PathPrefix is every endpoint's prefix; a request's path is // /endpoints/{name} and what follows it. PathPrefix = "/endpoints/" // EnvironmentPrefix is where an application endpoint answers in an // environment other than its last (#2696): // /environments/{env}/endpoints/{name}/... EnvironmentPrefix = "/environments/" // BotCheckPrefix is the bot check's routes. BotCheckPrefix = "/botcheck/" )
The routes.
const HeaderBotCheck = "X-Bot-Check"
HeaderBotCheck carries a public request's bot check answer.
Variables ¶
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) Raw ¶ added in v1.161.0
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.
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.