Functions on backd

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

You will create a config repository with a working sample function, run it locally, call it three ways, write your own, see what it did, and test it. You need Docker (or Podman) and the backd binary; Deno is optional, because the build can run in Deno’s own image.

1. Create a project

backd template project --dir ./shop --realm shop
cd shop

This writes a complete repository: the shop realm with a sample database, a sample function with a test, Dockerfiles, a compose.yaml for local development (MongoDB, backd, the functions executor and the egress proxy) and a CI workflow. Everything you need is in the generated README.md; the parts below follow it.

Writing a function

Mon, 01 Jan 0001 00:00:00 +0000

Layout

Each database may have one _functions directory: a Deno project for that application’s functions.

<realm>/<database>/
 posts/ collections, as usual
 _functions/
 deno.json the project's Deno config (imports), optional
 deno.lock pinned dependency versions, written by Deno
 lib/ code shared by the functions (not a function)
 stats/ one folder per function, named like collections
 function.yaml how the function runs (all keys optional)
 index.ts the code: index.ts or index.js
 input.schema.json optional JSON Schema of the input
 output.schema.json optional JSON Schema of the output
 .build/ bundles, written by `backd functions build`

Function names follow the same rules as collection names; lib is reserved for shared code.
The module’s default export is the function: it receives the call’s context and returns the output (any JSON value).

type Context = {
 input: unknown;
 user: { id: string; email: string; email_verified: boolean; roles: string[] } | null;
};

export default async function handler(ctx: Context) {
 return { hello: ctx.user?.email ?? "anonymous" };
}

Create a starter with:

Calling functions

Mon, 01 Jan 0001 00:00:00 +0000

Calling a function

curl -X POST https://api.example.com/v1/shop/orders/_func/checkout \
 -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
 -d '{"cart": "c1"}'
# → 200 {"order": "o7", "total": 1250}

The body is the function’s input (ctx.input), any JSON value; an empty body is null. The answer is its output. webhook functions are different: see Webhooks — the raw body reaches ctx.request.body unparsed, Content-Type isn’t required to be JSON, and the function’s own response is returned as-is.
In realms with auth: enabled, API keys may always call; other callers need the function’s invoke rule (webhook always needs one that allows anonymous callers). With X-Backd-On-Behalf-Of, an API key calls as that user.
With input.schema.json, invalid input answers 400 validation_error; with output.schema.json, an output that doesn’t match answers 500 invalid_output (and is logged). Neither applies to webhook.
An Idempotency-Key header reaches the function as ctx.idempotencyKey, and also deduplicates the call itself (see Idempotency).
sync functions run immediately and answer with their output, as above. async functions (below) answer 202 with a job to poll. webhook functions (below) set their own response.

Answer	When
`200`	A `sync` function returned; the body is its output
`202`	An `async` function was queued; poll `Location` for its result (see Async jobs)
(the function’s own choice)	A `webhook` function’s own response (see Webhooks)
`4xx` with the function’s code	The function threw `ctx.error(status, code, message)` (for `async`, this lands in the job’s `result` instead; `webhook` functions answer errors through their own response, not `ctx.error`)
`400 validation_error`	The input doesn’t match `input.schema.json`
`400 idempotency_key_required`	`function.yaml` has `idempotency: required` and the call has no `Idempotency-Key`
`401`, `403`	The `invoke` rule doesn’t allow the caller
`404 not_found`	No such function
`409 request_in_progress`	A call with this `Idempotency-Key` is still running (see Idempotency)
`422 idempotency_key_reused`	This `Idempotency-Key` was already used with different input
`429 too_many_requests`	A `sync` or `async` function, or its realm, is at its concurrency limit on this instance (`Retry-After: 1`); or the caller is over the function’s rate limit (`Retry-After` set to when it resets)
`500 function_failed`	The function threw another error, crashed, or went over its memory or CPU limit. The stack trace is in `backd`’s log only
`500 invalid_output`	The output is larger than `max_output`, or doesn’t match `output.schema.json`
`500 secret_missing`	The function declares a secret that isn’t set for its database or realm
`503 unavailable`	The executor isn’t configured, doesn’t answer, or runs its maximum of functions (`Retry-After: 1`); or a `webhook` function is at its concurrency limit (`Retry-After: 1` — `503`, not `429`, since webhook senders retry on 5xx)
`504 function_timeout`	The function didn’t finish within its `timeout`; it was stopped

