ras-stack 0.39.5 → 0.40.0

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

@@ -0,0 +1,130 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { eq } from 'drizzle-orm'
+import { clearGlobalSingleton } from 'ras-stack/server'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { app, closeApp } from './app'
+import { assertOutboxCapacity, OutboxWorker, outboxCapacity, outboxStatus } from './outbox'
+import { outbox } from './schema'
+
+let directory: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-outbox-'))
+  process.env.DATA_DIR = directory
+  process.env.APP_URL = 'http://localhost:3100'
+})
+
+afterEach(async () => {
+  vi.useRealTimers()
+  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
+})
+
+describe('transactional outbox worker', () => {
+  it('retains a failed publication and deletes it only after delivery', async () => {
+    const now = new Date()
+    app()
+      .database.insert(outbox)
+      .values({ channel: 'messages:all', payload: JSON.stringify({ id: 1 }), availableAt: now, createdAt: now })
+      .run()
+    const publish = vi.fn().mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce(undefined)
+    const worker = new OutboxWorker({ database: app().database, enabled: false, publish, batchSize: 1 })
+    await worker.drain()
+    const retained = app().database.select().from(outbox).get()!
+    expect(retained.attempts).toBe(1)
+    app()
+      .database.update(outbox)
+      .set({ availableAt: new Date(0) })
+      .where(eq(outbox.id, retained.id))
+      .run()
+    await worker.drain()
+    expect(app().database.select().from(outbox).all()).toEqual([])
+  })
+
+  it('does not overtake the oldest item while it waits for retry', async () => {
+    const now = new Date()
+    app()
+      .database.insert(outbox)
+      .values([
+        { channel: 'messages:all', payload: JSON.stringify({ id: 1 }), availableAt: now, createdAt: now },
+        { channel: 'messages:all', payload: JSON.stringify({ id: 2 }), availableAt: now, createdAt: now },
+      ])
+      .run()
+    const publish = vi.fn().mockRejectedValueOnce(new Error('offline')).mockResolvedValue(undefined)
+    const worker = new OutboxWorker({ database: app().database, enabled: false, publish })
+    await worker.drain()
+    await worker.drain()
+    expect(publish).toHaveBeenCalledTimes(1)
+    app()
+      .database.update(outbox)
+      .set({ availableAt: new Date(0) })
+      .run()
+    await worker.drain()
+    expect(publish.mock.calls.map(([, payload]) => payload)).toEqual([{ id: 1 }, { id: 1 }, { id: 2 }])
+  })
+
+  it('dead-letters terminal failures and exposes degraded status', async () => {
+    const now = new Date()
+    app()
+      .database.insert(outbox)
+      .values({ channel: 'messages:all', payload: JSON.stringify({ id: 1 }), availableAt: now, createdAt: now })
+      .run()
+    const worker = new OutboxWorker({
+      database: app().database,
+      enabled: false,
+      publish: vi.fn().mockRejectedValue(new Error('offline')),
+      maxAttempts: 2,
+    })
+    await worker.drain()
+    app()
+      .database.update(outbox)
+      .set({ availableAt: new Date(0) })
+      .run()
+    await worker.drain()
+    expect(outboxStatus(app().database)).toEqual({ pending: 0, failed: 1 })
+  })
+
+  it('rejects new work when pending and dead-lettered items reach capacity', () => {
+    const now = new Date()
+    app().database.transaction((transaction) => {
+      for (let index = 0; index < outboxCapacity - 1; index += 1) {
+        transaction.insert(outbox).values({ channel: 'messages:all', payload: '{}', availableAt: now, createdAt: now }).run()
+      }
+      transaction.insert(outbox).values({ channel: 'messages:all', payload: '{}', availableAt: now, createdAt: now, failedAt: now }).run()
+    })
+    expect(capture(() => assertOutboxCapacity(app().database))).toMatchObject({ status: 503 })
+  })
+
+  it('reports a scheduled drain failure and keeps scheduling', async () => {
+    vi.useFakeTimers()
+    const onError = vi.fn()
+    const worker = new OutboxWorker({ database: app().database, enabled: true, publish: vi.fn(), intervalMs: 10, onError })
+    const drain = vi.spyOn(worker, 'drain').mockRejectedValueOnce(new Error('database unavailable')).mockResolvedValue()
+    worker.start()
+    await vi.advanceTimersByTimeAsync(10)
+    expect({ calls: drain.mock.calls.length, errors: onError.mock.calls }).toEqual({
+      calls: 2,
+      errors: [[expect.objectContaining({ message: 'database unavailable' })]],
+    })
+    await worker.close()
+  })
+
+  it('propagates the final drain failure during close', async () => {
+    const worker = new OutboxWorker({ database: app().database, enabled: true, publish: vi.fn() })
+    vi.spyOn(worker, 'drain').mockRejectedValue(new Error('database unavailable'))
+    await expect(worker.close()).rejects.toThrow('database unavailable')
+  })
+})
+
+function capture(operation: () => unknown) {
+  try {
+    operation()
+  } catch (error) {
+    return error
+  }
+  throw new Error('Expected operation to fail')
+}

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

