@voidbase-cloud/voidbase 0.1.0

package/src/server/hooks/runtime.ts

@@ -0,0 +1,344 @@
+// The JSVM-compatible global API for pb_hooks files, plus the registries their calls populate.
+// Per-request state ($app's database, the request) is carried by AsyncLocalStorage.
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Context } from "hono";
+import type { Collection } from "../collections/model";
+import { ApiError } from "../errors";
+import { normalizeFilename, sniffMime } from "../records/files";
+import type { RecordContext } from "../records/service";
+import type { Upload } from "../records/values";
+import type { Settings } from "../settings";
+import type { AppEnv, AuthRecord } from "../types";
+import { CollectionRef, HookRecord } from "./record";
+
+export interface HookStore {
+  c: Context<AppEnv> | null;
+  ctx: () => Promise<RecordContext>;
+  collections: Map<string, Collection>;
+  settings: Settings;
+  env: Record<string, unknown>;
+}
+export const hookStore = new AsyncLocalStorage<HookStore>();
+const store = () => hookStore.getStore();
+const mustStore = () => { const s = store(); if (!s) throw new Error("hooks: no request context"); return s; };
+
+// ---- registries ------------------------------------------------------------------------------------
+export interface RouteReg { method: string; path: string; handler: HookFn; middlewares: HookMiddleware[] }
+export type HookFn = (e: unknown) => unknown;
+export type HookMiddleware = HookFn | { func: HookFn; id?: string; priority?: number };
+export const routes: RouteReg[] = [];
+export const eventHooks = new Map<string, { fn: HookFn; tags: string[] }[]>();
+export const crons = new Map<string, { expr: string; fn: () => unknown }>();
+
+export function onEvent(name: string, fn: HookFn, tags: string[]) {
+  const list = eventHooks.get(name) ?? [];
+  list.push({ fn, tags });
+  eventHooks.set(name, list);
+}
+
+// Runs the handlers for an event as a chain around `inner` (the core action). e.next() runs the rest once.
+export const hasHandlers = (name: string, tag: string | null) => (eventHooks.get(name) ?? []).some((h) => h.tags.length === 0 || (tag !== null && h.tags.includes(tag)));
+
+export async function trigger<T extends { next?: () => Promise<unknown> }>(name: string, e: T, tag: string | null, inner: () => Promise<unknown>): Promise<unknown> {
+  const handlers = (eventHooks.get(name) ?? []).filter((h) => h.tags.length === 0 || (tag !== null && h.tags.includes(tag)));
+  if (handlers.length === 0) return inner();
+  let i = 0;
+  let result: unknown;
+  let innerDone = false;
+  const next = async () => {
+    if (i < handlers.length) { const h = handlers[i++]!; return h.fn(e); }
+    if (!innerDone) { innerDone = true; result = await inner(); }
+    return result;
+  };
+  (e as { next: () => Promise<unknown> }).next = next;
+  await next();
+  if (!innerDone) { innerDone = true; result = await inner(); } // handlers that never call next() still run the core action
+  return result;
+}
+
+// Request-level hooks (OnXRequest): the handler's work is the innermost step; hooks may write the response
+// themselves (e.json), swap event fields before e.next(), or throw an ApiError.
+export async function requestHook(name: string, c: Context<AppEnv>, tag: string | null, fields: Record<string, unknown>, inner: (ev: RequestEvent & Record<string, unknown>) => Promise<Response>): Promise<Response> {
+  const ev = Object.assign(new RequestEvent(c, authToHookRecord(c.get("auth"))), fields) as unknown as RequestEvent & Record<string, unknown>;
+  let response: Response | null = null;
+  await trigger(name, ev, tag, async () => { response = await inner(ev); return response; });
+  return ev.written ?? response ?? c.body(null, 204);
+}
+// Same, for handlers that answer JSON hooks may edit after e.next(): the result lives on ev.result until the end.
+export async function requestHookResult(name: string, c: Context<AppEnv>, tag: string | null, fields: Record<string, unknown>, compute: (ev: RequestEvent & Record<string, unknown>) => Promise<unknown>): Promise<Response> {
+  const ev = Object.assign(new RequestEvent(c, authToHookRecord(c.get("auth"))), { result: null, ...fields }) as unknown as RequestEvent & Record<string, unknown>;
+  await trigger(name, ev, tag, async () => { ev.result = await compute(ev); return ev.result; });
+  return ev.written ?? c.json(ev.result as Record<string, unknown>);
+}
+
+// ---- errors (JSVM names) -----------------------------------------------------------------------------
+export class HookApiError extends ApiError {}
+export class NotFoundError extends ApiError { constructor(message = "The requested resource wasn't found.", data?: Record<string, unknown>) { super(404, message, data ?? {}); } }
+export class BadRequestError extends ApiError { constructor(message = "Something went wrong while processing your request.", data?: Record<string, unknown>) { super(400, message, data ?? {}); } }
+export class ForbiddenError extends ApiError { constructor(message = "You are not allowed to perform this request.", data?: Record<string, unknown>) { super(403, message, data ?? {}); } }
+export class UnauthorizedError extends ApiError { constructor(message = "Missing or invalid authentication.", data?: Record<string, unknown>) { super(401, message, data ?? {}); } }
+export class InternalServerError extends ApiError { constructor(message = "Something went wrong while processing your request.", data?: Record<string, unknown>) { super(500, message, data ?? {}); } }
+export class ValidationError extends Error { constructor(public code: string, message: string) { super(message); } }
+
+// ---- request event (the `c` / `e` object handlers receive) ------------------------------------------
+export class RequestEvent {
+  private storeMap = new Map<string, unknown>();
+  written: Response | null = null; // PocketBase handlers write the response (e.JSON) rather than return it
+  next: () => Promise<unknown> = async () => undefined;
+  record: HookRecord | null = null;
+  collection: CollectionRef | null = null;
+  constructor(public c: Context<AppEnv>, public auth: HookRecord | null) {}
+  get request() { return this.c.req.raw; }
+  get app() { return $app; }
+  get response() { return this.c.res; }
+  // goja values cross into Go maps, which marshal with sorted keys
+  json(status: number, data: unknown) { return (this.written = this.c.json(sortKeysDeep(data) as Record<string, unknown>, status as 200)); }
+  string(status: number, data: string) { return (this.written = this.c.text(data, status as 200)); }
+  html(status: number, data: string) { return (this.written = this.c.html(data, status as 200)); }
+  noContent(status = 204) { return (this.written = this.c.body(null, status as 204)); }
+  redirect(status: number, url: string) { return (this.written = this.c.redirect(url, status as 302)); }
+  get(key: string) { return this.storeMap.get(key); }
+  set(key: string, value: unknown) { this.storeMap.set(key, value); }
+  params: Record<string, string> = {}; // set by the hook route dispatcher (Hono's catch-all carries no named params)
+  pathParam(name: string) { return this.params[name] ?? this.c.req.param(name) ?? ""; }
+  queryParam(name: string) { return this.c.req.query(name) ?? ""; }
+  hasSuperuserAuth() { return !!this.auth?.isSuperuser(); }
+  realIP() { return this.c.req.header("CF-Connecting-IP") ?? this.c.req.header("X-Forwarded-For")?.split(",")[0]?.trim() ?? ""; }
+  async requestInfo() {
+    const query: Record<string, string> = {}; new URL(this.c.req.url).searchParams.forEach((v, k) => { query[k] = v; });
+    const headers: Record<string, string> = {}; this.c.req.raw.headers.forEach((v, k) => { headers[k.toLowerCase().replace(/-/g, "_")] = v; });
+    return { method: this.c.req.method, query, headers, body: await this.bindBody({}), auth: this.auth, context: "default", hasSuperuserAuth: () => this.hasSuperuserAuth() };
+  }
+  async bindBody(target: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const ct = this.c.req.header("content-type") ?? "";
+    let data: Record<string, unknown> = {};
+    try {
+      if (ct.includes("multipart/form-data") || ct.includes("application/x-www-form-urlencoded")) data = (await this.c.req.parseBody({ all: true })) as Record<string, unknown>;
+      else { const t = await this.c.req.text(); data = t.trim() ? JSON.parse(t) : {}; }
+    } catch { data = {}; }
+    Object.assign(target, data);
+    return target;
+  }
+}
+
+// ---- $app ---------------------------------------------------------------------------------------------
+export interface AppServices {
+  saveCollection(ref: CollectionRef): Promise<CollectionRef>;
+  deleteCollection(ref: CollectionRef): Promise<void>;
+  saveRecord: (rec: HookRecord) => Promise<HookRecord>;
+  deleteRecord: (rec: HookRecord) => Promise<void>;
+  findRecordById: (collection: string, id: string) => Promise<HookRecord | null>;
+  findRecordsByFilter: (collection: string, filter: string, sort: string, limit: number, offset: number, params?: Record<string, unknown>) => Promise<HookRecord[]>;
+  countRecords: (collection: string, where: DbxExpr | string | null) => Promise<number>;
+  findAuthRecordByEmail: (collection: string, email: string) => Promise<HookRecord | null>;
+  findAuthRecordByToken: (token: string, type: string) => Promise<HookRecord | null>;
+  expandRecords: (records: HookRecord[], expands: string[]) => Promise<void>;
+  sendMail: (msg: MailerMessage) => Promise<void>;
+}
+// $dbx: the small subset generated hooks use ($dbx.exp("col = {:v}", {v}), $dbx.hashExp({col: v}))
+export interface DbxExpr { sql: string; params: Record<string, unknown> }
+export const $dbx = {
+  exp: (sql: string, params: Record<string, unknown> = {}): DbxExpr => ({ sql, params }),
+  hashExp: (pairs: Record<string, unknown>): DbxExpr => ({ sql: Object.keys(pairs).map((k) => `[[${k}]] = {:${k}}`).join(" AND "), params: { ...pairs } }),
+};
+let services: AppServices | null = null;
+export function installServices(s: AppServices) { services = s; }
+const svc = () => { if (!services) throw new Error("hooks: services not installed"); return services; };
+
+export interface AppApi {
+  findCollectionByNameOrId(idOrName: string): CollectionRef;
+  findAllCollections(...types: string[]): CollectionRef[];
+  findRecordById(collection: string | CollectionRef, id: string): Promise<HookRecord | null>;
+  findRecordsByFilter(collection: string | CollectionRef, filter: string, sort?: string, limit?: number, offset?: number, params?: Record<string, unknown>): Promise<HookRecord[]>;
+  findFirstRecordByFilter(collection: string | CollectionRef, filter: string, params?: Record<string, unknown>): Promise<HookRecord>;
+  findFirstRecordByData(collection: string | CollectionRef, key: string, value: unknown): Promise<HookRecord>;
+  countRecords(collection: string | CollectionRef, ...exprs: (DbxExpr | string)[]): Promise<number>;
+  findAuthRecordByEmail(collection: string | CollectionRef, email: string): Promise<HookRecord>;
+  findAuthRecordByToken(token: string, type?: string): Promise<HookRecord>;
+  expandRecord(record: HookRecord, expands: string[], fetch?: unknown): Promise<void>;
+  expandRecords(records: HookRecord[], expands: string[], fetch?: unknown): Promise<void>;
+  save(model: HookRecord | CollectionRef): Promise<HookRecord | CollectionRef>;
+  saveNoValidate(model: HookRecord | CollectionRef): Promise<HookRecord | CollectionRef>;
+  delete(model: HookRecord | CollectionRef): Promise<void>;
+  settings(): Settings;
+  newMailClient(): { send: (msg: MailerMessage) => Promise<void> };
+  logger(): Console;
+  dao(): AppApi;
+  isDev(): boolean;
+  runInTransaction(fn: (txApp: AppApi) => unknown): Promise<unknown>;
+}
+
+export const $app: AppApi = {
+  findCollectionByNameOrId(idOrName: string): CollectionRef {
+    const c = mustStore().collections.get(idOrName);
+    if (!c) throw new Error(`sql: no rows in result set (collection "${idOrName}")`);
+    return new CollectionRef(c);
+  },
+  findAllCollections(...types: string[]): CollectionRef[] {
+    const seen = new Set<string>(); const out: CollectionRef[] = [];
+    for (const c of mustStore().collections.values()) { if (seen.has(c.id)) continue; seen.add(c.id); if (!types.length || types.includes(c.type)) out.push(new CollectionRef(c)); }
+    return out;
+  },
+  findRecordById: (collection: string | CollectionRef, id: string) => svc().findRecordById(typeof collection === "string" ? collection : collection.name, id),
+  findRecordsByFilter: (collection: string | CollectionRef, filter: string, sort = "", limit = 0, offset = 0, params?: Record<string, unknown>) => svc().findRecordsByFilter(typeof collection === "string" ? collection : collection.name, filter, sort, limit, offset, params),
+  async findFirstRecordByFilter(collection: string | CollectionRef, filter: string, params?: Record<string, unknown>) {
+    const rows = await svc().findRecordsByFilter(typeof collection === "string" ? collection : collection.name, filter, "", 1, 0, params);
+    if (!rows[0]) throw new Error("sql: no rows in result set");
+    return rows[0];
+  },
+  async findFirstRecordByData(collection: string | CollectionRef, key: string, value: unknown) {
+    const rows = await svc().findRecordsByFilter(typeof collection === "string" ? collection : collection.name, `${key} = {:v}`, "", 1, 0, { v: value });
+    if (!rows[0]) throw new Error("sql: no rows in result set");
+    return rows[0];
+  },
+  countRecords: (collection: string | CollectionRef, ...exprs: (DbxExpr | string)[]) => svc().countRecords(typeof collection === "string" ? collection : collection.name, exprs.length ? (exprs.length === 1 ? exprs[0]! : { sql: exprs.map((x) => `(${typeof x === "string" ? x : x.sql})`).join(" AND "), params: Object.assign({}, ...exprs.map((x) => (typeof x === "string" ? {} : x.params))) }) : null),
+  async findAuthRecordByEmail(collection: string | CollectionRef, email: string) {
+    const rec = await svc().findAuthRecordByEmail(typeof collection === "string" ? collection : collection.name, email);
+    if (!rec) throw new Error("sql: no rows in result set");
+    return rec;
+  },
+  async findAuthRecordByToken(token: string, type = "auth") {
+    const rec = await svc().findAuthRecordByToken(token, type);
+    if (!rec) throw new Error("sql: no rows in result set");
+    return rec;
+  },
+  expandRecord: (record: HookRecord, expands: string[]) => svc().expandRecords([record], expands),
+  expandRecords: (records: HookRecord[], expands: string[]) => svc().expandRecords(records, expands),
+  save: (model: HookRecord | CollectionRef) => (model instanceof CollectionRef ? svc().saveCollection(model) : svc().saveRecord(model)),
+  saveNoValidate: (model: HookRecord | CollectionRef) => (model instanceof CollectionRef ? svc().saveCollection(model) : svc().saveRecord(model)),
+  delete: (model: HookRecord | CollectionRef) => (model instanceof CollectionRef ? svc().deleteCollection(model) : svc().deleteRecord(model)),
+  settings() { return mustStore().settings; },
+  newMailClient() { return { send: (msg: MailerMessage) => svc().sendMail(msg) }; },
+  logger() { return console; },
+  dao() { return $app; }, // deprecated alias kept for older hooks
+  isDev() { return false; },
+  async runInTransaction(fn: (txApp: typeof $app) => unknown) { return fn($app); },
+};
+
+export class MailerMessage {
+  from: { address: string; name?: string } = { address: "" };
+  to: { address: string; name?: string }[] = [];
+  cc: { address: string; name?: string }[] = [];
+  bcc: { address: string; name?: string }[] = [];
+  subject = "";
+  html = "";
+  text = "";
+  headers: Record<string, string> = {};
+  constructor(init: Partial<MailerMessage> = {}) { Object.assign(this, init); }
+}
+
+export const $apis = {
+  // $apis.enrichRecord(e, record, ...expands): expands and applies the auth-aware export (as the API would)
+  async enrichRecord(_e: unknown, record: HookRecord, ...expands: string[]): Promise<HookRecord> { if (expands.length) await svc().expandRecords([record], expands); return record; },
+  async enrichRecords(_e: unknown, records: HookRecord[], ...expands: string[]): Promise<HookRecord[]> { if (expands.length) await svc().expandRecords(records, expands); return records; },
+  requireAuth(...collections: string[]): HookMiddleware {
+    return { id: "pbRequireAuth", func: async (e) => {
+      const ev = e as RequestEvent;
+      if (!ev.auth || (collections.length && !collections.includes(ev.auth.collection().name))) throw new UnauthorizedError("The request requires valid record authorization token.");
+      return ev.next();
+    } };
+  },
+  requireSuperuserAuth(): HookMiddleware {
+    return { id: "pbRequireSuperuserAuth", func: async (e) => {
+      const ev = e as RequestEvent;
+      if (!ev.auth) throw new UnauthorizedError("The request requires valid record authorization token.");
+      if (!ev.auth.isSuperuser()) throw new ForbiddenError("The authorized record is not allowed to perform this action.");
+      return ev.next();
+    } };
+  },
+  requireGuestOnly(): HookMiddleware {
+    return { id: "pbRequireGuestOnly", func: async (e) => { const ev = e as RequestEvent; if (ev.auth) throw new BadRequestError("The request can be accessed only by guests."); return ev.next(); } };
+  },
+  requireSuperuserOrOwnerAuth(ownerIdPathParam = "id"): HookMiddleware {
+    return { id: "pbRequireSuperuserOrOwnerAuth", func: async (e) => {
+      const ev = e as RequestEvent;
+      if (!ev.auth) throw new UnauthorizedError("The request requires superuser or record authorization token.");
+      if (!ev.auth.isSuperuser() && ev.auth.id !== ev.pathParam(ownerIdPathParam)) throw new ForbiddenError("You are not allowed to perform this request.");
+      return ev.next();
+    } };
+  },
+};
+
+export const $http = {
+  async send(cfg: { url: string; method?: string; body?: string; headers?: Record<string, string>; timeout?: number }) {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), (cfg.timeout ?? 120) * 1000);
+    try {
+      const r = await fetch(cfg.url, { method: cfg.method ?? "GET", body: cfg.body, headers: cfg.headers, signal: ac.signal });
+      const raw = await r.text();
+      let json: unknown = null; try { json = JSON.parse(raw); } catch { json = null; }
+      const headers: Record<string, string[]> = {}; r.headers.forEach((v, k) => { headers[k] = [v]; });
+      return { statusCode: r.status, headers, cookies: {}, raw, json, body: new TextEncoder().encode(raw) };
+    } finally { clearTimeout(t); }
+  },
+};
+
+export const $filesystem = {
+  async fileFromURL(url: string): Promise<Upload> {
+    const r = await fetch(url);
+    if (!r.ok) throw new Error(`failed to download ${url}: ${r.status}`);
+    const bytes = await r.arrayBuffer();
+    const name = decodeURIComponent(new URL(url).pathname.split("/").filter(Boolean).pop() ?? "file");
+    const sniffed = sniffMime(new Uint8Array(bytes), r.headers.get("content-type") ?? "", name);
+    return { name: normalizeFilename(name, sniffed.ext), type: sniffed.type, size: bytes.byteLength, bytes };
+  },
+  async fileFromBytes(bytes: ArrayBuffer | Uint8Array | number[], name: string): Promise<Upload> {
+    const buf = bytes instanceof ArrayBuffer ? bytes : new Uint8Array(bytes).buffer as ArrayBuffer;
+    const sniffed = sniffMime(new Uint8Array(buf), "", name);
+    return { name: normalizeFilename(name, sniffed.ext), type: sniffed.type, size: buf.byteLength, bytes: buf };
+  },
+  async fileFromPath(): Promise<never> { throw new Error("$filesystem.fileFromPath is not available on Workers"); },
+};
+
+export const $security = {
+  randomString: (n: number) => { const a = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; const b = crypto.getRandomValues(new Uint8Array(n)); let s = ""; for (let i = 0; i < n; i++) s += a[b[i]! % a.length]; return s; },
+  randomStringWithAlphabet: (n: number, a: string) => { const b = crypto.getRandomValues(new Uint8Array(n)); let s = ""; for (let i = 0; i < n; i++) s += a[b[i]! % a.length]; return s; },
+  pseudorandomString: (n: number) => $security.randomString(n),
+  sha256: async (s: string) => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s)))).map((b) => b.toString(16).padStart(2, "0")).join(""),
+};
+
+export function makeOs(files: Record<string, string>, hooksDir: string) {
+  return {
+    getenv: (name: string) => { const v = store()?.env[name]; return v == null ? "" : String(v); },
+    readFile: (path: string) => {
+      const rel = path.startsWith(hooksDir) ? path.slice(hooksDir.length).replace(/^\/+/, "") : path;
+      const text = files[rel];
+      if (text === undefined) throw new Error(`open ${path}: no such file or directory`);
+      return Array.from(new TextEncoder().encode(text));
+    },
+    writeFile: () => { throw new Error("$os.writeFile is not available on Workers"); },
+    exec: () => { throw new Error("$os.exec is not available on Workers"); },
+    cmd: () => { throw new Error("$os.cmd is not available on Workers"); },
+    args: [] as string[],
+  };
+}
+
+export function routerAdd(method: string, path: string, handler: HookFn, ...middlewares: HookMiddleware[]) {
+  routes.push({ method: method.toUpperCase() === "ANY" ? "ALL" : method.toUpperCase(), path: toHonoPath(path), handler, middlewares });
+}
+export function routerUse(..._middlewares: HookMiddleware[]) { /* global hook middleware: milestone six */ }
+export function cronAdd(id: string, expr: string, fn: () => unknown) { crons.set(id, { expr, fn }); }
+export function cronRemove(id: string) { crons.delete(id); }
+
+// Go 1.22 mux patterns -> Hono: {name} -> :name, {path...} -> *
+export function toHonoPath(p: string): string {
+  return p.replace(/\{(\w+)\.\.\.\}/g, "*").replace(/\{(\w+)\}/g, ":$1");
+}
+
+export const RecordUpsertFormFactory = (_app: AppApi) =>
+  class RecordUpsertForm {
+    constructor(private a: AppApi, private record: HookRecord) {}
+    submit() { return this.a.save(this.record); }
+    setRecord(r: HookRecord) { this.record = r; }
+  };
+
+export const authToHookRecord = (auth: AuthRecord | null) => (auth ? HookRecord.fromRow(auth.collection, auth.row) : null);
+
+export function sortKeysDeep(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeysDeep);
+  if (v && typeof v === "object" && !(v instanceof HookRecord) && Object.getPrototypeOf(v) === Object.prototype) {
+    return Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, x]) => [k, sortKeysDeep(x)]));
+  }
+  if (v instanceof HookRecord) return v.publicExport();
+  return v;
+}