From the JavaScript client and the command line

The same call, three ways:

function.yaml reference

Mon, 01 Jan 0001 00:00:00 +0000

function.yaml

Every key is optional. backd reads the file strictly: an unknown key or an invalid value stops startup, naming the file.

Key	Default	Meaning
`mode`	`sync`	`sync`: the caller waits for the output. `async`: the caller gets a job to check later. `webhook`: for callbacks from other services (see Webhooks) — needs `invoke` set to a rule that allows anonymous callers
`timeout`	`10s` (`sync`, `webhook`), `15m` (`async`)	The function is stopped after this long. At least `1s`; at most `60s` for `sync` and `webhook`, `24h` for `async`
`memory`	`128MB`	Memory for the function’s JavaScript heap, from `32MiB` to `4GiB`
`max_output`	`1MiB`	The largest output accepted, from `1KiB` to `64MiB` (`15MiB` for `async`)
`concurrency`	`10`	How many calls of the function may run at once on each `backd` instance (1–1000). With several instances, up to that many times this value run at once
`rate_limit`	none	Calls allowed per caller, counted across instances: `{per: user \| ip, limit: <n>, window: <duration>}`, window from `1s` to `24h`
`idempotency`	`optional`	Whether calls must send an `Idempotency-Key` header: `optional` or `required`
`invoke`	none	Who may call the function (see below). Without it, only API keys may call it
`admin`	`false`	`true` gives the function full access to the realm’s data, whatever the caller may do. Keep it off unless the function needs it
`internal`	`false`	`true` removes the function’s HTTP route: `_func/<name>` answers `404` to everyone, like a function that doesn’t exist. Only `backd` and scheduled runs may call it (see Internal functions). Can’t be combined with `invoke` or `mode: webhook`
`dev_only`	`false`	`true` makes `backd` refuse to start with the function unless `BACKD_DEV=true`: for development helpers such as the email capture function, which must never run in production
`email`	`false`	`true` gives the function `ctx.email.send()`: custom emails through the realm’s templates and delivery function, to any recipient, within the caps of `email.limits`. Needs `email` in `realm.yaml`; read the warning on that page first
`calls`	none	The functions of the same database this one lists as callable (see Internal functions); startup rejects unknown names, cycles and chains longer than 4 functions
`retry`	none	Tries a failed `async` function again: `{attempts, backoff, max_backoff}` (see Retrying a failed job). A single attempt unless `attempts` is above 1
`on_complete`	none	For an `async` function: `{function, on?}` queues that async function of the same database when a job of this one ends, with the outcome as its input; `on` narrows it to `ok`, `failed`, `cancelled`. See Be told when it ends
`schedule`	none	A cron expression: the function runs on a schedule. Needs `mode: async` and at least one running worker
`timezone`	`UTC`	For a scheduled function: the IANA time zone the schedule is read in, such as `Europe/Madrid`. Daylight saving changes are handled (documented there). Needs `schedule`
`overlap`	`allow`	For a scheduled function: `skip` doesn’t run a scheduled time while the function’s previous job hasn’t finished, and records the time as a `skipped` job. Needs `schedule`
`secrets`	none	Secrets the function may read: `NAME` (its own database’s) or `realm.NAME` (the realm’s). Names are upper-case letters, digits and `_`
`network`	none	Hosts the function may call: `host` or `host:port`, lower case, no scheme, path or wildcard. Without a list, a function can only call `backd`