@@ -0,0 +1,110 @@
+import { asc, eq, isNull, sql } from 'drizzle-orm'
+import type { app } from './app'
+import { outbox } from './schema'
+
+type Database = ReturnType<typeof app>['database']
+export const outboxCapacity = 1_000
+
+export class OutboxWorker {
+  private timer?: NodeJS.Timeout
+  private draining?: Promise<void>
+  private scheduled?: Promise<void>
+
+  constructor(
+    private readonly options: {
+      database: Database
+      enabled: boolean
+      publish: (channel: string, payload: unknown) => Promise<void>
+      intervalMs?: number
+      batchSize?: number
+      maxAttempts?: number
+      onError?: (error: unknown) => void
+    },
+  ) {}
+
+  start() {
+    if (!this.options.enabled || this.timer) return
+    this.timer = setInterval(() => this.scheduleDrain(), this.options.intervalMs ?? 500)
+    this.timer.unref()
+    this.scheduleDrain()
+  }
+
+  drain() {
+    if (this.draining) return this.draining
+    this.draining = this.drainBatch().finally(() => {
+      this.draining = undefined
+    })
+    return this.draining
+  }
+
+  async close() {
+    if (this.timer) clearInterval(this.timer)
+    this.timer = undefined
+    await this.draining
+    if (this.options.enabled) await this.drain()
+  }
+
+  private scheduleDrain() {
+    if (this.scheduled) return
+    const scheduled = this.drain()
+      .catch((error: unknown) => {
+        if (this.options.onError) this.options.onError(error)
+        else console.error({ event: 'example_outbox_drain_failed', error })
+      })
+      .finally(() => {
+        if (this.scheduled === scheduled) this.scheduled = undefined
+      })
+    this.scheduled = scheduled
+  }
+
+  private async drainBatch() {
+    const items = this.options.database
+      .select()
+      .from(outbox)
+      .where(isNull(outbox.failedAt))
+      .orderBy(asc(outbox.id))
+      .limit(this.options.batchSize ?? 20)
+      .all()
+    for (const item of items) {
+      if (item.availableAt.getTime() > Date.now()) break
+      try {
+        const payload: unknown = JSON.parse(item.payload)
+        // oxlint-disable-next-line no-await-in-loop
+        await this.options.publish(item.channel, payload)
+        this.options.database.delete(outbox).where(eq(outbox.id, item.id)).run()
+      } catch (error) {
+        const attempts = item.attempts + 1
+        const failed = attempts >= (this.options.maxAttempts ?? 8)
+        const delay = Math.min(60_000, 500 * 2 ** Math.min(attempts, 7))
+        this.options.database
+          .update(outbox)
+          .set({
+            attempts,
+            availableAt: new Date(Date.now() + delay),
+            failedAt: failed ? new Date() : null,
+            lastError: error instanceof Error ? error.message.slice(0, 500) : String(error).slice(0, 500),
+          })
+          .where(eq(outbox.id, item.id))
+          .run()
+        console.error({ event: 'example_outbox_delivery_failed', outboxId: item.id, attempts, error })
+        break
+      }
+    }
+  }
+}
+
+export function outboxStatus(database: Pick<Database, 'select'>): { pending: number; failed: number } {
+  const status = database
+    .select({
+      pending: sql<number>`coalesce(sum(case when ${outbox.failedAt} is null then 1 else 0 end), 0)`,
+      failed: sql<number>`coalesce(sum(case when ${outbox.failedAt} is not null then 1 else 0 end), 0)`,
+    })
+    .from(outbox)
+    .get()
+  return status ?? { pending: 0, failed: 0 }
+}
+
+export function assertOutboxCapacity(database: Pick<Database, 'select'>) {
+  const status = outboxStatus(database)
+  if (status.pending + status.failed >= outboxCapacity) throw new Response('Realtime queue is full', { status: 503 })
+}

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

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { postHogEnvironment, postHogRequestContext } from 'ras-stack/posthog'
+import { createManagedPostHogServerTelemetry, createPostHogServerClient } from 'ras-stack/posthog/server'
+import { postHogCoverage } from '../posthog'
+
+describe('PostHog integration boundary', () => {
+  it('stays disabled without deployment configuration', async () => {
+    expect(await createPostHogServerClient(postHogEnvironment({}))).toBeUndefined()
+    expect(postHogCoverage.browser.errorTracking).toBe(true)
+  })
+
+  it('propagates a browser session only with the authenticated identity', () => {
+    const request = new Request('https://example.test/action', {
+      headers: { 'x-posthog-distinct-id': 'person-123', 'x-posthog-session-id': 'session-456' },
+    })
+    expect(postHogRequestContext(request, { authenticatedDistinctId: 'person-123' })).toEqual({
+      distinctId: 'person-123',
+      sessionId: 'session-456',
+      properties: { $session_id: 'session-456' },
+    })
+  })
+
+  it('keeps the managed server lifecycle optional', async () => {
+    const telemetry = createManagedPostHogServerTelemetry({ environment: postHogEnvironment({}), serviceName: 'example' })
+    await telemetry.start()
+    await telemetry.log({ body: 'request completed', severityText: 'info' })
+    await telemetry.shutdown()
+    expect(postHogCoverage.server.logs).toBe(true)
+  })
+})

