drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

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.

LabelsMeaning
  • atomic
    Labels
    none
    Meaning
    The container for every backend. At most one per file.
  • backend "name"
    Labels
    the backend's name
    Meaning
    Inside atomic: a folder of one language's source and its one dependency manifest. Holds function and worker blocks.
  • function "TRIGGER"
    Labels
    an HTTP method and route, or QUEUE and a queue name
    Meaning
    One handler, its memory booking, and what guards and shapes it.
  • auth
    Labels
    none
    Meaning
    Inside a function: an API key gate.
  • worker "name"
    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.

TypeDefaultMeaning
  • backend "name"
    Type
    label
    Default
    REQUIRED
    Meaning
    "default" is ./atomic; any other name is ./atomic/<name>. Declared once per file.
  • dir
    Type
    string
    Default
    the folder the name implies
    Meaning
    The backend's folder, relative to the Driftfile, when it is not the default one.
  • function
    Type
    block
    Default
    none
    Meaning
    A Function that lives in this backend.
  • worker
    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.

TypeDefaultMeaning
  • handler
    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, pub in Rust, a named function in Node.
  • memory
    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.
  • response
    Type
    "envelope", "json" or "raw"
    Default
    "envelope"
    Meaning
    The shape of the Function's own reply. envelope wraps your payload as {status, message, payload}, which is what the SDKs expect. json writes your payload as the whole body, for an endpoint a third party parses directly: a webhook receiver, an OAuth token endpoint. raw writes it as bytes, base64-decoded, for a body that is not text at all; set your own Content-Type with it.
  • concurrent
    Type
    bool
    Default
    false
    Meaning
    Whether the handler is safe to run in parallel. true lets 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 it false.
  • stream
    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.
  • cron
    Type
    string
    Default
    none
    Meaning
    A five-field cron expression that also runs the Function on a schedule. An HTTP Function with a cron stays callable over HTTP.
  • poll
    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.
  • max_retries
    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.
  • env
    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 as BACKBONE_URL, is reserved and refused.
  • secrets
    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.
  • dir
    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.
  • auth
    Type
    block
    Default
    none
    Meaning
    An API key gate. See Gating a Function with an API key.
  • alert "name"
    Type
    block, repeatable
    Default
    none
    Meaning
    A condition the slice watches on this Function and the webhook it tells. See Alerts.
Driftfile
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.

TypeDefaultMeaning
  • api_key
    Type
    env("NAME")
    Default
    REQUIRED
    Meaning
    The environment variable the key is read from at apply. A literal, var.x and file() 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>.

TypeDefaultMeaning
  • handler
    Type
    string
    Default
    REQUIRED
    Meaning
    The callable it runs, func Name(ctx context.Context) error.
  • memory
    Type
    size
    Default
    REQUIRED
    Meaning
    The memory it books, "16MiB" or more, since a Worker runs Go. What it is billed at.
  • env
    Type
    map of string
    Default
    none
    Meaning
    Plain configuration injected into its environment.
  • secrets
    Type
    list of string
    Default
    none
    Meaning
    The secrets this Worker may read.
  • dir
    Type
    string
    Default
    the backend's folder
    Meaning
    The folder its handler is in, when it is not its backend's.
Driftfile
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:

Driftfile
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.