Durations are written as in realm.yaml (30s, 15m, 1d). Sizes need a unit: B, KB, MB, GB (powers of 1000) or KiB, MiB, GiB (powers of 1024).

Async jobs

Mon, 01 Jan 0001 00:00:00 +0000

mode: async runs a function in the background instead of within the request. The call answers 202 at once with a job, and a worker runs the function later, on its own schedule and for as long as its timeout allows.

Use it when the work:

takes more than a few seconds (a sync call is capped at 60 s, and a caller shouldn’t be made to hold a request open for anything close to that);
must survive the caller going away (a browser tab closed, a mobile app suspended);
can be retried safely if something goes wrong;
fans out (a batch of emails, a report over many documents, a slow third-party call).

Use a sync function when the caller needs the answer to continue and it’s quick. Use cron when nobody asks for the work: it just has to happen on a schedule.

Scheduled functions

Mon, 01 Jan 0001 00:00:00 +0000

Add schedule to an async function and it runs by itself, with no caller: nightly cleanups, daily digests, hourly syncs, monthly reports.

examples/config/workshop/main/_functions/nightly_cleanup/function.yaml

# A scheduled function: `schedule` (cron, UTC) on an async function. There is
# no caller, so ctx.input is empty, ctx.user is null, and ctx.admin.db (full
# access, recorded as this function) is always available in a scheduled run.
# Needs at least one running worker: `backd worker`, or
# `backd serve --with-worker`.
#
# `internal: true`: nobody can call it over HTTP. An administrator can still
# run it by hand to test it, as its schedule would run it:
# backd functions invoke --function workshop/main/nightly_cleanup
internal: true
mode: async
schedule: "0 3 * * *" # every day at 03:00 UTC
timeout: 10m

examples/config/workshop/main/_functions/nightly_cleanup/index.ts

Internal functions

Mon, 01 Jan 0001 00:00:00 +0000

Some functions must never be reachable from the internet: a clean-up that deletes data, a helper shared by several public functions, a scheduled job nobody should trigger by hand. An internal function has no HTTP route at all.

Marking a function internal

# _functions/cleanup/function.yaml
internal: true
mode: async

POST /v1/<realm>/<database>/_func/cleanup now answers 404 not_found, exactly like a function that doesn’t exist, to every caller: anonymous, signed in, API keys of either role. Nothing reaches the executor, and the answer doesn’t reveal that the function exists.

Email

Mon, 01 Jan 0001 00:00:00 +0000

backd never talks to a mail server. A realm names one delivery function: an internal, async function that receives a finished message and hands it to whatever provider you chose (Postmark, SES, Resend, Mailgun, SendGrid, …). backd does everything else: the templates, the tokens and links, the retries, the limits.

Note

backd sends no mail from its own servers or addresses, so deliverability is your responsibility, handled with your provider: a verified sending domain (SPF, DKIM, DMARC), a dedicated sender address, the provider’s bounce and complaint handling and suppression lists. Watch your provider’s bounce and complaint rates before sending real email, and try the flows with a test mailbox first.

Configuration

Email is configured in realm.yaml; backd template realm writes the section commented, with every key explained. A realm without email sends no email at all.

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

mode: webhook receives a callback from another service — Stripe, GitHub, and the like — and answers it directly: ctx carries the raw request instead of parsed input, and the function sets the response’s status, headers and body itself instead of returning a JSON value backd interprets.

Warning

A webhook function is callable by anyone on the internet (invoke must allow anonymous callers), so the function itself is the only check. Verify the sender’s signature against the raw body before doing anything, and deduplicate by the sender’s event id: providers retry.

Payment provider example: payment_webhook verifies the sender’s HMAC signature, deduplicates the provider’s retries by event id, and marks the order paid.

Secrets

Mon, 01 Jan 0001 00:00:00 +0000

A function that needs a third-party API key, or any value it shouldn’t hold in its own code, declares it in function.yaml’s secrets list and reads it from ctx.secrets, decrypted, at call time — never from an environment variable, which the function’s process doesn’t have.

Outbound network

