ras-stack 0.39.5 → 0.40.0

package/examples/full-stack/src/server/app.ts

@@ -0,0 +1,172 @@
+import { existsSync, mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { persistedSecret, standardRateLimitOptions, standardSessionOptions } from 'ras-stack/auth'
+import { openDrizzleSqlite, openSqliteClient, type OpenDrizzleSqliteOptions } from 'ras-stack/database/sqlite'
+import { createSmtpDelivery, smtpConfigFromEnvironment } from 'ras-stack/email'
+import { postHogEnvironment } from 'ras-stack/posthog'
+import { createManagedPostHogServerTelemetry } from 'ras-stack/posthog/server'
+import { CentrifugoPublisher } from 'ras-stack/realtime'
+import { globalSingleton } from 'ras-stack/server'
+import { createAuth } from './auth'
+import { loadEnvironment } from './environment'
+import { OutboxWorker } from './outbox'
+import * as schema from './schema'
+import { UploadStore } from './uploads'
+
+export function app() {
+  return globalSingleton('ras-stack.example.full-stack', createApp)
+}
+
+function createApp() {
+  const environment = loadEnvironment()
+  mkdirSync(environment.dataDirectory, { recursive: true })
+  const databaseFile = path.join(environment.dataDirectory, 'example.sqlite')
+  prepareLegacyMessages(databaseFile)
+  const options: OpenDrizzleSqliteOptions<typeof schema> = {
+    file: databaseFile,
+    schema,
+    migrationsFolder: migrationsDirectory(),
+  }
+  const database = openDrizzleSqlite(options)
+  importLegacyMessages(database.$client)
+  const smtp = smtpConfigFromEnvironment()
+  const email = smtp ? createSmtpDelivery(smtp) : undefined
+  let publishFailure: unknown
+  const publisher = new CentrifugoPublisher({
+    apiUrl: environment.centrifugoApiUrl,
+    apiKey: environment.centrifugoApiKey,
+    maxConcurrentChannels: 1,
+    maxPendingChannels: 32,
+    onError: (error, channel) => {
+      publishFailure = error
+      console.error({ event: 'example_realtime_publish_failed', channel, error })
+    },
+  })
+  const telemetry = createManagedPostHogServerTelemetry({
+    environment: postHogEnvironment({
+      projectToken: process.env.VITE_POSTHOG_PROJECT_TOKEN,
+      host: process.env.VITE_POSTHOG_HOST,
+    }),
+    serviceName: 'ras-stack-example',
+    deploymentEnvironment: process.env.NODE_ENV,
+    onError: (error) => console.error({ event: 'example_telemetry_failed', error }),
+  })
+  const auth = createAuth({
+    database,
+    email,
+    environment,
+    secret: process.env.BETTER_AUTH_SECRET ?? persistedSecret({ directory: environment.dataDirectory, filename: 'auth.secret' }),
+  })
+  const outbox = new OutboxWorker({
+    database,
+    enabled: environment.realtimeEnabled,
+    onError: (error) => console.error({ event: 'example_outbox_drain_failed', error }),
+    publish: async (channel, payload) => {
+      publishFailure = undefined
+      if (!publisher.publish(channel, payload)) throw new Error('Realtime publisher rejected the outbox item')
+      await publisher.idle()
+      if (publishFailure) throw publishFailure
+    },
+  })
+  const uploadStore = new UploadStore({
+    database,
+    directory: path.join(environment.dataDirectory, 'uploads'),
+    globalMaxFiles: environment.uploadGlobalMaxFiles,
+    globalQuotaBytes: environment.uploadGlobalQuotaBytes,
+    maxBytes: environment.uploadMaxBytes,
+    onError: (error) => console.error({ event: 'example_upload_cleanup_failed', error }),
+    quotaBytes: environment.uploadQuotaBytes,
+  })
+  void telemetry.start()
+  outbox.start()
+  uploadStore.startCleanup()
+  const application = { auth, database, email, environment, outbox, publisher, telemetry, uploadStore }
+  if (!process.env.VITEST) installShutdown(application)
+  return application
+}
+
+function prepareLegacyMessages(file: string) {
+  const client = openSqliteClient(file)
+  try {
+    if (!tableExists(client, 'messages')) return
+    const columns = client.pragma('table_info(messages)') as Array<{ name: string }>
+    if (columns.some((column) => column.name === 'author_id')) return
+    if (tableExists(client, 'messages_legacy')) throw new Error('Both messages and messages_legacy exist; refusing ambiguous migration')
+    client.exec('ALTER TABLE messages RENAME TO messages_legacy')
+  } finally {
+    client.close()
+  }
+}
+
+function importLegacyMessages(client: ReturnType<typeof openSqliteClient>) {
+  if (!tableExists(client, 'messages_legacy')) return
+  client.transaction(() => {
+    const now = Date.now()
+    client
+      .prepare('INSERT OR IGNORE INTO user (id, name, email, email_verified, created_at, updated_at) VALUES (?, ?, ?, false, ?, ?)')
+      .run('legacy-import', 'Legacy import', 'legacy-import@invalid.example', now, now)
+    client.exec(`INSERT INTO messages (id, author_id, author, body, created_at)
+      SELECT id, 'legacy-import', author, body, created_at FROM messages_legacy;
+      DROP TABLE messages_legacy;`)
+  })()
+}
+
+function tableExists(client: ReturnType<typeof openSqliteClient>, name: string) {
+  return Boolean(client.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name))
+}
+
+function migrationsDirectory() {
+  const directories = [
+    path.resolve(import.meta.dirname, 'drizzle'),
+    path.resolve(import.meta.dirname, '..', 'drizzle'),
+    path.resolve(process.cwd(), 'drizzle'),
+  ]
+  const directory = directories.find((candidate) => existsSync(path.join(candidate, 'meta', '_journal.json')))
+  if (!directory) throw new Error(`Drizzle migrations are missing from ${directories.join(', ')}`)
+  return directory
+}
+
+const closing = new WeakMap<object, Promise<void>>()
+
+export function closeApp(value = app()) {
+  const existing = closing.get(value)
+  if (existing) return existing
+  const promise = (async () => {
+    const failures: unknown[] = []
+    try {
+      await value.outbox.close()
+    } catch (error) {
+      failures.push(error)
+    }
+    for (const result of await Promise.allSettled([value.uploadStore.close(), value.publisher.close(), value.telemetry.shutdown()])) {
+      if (result.status === 'rejected') failures.push(result.reason)
+    }
+    try {
+      value.database.$client.close()
+    } catch (error) {
+      failures.push(error)
+    }
+    if (failures.length) throw new AggregateError(failures, 'Failed to close the full-stack example cleanly')
+  })()
+  closing.set(value, promise)
+  return promise
+}
+
+export { standardRateLimitOptions, standardSessionOptions }
+
+function installShutdown(application: ReturnType<typeof createApp>) {
+  let started = false
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+      if (started) return
+      started = true
+      void closeApp(application).then(
+        () => process.exit(0),
+        (error) => {
+          console.error({ event: 'example_shutdown_failed', error })
+          process.exit(1)
+        },
+      )
+    })
+  }
+}

