Skills · Simple Backend

The whole Skill. Click in the box, select all, copy.
---
name: simple-backend
description: Build on Simple Backend, the backend with batteries included.
  Use when the simple-backend MCP is connected, in a repository with a
  swarm.edn, or when asked for any backend piece — an endpoint, webhook,
  scheduled job, queue worker, data storage, file storage, user sign-in
  or a hosted page.
---

# Writing a Simple Backend function

A function is one file and one entry function. It takes the request and
returns a response map.

**Write Clojure.** It is the default and the platform's first language: it
runs in SCI (the Small Clojure Interpreter), its errors come back as values
you can check, and every example, console screen and starter is Clojure.
Use JavaScript (`:lang :js`) only when the user asks for it or the code
already exists in JavaScript.

```clojure
(ns contact
  (:require [backend.db :as db]))

;; req is {:body :headers :query :tenant :invocation-id}, plus :params
;; when the path has patterns. Return {:status :body} — the body is JSON
;; on the way out.

(defn submit [req]
  (let [{:keys [name email]} (:body req)
        saved (db/save! :contact {:name name :email email})]
    (if (:error/kind saved)
      {:status 400 :body {:error (:error/msg saved)}}
      {:status 200 :body {:saved true :id (:id saved)}})))
```

The same function in JavaScript, for when it is asked for. There is no
`require` and no `import`:
each namespace a function may use is already in scope under its short
name (`db`, `http`, `log`, `crypto`, `vars`, ...), and the names are
camel-cased with `!` and `?` dropped — `save!` is `db.save`, `count-of` is
`db.countOf`, `secure-equal?` is `crypto.secureEqual`. Calls are
synchronous. A failed call THROWS an Error carrying `.kind` and `.data`.

```javascript
function submit(req) {
  const { name, email } = req.body;
  const saved = db.save('contact', { name, email });
  return { status: 200, body: { saved: true, id: saved.id } };
}
```

**Require what you use.** `:needs` in the manifest decides what a function
MAY require; Clojure code still has to require it. This is the most common
mistake.

**Database calls return values, not exceptions** (in Clojure). A failure
comes back as a map carrying `:error/kind` and `:error/msg`. Check it.

**Independent reads can travel together.** Every database call is a round
trip out of the sandbox, so three lookups that do not depend on each other
are three waits in a row. `db/batch` sends them as one and answers a vector
of results, in order:

```clojure
(let [[session todos unread]
      (db/batch [[:get :session session-id]
                 [:find :todo {:done false} {:limit 5}]
                 [:count-of :note {:read false}]])]
  ...)
```

Each item is a read and its arguments, exactly as you would call it —
`:q :pull :get :find :count-of`, at most 50. Writes are refused. Each result
stands alone: an item that fails is an error map in its own slot and the
rest still answer, so check each one. Needs `:db/read`, like the reads
themselves.

## The manifest

`swarm.edn` sits beside the source and is what gets deployed.

```clojure
{:backend/version 1
 :tenant "acme"
 :allow {:http/hosts ["api.stripe.com"]}   ; only read if the workspace restricts outbound calls
 :functions
 [{:name    :contact/submit
   :file    "fns/contact.clj"
   :entry   contact/submit
   :trigger {:type :http :method :post :path "/contact"}
   :allow   :public
   :needs   #{:db/write}}

  {:name    :contact/list
   :file    "fns/list.js"
   :lang    :js
   :entry   list
   :trigger {:type :http :method :get :path "/contacts"}
   :allow   :key
   :needs   #{:db/read}}]}
```

`:entry` is namespace-qualified in Clojure (`contact/submit`) and a bare
function name in JavaScript (`list`).

### :trigger

- `{:type :http :method :post :path "/x"}` — methods `:get :post :put :patch :delete`. A path segment may be `:name` to capture it into `(:params req)`, and a trailing `*` captures the rest. `/products/:id` and `/blog/*` both work; the more specific route wins
- `{:type :cron :schedule "0 2 * * *"}` — five crontab fields, UTC, no URL
- `{:type :interval :seconds 15}` — every N seconds, 15 to 3600. Use it when a period is the point and there is no hour to name; the payload carries `:interval/seconds` and `:interval/slot` as well as `:cron/minute` and `:cron/at`, so a cron function moving here needs no code change
- `{:type :queue}` — invoked by another function via `queue/enqueue!`

### :allow — required on `:http`, and only there

- `:key` — a caller holding one of the workspace's API keys, sent as `x-simplebackend-key`
- `:public` — anyone, rate limited
- `:none` — no URL; queue and cron work
- `:signed-in` — an end user of the app, signed in with Simple Backend sign-in (emailed code, link or passkey) or the workspace's own Firebase. The request gains `:user` (`:user/id`, `:user/email`, `:user/method`). Refuses every call until sign-in is switched on — `configure_sign_in`, or `sb sign-in enable`

Cron, interval and queue functions default to `:none`; do not set `:allow` on them.

### :needs — nothing undeclared is bound