package/src/server/hooks/virtual-migrations.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:voidbase-migrations" {
+  export const migrationsDir: string;
+  export const migrations: { name: string; run: (g: Record<string, unknown>) => Promise<void> }[];
+}

package/src/server/hooks/virtual.d.ts

@@ -0,0 +1,7 @@
+declare module "virtual:voidbase-hooks" {
+  export const hooksDir: string;
+  export const asyncNames: string[];
+  export const hooks: { name: string; run: (g: Record<string, unknown>) => Promise<void> }[];
+  export const modules: Record<string, (g: Record<string, unknown>) => Promise<unknown>>;
+  export const files: Record<string, string>;
+}

package/src/server/hub.ts

@@ -0,0 +1,91 @@
+/// <reference types="@cloudflare/workers-types" />
+// The realtime hub: one SQLite-backed Durable Object per voidbase instance, exported from the instance's own Worker
+// (hooks-plugin appends it to Void's generated entry; the deploy's wrangler.jsonc declares the HUB binding and the
+// new_sqlite_classes migration), so no two instances share it or anything else. Every SSE connection holds one
+// hibernatable WebSocket here; a record write POSTs /publish and the object sends the change to the sockets whose
+// filter includes the collection, then goes back to sleep. Nothing is stored beyond each socket's attachment.
+interface Attachment { id: string; all: boolean; collections: string[]; since: number }
+interface Change { collection: string; recordId: string; action: string; data?: unknown }
+
+export class VoidbaseHub implements DurableObject {
+  constructor(private readonly state: DurableObjectState) {
+    // keepalive answered without waking the object; the alarm sweeps sockets that stopped pinging
+    this.state.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
+  }
+
+  // Connections ping every minute (auto-answered). A Worker whose request was torn down never closes its socket, so
+  // every few minutes the object drops sockets whose last ping is older than two intervals.
+  async alarm(): Promise<void> {
+    const open = this.sweep(150_000);
+    await this.state.storage.put("lastSweep", Date.now());
+    if (open) await this.state.storage.setAlarm(Date.now() + 120_000);
+  }
+  // closes sockets that have not pinged for staleMs; returns how many stay open
+  private sweep(staleMs: number): number {
+    const stale = Date.now() - staleMs;
+    let open = 0;
+    for (const ws of this.state.getWebSockets()) {
+      const seen = this.state.getWebSocketAutoResponseTimestamp(ws)?.getTime() ?? this.attachment(ws).since;
+      if (seen < stale) { try { ws.close(1001, "stale"); } catch { /* gone */ } } else open++;
+    }
+    return open;
+  }
+  private async armSweep(): Promise<void> { if ((await this.state.storage.getAlarm()) === null) await this.state.storage.setAlarm(Date.now() + 120_000); }
+
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+      const clientId = url.searchParams.get("client") ?? "";
+      const pair = new WebSocketPair();
+      this.state.acceptWebSocket(pair[1], clientId ? [clientId] : []);
+      pair[1].serializeAttachment({ id: clientId, all: true, collections: [], since: Date.now() } satisfies Attachment);
+      await this.armSweep();
+      return new Response(null, { status: 101, webSocket: pair[0] });
+    }
+    if (url.pathname === "/stats") return Response.json({ sockets: this.state.getWebSockets().length, alarm: await this.state.storage.getAlarm(), lastSweep: (await this.state.storage.get<number>("lastSweep")) ?? null });
+    if (req.method !== "POST") return new Response("Not Found", { status: 404 });
+    const body = (await req.json()) as Record<string, unknown>;
+    if (url.pathname === "/sweep") { const before = this.state.getWebSockets().length; const open = this.sweep(Number(body.staleMs ?? 150_000)); return Response.json({ before, closed: before - open, open, after: this.state.getWebSockets().length }); }
+    if (url.pathname === "/publish") {
+      const changes = (body.changes ?? []) as Change[];
+      let delivered = 0;
+      for (const ws of this.state.getWebSockets()) {
+        const att = this.attachment(ws);
+        const mine = att.all ? changes : changes.filter((ch) => att.collections.includes(ch.collection));
+        if (!mine.length) continue;
+        try { ws.send(JSON.stringify({ t: "changes", changes: mine })); delivered++; } catch { this.drop(ws); }
+      }
+      return Response.json({ delivered });
+    }
+    if (url.pathname === "/client" || url.pathname === "/control") {
+      const clientId = String(body.clientId ?? "");
+      const msg = url.pathname === "/client" ? { t: "message", event: body.event, data: body.data } : { t: "subs", subscriptions: body.subscriptions, token: body.token };
+      let delivered = 0;
+      for (const ws of clientId ? this.state.getWebSockets(clientId) : []) { try { ws.send(JSON.stringify(msg)); delivered++; } catch { this.drop(ws); } }
+      return Response.json({ delivered });
+    }
+    return new Response("Not Found", { status: 404 });
+  }
+
+  // the connection narrows what it wants: {t:"filter", collections:[names] | "*"}
+  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
+    if (typeof message !== "string") return;
+    try {
+      const m = JSON.parse(message) as { t?: string; collections?: string[] | "*" };
+      if (m.t !== "filter") return;
+      const att = this.attachment(ws);
+      const list = Array.isArray(m.collections) ? m.collections : null;
+      const all = !list;
+      const collections = list ? list.map(String).slice(0, 100) : [];
+      ws.serializeAttachment({ ...att, all, collections } satisfies Attachment);
+    } catch { /* ignore malformed frames */ }
+  }
+  webSocketClose(ws: WebSocket): void { try { ws.close(); } catch { /* already closed */ } }
+  webSocketError(ws: WebSocket): void { try { ws.close(); } catch { /* already closed */ } }
+
+  private drop(ws: WebSocket): void { try { ws.close(1011, "send failed"); } catch { /* gone */ } }
+  private attachment(ws: WebSocket): Attachment {
+    const att = ws.deserializeAttachment() as Attachment | null;
+    return att ?? { id: "", all: true, collections: [], since: 0 };
+  }
+}