package/examples/full-stack/src/server/auth-flow.test.ts

@@ -0,0 +1,148 @@
+import { createServer, type Server, type Socket } from 'node:net'
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { clearGlobalSingleton } from 'ras-stack/server'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { app, closeApp } from './app'
+import { currentUser } from './session'
+
+let directory: string
+let smtp: TestSmtp | undefined
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-auth-flow-'))
+  process.env.DATA_DIR = directory
+})
+
+afterEach(async () => {
+  await clearGlobalSingleton('ras-stack.example.full-stack', closeApp)
+  await smtp?.close()
+  smtp = undefined
+  await rm(directory, { recursive: true, force: true })
+  for (const name of ['APP_URL', 'SMTP_HOST', 'SMTP_PORT', 'EMAIL_FROM', 'EMAIL_REQUIRE_VERIFICATION']) delete process.env[name]
+})
+
+describe('production auth flows', () => {
+  it('verifies an email over SMTP and completes a password reset', async () => {
+    smtp = await TestSmtp.start()
+    process.env.APP_URL = 'http://localhost:3100'
+    process.env.SMTP_HOST = '127.0.0.1'
+    process.env.SMTP_PORT = String(smtp.port)
+    process.env.EMAIL_FROM = 'auth@example.test'
+    process.env.EMAIL_REQUIRE_VERIFICATION = 'true'
+
+    expect(
+      (
+        await authRequest('/sign-up/email', {
+          name: 'Ada',
+          email: 'ada@example.test',
+          password: 'correct horse battery staple',
+        })
+      ).status,
+    ).toBe(200)
+    expect((await authRequest('/sign-in/email', { email: 'ada@example.test', password: 'correct horse battery staple' })).status).toBe(403)
+
+    const verification = await app().auth.handler(new Request(messageUrl(smtp.messages[0]!)))
+    const cookie = verification.headers.get('set-cookie')
+    expect(cookie).toContain('ras_stack_example.session_token=')
+    expect((await currentUser(new Request('http://localhost:3100', { headers: { cookie: cookie! } })))?.email).toBe('ada@example.test')
+
+    expect((await authRequest('/request-password-reset', { email: 'ada@example.test', redirectTo: '/' })).status).toBe(200)
+    const resetLink = new URL(messageUrl(smtp.messages[1]!))
+    const token = resetLink.pathname.split('/').at(-1)
+    expect((await authRequest('/reset-password', { newPassword: 'new correct horse battery staple', token })).status).toBe(200)
+    expect((await authRequest('/sign-in/email', { email: 'ada@example.test', password: 'correct horse battery staple' })).status).toBe(401)
+    expect((await authRequest('/sign-in/email', { email: 'ada@example.test', password: 'new correct horse battery staple' })).status).toBe(
+      200,
+    )
+  })
+
+  it('marks session cookies Secure for an HTTPS origin', async () => {
+    process.env.APP_URL = 'https://example.test'
+    const response = await authRequest('/sign-up/email', {
+      name: 'Grace',
+      email: 'grace@example.test',
+      password: 'correct horse battery staple',
+    })
+    expect(response.headers.get('set-cookie')).toContain('; Secure')
+  })
+})
+
+function authRequest(endpoint: string, body: object) {
+  const origin = process.env.APP_URL!
+  return app().auth.handler(
+    new Request(`${origin}/api/auth${endpoint}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Origin: origin },
+      body: JSON.stringify(body),
+    }),
+  )
+}
+
+function messageUrl(message: string) {
+  const decoded = message
+    .replace(/=\r?\n/g, '')
+    .replace(/=([\dA-F]{2})/gi, (_, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)))
+  const match = decoded.match(/https?:\/\/[^\s]+/)
+  if (!match) throw new Error(`SMTP message contains no URL: ${decoded}`)
+  return match[0]
+}
+
+class TestSmtp {
+  private constructor(
+    private readonly server: Server,
+    readonly port: number,
+    readonly messages: string[],
+  ) {}
+
+  static async start() {
+    const messages: string[] = []
+    const server = createServer((socket) => acceptSmtp(socket, messages))
+    await new Promise<void>((resolve, reject) => server.listen(0, '127.0.0.1', resolve).once('error', reject))
+    const address = server.address()
+    if (!address || typeof address === 'string') throw new Error('SMTP sink did not bind a TCP port')
+    return new TestSmtp(server, address.port, messages)
+  }
+
+  close() {
+    return new Promise<void>((resolve, reject) => this.server.close((error) => (error ? reject(error) : resolve())))
+  }
+}
+
+function acceptSmtp(socket: Socket, messages: string[]) {
+  socket.setEncoding('utf8')
+  socket.write('220 localhost ESMTP\r\n')
+  let buffer = ''
+  let data = false
+  let message = ''
+  socket.on('data', (chunk: string) => {
+    buffer += chunk
+    while (buffer.includes('\n')) {
+      const index = buffer.indexOf('\n')
+      const line = buffer.slice(0, index).replace(/\r$/, '')
+      buffer = buffer.slice(index + 1)
+      if (data) {
+        if (line === '.') {
+          messages.push(message)
+          message = ''
+          data = false
+          socket.write('250 queued\r\n')
+        } else {
+          message += `${line.startsWith('..') ? line.slice(1) : line}\r\n`
+        }
+      } else if (/^(EHLO|HELO)/i.test(line)) {
+        socket.write('250-localhost\r\n250 PIPELINING\r\n')
+      } else if (/^(MAIL FROM|RCPT TO|RSET|NOOP)/i.test(line)) {
+        socket.write('250 ok\r\n')
+      } else if (/^DATA/i.test(line)) {
+        data = true
+        socket.write('354 end with .\r\n')
+      } else if (/^QUIT/i.test(line)) {
+        socket.end('221 bye\r\n')
+      } else {
+        socket.write('502 unsupported\r\n')
+      }
+    }
+  })
+}

package/examples/full-stack/src/server/auth.ts

@@ -0,0 +1,60 @@
+import { drizzleAdapter } from '@better-auth/drizzle-adapter'
+import { betterAuth } from 'better-auth'
+import { tanstackStartCookies } from 'better-auth/tanstack-start'
+import { standardRateLimitOptions, standardSessionOptions } from 'ras-stack/auth'
+import type { EmailDelivery } from 'ras-stack/email'
+import type { AppEnvironment } from './environment'
+import * as schema from './schema'
+
+type Database = Parameters<typeof drizzleAdapter>[0]
+
+export function createAuth(options: { database: Database; email?: EmailDelivery; environment: AppEnvironment; secret: string }) {
+  const email = options.email
+  const mail = email
+    ? {
+        emailVerification: {
+          sendOnSignUp: true,
+          autoSignInAfterVerification: true,
+          sendVerificationEmail: async ({ user, url }: { user: { email: string }; url: string }) => {
+            await email.send({
+              to: user.email,
+              subject: 'Verify your ras-stack example account',
+              text: `Verify your email: ${url}`,
+            })
+          },
+        },
+      }
+    : {}
+  return betterAuth({
+    appName: 'ras-stack full-stack example',
+    baseURL: options.environment.appUrl,
+    secret: options.secret,
+    trustedOrigins: [options.environment.appUrl],
+    database: drizzleAdapter(options.database, { provider: 'sqlite', schema }),
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: Boolean(email) && options.environment.requireEmailVerification,
+      revokeSessionsOnPasswordReset: true,
+      ...(email
+        ? {
+            sendResetPassword: async ({ user, url }: { user: { email: string }; url: string }) => {
+              await email.send({
+                to: user.email,
+                subject: 'Reset your ras-stack example password',
+                text: `Reset your password: ${url}`,
+              })
+            },
+          }
+        : {}),
+    },
+    ...mail,
+    session: standardSessionOptions(),
+    rateLimit: standardRateLimitOptions(),
+    advanced: {
+      cookiePrefix: 'ras_stack_example',
+      useSecureCookies: options.environment.appUrl.startsWith('https://'),
+      disableOriginCheck: false,
+    },
+    plugins: [tanstackStartCookies()],
+  })
+}

package/examples/full-stack/src/server/environment.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest'
+import { loadEnvironment } from './environment'
+
+describe('startup environment', () => {
+  it('requires production state and proxy secrets', () => {
+    expect(() => loadEnvironment({ NODE_ENV: 'production', APP_URL: 'https://example.test', DATA_DIR: 'relative' })).toThrow(
+      'DATA_DIR must be absolute in production',
+    )
+    expect(() =>
+      loadEnvironment({
+        NODE_ENV: 'production',
+        APP_URL: 'https://example.test',
+        DATA_DIR: '/data',
+        CENTRIFUGO_API_URL: 'https://realtime.example.test/api',
+        CENTRIFUGO_API_KEY: 'key',
+      }),
+    ).toThrow('CENTRIFUGO_PROXY_SECRET is required when realtime is enabled in production')
+  })
+
+  it('rejects ambiguous origins and partial realtime credentials', () => {
+    expect(() => loadEnvironment({ APP_URL: 'https://example.test/path' })).toThrow('APP_URL must be an HTTP origin')
+    expect(() => loadEnvironment({ CENTRIFUGO_API_URL: 'http://localhost/api' })).toThrow(
+      'CENTRIFUGO_API_URL and CENTRIFUGO_API_KEY must be configured together',
+    )
+  })
+
+  it.each([
+    ['UPLOAD_GLOBAL_QUOTA_BYTES', '0'],
+    ['UPLOAD_GLOBAL_MAX_FILES', '0'],
+  ])('rejects an invalid %s', (name, value) => {
+    expect(() => loadEnvironment({ [name]: value })).toThrow(`${name} must be a positive integer`)
+  })
+
+  it('requires the global byte cap to accept one maximum-size upload', () => {
+    expect(() => loadEnvironment({ UPLOAD_MAX_BYTES: '10', UPLOAD_GLOBAL_QUOTA_BYTES: '9' })).toThrow(
+      'UPLOAD_GLOBAL_QUOTA_BYTES must be at least UPLOAD_MAX_BYTES',
+    )
+  })
+
+  it('supports production startup with realtime disabled', () => {
+    expect(loadEnvironment({ NODE_ENV: 'production', APP_URL: 'https://example.test', DATA_DIR: '/data' }).realtimeEnabled).toBe(false)
+  })
+})

package/examples/full-stack/src/server/environment.ts

@@ -0,0 +1,67 @@
+import path from 'node:path'
+
+export type AppEnvironment = ReturnType<typeof loadEnvironment>
+
+export function loadEnvironment(environment: NodeJS.ProcessEnv = process.env) {
+  const production = environment.NODE_ENV === 'production'
+  const appUrl = validUrl(environment.APP_URL ?? (production ? '' : 'http://localhost:3100'), 'APP_URL')
+  const dataDirectory = path.resolve(environment.DATA_DIR ?? '.data/example-full-stack')
+  if (production && !path.isAbsolute(environment.DATA_DIR ?? '')) throw new Error('DATA_DIR must be absolute in production')
+  const trustProxy = booleanValue(environment.TRUST_PROXY, 'TRUST_PROXY', false)
+  const requireEmailVerification = booleanValue(environment.EMAIL_REQUIRE_VERIFICATION, 'EMAIL_REQUIRE_VERIFICATION', true)
+  const centrifugoApiUrl = environment.CENTRIFUGO_API_URL?.trim() ?? ''
+  const centrifugoApiKey = environment.CENTRIFUGO_API_KEY?.trim() ?? ''
+  if (Boolean(centrifugoApiUrl) !== Boolean(centrifugoApiKey)) {
+    throw new Error('CENTRIFUGO_API_URL and CENTRIFUGO_API_KEY must be configured together')
+  }
+  const realtimeEnabled = Boolean(centrifugoApiUrl)
+  if (production && realtimeEnabled && !environment.CENTRIFUGO_PROXY_SECRET?.trim()) {
+    throw new Error('CENTRIFUGO_PROXY_SECRET is required when realtime is enabled in production')
+  }
+  const uploadMaxBytes = positiveInteger(environment.UPLOAD_MAX_BYTES ?? '1000000', 'UPLOAD_MAX_BYTES')
+  const uploadQuotaBytes = positiveInteger(environment.UPLOAD_QUOTA_BYTES ?? '5000000', 'UPLOAD_QUOTA_BYTES')
+  const uploadGlobalQuotaBytes = positiveInteger(environment.UPLOAD_GLOBAL_QUOTA_BYTES ?? '100000000', 'UPLOAD_GLOBAL_QUOTA_BYTES')
+  const uploadGlobalMaxFiles = positiveInteger(environment.UPLOAD_GLOBAL_MAX_FILES ?? '1024', 'UPLOAD_GLOBAL_MAX_FILES')
+  if (uploadQuotaBytes < uploadMaxBytes) throw new Error('UPLOAD_QUOTA_BYTES must be at least UPLOAD_MAX_BYTES')
+  if (uploadGlobalQuotaBytes < uploadMaxBytes) throw new Error('UPLOAD_GLOBAL_QUOTA_BYTES must be at least UPLOAD_MAX_BYTES')
+  return {
+    appUrl,
+    centrifugoApiKey,
+    centrifugoApiUrl,
+    dataDirectory,
+    production,
+    realtimeEnabled,
+    requireEmailVerification,
+    trustProxy,
+    uploadGlobalMaxFiles,
+    uploadGlobalQuotaBytes,
+    uploadMaxBytes,
+    uploadQuotaBytes,
+  }
+}
+
+function validUrl(value: string, name: string) {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`${name} must be an absolute HTTP URL`)
+  }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new Error(`${name} must be an HTTP origin without credentials, path, query, or fragment`)
+  }
+  return url.origin
+}
+
+function booleanValue(value: string | undefined, name: string, fallback: boolean) {
+  if (value === undefined) return fallback
+  if (value === 'true') return true
+  if (value === 'false') return false
+  throw new Error(`${name} must be true or false`)
+}
+
+function positiveInteger(value: string, name: string) {
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`${name} must be a positive integer`)
+  return parsed
+}

package/examples/full-stack/src/server/fns.ts

@@ -0,0 +1,38 @@
+import { createServerFn } from '@tanstack/react-start'
+import { getRequest } from '@tanstack/react-start/server'
+import { desc } from 'drizzle-orm'
+import { z } from 'zod'
+import { app } from './app'
+import { writeMessage } from './messages'
+import { messages } from './schema'
+import { currentUser } from './session'
+import { mutationRpc, rpc } from './rpc'
+import { limitAuthenticatedRequest } from './rate-limit'
+
+export const snapshot = createServerFn({ method: 'GET' }).handler(() =>
+  rpc(async () => ({
+    user: await currentUser(),
+    messages: app().database.select().from(messages).orderBy(desc(messages.id)).limit(50).all(),
+    emailConfigured: Boolean(app().email),
+    realtimeEnabled: app().environment.realtimeEnabled,
+  })),
+)
+
+export const addMessage = createServerFn({ method: 'POST' })
+  .validator(z.object({ body: z.string().trim().min(1).max(280) }))
+  .handler(({ data }) =>
+    mutationRpc(async () => {
+      const request = getRequest()
+      const user = await currentUser(request)
+      if (!user) throw new Response('Sign in first', { status: 401 })
+      await limitAuthenticatedRequest(request, 'messages', user.id, { window: 60, max: 30 })
+      const now = new Date()
+      const application = app()
+      return writeMessage(application.database, application.environment.realtimeEnabled, {
+        authorId: user.id,
+        author: user.name,
+        body: data.body,
+        createdAt: now,
+      })
+    }),
+  )

package/examples/full-stack/src/server/messages.test.ts

@@ -0,0 +1,38 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { clearGlobalSingleton } from 'ras-stack/server'
+import { afterEach, beforeEach, expect, it } from 'vitest'
+import { app, closeApp } from './app'
+import { writeMessage } from './messages'
+import { outboxCapacity } from './outbox'
+import { messages, outbox, user } from './schema'
+
+let directory: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-messages-'))
+  process.env.DATA_DIR = directory
+  process.env.APP_URL = 'http://localhost:3100'
+  const now = new Date()
+  app().database.insert(user).values({ id: 'alice', name: 'Alice', email: 'alice@example.test', createdAt: now, updatedAt: now }).run()
+})
+
+afterEach(async () => {
+  await clearGlobalSingleton('ras-stack.example.full-stack', closeApp)
+  await rm(directory, { recursive: true, force: true })
+  delete process.env.DATA_DIR
+  delete process.env.APP_URL
+})
+
+it('writes without adding to a full outbox when realtime is disabled', () => {
+  const now = new Date()
+  app().database.transaction((transaction) => {
+    for (let index = 0; index < outboxCapacity; index += 1) {
+      transaction.insert(outbox).values({ channel: 'messages:all', payload: '{}', availableAt: now, createdAt: now }).run()
+    }
+  })
+  writeMessage(app().database, false, { authorId: 'alice', author: 'Alice', body: 'stored without realtime', createdAt: now })
+  expect(app().database.select().from(messages).all()).toHaveLength(1)
+  expect(app().database.select().from(outbox).all()).toHaveLength(outboxCapacity)
+})

package/examples/full-stack/src/server/messages.ts

@@ -0,0 +1,28 @@
+import type { app } from './app'
+import { assertOutboxCapacity } from './outbox'
+import { messages, outbox } from './schema'
+
+type Database = ReturnType<typeof app>['database']
+
+export function writeMessage(
+  database: Database,
+  realtimeEnabled: boolean,
+  values: { authorId: string; author: string; body: string; createdAt: Date },
+) {
+  return database.transaction((transaction) => {
+    if (realtimeEnabled) assertOutboxCapacity(transaction)
+    const [message] = transaction.insert(messages).values(values).returning().all()
+    if (realtimeEnabled) {
+      transaction
+        .insert(outbox)
+        .values({
+          channel: 'messages:all',
+          payload: JSON.stringify({ type: 'message-added', id: message!.id }),
+          availableAt: values.createdAt,
+          createdAt: values.createdAt,
+        })
+        .run()
+    }
+    return message!
+  })
+}

package/examples/full-stack/src/server/migration.test.ts

@@ -0,0 +1,34 @@
+import Database from 'better-sqlite3'
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { clearGlobalSingleton } from 'ras-stack/server'
+import { afterEach, expect, it } from 'vitest'
+import { app, closeApp } from './app'
+import { messages } from './schema'
+
+let directory: string | undefined
+
+afterEach(async () => {
+  await clearGlobalSingleton('ras-stack.example.full-stack', closeApp)
+  if (directory) await rm(directory, { recursive: true, force: true })
+  delete process.env.DATA_DIR
+  delete process.env.APP_URL
+})
+
+it('preserves rows from the pre-migration messages table', async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-legacy-'))
+  process.env.DATA_DIR = directory
+  process.env.APP_URL = 'http://localhost:3100'
+  const legacy = new Database(path.join(directory, 'example.sqlite'))
+  legacy.exec(`CREATE TABLE messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    author TEXT NOT NULL,
+    body TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+  ); INSERT INTO messages (author, body, created_at) VALUES ('Ada', 'legacy row', 1234);`)
+  legacy.close()
+  expect(app().database.select().from(messages).all()).toEqual([
+    { id: 1, authorId: 'legacy-import', author: 'Ada', body: 'legacy row', createdAt: new Date(1234) },
+  ])
+})