| Capability | Namespace | Calls |
| --- | --- | --- |
| `:db/read` | `backend.db` | `q pull as-of get find count-of batch` — `(get :kind id)`, `(find :kind {:field v} {:limit 10 :order :newest})`, `(count-of :kind {:field v})` |
| `:db/write` | `backend.db` | `save! update! delete! transact!` — `(save! :kind m)` answers the record with `:id`; `(update! :kind id m)` merges; `(delete! :kind id)` |
| `:http/out` | `backend.http` | `get post put patch delete` — each `(url)` or `(url opts)`, to any public address. Private and internal addresses are always refused. A workspace that restricts outbound calls allows only the hosts in the manifest's `:allow {:http/hosts [...]}` (a bare host like `api.stripe.com`, never a URL) |
| `:queue` | `backend.queue` | `enqueue!` |
| `:secrets` | `backend.secrets` | `get has?` — set in the console under Settings › Secrets & variables or with the `set_secret` tool, named like environment variables (`STRIPE_KEY`); `:stripe-key` and `stripeKey` find it too |
| `:files` | `backend.files` | `put! get delete! list move! url usage` — the workspace's own folder in the platform's two buckets. Every call names `:private` or `:public`; only a public file has a `url`. Content goes in and comes out as base64 |
| `:cache` | `backend.cache` | `get put! delete! clear! keys usage` — five megabytes per workspace, shared by every copy of the platform. For what you would be sad to recompute and fine to lose |
| `:state` | `backend.state` | `get get-many put! merge! delete! list watch usage` — documents by `(coll id)`, any plain data, rewritten with no history. `put!`, `merge!` and `delete!` take `{:if-version n}` (0 = only if absent) and answer `:state/conflict` when someone wrote first. For sessions, presence, settings, cursors: what changes often and has no past worth keeping. `(watch [[coll id] ...])` gives a caller a `/_watch/…` path to long-poll until one of them changes, so pages and agents wait at the gateway instead of polling a function; `{:db? true}` also wakes on any committed database transaction |
| `:stream` | `backend.stream` | `append! append-all! read latest keys delete! usage` — append-only entries by `(stream key)`, read newest first and paged by `:seq`. Each expires after `:keep-days` (90 by default, up to 3650). For transcripts, traces and feeds |
| `:http/raw-body` | — | no namespace: the request gains `:raw-body`, the body's bytes as a UTF-8 string. For verifying a signed webhook — Paddle, Stripe and GitHub sign the wire bytes, and the parsed `:body` cannot reproduce them |

`backend.log`, `backend.json`, `backend.time`, `backend.crypto`, `backend.schema` and
`backend.vars` are always bound and never declared. `backend.log` is `info warn
error`, each `(msg)` or `(msg data)`. `backend.json` is `parse` (keyword keys) and
`generate`; `backend.time` is `nanos` and `now-ms`, for timing your own code.
`backend.crypto` is `sha256 sha512 hmac-sha256 hmac-sha512 secure-equal?
random-hex base64 base64url base64-decode hex hex-decode` and NaCl `box` /
`secretbox` — compare signatures with `secure-equal?`, never `=`.
`backend.schema` is malli: `validate validator explain decode json-schema`.
`backend.vars` is `get has?` over the workspace's VARIABLES — plain values set in
the console under Settings › Secrets & variables or with `set_var`, shown in full,
named the same way (`REGION`;
`:region` and `myRegion` find it). A name is a variable or a secret, never both.

### :limits

`{:timeout-ms 15000 :isolation :process}` is the default. `:timeout-ms`
accepts 100 to 300000. Longer work belongs behind a `:queue` trigger in
pieces that can be retried. `:isolation :inline` is not available to
tenants. A database query is held to the same limit: one still running
when the function's time is up is stopped and answers `:db/query-timeout`.
Index the fields it filters on (`index_field`), or narrow it.

## The sandbox

Clojure runs in an interpreter, not a JVM. No Java interop, no `eval`,
`require` at runtime, `slurp`, threads or agents. `clojure.core` predates
1.11, so `parse-long`, `parse-double`, `abs` and `random-uuid` are provided
explicitly. JavaScript runs in QuickJS with no `fetch`, no `console`, no
modules and no Node APIs — use `http`, `log` and the rest instead.

## Records

No schema is required before the first write; attributes exist because they
were used. Every version of every value is kept, so `db/as-of` reads the
store as it was. `db/save!` stamps `:id`, `:created-at` and `:updated-at`.
Kinds are keywords in Clojure (`:contact`) and strings in JavaScript
(`'contact'`).

## The loop, through the MCP

1. `list_workspaces` — or `create_workspace` if there is none.
2. `get_source` before changing a workspace you did not just write.
3. `test_function` with `function_edn` and `source` — runs the candidate in
   the real sandbox and stores no release. Read the error, fix, run again.
4. `add_function` to ship ONE function and keep the rest. Use `deploy` only
   with the whole manifest.
5. `call_function` to prove the live endpoint answers; `read_log` when it
   does not.

## The loop, from a terminal

```
sb test      # run the candidate on the platform, in the real sandbox
sb deploy    # validate, store, activate
sb rollback  # the release before this one
```

`sb test` and `test_function` write to the workspace's real database —
point pipelines at a staging workspace.
The trap	What the Skill says
Ticking a capability and not requiring it	`:needs` decides what a function may require. The code still has to require it
Wrapping database calls in try/catch	They return values. A failure is a map with `:error/kind`
Reaching for `:allow :signed-in`	It refuses every call. End-user auth is not built, and the console does not offer it
Assuming `clojure.core` is current	It predates 1.11. `parse-long` and friends are provided explicitly
A Skill for writing functions

Why this is worth handing over

Then let it deploy
