Guide
Server endpoints (portable, no vendor lock-in)
Some sites need a little server behind the static output — a redirect that
depends on the request, or a proxy that keeps an upstream key server-side.
endpoints: declares those once, in a vendor-neutral way. The built-in
server runs them natively (--http), in the single Go binary, with no external
runtime — so a self-hosted deploy behind nginx/Caddy or the Docker image gets the
dynamic bits for free. Empty endpoints: ⇒ a pure-static build, unchanged.
Endpoints are the small, declarative end of server code. For anything with its own storage or an admin panel — comments, a newsletter, a shop — use a worker template instead: WORKERS. A worked example is in examples/server-endpoints.
The keys
| Key | Notes |
|---|---|
path |
Request path handled by this endpoint, e.g. /api/quote (exact match) |
type |
redirect, proxy, form or auth |
to / status |
redirect: destination and 3xx code (default 302) |
target |
proxy: upstream URL; the client's path is replaced by the target's |
methods |
proxy: allowed HTTP methods (empty = any) |
to |
form: the webhook the submission is POSTed to as JSON |
fields |
form: which fields to forward (empty = all submitted fields) |
honeypot |
form: a field that must stay empty — a filled one is a bot, silently dropped |
redirect |
form: where the browser goes after a successful submit (303); empty = a small JSON ok |
allow_private |
proxy/form: permit a private/loopback upstream or webhook (a self-hosted service) |
user / password |
auth: Basic-auth credentials; password should reference an env var ($MEMBERS_PW), never a literal |
1endpoints:
2 - path: /go/latest
3 type: redirect
4 to: /releases/1-8-14/
5 status: 302
6 - path: /api/quote
7 type: proxy
8 target: https://api.example.com/v1/quote # upstream key stays server-side
9 methods: [GET, POST]
10 - path: /api/contact
11 type: form
12 to: https://hooks.example.com/email # delivery webhook stays server-side
13 fields: [name, email, message]
14 honeypot: company # bots that fill it are dropped
15 redirect: /thanks/
Forms
A form endpoint accepts a POSTed submission, drops obvious bots via the
honeypot (a hidden field a human leaves empty), and delivers the collected
fields as JSON to to — so the delivery webhook (an email service, a chat hook)
is never exposed to the browser. On the self-hosted server the delivery uses the
same dial-time SSRF guard as proxy.
Password-protected sections
An auth endpoint guards its path as a prefix with HTTP Basic auth:
1endpoints:
2 - path: /members/ # protects /members/ and everything under it
3 type: auth
4 user: ada
5 password: $MEMBERS_PW # from the environment, never a literal
The password is read from the named environment variable; the comparison is
constant-time. Auth guards run on the built-in server only — on a serverless
platform, protect a section with that platform's own access control — so
endpoints_platform compiles the other endpoint types and skips auth.
Proxies and the SSRF guard
A proxy endpoint resolves and vets the upstream IP itself and refuses
loopback/private ranges at dial time — the same SSRF / DNS-rebinding guard the
external-source client uses — so it can't be turned into a pivot to internal
hosts. Set allow_private: true only when the upstream really is a private
self-hosted API. Endpoint responses are sent Cache-Control: no-store.
Same declaration, any target
The built-in server runs endpoints directly. To run the same endpoints on a
serverless platform instead, set endpoints_platform and the build compiles
them into that platform's functions — no rewrite, no second definition:
endpoints_platform |
Emits |
|---|---|
| (empty) | Self-hosted only — served natively by --http |
cloudflare |
functions/<path>.js Pages Functions (the same tree hand-written workers use) |
netlify |
netlify/functions/<name>.mjs (v2, each declares its own path — no _redirects wiring) |
vercel |
api/<name>.js Edge Functions + a vercel.json that rewrites each path to its function |
1endpoints_platform: cloudflare # compile endpoints: into functions/ at build time
Adapters are self-contained plugins — one file per platform — so a new target drops in without touching the format or your config. Redirect and proxy behave the same on every target; the proxy's dial-time SSRF guard is specific to the self-hosted server (on a platform the upstream runs at the edge).