@voidbase-cloud/voidbase 0.1.0

package/db/migrations/meta/_journal.json

@@ -0,0 +1,34 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1788631175137,
+      "tag": "20260905175935_large_swarm",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1788634640757,
+      "tag": "20260905185720_wild_sunspot",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1788635243749,
+      "tag": "20260905190723_solid_toro",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1788644020730,
+      "tag": "20260905213340_remarkable_union_jack",
+      "breakpoints": true
+    }
+  ]
+}

package/db/schema.ts

@@ -0,0 +1,130 @@
+// System tables only. User collections are created at runtime from _collections rows (schema is data, as in PocketBase).
+// This file exists so `void db generate` produces the bootstrap migration that `void deploy` applies.
+import { index, integer, sqliteTable, text, uniqueIndex } from "void/schema-d1";
+import { sql } from "void/db";
+
+const now = sql`(strftime('%Y-%m-%d %H:%M:%fZ'))`;
+const randomId = sql`('r'||lower(hex(randomblob(7))))`;
+
+export const collections = sqliteTable(
+  "_collections",
+  {
+    id: text("id").primaryKey().notNull().default(randomId),
+    system: integer("system", { mode: "boolean" }).notNull().default(false),
+    type: text("type").notNull().default("base"),
+    name: text("name").notNull().unique(),
+    fields: text("fields").notNull().default("[]"),
+    indexes: text("indexes").notNull().default("[]"),
+    listRule: text("listRule"),
+    viewRule: text("viewRule"),
+    createRule: text("createRule"),
+    updateRule: text("updateRule"),
+    deleteRule: text("deleteRule"),
+    options: text("options").notNull().default("{}"),
+    created: text("created").notNull().default(now),
+    updated: text("updated").notNull().default(now),
+  },
+  (t) => [index("idx__collections_type").on(t.type)],
+);
+
+export const params = sqliteTable("_params", {
+  id: text("id").primaryKey().notNull().default(randomId),
+  value: text("value"),
+  created: text("created").notNull().default(now),
+  updated: text("updated").notNull().default(now),
+});
+
+// PocketBase-style JS migrations (pb_migrations) applied by the hooks runtime. Named _pbMigrations because Void keeps its own _migrations table.
+export const migrations = sqliteTable("_pbMigrations", {
+  file: text("file").primaryKey().notNull(),
+  applied: integer("applied").notNull(),
+});
+
+// System auth collection: superusers (collection id pbc_3142635823 in PocketBase).
+export const superusers = sqliteTable(
+  "_superusers",
+  {
+    id: text("id").primaryKey().notNull().default(randomId),
+    password: text("password").notNull().default(""),
+    tokenKey: text("tokenKey").notNull().default(""),
+    email: text("email").notNull().default(""),
+    emailVisibility: integer("emailVisibility", { mode: "boolean" }).notNull().default(false),
+    verified: integer("verified", { mode: "boolean" }).notNull().default(false),
+    created: text("created").notNull().default(""),
+    updated: text("updated").notNull().default(""),
+  },
+  (t) => [
+    uniqueIndex("idx_tokenKey_pbc_3142635823").on(t.tokenKey),
+    uniqueIndex("idx_email_pbc_3142635823").on(t.email).where(sql`${t.email} != ''`),
+  ],
+);
+
+const refCols = {
+  id: text("id").primaryKey().notNull().default(randomId),
+  collectionRef: text("collectionRef").notNull().default(""),
+  recordRef: text("recordRef").notNull().default(""),
+  created: text("created").notNull().default(""),
+  updated: text("updated").notNull().default(""),
+};
+
+export const mfas = sqliteTable("_mfas", { ...refCols, method: text("method").notNull().default("") }, (t) => [
+  index("idx_mfas_collectionRef_recordRef").on(t.collectionRef, t.recordRef),
+]);
+
+export const otps = sqliteTable(
+  "_otps",
+  { ...refCols, password: text("password").notNull().default(""), sentTo: text("sentTo").notNull().default("") },
+  (t) => [index("idx_otps_collectionRef_recordRef").on(t.collectionRef, t.recordRef)],
+);
+
+export const externalAuths = sqliteTable(
+  "_externalAuths",
+  { ...refCols, provider: text("provider").notNull().default(""), providerId: text("providerId").notNull().default("") },
+  (t) => [
+    uniqueIndex("idx_externalAuths_record_provider").on(t.collectionRef, t.recordRef, t.provider),
+    uniqueIndex("idx_externalAuths_collection_provider").on(t.collectionRef, t.provider, t.providerId),
+  ],
+);
+
+export const authOrigins = sqliteTable(
+  "_authOrigins",
+  { ...refCols, fingerprint: text("fingerprint").notNull().default("") },
+  (t) => [uniqueIndex("idx_authOrigins_unique_pairs").on(t.collectionRef, t.recordRef, t.fingerprint)],
+);
+
+// Realtime change feed (decision d5): appended inside the record write batch, polled by open SSE streams.
+export const changes = sqliteTable(
+  "_changes",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    collection: text("collection").notNull(),
+    recordId: text("recordId").notNull(),
+    action: text("action").notNull(), // create | update | delete
+    data: text("data"), // record JSON at the time of the change (deletes cannot be re-read)
+    created: text("created").notNull().default(now),
+  },
+  (t) => [index("idx__changes_collection").on(t.collection, t.id)],
+);
+
+// Connected SSE clients and their subscriptions (the POST can land on any isolate).
+export const realtimeClients = sqliteTable("_realtime_clients", {
+  id: text("id").primaryKey().notNull(),
+  subscriptions: text("subscriptions").notNull().default("[]"),
+  token: text("token").notNull().default(""),
+  created: text("created").notNull().default(now),
+  updated: text("updated").notNull().default(now),
+});
+
+// Request and application logs (PocketBase's auxiliary _logs table): data is the JSON payload PocketBase's
+// panel filters on (data.type, data.status, data.auth ...), level uses slog levels (-4 debug, 0 info, 4 warn, 8 error).
+export const logs = sqliteTable(
+  "_logs",
+  {
+    id: text("id").primaryKey(),
+    created: text("created").notNull().default(""),
+    data: text("data").notNull().default("{}"),
+    message: text("message").notNull().default(""),
+    level: integer("level").notNull().default(0),
+  },
+  (t) => [index("idx_logs_created").on(t.created), index("idx_logs_level").on(t.level), index("idx_logs_message").on(t.message)],
+);

