Documentation
¶
Overview ¶
Package server is Backyard's HTTP layer (SPEC §2–§6): host/path routing, static site serving, the site API (identity, db, files, ai, warehouse, websocket), the hub (UI, docs, llms.txt, site list, tokens), the embedded deploy gateway mount, health checks, rate limiting and metrics.
Routing ¶
The request host (Host, or X-Forwarded-Host from server.trusted_proxies) is classified as the hub (server.base_domain or the public URL's host), a site (a single DNS label under base_domain, host mode only) or an unknown host (404). With server.dev, IP-literal and localhost host names also reach the hub (other names stay unknown, which defeats DNS rebinding against a local dev server). In path mode sites live under /s/<site>/ on the hub host. The path prefix /__backyard/ is reserved on every host: site files can never shadow it. /__backyard/healthz and /__backyard/readyz answer on any host without authentication.
Security ¶
Every other request is authenticated with the configured auth.Authenticator, except the SDK files, the auth endpoints and the deploy gateway (which authenticates by itself). Unauthenticated browser page loads are redirected to the login URL; API calls get 401 JSON with "login_url". State-changing API calls must carry "X-Backyard: 1" and, when present, an Origin equal to the request's own origin (path mode: the hub origin). Site API calls are rate limited per user (anonymous: per client IP).
Timeouts ¶
No http.TimeoutHandler is used: streaming responses (AI server-sent events, websockets, large downloads and uploads) extend or clear the connection deadlines themselves, and backend calls are bounded by contexts.
Large responses on Cloud Run ¶
Cloud Run rejects HTTP/1 responses that declare a Content-Length above 32 MiB. When K_SERVICE is set, static files and uploads above that size are streamed without a Content-Length (chunked), and byte ranges above it are shortened to 32 MiB (see serveObject).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Deps ¶
type Deps struct {
Config *config.Config
Logger *slog.Logger
Blob blob.Store
Docs docstore.Store
Sites *sites.Registry
Auth auth.Authenticator
Tokens *auth.Tokens
Users *identity.UserCache
Realtime realtime.Hub
AI ai.Service
Warehouse warehouse.Service
// Gateway is the embedded deploy gateway, mounted at /__backyard/api/deploy
// on the hub host with that prefix stripped. GET /__backyard/api/info is
// served by forwarding to the gateway's /info.
Gateway http.Handler
// DevSites maps site names to local directories served live (backyard dev).
// Like deploys, they never expose hidden paths (a segment starting with
// "." other than ".well-known").
DevSites map[string]string
// Version string reported by /__backyard/api/info.
Version string
}
Deps are the components the server needs. AI, Warehouse, Realtime and Gateway may be nil (feature disabled → 404/unsupported responses).
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the assembled HTTP application.
func New ¶
New validates deps and builds the server.
Deps.Docs is wrapped with docstore.WithLimits(database.max_doc_bytes, database.max_docs_per_site) unless it already exposes an Unwrap method (i.e. the caller wrapped it). The embedded deploy gateway is mounted only when deploy.embedded_gateway is not false; GET /__backyard/api/info is forwarded to Deps.Gateway whenever it is set.
func (*Server) Close ¶
Close waits (bounded by ctx) for background work such as user-cache writes and audit records to finish. The handler keeps working after Close (work started meanwhile is waited for too); call it after the HTTP server has shut down and before closing Deps.Docs.
func (*Server) MetricsHandler ¶
MetricsHandler returns the Prometheus handler (for telemetry.metrics_listen).
func (*Server) ObserveDeploy ¶
ObserveDeploy counts a deploy for the deploys_total metric. Deploys through the embedded gateway are counted automatically; this is for other paths (e.g. a standalone gateway sharing the process).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package servertest holds end-to-end tests that run the HTTP server against real components: the filesystem blob store, the SQLite (and, when BACKYARD_TEST_POSTGRES_DSN is set, PostgreSQL) document store, the realtime hub over in-memory (and, when BACKYARD_TEST_REDIS_URL is set, Redis) pub/sub, the auth package in mode "none" and the embedded deploy gateway.
|
Package servertest holds end-to-end tests that run the HTTP server against real components: the filesystem blob store, the SQLite (and, when BACKYARD_TEST_POSTGRES_DSN is set, PostgreSQL) document store, the realtime hub over in-memory (and, when BACKYARD_TEST_REDIS_URL is set, Redis) pub/sub, the auth package in mode "none" and the embedded deploy gateway. |