Atomic: Backends, Functions and Workers
Atomic is where your code is declared, inside one atomic block. A backend groups the source of one language, and inside it each function and each worker names a handler in that source and books the memory it runs in. Your source carries none of that: it is ordinary code, and the Driftfile is the whole declaration of what the slice exposes, which callable serves it, what it books and what guards it.
A Function answers one call with one result. A Worker is a long-running process that the slice keeps running. Timeouts, deploy history and the storage budget are slice-wide and live in the limits block of slice. The request rate and outbound egress are declared under edge, with everything else about what reaches the slice and what it reaches.
- Labels
- none
- Meaning
- The container for every backend. At most one per file.
- Labels
- the backend's name
- Meaning
- Inside
atomic: a folder of one language's source and its one dependency manifest. Holdsfunctionandworkerblocks.
- Labels
- an HTTP method and route, or
QUEUEand a queue name - Meaning
- One handler, its memory booking, and what guards and shapes it.
- Labels
- none
- Meaning
- Inside a
function: an API key gate.
- Labels
- the worker's name
- Meaning
- One long-running process and its memory booking.
Backends
A backend is the group of Functions and Workers that share one language, one dependency manifest and one runtime. The backend named "default" is the folder ./atomic itself. Any other name is the folder ./atomic/<name>, and dir points a backend somewhere else.
- Type
- label
- Default
- REQUIRED
- Meaning
"default"is./atomic; any other name is./atomic/<name>. Declared once per file.
- Type
- string
- Default
- the folder the name implies
- Meaning
- The backend's folder, relative to the Driftfile, when it is not the default one.
- Type
- block
- Default
- none
- Meaning
- A Function that lives in this backend.
- Type
- block
- Default
- none
- Meaning
- A Worker that lives in this backend.
A backend with no function and no worker is refused, since it books nothing and runs nothing. A folder that does not exist is refused at the backend's line. Each Function and Worker is declared inside the backend its handler lives in, so two backends may each have a handler with the same name. See Backends for how a folder becomes a deployable unit.
Functions
function "TRIGGER" is labelled with how it is called. An HTTP Function is labelled with its method and route, written the way people write a route: "GET /ping", "POST /rpc", "GET /groups/:id". The method is one of GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS, and the route sits under /api/. A queue Function is labelled QUEUE and the queue it drains, "QUEUE orders": the slice invokes it once per message, and it has no URL. Declare the queue itself with a queue block.
The method is part of the identity, not a detail: GET /items and POST /items are two Functions with two bookings. The booking key of a Function is its method and route, unique across the slice.
- Type
- string
- Default
- REQUIRED
- Meaning
- The callable in the backend's source that serves this Function:
PostRPC,handle_order,createBoard. Looked for in the backend's folder only. It has to be reachable from outside its file: exported in Go,pubin Rust, a namedfunctionin Node.
- Type
- size
- Default
- REQUIRED
- Meaning
- The memory it books, in whole MiB, from
"8MiB"to"256MiB"("16MiB"or more in a compiled language). See the memory booking.
- Type
"envelope","json"or"raw"- Default
"envelope"- Meaning
- The shape of the Function's own reply.
envelopewraps your payload as{status, message, payload}, which is what the SDKs expect.jsonwrites your payload as the whole body, for an endpoint a third party parses directly: a webhook receiver, an OAuth token endpoint.rawwrites it as bytes, base64-decoded, for a body that is not text at all; set your own Content-Type with it.
- Type
- bool
- Default
false- Meaning
- Whether the handler is safe to run in parallel.
truelets one warm process serve many calls at once; how many is the slice's to decide, and there is no count to write. A streaming Function must leave itfalse.
- Type
"sse"or"ws"- Default
- buffered
- Meaning
- Hold the connection open instead of buffering one response:
"sse"for Server-Sent Events,"ws"for WebSocket. See streaming.
- Type
- string
- Default
- none
- Meaning
- A five-field cron expression that also runs the Function on a schedule. An HTTP Function with a
cronstays callable over HTTP.
- Type
- duration string
- Default
"500ms"- Meaning
- On a Function labelled
QUEUE: how often the slice looks in the queue, from"50ms"to"60s". Refused on any other Function.
- Type
- number
- Default
3- Meaning
- On a Function labelled
QUEUE: how many times a message that makes it fail is delivered again before it moves to<queue>-dlq, from 1 to 100. Refused on any other Function.
- Type
- map of string
- Default
- none
- Meaning
- Plain configuration injected into the Function's process environment: a base URL, a bucket name, a feature flag, anything that is not a credential. A short list of names,
DRIFT_*and a few others such asBACKBONE_URL, is reserved and refused.
- Type
- list of string
- Default
- none
- Meaning
- The names of the Backbone secrets this Function may read. A secret not named here is unreachable from it, though the slice holds it.
- Type
- string
- Default
- the backend's folder
- Meaning
- The folder its handler is in, relative to the Driftfile, for the odd Function that lives outside its backend's folder.
- Type
- block
- Default
- none
- Meaning
- An API key gate. See Gating a Function with an API key.
- Type
- block, repeatable
- Default
- none
- Meaning
- A condition the slice watches on this Function and the webhook it tells. See Alerts.
slice "orders" {}
backbone {
secret "STRIPE_KEY" {
value = env("STRIPE_KEY")
}
queue "orders" {}
}
atomic {
backend "default" {
function "GET /digest" {
handler = "GetDigest"
memory = "32MiB"
concurrent = true
}
function "POST /charge" {
handler = "PostCharge"
memory = "64MiB"
secrets = ["STRIPE_KEY"]
env = { STRIPE_API_BASE = "https://api.stripe.com" }
auth {
api_key = env("CHARGE_KEY")
}
}
function "POST /webhooks/stripe" {
handler = "PostStripeWebhook"
memory = "32MiB"
response = "json"
}
function "GET /events" {
handler = "GetEvents"
memory = "32MiB"
stream = "sse"
}
function "QUEUE orders" {
handler = "HandleOrder"
memory = "32MiB"
}
}
backend "billing" {
function "POST /reconcile" {
handler = "PostReconcile"
memory = "32MiB"
cron = "0 3 * * *"
}
worker "ledger" {
handler = "Ledger"
memory = "64MiB"
}
}
backend "reports" {
dir = "atomic/reports-src"
function "GET /reports/daily" {
handler = "GetDaily"
memory = "32MiB"
}
}
}The cron expression has five fields, and a malformed one is refused when the file is checked. scheduled_jobs in limits defaults to the number of Functions that carry a cron, the fewest that runs them; writing fewer is refused. drift file lint also checks that every handler exists in its backend's source.
Gating a Function with an API key
An auth block puts an API key in front of one Function: it answers only a caller that presents the key. The block has one attribute, api_key, and it is always written env("NAME"), so the file never holds the key.
- Type
env("NAME")- Default
- REQUIRED
- Meaning
- The environment variable the key is read from at apply. A literal,
var.xandfile()are refused: the Driftfile is committed, and a key in it would be committed with it.
drift plan compares a key by the slice's fingerprint, the last four characters. A key that matches is left alone, and a different one shows as rotates to the key in $CHARGE_KEY. The variable is read through the env() sources: the terminal, then --var, then .env.<environment>, then .env. A Function with no auth block has no gate. See authentication for what the gate does to a request.
Workers
A Worker is a long-running process. The slice keeps exactly one running, starts it on every deploy and restarts it when it exits. A Worker runs Go. Its booking key is worker:<name>.
- Type
- string
- Default
- REQUIRED
- Meaning
- The callable it runs,
func Name(ctx context.Context) error.
- Type
- size
- Default
- REQUIRED
- Meaning
- The memory it books,
"16MiB"or more, since a Worker runs Go. What it is billed at.
- Type
- map of string
- Default
- none
- Meaning
- Plain configuration injected into its environment.
- Type
- list of string
- Default
- none
- Meaning
- The secrets this Worker may read.
- Type
- string
- Default
- the backend's folder
- Meaning
- The folder its handler is in, when it is not its backend's.
atomic {
backend "billing" {
worker "ledger" {
handler = "Ledger"
memory = "64MiB"
env = { LEDGER_MODE = "append" }
secrets = ["STRIPE_KEY"]
}
}
}The memory booking
Every Function and every Worker states its memory. It is the Function's or Worker's own pool and what it is billed at, so it has no default: a figure nobody chose is one nobody can be held to. A missing memory is refused, naming the Function or Worker.
| Case | Range |
|---|---|
| a Function | "8MiB" to "256MiB", in whole MiB |
| a Function in a compiled language | "16MiB" to "256MiB" |
| a Worker | "16MiB" or more |
A size is a whole number of KiB, MiB or GiB. "64MB" is refused rather than guessed at:
Driftfile:13:15: Not a size: function "GET /b": memory "32MB" is not a size: write a whole number of KiB, MiB or GiB, e.g. "64MiB"drift file benchmark reports what each Function and Worker has measured, with the size it should book. drift size writes those figures into the memory lines of your Driftfile, keeping comments and layout, and shows the change as a diff (--dry-run shows it without writing). A Function nobody has called is left alone. Then drift plan shows what the new bookings cost, and drift apply applies them like any other edit. A booking that shrinks is a removal that apply asks about, and a change in the total booked memory restarts the slice once.
The number of slots the slice holds is the number of Functions and Workers in the file, so no count is written.
Alerts
An alert fires a notification when a Function errors. It is an alert block inside the Function it watches, planned and applied with the rest of the file:
function "POST /checkout" {
handler = "PostCheckout"
memory = "32MiB"
alert "checkout-errors" {
threshold = 1
window = "5m"
webhook = env("CHECKOUT_ALERT_HOOK")
}
}The label is the alert's name, unique across the whole slice. on accepts "errors", which is also its default. threshold is the number of errors within the window that fires the alert, and defaults to 1. window is the evaluation window, "1m" at the least, and defaults to "5m". webhook is the environment variable holding the http(s) URL to notify, the one channel there is. The URL carries whatever credential its endpoint needs, so it is written env("NAME") like every other write-only value and never appears in the file or in the plan.
drift plan lists each alert as added, changed or removed, and drift apply sets them once the Function is deployed. An alert the file does not name is deleted on apply, after the question every removal asks. drift atomic alert list shows the alerts the slice holds.
Outbound egress
Which hosts your Functions and Workers may reach is declared once, under edge.egress. It is not repeated here: the allowlist belongs to the slice, so it sits with the rest of what reaches the slice and what it reaches.
Read the Atomic guide for how to write a handler.