package/docs/deploy.md

@@ -0,0 +1,153 @@
+# Deploying voidbase
+
+voidbase is a Void app: one Worker (with its realtime hub Durable Object inside), one D1 database, one R2 bucket, a
+jobs queue and the cron triggers the hooks need. Void infers the bindings (`DB`, `STORAGE`, the queue from `queues/`) from the source and provisions them; the
+system tables come from the checked-in Drizzle migrations in `db/migrations/`, and PocketBase-style `pb_migrations`
+run on the first request.
+
+## Before the first deploy
+
+```bash
+bun install
+bun run panel:sync                      # unmodified PocketBase admin panel -> public/_  (see --brand in scripts/sync-panel.ts)
+bun run app:sync                        # optional: a built SvelteKit/SPA app -> public/  (deep links get index.html as the 404 page)
+bun run build                           # vp build; bundles pb_hooks and pb_migrations into the Worker
+```
+
+Secrets and settings that must exist in production (declared in `env.ts`):
+
+| Variable | Purpose |
+| --- | --- |
+| `VOIDBASE_SUPERUSER_EMAIL`, `VOIDBASE_SUPERUSER_PASSWORD` | first superuser, upserted on the first request. Remove or rotate after the first login |
+| `VOIDBASE_ENCRYPTION_KEY` | optional; encrypts the settings row (SMTP password, OAuth2 secrets) at rest |
+| `AUDITLOG` | only if your `pb_hooks` read it, like the starter's audit log |
+| `VOIDBASE_ALERT_WEBHOOK_URL` | optional; every unhandled request error (HTTP 500) is POSTed there as JSON `{source, level, message, status, time, method, path, error, stack}` (Slack/Discord/PagerDuty-style receivers or your own endpoint) |
+| `VOIDBASE_MAIL_HTTP_URL`, `VOIDBASE_MAIL_HTTP_KEY` | optional HTTP mail provider (Resend-compatible JSON endpoint + bearer key) used instead of SMTP for every email, including the panel's test email |
+
+Everything else (SMTP, OAuth2 providers, rate limits, backups cron, trusted proxy) is configured from the
+panel's Settings pages and stored in D1.
+
+## Go live on your Cloudflare account (primary path)
+
+One API token, one command. Create the token with this link; it opens the Cloudflare dashboard's token wizard for
+your account with the permissions voidbase needs already selected (Workers Scripts edit, D1 edit, Workers R2
+Storage edit, Queues edit, Account Settings read):
+
+[Create VOIDBASE_DEPLOY_CF_API_KEY](https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22d1%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_r2%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22queues%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%5D&name=VOIDBASE_DEPLOY_CF_API_KEY)
+
+Queues edit is optional: a token without it (one created before this permission was added) still deploys, the
+deploy just skips the jobs queue and says so.
+
+`voidbase token` prints the same link. Then, in the directory that holds `pb_hooks/` and `pb_migrations/`
+(`voidbase-sveltekit-starter/vb` for the starter):
+
+```bash
+export VOIDBASE_DEPLOY_CF_API_KEY=...        # or put it in .env next to pb_hooks, or a CI secret
+voidbase deploy --public-dir ../sk/build     # --name <worker>, --account <id> when the token reaches several accounts
+```
+
+What it does, in order: resolves the account through the token, creates `<name>-db` (D1), `<name>-storage`
+(R2) and `<name>-jobs` (Queue) if they do not exist, writes the Void project inside the voidbase package
+(`node_modules/voidbase/.cloud/<name>`, nothing appears in your tree) with a `wrangler.jsonc` carrying the real
+ids and, when the directory has a `main.ts` exporting `register(app)`, composes it into the Worker; stores the
+superuser as worker secrets (from `VOIDBASE_SUPERUSER_*` / `PB_SUPERUSER_*`, or a generated
+password saved in `pb_data/.superuser-credentials`; the local dev default `changeme123` never goes live), syncs
+the admin panel and your frontend build into that project, and runs `void deploy --backend cloudflare`,
+which builds, applies the D1 migrations and uploads the Worker with its cron trigger. It ends with the
+`https://<name>.<your-subdomain>.workers.dev` URL and a health check. Re-running is idempotent: existing resources
+and credentials are reused. `--dry-run` does everything except install, secrets and the upload.
+
+Quotas to know: the Workers Free plan allows 10 D1 databases per account (paid plans 50,000) and 5 cron
+triggers per worker; voidbase needs one database, one bucket, one queue and the triggers its hooks declare (an
+hourly tick without any). Cloudflare's own permission reference is at
+https://developers.cloudflare.com/fundamentals/api/reference/permissions/ should the link's pre-selection ever
+stop matching (the token then needs those permissions, picked by hand at
+https://dash.cloudflare.com/?to=/:account/api-tokens).
+
+### A custom domain
+
+`voidbase deploy --domain api.example.com` (or `VOIDBASE_DEPLOY_DOMAIN`) turns workers.dev off for the Worker and attaches
+the hostname through the Workers Custom Domains API after the upload: Cloudflare creates the DNS record and the
+certificate (a minute or two), and the token needs nothing beyond Workers Scripts edit, provided the zone is on the same
+account. Cloudflare still requires the account to have a workers.dev subdomain before it accepts any upload (error
+10063): open Workers & Pages once, or `PUT /accounts/<id>/workers/subdomain {"subdomain": "<name>"}`.
+`destroyInstance` in `voidbase/cloud` detaches custom domains before deleting the Worker.
+
+### What the deploy wires up, and the knobs
+
+| Binding | What it does | Knob |
+| --- | --- | --- |
+| `<name>-jobs` queue (`queues/<name>-jobs.ts`) | outbound mail and automatic backups run from the queue with retries (30 s, 60 s, ... up to 15 min, five times, then dropped and posted to `VOIDBASE_ALERT_WEBHOOK_URL`). Requests never wait on SMTP. Without the queue everything runs inline, as on the Bun runtime | `--no-queue` / `VOIDBASE_DEPLOY_QUEUE=0`; skipped automatically when the token lacks Queues edit |
+| `RATE_LIMITER` (Cloudflare rate-limit binding) | a ceiling per client IP on `/api`, counted per Cloudflare location across every isolate there, on top of the settings' rate-limit rules (which count per isolate). Applies only while rate limits are enabled in Settings, and skips superusers and excluded IPs like the rules do. Cloudflare documents it as eventually consistent, not an exact counter | `--rate-limit 300/10` (requests per 10 or 60 seconds, default PocketBase's `/api/` rule) / `VOIDBASE_DEPLOY_RATE_LIMIT`, `0` disables |
+| `LOGS_ANALYTICS` (Workers Analytics Engine) | one data point per request (method, path, status, auth collection, error, execution time) at any log level, queryable in the dashboard and the SQL API at $0.25 per million points, while the panel's log keeps writing D1 rows from `VOIDBASE_LOG_MIN_LEVEL` up. The account has to enable Analytics Engine once, at https://dash.cloudflare.com/?to=/:account/workers/analytics-engine, or the upload fails with code 10089 | opt-in: `--analytics` / `VOIDBASE_DEPLOY_ANALYTICS=1` |
+| `HUB` (Durable Object `VoidbaseHub`, SQLite-backed, in this Worker) | the realtime hub: every SSE connection holds one hibernatable socket to it, writes publish to it, so events arrive in tens of milliseconds instead of the D1 poll's second, and idle apps cost nothing (the object sleeps). Free plan included | `--no-hub` / `VOIDBASE_DEPLOY_HUB=0` keeps the D1 poll |
+| Smart Placement | the Worker runs next to its D1 database | always on |
+
+### Every instance is isolated
+
+Two voidbase instances on one account never share a resource. Everything the deploy creates is named or derived from
+the worker name: `<name>-db`, `<name>-storage`, `<name>-jobs`, the `<name>_requests` dataset, and the rate-limit
+binding's `namespace_id` is hashed from the name, because Cloudflare shares counters between bindings that reuse an
+id across Workers. The realtime hub is a Durable Object class exported from the instance's own Worker rather than a Worker shared
+by apps. `test/deploy-cf.ts` asserts the naming.
+
+## Option B: the Void platform
+
+```bash
+void auth login
+voidbase deploy --void            # void deploy from this checkout, or from cloud/ in a consumer
+```
+
+`void deploy` builds, applies the Drizzle migrations to the remote D1, provisions D1/R2/cron from the source and
+makes the deploy live; secrets go through `void secret put`. Continuous deploys: `void init --github` (GitHub
+OIDC) or the Void GitHub app. Operations: `void project logs --level error`, `void project requests --status 5xx`,
+`void project rollback`.
+
+## Option C: a visible Void project
+
+`voidbase cloud init [dir]` writes the same project into your tree, importing the `voidbase` package by name, for
+people who want to edit it (extra routes, bindings, a custom domain in `wrangler.jsonc`). Deploy it with
+`voidbase deploy --dir <dir>`, or by hand: `wrangler login`, `CLOUDFLARE_ACCOUNT_ID`, then
+`void deploy --backend cloudflare --provision` (interactive shells only; commit the `wrangler.jsonc` it writes for
+CI). Every `.env*` file that backend loads ships as plaintext worker vars, so keep secrets in `wrangler secret put`.
+
+## Option D: instances created by a control plane (`voidbase bundle` + `voidbase/cloud`)
+
+`voidbase deploy` builds on your machine. A service that creates voidbase instances for other people (the site's
+/cloud page is one: sign in with Cloudflare, one click, an instance in the user's own account) cannot build, so it
+uploads a prebuilt release over Cloudflare's REST API instead:
+
+```bash
+voidbase bundle                                   # builds the generic Worker + panel once -> .cloud/releases/<version>/
+voidbase bundle --push https://<control plane> --token <superuser token>   # ... and stores it in that instance (POST /api/vbcloud/releases)
+```
+
+`voidbase/cloud` (src/cloud/rest.ts, plain fetch, runs in a Worker) then does what the deploy does, from the
+release: `provisionInstance(cf, { account, name, release, superuser })` creates `<name>-db`, `<name>-storage`,
+`<name>-jobs`, applies the D1 migrations through `/query` (tracked in wrangler's `d1_migrations` table), uploads the
+assets through an upload session and the script with its bindings, DO migration, cron trigger and workers.dev
+subdomain, tagged `voidbase` + `voidbase-release:<version>`; `destroyInstance` removes all of it (worker first,
+bucket last, emptied before); `listVoidbaseWorkers` finds instances by tag. The token is the user's OAuth access token
+(`cloudflare` OAuth2 provider, see `voidbase-site/vb/cloud`) or an API token with the same permissions.
+`test/cloud-rest.ts` exercises it against `test/cf-mock.ts`. The hub and the queue are decided when the release
+is bundled (`voidbase bundle --no-hub` / `--no-queue`), not per instance: an instance can leave them out at
+provisioning, but cannot add what the release does not carry. Tokens a control plane keeps go to rest sealed
+with `VOIDBASE_ENCRYPTION_KEY` (`sealSecret` / `openSecret` from `voidbase/cloud`).
+
+## After deploying
+
+1. Open `/_/`, log in with the bootstrap superuser, change the password.
+2. Settings > Application: set the application URL (used in emails) and, if you terminate TLS elsewhere,
+   the trusted proxy header. On Workers the client IP already comes from `CF-Connecting-IP`.
+3. Settings > Mail server: SMTP on port 465 or 587 (25 is blocked on Workers); send the test email.
+4. Settings > Backups: set a cron to write zips to R2 (`__backups__/`).
+5. Point your app at the Worker URL. The `pocketbase` JS SDK needs no other change.
+
+## Local preview of the production build
+
+```bash
+VOIDBASE_PERSIST_TO=.void-preview bun run build && vp preview --port 5181
+```
+
+`vp preview` runs the built Worker in workerd with the same module-scope restrictions as production, which is
+how `test/fresh-db.ts` catches code that only works in dev.

package/docs/differences.md

@@ -0,0 +1,88 @@
+# Differences and limits versus PocketBase
+
+voidbase speaks PocketBase's HTTP API on Cloudflare Workers with D1 (SQLite), R2 (files) and the Workers cron
+trigger. The panel and the SDK cannot tell the two apart for the surfaces listed in [COMPAT.md](../COMPAT.md);
+this page lists where the platform forces a different shape, and the limits that come with it.
+
+## Storage and database
+
+| Topic | PocketBase | voidbase |
+| --- | --- | --- |
+| Database | one SQLite file on local disk | one D1 database (SQLite semantics, remote) |
+| Transactions | interactive, `RunInTransaction` | none: every write validates first, then runs as **one D1 batch** (atomic). Hook code cannot open a transaction; `$app.runInTransaction(fn)` runs `fn` directly |
+| Bound parameters | SQLite default (32766) | **100 per statement** (D1). Large `IN (...)` lists and wide inserts are chunked by the server; hand-written `$app.dao()` SQL must respect it |
+| Columns per table | 2000 | 100 (D1) |
+| Row / query size | SQLite limits | 1 MB per row, 128 MB per query result (D1). List endpoints paginate anyway |
+| `_logs`, `_changes` | logs in a second SQLite file | tables in the same D1 database, pruned by the built-in crons |
+| Files | local `pb_data/storage` or S3 | R2 bucket bound as `STORAGE` (keys `{collectionId}/{recordId}/{filename}`), or any S3-compatible bucket when `settings.s3.enabled` (SigV4 over fetch, path-style or virtual-host); `settings.backups.s3` likewise for archives |
+| Backups | zip of the SQLite files + storage | zip of `data.json` (every table) + `storage/`, kept in R2 under `__backups__/`. A PocketBase backup cannot be restored here and vice versa; use import/export for cross-migration |
+
+## Runtime
+
+| Topic | PocketBase | voidbase |
+| --- | --- | --- |
+| Process | long-running binary, in-memory state | `voidbase serve` is a long-running Bun process with SQLite and local files (limits below do not apply there: transactions are real, rate limits exact, realtime pushes from memory); on Cloudflare, stateless isolates. Anything PocketBase keeps in memory (resend limits, OTP attempts, MFA sessions, WebAuthn challenges, backup lock) lives in `_params` or its own table |
+| Rate limits | per process, exact | per isolate, **approximate**: each isolate keeps its own fixed-window counters. Configure limits as a safety net, not as billing |
+| Realtime | in-process broadcaster | every SSE connection polls the `_changes` table from inside its own request, about once a second; connections in one isolate share the read. Events arrive within roughly one second and cost one D1 read per second per isolate while at least one client is connected (zero when idle) |
+| Crons | in-process scheduler | Cloudflare cron trigger every minute runs the due jobs (`runDue`). A job may run on any isolate; keep jobs idempotent. `POST /api/crons/:id` runs a job on demand |
+| CPU time | unlimited | Workers CPU limit per request (30 s on paid plans by default). Thumbnail generation of very large images and huge batch requests are the operations most likely to hit it |
+| Request body | 32 MB default (configurable) | 32 MB, and Cloudflare's own upload limit applies (100 MB on Free/Pro plans, higher on Business/Enterprise) |
+| Outbound mail | net/smtp | `cloudflare:sockets` TCP with STARTTLS or implicit TLS (port 25 is blocked on Workers; use 465 or 587), or an HTTP provider when `VOIDBASE_MAIL_HTTP_URL` is set (Resend-compatible JSON, bearer key in `VOIDBASE_MAIL_HTTP_KEY`); the settings JSON stays PocketBase-shaped either way |
+| OAuth2 | Go providers | the same 32 providers implemented on `fetch`; Apple client secret generation with ES256 in WebCrypto |
+| JS hooks | goja VM, synchronous | bundled at build time into the Worker (`pb_hooks/*.pb.js`), running on V8. `$app.*`, `$http.send`, `$filesystem.*` and mail calls are asynchronous under the hood; the bundler inserts the awaits so hook code stays PocketBase-shaped. See [hooks.md](./hooks.md) |
+| Migrations | `pb_migrations/*.js` at startup | the same files, bundled at build time and applied on the first request after a deploy (tracked in `_pbMigrations`) |
+| Panel | embedded | the unmodified panel build copied to `public/_` by `bun run panel:sync` |
+| Settings encryption | `--encryptionEnv` | `VOIDBASE_ENCRYPTION_KEY` (16, 24 or 32 chars): the settings row is stored AES-GCM encrypted |
+| Superuser bootstrap | `superuser upsert` CLI | `VOIDBASE_SUPERUSER_EMAIL` / `VOIDBASE_SUPERUSER_PASSWORD` env, upserted on the first request |
+
+## Thumbnails
+
+Sizes, crop anchors and fit rules follow PocketBase's `tools/filesystem` (imaging semantics), generated in Photon
+(Rust compiled to wasm) and cached in R2. Only sizes declared on the field (plus `100x100`) are honoured, as in
+PocketBase. WebP output is not produced: JPEG in, JPEG out; PNG in, PNG out.
+
+## Not implemented
+
+- `OnTerminate`, `OnBackupCreate` / `OnBackupRestore` hook events (registered, never fired).
+- `$os.cmd` / `$os.exec`, `$filesystem.fileFromPath`, `$template` rendering from disk: there is no filesystem or shell on Workers.
+- PocketBase's own CLI (`pocketbase serve|migrate|superuser`). Use the panel, `bun run` scripts and Void's CLI ([deploy.md](./deploy.md)).
+
+## Health endpoint
+
+`GET /api/health` returns `canBackup: false` while a backup or restore is running. `possibleProxyHeader` never
+reports `CF-Connecting-IP`: Workers set that header themselves and voidbase already uses it as the client IP,
+so the panel's "behind a reverse proxy" reminder only fires for other proxy headers you have not listed in
+`settings.trustedProxy`.
+
+## Static files on Cloudflare
+
+PocketBase serves `--publicDir` itself: an existing file, otherwise `index.html` with status 200, and the admin panel's
+index for any `/_/` path. On Cloudflare, voidbase hands everything outside `/api` to the static asset layer, which
+never invokes the Worker (assets are free and skip the isolate; see docs/platform.md). Cloudflare answers a miss with
+the nearest `404.html`, so the build ships `404.html` copies of `index.html` and of `_/index.html`:
+
+- deep links (`/posts/abc/`) get the SPA shell with **status 404** instead of PocketBase's 200 (the body is identical; the
+  client router boots as usual, and this is the shape SvelteKit documents for Cloudflare);
+- a browser navigating to an unknown `/api/...` URL gets that HTML page with status 404, while API clients (anything
+  without `text/html` in `Accept`) get PocketBase's JSON 404;
+- `voidbase serve` (Bun) keeps PocketBase's exact semantics, including the 200 index fallback.
+
+## Background jobs on Cloudflare
+
+With the jobs queue that `voidbase deploy` creates, the system emails (verification, password reset, email change,
+OTP, login alert) and the automatic backups run from a Cloudflare Queue instead of inside the request. Hooks still
+run in the request on the final message; only the transport (SMTP or the HTTP provider) is deferred, retried five
+times with backoff and, when it keeps failing, dropped and posted to `VOIDBASE_ALERT_WEBHOOK_URL`. Delivery is
+at-least-once: a mail whose SMTP session broke after the server accepted it can arrive twice. The panel's test
+email and `$app.newMailClient().send()` stay synchronous and report transport errors, as in PocketBase. Without the
+queue (the Bun runtime, or a deploy whose token could not create one) everything runs inline as before.
+
+## Realtime transport
+
+The SSE protocol, topics, `PB_CONNECT`, subscription updates and the per-subscriber rule checks are PocketBase's.
+What differs is the transport behind them. On Cloudflare a per-instance Durable Object (the hub) fans out changes:
+every connection holds one hibernatable WebSocket to it, a record write publishes after its D1 batch has committed,
+and the isolate holding the connection fetches the record with the subscriber's auth and rules before sending. Like
+PocketBase there is no replay: an event that happens while a client is reconnecting is missed. If the hub becomes
+unreachable the stream ends and the SDK reconnects. Without the hub binding (the Bun runtime, or a deploy with
+`--no-hub`) the same protocol runs on a D1 change feed polled about once a second by each connection.

package/docs/hooks.md

@@ -0,0 +1,84 @@
+# JS hooks and migrations
+
+voidbase runs PocketBase's `pb_hooks/*.pb.js` and `pb_migrations/*.js` files with the same globals. The
+difference is *when* they load: the files are bundled into the Worker at build time (`hooks-plugin.ts`), so a
+hook change needs a rebuild and redeploy, not a restart. Directories are configured with `VOIDBASE_HOOKS_DIR`
+and `VOIDBASE_MIGRATIONS_DIR` (defaults `pb_hooks`, `pb_migrations`).
+
+## Writing hooks
+
+Hook code is written exactly as for PocketBase. Because `$app.*`, `$http.send`, `$filesystem.*` and mail
+calls are asynchronous on Workers, the bundler rewrites the file so each of those calls is awaited and the
+enclosing function becomes async; `e.next()` is awaited too. Ordinary synchronous-looking PocketBase code works
+unchanged. `require("./other.js")` resolves against the hooks directory bundle.
+
+```js
+/// <reference path="../pb_data/types.d.ts" />
+routerAdd("GET", "/api/hello", (e) => {
+  return e.json(200, { hello: e.auth?.email() ?? "guest" });
+}, $apis.requireAuth());
+
+onRecordCreateRequest((e) => {
+  e.record.set("slug", e.record.get("title").toLowerCase().replaceAll(" ", "-"));
+  e.next();
+}, "posts");
+
+cronAdd("digest", "0 8 * * *", () => {
+  const users = $app.findRecordsByFilter("users", "verified = true", "-created", 100, 0);
+  $app.logger().info("digest", "count", users.length);
+});
+```
+
+## Events
+
+Every `on*` function registers a handler; `e.next()` runs the remaining handlers and then the core action.
+Throwing an `ApiError` subclass (`BadRequestError`, `ForbiddenError`, `NotFoundError`, `UnauthorizedError`,
+`InternalServerError`, `ValidationError`) answers the request with that error. Handlers accept optional
+collection-name tags as trailing arguments.
+
+| Family | Events |
+| --- | --- |
+| App | `onBootstrap`, `onServe` (both once per isolate on its first request), `onSettingsReload` |
+| Records (model) | `onRecordEnrich`, `onRecordValidate`, `onRecord{Create,Update,Delete}`, `onRecord{Create,Update,Delete}Execute`, `onRecordAfter{Create,Update,Delete}{Success,Error}`, and the `onModel*` equivalents |
+| Records (request) | `onRecordsListRequest`, `onRecordViewRequest`, `onRecord{Create,Update,Delete}Request` |
+| Auth (request) | `onRecordAuthRequest`, `onRecordAuthWithPasswordRequest`, `onRecordAuthWithOAuth2Request`, `onRecordAuthWithOTPRequest`, `onRecordAuthRefreshRequest`, `onRecordRequestOTPRequest`, `onRecordRequest{Verification,PasswordReset,EmailChange}Request`, `onRecordConfirm{Verification,PasswordReset,EmailChange}Request` |
+| Collections | `onCollectionValidate`, `onCollection{Create,Update,Delete}`, `onCollectionAfter{Create,Update,Delete}{Success,Error}`, `onCollectionsListRequest`, `onCollectionViewRequest`, `onCollection{Create,Update,Delete}Request`, `onCollectionsImportRequest` |
+| Files | `onFileDownloadRequest` (`e.servedName` editable), `onFileTokenRequest` |
+| Realtime | `onRealtimeConnectRequest`, `onRealtimeSubscribeRequest` (`e.subscriptions` editable), `onRealtimeMessageSend` (`e.message` editable) |
+| Settings | `onSettingsListRequest` (`e.settings` editable), `onSettingsUpdateRequest` (`e.oldSettings`, `e.newSettings`) |
+| Mail | `onMailerSend`, `onMailerRecord{AuthAlert,PasswordReset,Verification,EmailChange,OTP}Send` |
+| Batch | `onBatchRequest` (`e.batch` editable) |
+| Registered, never fired | `onTerminate`, `onBackupCreate`, `onBackupRestore` |
+
+Request events expose the PocketBase `RequestEvent` surface: `e.auth`, `e.request`, `e.requestInfo()`,
+`e.pathParam(name)`, `e.bindBody(obj)`, `e.json(status, data)`, `e.string`, `e.html`, `e.noContent`,
+`e.redirect`, `e.next()`.
+
+## Globals
+
+| Global | Supported members |
+| --- | --- |
+| `$app` | `findCollectionByNameOrId`, `findAllCollections`, `findRecordById`, `findFirstRecordByData`, `findFirstRecordByFilter`, `findRecordsByFilter`, `findAuthRecordByEmail`, `findAuthRecordByToken`, `countRecords`, `expandRecord(s)`, `save`, `saveNoValidate`, `delete`, `runInTransaction` (runs the callback directly), `settings()`, `isDev()`, `logger()`, `newMailClient()`, `dao()` (raw SQL, D1 limits apply) |
+| `$apis` | `requireAuth`, `requireSuperuserAuth`, `requireGuestOnly`, `requireSuperuserOrOwnerAuth`, `enrichRecord(s)` |
+| `$http` | `send({url, method, body, headers, timeout})` |
+| `$filesystem` | `fileFromURL`, `fileFromBytes`; `fileFromPath` throws (no filesystem) |
+| `$security` | `randomString`, `randomStringWithAlphabet`, `pseudorandomString`, `sha256` |
+| `$os` | `getenv` (Worker env vars), `readFile` (files bundled from the hooks directory), `writeFile`, `args`; `cmd`/`exec` throw |
+| `$dbx` | `exp`, `hashExp` |
+| `$mails`, `$template` | placeholders: `$template.loadFiles(...).render()` returns `""`. Build mail bodies as strings and send them with `$app.newMailClient().send(new MailerMessage({...}))` |
+| Classes | `Record`, `Collection`, `RecordUpsertForm`, `MailerMessage`, `DateTime`, `RequestInfo`, `Field` and the typed field classes (`TextField`, `RelationField`, ...) |
+| Registration | `routerAdd`, `routerUse`, `cronAdd`, `cronRemove`, `migrate` |
+
+## Migrations
+
+`pb_migrations/*.js` files written by PocketBase's automigrate (`new Collection({...})`, `app.save`,
+`app.findCollectionByNameOrId`, `collection.fields.addAt`, `unmarshal`) run unchanged. Pending migrations are
+applied on the first request after a deploy, in file order, and recorded in `_pbMigrations`. The down
+function is kept for parity but there is no CLI to run it; roll back by deploying a new migration.
+
+## Testing hooks locally
+
+`bun test/fresh-db.ts` builds the Worker with `test/fixtures/hooks` and `test/fixtures/migrations`, boots
+`vp preview` on an empty D1 and checks the hook side effects end to end. Point it at your own hooks with
+`VOIDBASE_HOOKS_DIR` / `VOIDBASE_MIGRATIONS_DIR`, or run `./scripts/dev.sh start 5180` and edit `pb_hooks/`:
+the dev server rebuilds the hooks bundle on save.