package/examples/full-stack/src/server/rate-limit.test.ts

@@ -0,0 +1,32 @@
+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 { closeApp } from './app'
+import { limitAuthenticatedRequest } from './rate-limit'
+
+let directory: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-rate-limit-'))
+  process.env.DATA_DIR = directory
+  process.env.APP_URL = 'http://localhost:3100'
+})
+
+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('keeps authenticated user budgets separate', async () => {
+  await limitAuthenticatedRequest(request(), 'messages', 'alice', { window: 60, max: 1 })
+  await expect(limitAuthenticatedRequest(request(), 'messages', 'alice', { window: 60, max: 1 })).rejects.toMatchObject({ status: 429 })
+  await expect(limitAuthenticatedRequest(request(), 'messages', 'bob', { window: 60, max: 1 })).resolves.toMatchObject({ remaining: 0 })
+})
+
+function request() {
+  return new Request('http://localhost:3100/messages')
+}

package/examples/full-stack/src/server/rate-limit.ts

@@ -0,0 +1,29 @@
+import { sqliteRateLimitStore } from 'ras-stack/database/sqlite'
+import { createRateLimit } from 'ras-stack/server'
+import type { RateLimitRule } from 'ras-stack/auth'
+import { app } from './app'
+
+const limiters = new WeakMap<object, Map<string, ReturnType<typeof createRateLimit>>>()
+const identities = new WeakMap<Request, string>()
+
+export function limitAuthenticatedRequest(request: Request, scope: string, userId: string, rule: RateLimitRule) {
+  const database = app().database
+  let databaseLimiters = limiters.get(database)
+  if (!databaseLimiters) {
+    databaseLimiters = new Map()
+    limiters.set(database, databaseLimiters)
+  }
+  let limiter = databaseLimiters.get(scope)
+  if (!limiter) {
+    limiter = createRateLimit({
+      store: sqliteRateLimitStore(database.$client, 'app_rate_limit'),
+      rule,
+      scope,
+      identify: (candidate) => identities.get(candidate),
+      onUnavailable: 'reject',
+    })
+    databaseLimiters.set(scope, limiter)
+  }
+  identities.set(request, userId)
+  return limiter(request).finally(() => identities.delete(request))
+}

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

@@ -0,0 +1,16 @@
+import { createTanStackRpc, requireTanStackMutationOrigin } from 'ras-stack/tanstack/server'
+import { createPostHogRpcLogger } from 'ras-stack/posthog/server'
+import { app } from './app'
+import { currentUser } from './session'
+
+const reportRpcError = createPostHogRpcLogger(app().telemetry, {
+  logError: (error, context) => console.error({ event: 'example_server_function_failed', ...context, error }),
+  resolveAuthenticatedDistinctId: async (request) => (await currentUser(request))?.id,
+  allowAnonymousDistinctId: true,
+})
+
+export const { rpc, mutationRpc } = createTanStackRpc({
+  requireMutation: (request) =>
+    requireTanStackMutationOrigin({ configured: [app().environment.appUrl], trustForwardedHeaders: app().environment.trustProxy }, request),
+  logError: reportRpcError,
+})

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