Mon, 01 Jan 0001 00:00:00 +0000

Calling an outside API

A function reaches the outside world only for hosts it declares. Say it needs to email a digest through a provider’s HTTP API: declare the host, declare the key as a secret, and use fetch:

# function.yaml
mode: async
schedule: "@daily"
network: [api.mailer.example]  # host or host:port, lower case; no scheme, path or wildcard
secrets: [MAILER_KEY]

const res = await fetch("https://api.mailer.example/v1/send", {
 method: "POST",
 headers: { "content-type": "application/json", authorization: `Bearer ${ctx.secrets.MAILER_KEY}` },
 body: JSON.stringify({ to: "ops@example.com", subject: `Digest ${day}`, text: `${orders} orders, ${revenue / 100} in revenue` }),
});
if (!res.ok) throw ctx.error(424, "mailer_failed", `the mail provider answered ${res.status}`);

A request to any host not in network fails, and so does one to a private, loopback or link-local address, even for a declared host name that resolves to one.
Without a network list, a function can only call backd itself (through ctx.db).
This is how the cookbook’s daily_digest would send its result by email instead of storing it.
Send an idempotency key to the provider when the call has side effects and the function can run twice (Async jobs).

Egress: the network allowlist, completed

Why this exists. A function runs code you may not have written yourself (an npm dependency, a library update). If its outbound network were left to a single hostname allowlist, a bug or a compromised dependency could still: connect to MongoDB or another private service directly; reach your cloud provider’s metadata endpoint (169.254.169.254) and steal the credentials your infrastructure runs as (SSRF); or reach the executor’s or backd’s own internal endpoints. A hostname allowlist alone doesn’t stop any of this, because it checks names, not the addresses they resolve to — an allowed name can resolve to a private or loopback address (by mistake, by DNS rebinding, or because an attacker controls that DNS record) — and a raw TCP connection (Deno.connect, used directly instead of fetch) never goes through an HTTP proxy at all, so a proxy-based check alone can’t see it either.

Build, dev and test

Mon, 01 Jan 0001 00:00:00 +0000

Building

Functions are bundled before backd starts: each function, with everything it imports (lib/, npm and JSR packages), becomes one JavaScript file.

CONFIG_DIR=./config backd functions build
# bundled blog/main/stats → stats-3f2a9c0d1e4b5a6c.js (1843 bytes)

On Windows and macOS, backd itself runs, but its executor doesn’t (see what runs where): develop with the local stack’s containers, which include one.
The build runs deno bundle and needs Deno 2.9.7 on the PATH (or the binary named by DENO); it refuses any other version, because bundles must match the Deno that runs them. Without Deno installed, run it in the official Deno image with a Linux backd binary (from the release archives):

Running in production

Mon, 01 Jan 0001 00:00:00 +0000

What runs where

Functions add up to four kinds of process. All are the same backd binary (the executor’s image adds Deno), each in its own role:

Process	Command	Needed for	How many
API	`backd serve`	calling functions over HTTP	as many as you like, all with the same config
Executor	`backd executor`	running any function	one or more, reachable only from `backd` and workers
Worker	`backd worker`, or `backd serve --with-worker`	async jobs and cron schedules	one or more; each job and each scheduled run is done by exactly one
Egress	`backd egress`	functions that declare `network`	one or more; the executor’s only way out

Function logs

Mon, 01 Jan 0001 00:00:00 +0000

Every function call — sync, webhook, and once an async job finishes — is recorded in <realm>___system.invocations: what happened, not what was sent or returned. backd is a short debugging window, not a log archive — plan to ship logs elsewhere for anything you need to keep.

What’s recorded

The function (<database>/<name>), who called it, its mode, status and duration.
The function’s own console output (console.log, console.error, …), already masked of any declared secrets’ exact values.
The steps the function reported with ctx.step(), closed when the call ended (at most 100).
The request id, so a record can be matched to backd’s own JSON log line for the same call.
Never the input or output. If you need to reproduce what a specific call did, log what matters yourself with console.log inside the function.