package/docs/migrating.md

@@ -0,0 +1,29 @@
+# Migrating an app from PocketBase
+
+1. **Export the schema** from PocketBase: Settings > Export collections, or `GET /api/collections?perPage=500`.
+   Import it into voidbase with Settings > Import collections (`PUT /api/collections/import`). Collection and
+   field ids are preserved, so existing tokens' `collectionId` claims and relation fields keep working.
+2. **Move the data.** For each collection, page through `GET /api/collections/{name}/records` on PocketBase and
+   `POST` the records to voidbase as a superuser (ids are kept when supplied). Files: download from
+   `/api/files/...` and re-upload as multipart. Passwords cannot be exported by PocketBase; users keep their
+   accounts through a password reset, or you write the `password` hash column directly with `POST /api/sql`
+   (bcrypt hashes are compatible).
+3. **Copy `pb_hooks/` and `pb_migrations/`** into the voidbase project (or point `VOIDBASE_HOOKS_DIR` and
+   `VOIDBASE_MIGRATIONS_DIR` at them) and rebuild. Read [hooks.md](./hooks.md) for the few members that do
+   not exist on Workers (`$os.cmd`, `$filesystem.fileFromPath`, `$template` from disk).
+4. **Settings:** re-enter SMTP credentials and OAuth2 client secrets in the panel (PocketBase never exports
+   secrets). Update every provider's redirect URL to `https://<your-worker>/api/oauth2-redirect`.
+5. **Client apps:** change the base URL passed to `new PocketBase(...)`. Realtime, files, thumbs, batch, auth
+   flows and the admin panel behave the same; the differences that can matter are listed in
+   [differences.md](./differences.md).
+6. **Verify.** `bun test/conformance/compare.ts <pocketbaseURL> <voidbaseURL>` runs the same requests against
+   both servers and diffs the JSON; the other suites under `test/conformance/` cover records, files, auth,
+   realtime, settings, logs, crons, backups and SQL.
+
+## Leaving voidbase
+
+`bun scripts/export.ts <url> <outDir>` logs in as a superuser and writes `data.db` (SQLite with PocketBase's table
+and column layout, password hashes included), `collections.json` (import format) and `storage/` (every file as
+`{collectionId}/{recordId}/{filename}`), reading only through the API so it works against a deployed instance.
+Import `collections.json` into PocketBase, copy `storage/` into `pb_data/storage/` and load the rows from `data.db`.
+