package/src/server/ids.ts

@@ -0,0 +1,22 @@
+const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+const STRING_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+export function randomWithAlphabet(length: number, alphabet: string): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+  let out = "";
+  for (let i = 0; i < length; i++) out += alphabet[bytes[i]! % alphabet.length];
+  return out;
+}
+
+// PocketBase record ids: 15 chars of [a-z0-9].
+export const randomId = () => randomWithAlphabet(15, ID_ALPHABET);
+// PocketBase security.RandomString: [a-zA-Z0-9]. Used for token secrets (50) and tokenKey (50).
+export const randomString = (length: number) => randomWithAlphabet(length, STRING_ALPHABET);
+
+// PocketBase datetime format: "2006-01-02 15:04:05.000Z"
+export function nowString(d = new Date()): string {
+  return d.toISOString().replace("T", " ");
+}
+
+// PocketBase appends a 10-char pseudorandom suffix to auto-generated index names.
+export const randomIdSuffix = () => randomWithAlphabet(10, ID_ALPHABET);

package/src/server/jobs.ts

@@ -0,0 +1,84 @@
+// Background jobs: outbound mail and automatic backups. On Cloudflare a Queue carries them
+// (binding QUEUE_JOBS, declared by queues/jobs.ts) with at-least-once delivery and retries; without the binding
+// (the Bun runtime, or a deploy whose token could not create the queue) `dispatch` runs the job inline instead.
+// Handlers register themselves from the module that owns the work, so this module stays free of heavy imports.
+import { logger } from "#platform/log";
+import type { MailMessage } from "./mail/message";
+import type { Bindings } from "./types";
+
+export type Job =
+  | { type: "mail"; message: MailMessage; text: string }
+  | { type: "backup"; name: string };
+export type JobHandler<T extends Job = Job> = (env: Bindings, job: T) => Promise<void>;
+
+const handlers = new Map<Job["type"], JobHandler>();
+export function registerJobHandler<T extends Job["type"]>(type: T, fn: JobHandler<Extract<Job, { type: T }>>): void { handlers.set(type, fn as JobHandler); }
+
+// the bindings of the last bootstrap on this isolate (Workers hand every request the same binding objects)
+let attached: Bindings | undefined;
+export function attachJobs(env: Bindings): void { attached = env; }
+// Void names the binding after the consumer file: QUEUE_JOBS for queues/jobs.ts (this checkout), QUEUE_<WORKER>_JOBS for
+// the queues/<worker>-jobs.ts a deploy writes (queue names are account-wide, so each app gets its own)
+export function jobQueue(env: Bindings | undefined): Bindings["QUEUE_JOBS"] | undefined {
+  if (!env) return undefined;
+  if (env.QUEUE_JOBS) return env.QUEUE_JOBS;
+  const key = Object.keys(env).find((k) => /^QUEUE_[A-Z0-9_]*JOBS$/.test(k));
+  return key ? (env as unknown as Record<string, Bindings["QUEUE_JOBS"]>)[key] : undefined;
+}
+export const jobsQueued = (): boolean => !!jobQueue(attached);
+
+const MAX_MESSAGE_BYTES = 120_000; // Cloudflare Queues: 128 KB per message, ~100 bytes of it metadata
+
+export async function runJob(env: Bindings, job: Job): Promise<void> {
+  const fn = handlers.get(job.type);
+  if (!fn) throw new Error(`voidbase: no handler for job "${job.type}"`);
+  await fn(env, job);
+}
+
+/** Queues the job when a queue is attached (and the message fits), otherwise runs it now. `inline` forces the
+ * immediate path so the caller sees delivery errors (the panel's test email, hooks' mail client). */
+export async function dispatch(job: Job, opts: { env?: Bindings; inline?: boolean } = {}): Promise<"queued" | "ran"> {
+  const env = opts.env ?? attached;
+  const queue = jobQueue(env) ?? jobQueue(attached);
+  if (!opts.inline && queue && JSON.stringify(job).length <= MAX_MESSAGE_BYTES) { await queue.send(job); return "queued"; }
+  if (!env) throw new Error("voidbase: jobs have no bindings (attachJobs was never called)");
+  await runJob(env, job);
+  return "ran";
+}
+
+/** Queue-only: for work that is an optimization and is simply skipped without a queue. */
+export async function dispatchIfQueued(job: Job, env: Bindings | undefined = attached): Promise<boolean> {
+  const queue = jobQueue(env);
+  if (!queue) return false;
+  try { await queue.send(job); return true; } catch (err) { logger.warn("voidbase: queue send failed", { job: job.type, error: err instanceof Error ? err.message : String(err) }); return false; }
+}
+
+export interface QueuedMessage { id: string; body: Job; attempts: number; ack(): void; retry(options?: { delaySeconds?: number }): void }
+export interface JobBatch { queue?: string; messages: QueuedMessage[] }
+
+/** The queue consumer: runs every message, retries failures with backoff (30 s, 60 s, ... up to 15 min) and logs the
+ * ones Cloudflare is about to drop after `maxRetries` (the consumer file's export). */
+export async function consumeJobs(batch: JobBatch, env: Bindings, maxRetries = 5): Promise<{ done: number; failed: number }> {
+  attachJobs(env);
+  let done = 0, failed = 0;
+  for (const msg of batch.messages) {
+    try { await runJob(env, msg.body); msg.ack(); done++; }
+    catch (err) {
+      failed++;
+      const error = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+      const dropping = msg.attempts > maxRetries;
+      logger.error(dropping ? "voidbase: job dropped after its last retry" : "voidbase: job failed, will retry", { job: msg.body.type, id: msg.id, attempt: msg.attempts, error });
+      if (dropping) await alertWebhook({ message: `job ${msg.body.type} dropped after ${msg.attempts} attempts`, job: msg.body.type, id: msg.id, error });
+      msg.retry({ delaySeconds: Math.min(900, 30 * 2 ** Math.max(0, msg.attempts - 1)) });
+    }
+  }
+  return { done, failed };
+}
+
+// VOIDBASE_ALERT_WEBHOOK_URL: the same receiver the request error handler posts to
+export async function alertWebhook(fields: Record<string, unknown>): Promise<void> {
+  const { env } = await import("#platform/env");
+  const webhook = String((env as Record<string, unknown>).VOIDBASE_ALERT_WEBHOOK_URL ?? "").trim();
+  if (!webhook) return;
+  await fetch(webhook, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ source: "voidbase", level: "error", time: new Date().toISOString(), ...fields }) }).catch(() => undefined);
+}

