README
¶
backd
backd is a config-driven backend service that exposes schema-validated REST APIs over document data stored in MongoDB.
Declare realms, databases and collections as directories on disk, each collection with a JSON Schema, and backd serves create, read, update, delete and query endpoints for them.
Features
- Config-driven data model — realms, databases and collections declared as directories, with a JSON Schema per collection and config validation at startup (
backd config check). Configuration - Document API — schema-validated CRUD plus
where,order_by, pagination and counts over an allowlisted query language; optimistic concurrency viaETag/If-Match. HTTP API - Built-in auth — users, sessions and API keys per realm, per-document access rules, brute-force protection and an audit trail. Authentication
- Server-side functions — isolated Deno processes for privileged logic: sync calls, background jobs, cron schedules, webhooks, encrypted secrets and a network allowlist. Functions
- JavaScript client — typed client for the document API and functions. Clients
- Production path — tested reference deployment (TLS, least-privilege MongoDB, encrypted backups) and a config fingerprint so every instance runs the same configuration. Operations
Quick start
make example # backd + MongoDB with examples/config, docs, example app
export CURL_CA_BUNDLE=$PWD/docker/certs/ca.crt # trust the local CA in curl
curl https://localhost:8443/readyz
curl -X POST https://localhost:8443/v1/shop/orders/items \
-H 'Content-Type: application/json' \
-d '{"name": "Widget", "price": 12.5}'
curl -G https://localhost:8443/v1/shop/orders/items \
--data-urlencode 'where={"price": {"$lt": 20}}' \
--data-urlencode 'order_by=-price' -d count=true
make example serves everything over HTTPS with a certificate from a local CA that it creates (and renews) in docker/certs/ with certsfor; it prints how to trust that CA in your browser or system.
- Data model —
examples/configholds one directory per realm (with arealm.yaml), database and collection, each collection with aschema.json.backd template realm <name> --samplecreates a starter realm. shoprealm —auth: disabled, so the requests above need no key.blogrealm — access rules let anyone read published posts; writes need a user or an API key, created by the realm's administrators.docker compose exec backd /backd bootstrap --realm blog --email <email>creates the first one.
See Getting started for a full walkthrough.
Security
See SECURITY.md to report vulnerabilities, and the security model in the docs (Authentication → Security model). To run backd in public, start from the tested reference in deploy/production: TLS, rate limits, MongoDB with authentication and TLS, and a least-privilege database user.
Development
make test # full test suite in docker (same as CI)
make test-local # tests that need no external services
make build # binary in bin/backd
make docs-serve # documentation site at http://localhost:1313/backd/
make example # everything on https://localhost:8443: API, docs (live reload), JS example app
make prod-test # end-to-end test of the production reference deployment
make release-check # build every release archive into dist/ without publishing
make hack-expenses # attack the expenses example (needs make example running)
make hack-expenses-functions # attack the expenses-with-functions example (needs make example running)
make workshop-tour # walk the workshop tour without a browser and check each step (needs make example running)
make shelf-tour # replay the Shelf tutorial's checks against the tutorial's own stack
Documentation lives in docs/ and is built with Hugo.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api embeds backd's HTTP API contract, which per-realm documents are derived from.
|
Package api embeds backd's HTTP API contract, which per-realm documents are derived from. |
|
clients
|
|
|
js
Package jsclient embeds the JavaScript client's sources, so the functions runner can give each function a real client as ctx.db.
|
Package jsclient embeds the JavaScript client's sources, so the functions runner can give each function a real client as ctx.db. |
|
cmd
|
|
|
backd
command
Command backd serves a config-driven REST API over MongoDB.
|
Command backd serves a config-driven REST API over MongoDB. |
|
internal
|
|
|
adminui
Package adminui serves the admin web interface under /_ui/.
|
Package adminui serves the admin web interface under /_ui/. |
|
appconfig
Package appconfig keeps a realm's app configuration: the values admins and functions set over the declared defaults, with optimistic concurrency, an audited history and rollback.
|
Package appconfig keeps a realm's app configuration: the values admins and functions set over the declared defaults, with optimistic concurrency, an audited history and rollback. |
|
auth
Package auth holds backd's identity model: users, their sign-in identities and password handling.
|
Package auth holds backd's identity model: users, their sign-in identities and password handling. |
|
auth/authtest
Package authtest provides an in-memory auth.Store for tests.
|
Package authtest provides an in-memory auth.Store for tests. |
|
cron
Package cron parses five-field cron expressions and computes their schedule, in UTC or in a time zone.
|
Package cron parses five-field cron expressions and computes their schedule, in UTC or in a time zone. |
|
egress
Package egress runs backd's egress role: the only way a function process reaches the network.
|
Package egress runs backd's egress role: the only way a function process reaches the network. |
|
email
Package email holds what backd knows about the emails it asks a realm's delivery function to send: the kinds, the templates (loaded from <realm>/email/ into memory at startup and rendered per message), and the shape of the message handed to the function.
|
Package email holds what backd knows about the emails it asks a realm's delivery function to send: the kinds, the templates (loaded from <realm>/email/ into memory at startup and rendered per message), and the shape of the message handed to the function. |
|
executor
Package executor runs server-side functions: `backd executor` is a supervisor that runs each invocation in its own Deno process, with only the function's permissions and limits, and returns its output.
|
Package executor runs server-side functions: `backd executor` is a supervisor that runs each invocation in its own Deno process, with only the function's permissions and limits, and returns its output. |
|
functions
Package functions builds server-side functions: `backd functions build` bundles each function of a database's Deno project into one file with `deno bundle`, and records the bundles in a manifest that startup checks.
|
Package functions builds server-side functions: `backd functions build` bundles each function of a database's Deno project into one file with `deno bundle`, and records the bundles in a manifest that startup checks. |
|
httpapi
Package httpapi is backd's HTTP layer: routing, middleware, error envelope, the generic document handlers and the /_auth endpoints.
|
Package httpapi is backd's HTTP layer: routing, middleware, error envelope, the generic document handlers and the /_auth endpoints. |
|
imaging
Package imaging turns one image into resized copies, safely: pure Go (no cgo, no external library), the pixel count checked from the header before anything is decoded, the orientation flag applied, a time limit per image, and output that never carries metadata.
|
Package imaging turns one image into resized copies, safely: pure Go (no cgo, no external library), the pixel count checked from the header before anything is decoded, the orientation flag applied, a time limit per image, and output that never carries metadata. |
|
jsonnum
Package jsonnum converts json.Number values into concrete Go numbers.
|
Package jsonnum converts json.Number values into concrete Go numbers. |
|
metrics
Package metrics is backd's Prometheus instrumentation (design/metrics.md).
|
Package metrics is backd's Prometheus instrumentation (design/metrics.md). |
|
mongodb
Package mongodb holds everything MongoDB-specific: the $jsonSchema validator translation, the repository implementation and the provisioner.
|
Package mongodb holds everything MongoDB-specific: the $jsonSchema validator translation, the repository implementation and the provisioner. |
|
oauth
Package oauth talks to external identity providers (Google, Microsoft, Apple): the authorize URL, the code exchange, the verification of ID tokens and Apple's client secret.
|
Package oauth talks to external identity providers (Google, Microsoft, Apple): the authorize URL, the code exchange, the verification of ID tokens and Apple's client secret. |
|
oauth/oauthtest
Package oauthtest is a small identity provider for tests: it signs ID tokens with its own key, publishes them, and plays the parts of a provider's authorize, token and keys endpoints, so the sign-in flow can be run end to end without a real one.
|
Package oauthtest is a small identity provider for tests: it signs ID tokens with its own key, publishes them, and plays the parts of a provider's authorize, token and keys endpoints, so the sign-in flow can be run end to end without a real one. |
|
openapigen
Package openapigen derives an OpenAPI 3.1 document for one realm from the generic contract (api/openapi.yaml) and the realm's loaded config: its collections with their schemas and features, its enabled authentication methods, its functions, and what its clients can reach.
|
Package openapigen derives an OpenAPI 3.1 document for one realm from the generic contract (api/openapi.yaml) and the realm's loaded config: its collections with their schemas and features, its enabled authentication methods, its functions, and what its clients can reach. |
|
push
Package push holds what backd knows about push notification messages that doesn't depend on the realm's settings or its store: the templates they are written from, the portable message and its validation, and the payloads each provider receives (design: design/push-notifications.md §6).
|
Package push holds what backd knows about push notification messages that doesn't depend on the realm's settings or its store: the templates they are written from, the portable message and its validation, and the payloads each provider receives (design: design/push-notifications.md §6). |
|
pushsend
Package pushsend holds backd's built-in push senders: FCM (HTTP v1), APNs (HTTP/2, token authentication) and Web Push (VAPID, RFC 8291).
|
Package pushsend holds backd's built-in push senders: FCM (HTTP v1), APNs (HTTP/2, token authentication) and Web Push (VAPID, RFC 8291). |
|
query
Package query parses and checks the list query language (where, order_by) against a collection's schema, producing backend-neutral storage conditions.
|
Package query parses and checks the list query language (where, order_by) against a collection's schema, producing backend-neutral storage conditions. |
|
registry
Package registry loads the realm/database/collection tree from CONFIG_DIR into an immutable, validated registry used by routing, validation and provisioning.
|
Package registry loads the realm/database/collection tree from CONFIG_DIR into an immutable, validated registry used by routing, validation and provisioning. |
|
rules
Package rules checks and compiles a collection's rules (the `rules:` section of its collection.yaml): expr-lang expressions deciding, per operation, whether a caller may act on a whole document.
|
Package rules checks and compiles a collection's rules (the `rules:` section of its collection.yaml): expr-lang expressions deciding, per operation, whether a caller may act on a whole document. |
|
rulestest
Package rulestest runs the fixtures of `backd rules test`: it decides who may read, create, update and delete which documents of a collection, with the collection's real rules (the `rules:` of its collection.yaml) and schema.json and no database, and compares the decisions with what the fixture expects.
|
Package rulestest runs the fixtures of `backd rules test`: it decides who may read, create, update and delete which documents of a collection, with the collection's real rules (the `rules:` of its collection.yaml) and schema.json and no database, and compares the decisions with what the fixture expects. |
|
settings
Package settings reads backd's runtime configuration from environment variables.
|
Package settings reads backd's runtime configuration from environment variables. |
|
storage
Package storage defines the backend-neutral data access contract.
|
Package storage defines the backend-neutral data access contract. |
|
storage/storagetest
Package storagetest is a small in-memory S3 server for tests that need an object storage but not a real one: path-style addressing, the operations backd uses (bucket HEAD, PUT, GET with Range, HEAD, DELETE, ListObjectsV2) and the signed SHA-256 check a PUT carries.
|
Package storagetest is a small in-memory S3 server for tests that need an object storage but not a real one: path-style addressing, the operations backd uses (bucket HEAD, PUT, GET with Range, HEAD, DELETE, ListObjectsV2) and the signed SHA-256 check a PUT carries. |
|
templates
Package templates writes commented starter files for realms and databases into CONFIG_DIR (`backd template`).
|
Package templates writes commented starter files for realms and databases into CONFIG_DIR (`backd template`). |
|
typegen
Package typegen turns a realm's loaded config into TypeScript types: documents, queries, functions, configuration, templates and roles.
|
Package typegen turns a realm's loaded config into TypeScript types: documents, queries, functions, configuration, templates and roles. |
Click to show internal directories.
Click to hide internal directories.