backd

module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2026 License: MIT

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 via ETag/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/config holds one directory per realm (with a realm.yaml), database and collection, each collection with a schema.json. backd template realm <name> --sample creates a starter realm.
  • shop realm — auth: disabled, so the requests above need no key.
  • blog realm — 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)

Documentation lives in docs/ and is built with Hugo.

License

MIT

Directories

Path Synopsis
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
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, always in UTC.
 Package cron parses five-field cron expressions and computes their schedule, always in UTC.
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.
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.
jsonnum
Package jsonnum converts json.Number values into concrete Go numbers.
 Package jsonnum converts json.Number values into concrete Go numbers.
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.
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 loads and checks a collection's rules.yaml: expr-lang expressions deciding, per operation, whether a caller may act on a whole document.
 Package rules loads and checks a collection's rules.yaml: expr-lang expressions deciding, per operation, whether a caller may act on a whole document.
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.
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`).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.