Functions

Server-side functions run code you write on the server, next to your collections, for the things a client must not do or be trusted with: computing what readers may not compute themselves, making privileged changes, calling payment or email services with a secret, working on a schedule, answering another service’s callbacks. Each function is a small JavaScript or TypeScript module in your CONFIG_DIR, next to the collections it works on. backd runs it in Deno, in its own process, with only the permissions and limits it declares.

They are a core part of backd, not an add-on: a function reaches data through the same access rules as any other caller (or, when you say so, with full access), and everything around it is built in: input and output schemas, per-caller rate limits, idempotent retries, encrypted secrets, a network allowlist, background jobs, cron schedules, invocation history and console logs.

What a function looks like#

A function is a folder with a function.yaml (how it runs) and an index.ts (what it does). This one prices one of the caller’s orders. It runs as the caller, so the orders’ access rules decide which orders they can read:

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

# A sync function that runs as the caller: ctx.db reads with the caller's
# own access rules, so a customer can only price their own orders.
invoke: "user != nil"

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

// order_total: the amount a customer will be charged for one of their
// orders. The tax rule lives here, on the server, not in every client.
//
// ctx.db acts as the caller, so orders/collection.yaml decides what they may
// read: someone else's order (or one that doesn't exist) answers 404, the
// same as reading the collection directly would.
import { relay } from "../lib/relay.ts";
import type { Context, Doc } from "../lib/types.ts";

const TAX_RATE = 0.2;

export default async function handler(ctx: Context) {
  const { order_id } = ctx.input as { order_id: string };

  let order: Doc;
  try {
    order = await ctx.db("main").collection("orders").get(order_id);
  } catch (err) {
    relay(err, ctx.error);
  }
  if (order.status === "refunded") {
    throw ctx.error(409, "order_refunded", "This order was refunded");
  }

  const subtotal = order.amount as number;
  const tax = Math.round(subtotal * TAX_RATE);
  return { order_id, subtotal, tax, total: subtotal + tax };
}

curl -X POST https://api.example.com/v1/workshop/main/_func/order_total \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"order_id": "d3c9ljp8hc2g00b6s1m0"}'
# → 200 {"order_id": "d3c9ljp8hc2g00b6s1m0", "subtotal": 1000, "tax": 200, "total": 1200}

This function, and every other one quoted in this section, is in examples/config/workshop in the repository, where it is tested for real; the Cookbook walks through them all.

Which kind of function do I need?#

The three modes, and cron#

How it fits together#

 client ── HTTP ──▶ backd ── runs the function in ──▶ executor ─▶ one Deno process per call
                     │  ▲                                              │
                     │  └────── ctx.db / ctx.admin.db, over an ◀───────┘
                     │           internal listener (short-lived credentials)
                     │
              worker (async jobs and cron schedules) ── also uses the executor
                                                               │  network: only what the function
                                                               ▼  declares, through backd egress

• backd authenticates the caller, applies the function’s invoke rule, validates input and output, and answers.
• The executor starts one Deno process per call and stops it at its deadline. It never sees CONFIG_DIR, MongoDB or the signing keys.
• A worker (backd worker, or backd serve --with-worker) claims async jobs and creates the runs of scheduled functions. Async jobs and cron only happen while at least one worker runs.
• backd egress is the only way a function reaches the outside network, and only the hosts it declares.

What backd enforces for you#

• The caller’s rules apply to ctx.db; full access needs an explicit admin: true (or is the point of a scheduled run).
• Time, memory, output size and concurrency limits per function, and a per-caller rate limit you can declare.
• Input and output JSON Schemas, checked on every call.
• Idempotency keys, so a retried request doesn’t do the work twice.
• Secrets encrypted at rest and delivered as ctx.secrets, masked in logs.
• No environment variables, no files but the function’s bundle, no processes, and a network limited to a declared allowlist.
• A record of every call (never its input or output) and the function’s own console output, kept for a week by default.

Where to go next#

• New here? Start with the Quickstart, then Writing a function.
• Calling functions: Calling functions covers HTTP, the JavaScript client and the CLI, and the answers you can get.
• Background work: Async jobs (including how to know a job finished) and Scheduled functions (when to use cron).
• Recipes: the Cookbook has six complete, tested examples.
• Reference: function.yaml, Secrets, Outbound network, Build, dev and test, Function logs.
• Operating it: Running in production, and the production reference deployment.
• Worked examples with commentary: the blog example’s stats function is the smallest possible one; Expenses with functions is a complete small app built around five functions, compared side by side with a version that doesn’t use them.