Repository navigation
ADR 0031
Status: superseded · Built: done · Date: 2026-11-14 · Supersedes: 0016 · Superseded by: 0032, 0036
Built in kit 0.4.0: clientAddress and network, isGuestLimitError, backend.check(), @spotcraft/kit/migrate (migrateApp, migrationsFromFiles, adoptDrizzle), prepare and healthResponse, and the Nuxt and TanStack Start adapters. Found while building: Nitro 2 doesn't wait for an async plugin before serving, so healthResponse waits for prepare; the Nuxt adapter imports nothing from h3 and answers the guest limit itself, since h3 logs a thrown error as unhandled.
ADR 0016 made the kit framework-neutral: a Web Request goes in, Headers come out, and the
app passes clientAddress to guest(). It left the app's own migrations to the app. This
record replaces those two rules of ADR 0016; the rest of it stands.
The two apps on Spotcraft, on Nuxt and on TanStack Start, each wrote the same code around the kit, and got parts of it differently:
- reading the client address from the X-Forwarded-For entry Spotcraft's Caddy adds, with an IPv6 address counted as its /64 (only one of them did);
- spotting the guest limit's error by its shape, since
instanceoffails across bundles; - a check at start that stops the server when the database is wrong;
- a runner for the app's own SQL migrations, with an advisory lock and an ordering check, or Drizzle's folder migrator, which needs a folder at run time.
-
Client address.
guest(request)no longer needsclientAddress. Without it, the kit takes the last X-Forwarded-For entry, which Spotcraft's Caddy sets, and'unknown'without one. Any address, passed in or read, counts as its /64 if it is IPv6.clientAddress(request, fallback)andnetwork(address)are exported for adapters. -
isGuestLimitError(error)checks the shape (status429 and a finiteretryAfterSeconds), so it works across copies of the kit. -
backend.check()connects and checks theauthschema version, with an error that names the problem. Apps call it at start. -
@spotcraft/kit/migrateruns an app's own migrations, in its database'spublic:-
migrateApp(db, migrations, { adoptDrizzle })takes{ version, name, sql }, numbered 1, 2, 3… It applies the new ones in one transaction under an advisory lock, with a 5 slock_timeout, and records them inpublic.app_migrations. - It refuses to run when a migration is missing below the newest applied one, when an applied version now has another name, or when the database is newer than the app.
-
migrationsFromFiles(files)sorts.sqlfiles by name and numbers them from 1, sodrizzle-kit generate's files work as they are, read from a folder or from server assets. -
adoptDrizzletakes over from Drizzle's migrator once: whenapp_migrationsis empty anddrizzle.__drizzle_migrationshas N rows, the first N migrations count as applied, if each file's SHA-256 matches the hash Drizzle stored. - Migrations still only add: during a release two versions of the app run against one database (ADR 0028).
-
-
Framework adapters as optional subpath exports with optional peer dependencies:
@spotcraft/kit/nuxtand@spotcraft/kit/tanstack-start. They are functions, not ready-made plugins: Nitro replacesimport.meta.devandimport.meta.prerenderonly in the app's code, so the app keeps a short plugin that calls the kit.
- Apps on Spotcraft drop their own copies of this code, and get the same IPv6 grouping.
- An app hosted behind another proxy, or none, must pass
clientAddressitself: without it, a client could put any address in X-Forwarded-For and dodge the guest limit. -
migrateAppuses the same lock number andapp_migrationstable as the runner vinskiano had, so it takes over with nothing to change in the database. - Inserting a file between applied migrations now stops the app at start, instead of renumbering what ran. New migration files go at the end.
- The kit has more to keep working: each adapter is tested against the framework versions its peer range names.
Published from docs/. Edit the files there; changes here are overwritten.