@@ -0,0 +1,134 @@
+import { index, integer, sqliteTable, text, uniqueIndex } from 'drizzle-orm/sqlite-core'
+
+const timestamps = {
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+}
+
+export const user = sqliteTable(
+  'user',
+  {
+    id: text().primaryKey(),
+    name: text().notNull(),
+    email: text().notNull(),
+    emailVerified: integer('email_verified', { mode: 'boolean' }).notNull().default(false),
+    image: text(),
+    ...timestamps,
+  },
+  (table) => [uniqueIndex('user_email_unique').on(table.email)],
+)
+
+export const session = sqliteTable(
+  'session',
+  {
+    id: text().primaryKey(),
+    expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+    token: text().notNull(),
+    ...timestamps,
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+  },
+  (table) => [uniqueIndex('session_token_unique').on(table.token), index('session_user_id_idx').on(table.userId)],
+)
+
+export const account = sqliteTable(
+  'account',
+  {
+    id: text().primaryKey(),
+    accountId: text('account_id').notNull(),
+    issuer: text().notNull(),
+    providerId: text('provider_id').notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    accessToken: text('access_token'),
+    refreshToken: text('refresh_token'),
+    idToken: text('id_token'),
+    accessTokenExpiresAt: integer('access_token_expires_at', { mode: 'timestamp_ms' }),
+    refreshTokenExpiresAt: integer('refresh_token_expires_at', { mode: 'timestamp_ms' }),
+    scope: text(),
+    password: text(),
+    ...timestamps,
+  },
+  (table) => [
+    index('account_user_id_idx').on(table.userId),
+    uniqueIndex('account_issuer_account_id_unique').on(table.issuer, table.accountId),
+  ],
+)
+
+export const verification = sqliteTable(
+  'verification',
+  {
+    id: text().primaryKey(),
+    identifier: text().notNull(),
+    value: text().notNull(),
+    expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+    ...timestamps,
+  },
+  (table) => [index('verification_identifier_idx').on(table.identifier)],
+)
+
+export const rateLimit = sqliteTable(
+  'rate_limit',
+  {
+    id: text().primaryKey(),
+    key: text().notNull(),
+    count: integer().notNull(),
+    lastRequest: integer('last_request').notNull(),
+  },
+  (table) => [uniqueIndex('rate_limit_key_unique').on(table.key)],
+)
+
+export const messages = sqliteTable(
+  'messages',
+  {
+    id: integer().primaryKey({ autoIncrement: true }),
+    authorId: text('author_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    author: text().notNull(),
+    body: text().notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  },
+  (table) => [index('messages_author_id_idx').on(table.authorId)],
+)
+
+export const uploads = sqliteTable(
+  'uploads',
+  {
+    id: text().primaryKey(),
+    ownerId: text('owner_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    filename: text().notNull(),
+    mediaType: text('media_type').notNull(),
+    length: integer().notNull(),
+    offset: integer().notNull().default(0),
+    state: text({ enum: ['active', 'complete'] })
+      .notNull()
+      .default('active'),
+    createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+    updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+  },
+  (table) => [index('uploads_owner_id_state_idx').on(table.ownerId, table.state)],
+)
+
+export const outbox = sqliteTable(
+  'outbox',
+  {
+    id: integer().primaryKey({ autoIncrement: true }),
+    channel: text().notNull(),
+    payload: text().notNull(),
+    attempts: integer().notNull().default(0),
+    availableAt: integer('available_at', { mode: 'timestamp_ms' }).notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+    failedAt: integer('failed_at', { mode: 'timestamp_ms' }),
+    lastError: text('last_error'),
+  },
+  (table) => [index('outbox_available_at_idx').on(table.availableAt, table.id)],
+)
+
+export type Message = typeof messages.$inferSelect

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

@@ -0,0 +1,56 @@
+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
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-auth-'))
+  process.env.DATA_DIR = directory
+  process.env.APP_URL = 'http://localhost:3100'
+})
+
+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
+})
+
+describe('Better Auth integration', () => {
+  it('creates a database-backed user and session', async () => {
+    const response = await authRequest('/sign-up/email', {
+      name: 'Ada',
+      email: 'ada@example.test',
+      password: 'correct horse battery staple',
+    })
+    expect(response.status).toBe(200)
+    const cookie = response.headers.get('set-cookie')
+    expect(cookie).toContain('ras_stack_example.session_token=')
+    const request = new Request('http://localhost:3100', { headers: { cookie: cookie! } })
+    expect((await currentUser(request))?.email).toBe('ada@example.test')
+  })
+
+  it('rejects a cross-origin sign-up', async () => {
+    const response = await authRequest(
+      '/sign-up/email',
+      { name: 'Mallory', email: 'mallory@example.test', password: 'correct horse battery staple' },
+      'https://attacker.example',
+    )
+    expect(response.status).toBe(403)
+  })
+})
+
+function authRequest(endpoint: string, body: object, origin = 'http://localhost:3100') {
+  return app().auth.handler(
+    new Request(`http://localhost:3100/api/auth${endpoint}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Origin: origin },
+      body: JSON.stringify(body),
+    }),
+  )
+}

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

@@ -0,0 +1,13 @@
+import { getRequest } from '@tanstack/react-start/server'
+import { app } from './app'
+
+export async function currentUser(request = getRequest()) {
+  const session = await app().auth.api.getSession({ headers: request.headers })
+  return session?.user
+}
+
+export async function requireCurrentUser(request: Request) {
+  const user = await currentUser(request)
+  if (!user) throw new Response('Sign in first', { status: 401 })
+  return user
+}