DocsServer
Hooks and events
Change a record before it is written, say what happened, and act on it elsewhere.
A hook runs before a write and can change or reject it. When something worth knowing happens, it emits an event, and agents react to it: they send an email, write an audit row or emit the next event. Each piece stays small and independent. To add a hook, name a file in hooks/ after a collection:
export function beforeCreate({ record, reject, alert }) {
if (String(record.note ?? "").includes("<script")) {
alert("A script in an order's note", { email: record.email });
reject("That note is not allowed.");
}
// Card numbers never reach the database.
return { ...record, note: String(record.note ?? "").replace(/\d{16}/g, "[card]") };
}
export function beforeUpdate({ record, previous, emit }) {
// `record` holds the changes; `previous` is the current row.
const order = { ...previous, ...record };
if (order.paid && !previous.paid) emit("order.paid", { id: order.id, email: order.email });
return record;
}Features include:
- Hooks before every create, update and delete, whatever made the write
- Events emitted only once the write commits
- Agents that react to events, in order, and can emit the next one
- Alerts for a human, logged and forwarded
- Events from outside, over HTTP or local UDP, as JSON, MessagePack or CBOR
Hooks
beforeCreate, beforeUpdate and beforeDelete receive the record and return it, changed if needed. reject stops the write with a message, answered as a 403. hooks/_all.ts runs before every collection’s hook, for logic that applies everywhere.
A hook runs on every write, whatever made it: the REST API, the admin, a server function or a migration. Its reads ignore the collection rules, so it can enforce limits that depend on other rows, such as “no one leads more than two projects”, which a rule can’t express:
export async function beforeCreate({ record, db, reject }) {
const led = await db.count("projects", `lead = "${record.lead}"`);
if (led >= 2) reject(`Already leading ${led} projects.`);
}Emit an event
emit(name, data) publishes an event. From a hook, events are published only once the write commits; a rejected write emits nothing except alerts. Server functions and agents can emit too.
React to an event
An agent watching an event receives each one, in order:
export const watch = { event: "order.paid" };
export async function act({ event, mail, emit }) {
mail({ to: event.data.email, subject: "Paid, thank you", text: `Order ${event.data.id} is paid.` });
emit("receipt.sent", { order: event.data.id });
}Another agent can react to that:
export const watch = { event: "receipt.sent" };
export async function act({ event, server }) {
server.collection("audit").create({ what: `receipt for ${event.data.order}` });
}The hook doesn’t send email; it only says the order is paid. What happens next is up to the agents, and adding one doesn’t touch the code already there.
A chain of events deeper than eight is rejected, so two agents can’t loop forever.
Alerts
alert(message, details) flags something for a human. It’s logged, counted in the dev overlay, and emitted as an alert event, so an agent can forward it:
export const watch = { event: "alert" };
export async function act({ event, mail }) {
mail({ to: "ops@example.com", subject: "Alert", text: event.data.message });
}Events from outside
Other programs can emit events too. To send one over HTTP, as a superuser:
curl -X POST http://localhost:8090/api/events/door.opened \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"door": 3}'JSON, MessagePack (application/msgpack) and CBOR (application/cbor) are all delivered as JSON; other payloads as { "bytes": "<base64>" }. ?app=reports sends it only to the app mounted as reports.
Over UDP
On the same machine, without a token, the server can also listen on UDP:
sluurp serve --public ./app --events
# from anything else on this machine:
sluurp emit door.opened '{"door": 3}'By default, --events listens on 127.0.0.1:9900. Each datagram is a map with name, data and optionally app, encoded as JSON, MessagePack or CBOR. A sensor, a script or a cron job can send one in a single line.