package/docs/perf.md

@@ -0,0 +1,53 @@
+# Performance baseline
+
+Numbers below come from `scripts/bench.ts` and `scripts/bench-realtime.ts` against the **local dev server**
+(Void `vp dev`, miniflare/workerd on WSL2, D1 and R2 emulated on disk). They show the shape of the cost per
+endpoint, not production latency: on Cloudflare the Worker runs next to D1 (single-digit ms reads in the same
+region), R2 adds a few ms, and cold starts of the Worker are in the tens of milliseconds. Re-run both scripts against
+a deployment for real figures (`bun scripts/bench.ts https://<your-worker> --n 50 --concurrency 20`).
+
+## Endpoints (local, 2026-09-06)
+
+| endpoint | p50 ms | p95 ms | max ms | concurrent req/s | errors |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| GET /api/health | 23.3 | 45.9 | 46.7 | 52 | 0 |
+| GET records list (30) | 30.7 | 48.2 | 151.0 | 56 | 0 |
+| GET records list + filter + sort | 24.9 | 41.1 | 86.1 | 40 | 0 |
+| GET record view | 23.8 | 39.4 | 52.7 | 54 | 0 |
+| POST record create | 28.5 | 40.5 | 77.7 | 37 | 0 |
+| PATCH record update | 29.6 | 38.8 | 53.8 | 37 | 0 |
+| POST auth-with-password | 117.6 | 137.9 | 202.9 | 9 | 0 |
+| GET file | 24.3 | 32.1 | 53.7 | 52 | 0 |
+| GET thumb 100x100 (cached after first) | 37.2 | 59.2 | 92.3 | 38 | 0 |
+| GET collections list (superuser) | 25.3 | 33.7 | 53.9 | 54 | 0 |
+
+Reading the table: every request pays one settings read (cached per isolate for a few seconds), one auth lookup when a
+token is present, and the D1 statements the endpoint needs (list: one count + one page query; create: one batch with
+the insert and the realtime change-feed row). `auth-with-password` is dominated by bcrypt (cost 10, ~100 ms of CPU),
+as in PocketBase. Thumbnails are generated once (Photon, wasm) and then served from the R2/S3 cache.
+
+## Realtime fan-out (local)
+
+| transport | clients | opened + subscribed | received the event | delivery p50 | p95 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| hub (Durable Object, push) | 100 | 3.4 s | 100 / 100 | 346 ms | 353 ms |
+| hub, one client | 1 | | 1 / 1 | about 50 ms | |
+| D1 poll (fallback) | 100 | 4.5 s | 100 / 100 | 587 ms | 837 ms |
+
+With the hub, a write publishes once to the instance's Durable Object, which pushes to every connection's socket;
+the remaining latency at 100 clients is the per-subscriber record fetch and rule check the isolate does for each
+connection (one D1 read each, serialized in the single-threaded local runtime). With the poll, each SSE connection
+is a long-running Worker request that polls the `_changes` table about once per second; connections in the same
+isolate share the read, so the D1 cost is roughly one query per second per isolate while at least one client is
+connected and zero when idle, and delivery latency is bounded by the poll interval. The local dev server could not hold 300 concurrent streams within the bench's five-minute budget; that is a
+miniflare limit, not the design's. The dev server also never cancels an SSE request whose client vanished, so a
+killed benchmark leaves streams (and their hub sockets, which keep pinging) behind until the idle cleanup; on
+Cloudflare a client disconnect cancels the request and the hub sees the socket close. Production limits to measure on a deployment: concurrent connections per isolate
+(Cloudflare spreads long requests across isolates), D1 reads per second at 1k and 10k clients (expected: number of
+isolates x 1/s), and per-request CPU (the poll loop sleeps, it does not spin).
+
+## Cold start
+
+The Worker bundle is about 1.5 MB with the Photon wasm (loaded lazily on the first thumbnail). Bootstrap on a fresh
+isolate runs one `_params` read (settings) and, on the very first request after a deploy, the pending
+`pb_migrations`. There is no in-memory state to warm apart from the settings cache and rate-limit counters.