package/src/server/jwt.ts

@@ -0,0 +1,61 @@
+// HS256 JWT compatible with PocketBase tokens (header {"alg":"HS256","typ":"JWT"}).
+const enc = new TextEncoder();
+
+export function b64urlEncode(input: string | Uint8Array): string {
+  const bytes = typeof input === "string" ? enc.encode(input) : input;
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function b64urlDecode(input: string): Uint8Array<ArrayBuffer> {
+  const pad = "=".repeat((4 - (input.length % 4)) % 4);
+  const bin = atob(input.replace(/-/g, "+").replace(/_/g, "/") + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+}
+
+export type JwtClaims = Record<string, unknown> & { exp?: number };
+
+export async function signJWT(claims: JwtClaims, secret: string, durationSeconds: number): Promise<string> {
+  // Go's jwt.MapClaims marshals keys sorted; match it so tokens diff cleanly against PocketBase.
+  const unsorted: JwtClaims = { ...claims, exp: Math.floor(Date.now() / 1000) + durationSeconds };
+  const payload = Object.fromEntries(Object.keys(unsorted).sort().map((k) => [k, unsorted[k]])) as JwtClaims;
+  const head = b64urlEncode(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = b64urlEncode(JSON.stringify(payload));
+  const sig = await crypto.subtle.sign("HMAC", await hmacKey(secret), enc.encode(`${head}.${body}`));
+  return `${head}.${body}.${b64urlEncode(new Uint8Array(sig))}`;
+}
+
+// Decode without verifying. Returns null on malformed input.
+export function decodeJWT(token: string): JwtClaims | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(b64urlDecode(parts[1]!)));
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyJWT(token: string, secret: string): Promise<JwtClaims | null> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [head, body, sig] = parts as [string, string, string];
+  let ok = false;
+  try {
+    ok = await crypto.subtle.verify("HMAC", await hmacKey(secret), b64urlDecode(sig), enc.encode(`${head}.${body}`));
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+  const claims = decodeJWT(token);
+  if (!claims) return null;
+  if (typeof claims.exp !== "number" || claims.exp <= Date.now() / 1000) return null;
+  return claims;
+}