{
 "id": "d3c9ljp8hc2g00b6s1m0",
 "at": "2026-09-29T12:00:03.500Z",
 "function": "orders/checkout",
 "actor": "user:d3c9lg38hc2g00b6s1lg",
 "mode": "sync",
 "status": "ok",
 "code": null,
 "duration_ms": 118,
 "request_id": "darf9mq5mh5g00aq9df0",
 "job_id": null,
 "parent_id": null,
 "origin": "http",
 "logs": [{ "level": "log", "line": "charging card for 1250" }],
 "steps": [],
 "steps_omitted": 0
}

status is one of ok, function_error, timeout, memory, cpu, crash, output_too_large, busy, bundle or cancelled (an async job’s attempt that an administrator cancelled while it ran) — the same reasons a call can end that show up in backd’s own log and in the error table. code is the function’s own error code (ctx.error’s second argument) when status is function_error. For an async call, mode is async and job_id names the job; the record is written once the job finishes, not when it’s queued.

Cookbook

Mon, 01 Jan 0001 00:00:00 +0000

Every recipe here is a function of the workshop realm (examples/config/workshop in the repository): a tiny shop with orders, refunds, reports, digests and events. The code on this page is read straight from those files, and TestWorkshopExample runs every function for real (MongoDB, a real executor, a real worker), so what you read is what runs.

Run the workshop

The repository’s local stack serves the realm, and its backd runs a worker (serve --with-worker), so jobs and schedules work:

Files in functions

Mon, 01 Jan 0001 00:00:00 +0000

A function reaches the files of a document through the same client it uses for data: files(id, field) on a collection of ctx.db or ctx.admin.db. It makes the same requests as any client, to the _files routes, so the same limits, type detection, journal and usage totals apply.

const photos = ctx.db("main").collection("people").files(personId, "photo");

const doc = await photos.put(bytes, { name: "ada.png", type: "image/png" }); // the updated document
const file = await photos.get(); // { file, response, bytes(), text() }
const link = await photos.link(); // { url, expires_at }
await photos.delete(); // the field's files; delete(fileId) removes one


`put(data, { name, type, ifMatch })`	Stores a file (a string, bytes, a `Blob` or a stream): it replaces a single field’s file and is added to a `multiple` field’s. Resolves with the document, which now holds the file’s details. `type` is a hint: backd detects the real one from the content
`get(fileId?)`	Downloads a file. Without `fileId`, the one a single field holds; a field with several needs one. The bytes come through backd, even where downloads are redirects for everyone else, because a function can’t reach the bucket
`link(fileId?)`	`{ url, expires_at }`, exactly like `?link=json`: for the app to open. A link of the storage is for the bucket; a backd link needs `BACKD_URL`, so it can name backd’s public address
`delete(fileId?, { ifMatch })`	Removes one file, or every file of the field. Resolves with the document

As the caller, or as the function

ctx.db acts as the caller: put and delete are asked of the document’s update rule (with data and changed() as for an upload), get and link of the read rule, and an upload is recorded as theirs. A document the caller can’t read is a NotFoundError.

Functions on backd

Quickstart

1. Create a project#

Writing a function

Layout#

Calling functions

Calling a function#

From the JavaScript client and the command line#

function.yaml reference

function.yaml#

Async jobs

Scheduled functions

Internal functions

Marking a function internal#

Email

Configuration#

Webhooks

Secrets

Outbound network

Calling an outside API#

Egress: the network allowlist, completed#

Build, dev and test

Building#

Running in production

What runs where#

Function logs

What’s recorded#

Cookbook

Run the workshop#

Files in functions

As the caller, or as the function#

1. Create a project

Layout

Calling a function

From the JavaScript client and the command line

function.yaml

Marking a function internal

Configuration

Calling an outside API

Egress: the network allowlist, completed

Building

What runs where

What’s recorded

Run the workshop

As the caller, or as the function