ras-stack 0.39.4 → 0.40.0

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

@@ -0,0 +1,142 @@
+import { mkdtemp, readdir, rm, stat } 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 { uploads, user } from './schema'
+import { UploadStore } from './uploads'
+
+let directory: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-upload-'))
+  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 },
+      { id: 'bob', name: 'Bob', email: 'bob@example.test', createdAt: now, updatedAt: now },
+    ])
+    .run()
+})
+
+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('durable upload store', () => {
+  it('persists completed content and metadata', async () => {
+    const id = app().uploadStore.create('alice', 5, metadata('proof.txt', 'text/plain'))
+    const upload = await app().uploadStore.append(id, 'alice', 0, new TextEncoder().encode('proof'))
+    expect({ filename: upload.filename, offset: upload.offset, state: upload.state }).toEqual({
+      filename: 'proof.txt',
+      offset: 5,
+      state: 'complete',
+    })
+    expect((await stat(path.join(directory, 'uploads', `${id}.bin`))).size).toBe(5)
+  })
+
+  it('continues after a rejected chunk without retaining a poisoned queue', async () => {
+    const id = app().uploadStore.create('alice', 5, metadata('proof.txt', 'text/plain'))
+    await expect(app().uploadStore.append(id, 'alice', 1, new TextEncoder().encode('wrong'))).rejects.toMatchObject({ status: 409 })
+    await expect(app().uploadStore.append(id, 'alice', 0, new TextEncoder().encode('proof'))).resolves.toMatchObject({
+      offset: 5,
+      state: 'complete',
+    })
+  })
+
+  it('does not reveal another user upload', () => {
+    const id = app().uploadStore.create('alice', 5, metadata('proof.txt', 'text/plain'))
+    expect(app().uploadStore.getOwned(id, 'bob')).toBeUndefined()
+  })
+
+  it('rejects unsafe metadata and quota overflow', () => {
+    expect(capture(() => app().uploadStore.create('alice', 5, metadata('../proof.txt', 'text/plain')))).toMatchObject({ status: 400 })
+    expect(capture(() => app().uploadStore.create('alice', 5, 'filename YWJj!,filetype dGV4dC9wbGFpbg=='))).toMatchObject({
+      status: 400,
+    })
+    for (let index = 0; index < 5; index += 1) app().uploadStore.create('alice', 1_000_000, metadata(`proof-${index}.txt`, 'text/plain'))
+    expect(capture(() => app().uploadStore.create('alice', 1, metadata('overflow.txt', 'text/plain')))).toMatchObject({ status: 413 })
+  })
+
+  it('removes content when metadata persistence fails', async () => {
+    expect(capture(() => app().uploadStore.create('missing-user', 5, metadata('proof.txt', 'text/plain')))).toBeInstanceOf(Error)
+    expect(await readdir(path.join(directory, 'uploads'))).toEqual([])
+  })
+
+  it('enforces the deployment byte cap across users', () => {
+    const store = deploymentStore({ globalQuotaBytes: 6 })
+    store.create('alice', 5, metadata('alice.txt', 'text/plain'))
+    expect(capture(() => store.create('bob', 2, metadata('bob.txt', 'text/plain')))).toMatchObject({ status: 507 })
+  })
+
+  it('enforces the deployment file cap across users', () => {
+    const store = deploymentStore({ globalMaxFiles: 1 })
+    store.create('alice', 1, metadata('alice.txt', 'text/plain'))
+    expect(capture(() => store.create('bob', 1, metadata('bob.txt', 'text/plain')))).toMatchObject({ status: 507 })
+  })
+
+  it('periodically removes uploads abandoned after startup', async () => {
+    await app().uploadStore.close()
+    vi.useFakeTimers()
+    app().uploadStore.startCleanup(10)
+    const id = app().uploadStore.create('alice', 5, metadata('stale.txt', 'text/plain'))
+    app()
+      .database.update(uploads)
+      .set({ updatedAt: new Date(0) })
+      .where(eq(uploads.id, id))
+      .run()
+    await vi.advanceTimersByTimeAsync(10)
+    await expect(stat(path.join(directory, 'uploads', `${id}.bin`))).rejects.toMatchObject({ code: 'ENOENT' })
+    vi.useRealTimers()
+  })
+
+  it('reports a scheduled cleanup failure and continues scheduling', async () => {
+    vi.useFakeTimers()
+    const onError = vi.fn()
+    const store = deploymentStore({ onError })
+    const cleanup = vi.spyOn(store, 'cleanupStale').mockImplementationOnce(() => {
+      throw new Error('database unavailable')
+    })
+    store.startCleanup(10)
+    await vi.advanceTimersByTimeAsync(10)
+    expect({ calls: cleanup.mock.calls.length, errors: onError.mock.calls }).toEqual({
+      calls: 2,
+      errors: [[expect.objectContaining({ message: 'database unavailable' })]],
+    })
+    await store.close()
+  })
+})
+
+function deploymentStore(overrides: Partial<ConstructorParameters<typeof UploadStore>[0]> = {}) {
+  return new UploadStore({
+    database: app().database,
+    directory: path.join(directory, 'deployment-uploads'),
+    maxBytes: 5,
+    quotaBytes: 5,
+    globalQuotaBytes: 100,
+    globalMaxFiles: 100,
+    ...overrides,
+  })
+}
+
+function metadata(filename: string, filetype: string) {
+  return `filename ${Buffer.from(filename).toString('base64')},filetype ${Buffer.from(filetype).toString('base64')}`
+}
+
+function capture(operation: () => unknown) {
+  try {
+    operation()
+  } catch (error) {
+    return error
+  }
+  throw new Error('Expected operation to fail')
+}

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

@@ -0,0 +1,199 @@
+import { and, eq, lt, sql } from 'drizzle-orm'
+import { appendFileSync, mkdirSync, rmSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { randomId } from 'ras-stack/auth'
+import type { app } from './app'
+import { uploads } from './schema'
+
+type Database = ReturnType<typeof app>['database']
+type Upload = typeof uploads.$inferSelect
+
+export class UploadStore {
+  private readonly locks = new Map<string, Promise<void>>()
+  private cleanupTimer?: NodeJS.Timeout
+
+  constructor(
+    private readonly options: {
+      database: Database
+      directory: string
+      maxBytes: number
+      quotaBytes: number
+      globalQuotaBytes: number
+      globalMaxFiles: number
+      onError?: (error: unknown) => void
+    },
+  ) {
+    mkdirSync(options.directory, { recursive: true })
+  }
+
+  create(ownerId: string, length: number, metadataHeader: string | null) {
+    if (!Number.isSafeInteger(length) || length < 1 || length > this.options.maxBytes) {
+      throw new Response('Invalid upload length', { status: 400 })
+    }
+    const metadata = parseMetadata(metadataHeader)
+    const id = randomId()
+    const now = new Date()
+    let fileCreated = false
+    try {
+      return this.options.database.transaction(
+        (transaction) => {
+          const { count, bytes } = transaction
+            .select({ count: sql<number>`count(*)`, bytes: sql<number>`coalesce(sum(${uploads.length}), 0)` })
+            .from(uploads)
+            .where(eq(uploads.ownerId, ownerId))
+            .get() ?? { count: 0, bytes: 0 }
+          if (count >= 32) throw new Response('Too many uploads', { status: 429 })
+          if (bytes + length > this.options.quotaBytes) throw new Response('Upload quota exceeded', { status: 413 })
+          const global = transaction
+            .select({ count: sql<number>`count(*)`, bytes: sql<number>`coalesce(sum(${uploads.length}), 0)` })
+            .from(uploads)
+            .get() ?? { count: 0, bytes: 0 }
+          if (global.count >= this.options.globalMaxFiles || global.bytes + length > this.options.globalQuotaBytes) {
+            throw new Response('Deployment upload storage limit reached', { status: 507 })
+          }
+          appendFileSync(this.file(id), new Uint8Array(), { flag: 'wx' })
+          fileCreated = true
+          transaction
+            .insert(uploads)
+            .values({
+              id,
+              ownerId,
+              filename: metadata.filename,
+              mediaType: metadata.mediaType,
+              length,
+              offset: 0,
+              state: 'active',
+              createdAt: now,
+              updatedAt: now,
+            })
+            .run()
+          return id
+        },
+        { behavior: 'immediate' },
+      )
+    } catch (error) {
+      if (fileCreated) {
+        try {
+          rmSync(this.file(id), { force: true })
+        } catch (cleanupError) {
+          const failure = new AggregateError([error, cleanupError], 'Upload metadata failed and empty-file cleanup was incomplete')
+          failure.cause = error
+          throw failure
+        }
+      }
+      throw error
+    }
+  }
+
+  getOwned(id: string, ownerId: string) {
+    const upload = this.options.database
+      .select()
+      .from(uploads)
+      .where(and(eq(uploads.id, id), eq(uploads.ownerId, ownerId)))
+      .get()
+    if (!upload) return undefined
+    return this.reconcile(upload)
+  }
+
+  append(id: string, ownerId: string, expectedOffset: number, chunk: Uint8Array) {
+    const previous = this.locks.get(id) ?? Promise.resolve()
+    const running = previous.catch(() => undefined).then(() => this.appendUnlocked(id, ownerId, expectedOffset, chunk))
+    const stored = running.then(
+      () => undefined,
+      () => undefined,
+    )
+    this.locks.set(id, stored)
+    void stored.finally(() => {
+      if (this.locks.get(id) === stored) this.locks.delete(id)
+    })
+    return running
+  }
+
+  startCleanup(intervalMs = 60 * 60 * 1_000) {
+    if (this.cleanupTimer) return
+    this.runScheduledCleanup()
+    this.cleanupTimer = setInterval(() => this.runScheduledCleanup(), intervalMs)
+    this.cleanupTimer.unref()
+  }
+
+  async close() {
+    if (this.cleanupTimer) clearInterval(this.cleanupTimer)
+    this.cleanupTimer = undefined
+    await Promise.all(this.locks.values())
+  }
+
+  cleanupStale(now = new Date(), maxAgeMs = 24 * 60 * 60 * 1_000) {
+    const stale = this.options.database
+      .select({ id: uploads.id })
+      .from(uploads)
+      .where(and(eq(uploads.state, 'active'), lt(uploads.updatedAt, new Date(now.getTime() - maxAgeMs))))
+      .limit(100)
+      .all()
+    for (const { id } of stale) {
+      rmSync(this.file(id), { force: true })
+      this.options.database.delete(uploads).where(eq(uploads.id, id)).run()
+    }
+    return stale.length
+  }
+
+  private appendUnlocked(id: string, ownerId: string, expectedOffset: number, chunk: Uint8Array) {
+    const upload = this.getOwned(id, ownerId)
+    if (!upload) throw new Response('Upload not found', { status: 404 })
+    if (upload.state !== 'active') throw new Response('Upload is complete', { status: 409 })
+    if (expectedOffset !== upload.offset) throw new Response('Upload offset conflict', { status: 409 })
+    if (chunk.length < 1 || upload.offset + chunk.length > upload.length) throw new Response('Invalid upload chunk', { status: 413 })
+    appendFileSync(this.file(id), chunk)
+    const offset = upload.offset + chunk.length
+    const state = offset === upload.length ? 'complete' : 'active'
+    this.options.database.update(uploads).set({ offset, state, updatedAt: new Date() }).where(eq(uploads.id, id)).run()
+    return { ...upload, offset, state } satisfies Upload
+  }
+
+  private runScheduledCleanup() {
+    try {
+      this.cleanupStale()
+    } catch (error) {
+      if (this.options.onError) this.options.onError(error)
+      else console.error({ event: 'example_upload_cleanup_failed', error })
+    }
+  }
+
+  private reconcile(upload: Upload) {
+    const size = statSync(this.file(upload.id)).size
+    if (size > upload.length) throw new Error(`Upload ${upload.id} exceeds its declared length`)
+    if (size === upload.offset) return upload
+    const state = size === upload.length ? 'complete' : 'active'
+    this.options.database.update(uploads).set({ offset: size, state, updatedAt: new Date() }).where(eq(uploads.id, upload.id)).run()
+    return { ...upload, offset: size, state } satisfies Upload
+  }
+
+  private file(id: string) {
+    return path.join(this.options.directory, `${id}.bin`)
+  }
+}
+
+function parseMetadata(header: string | null) {
+  if (!header || header.length > 2_048) throw new Response('Upload metadata is required', { status: 400 })
+  const values = new Map<string, string>()
+  for (const item of header.split(',')) {
+    const [key, encoded, extra] = item.trim().split(' ')
+    if (!key || !encoded || extra || values.has(key)) throw new Response('Invalid upload metadata', { status: 400 })
+    let value: string
+    try {
+      const decoded = Buffer.from(encoded, 'base64')
+      if (decoded.toString('base64') !== encoded) throw new Error('Non-canonical base64')
+      value = new TextDecoder('utf-8', { fatal: true }).decode(decoded)
+    } catch {
+      throw new Response('Invalid upload metadata', { status: 400 })
+    }
+    values.set(key, value)
+  }
+  const filename = values.get('filename')?.trim() ?? ''
+  const mediaType = values.get('filetype')?.trim() || 'application/octet-stream'
+  const hasControlCharacter = filename.split('').some((character) => character.charCodeAt(0) < 32)
+  if (!filename || filename.length > 120 || path.basename(filename) !== filename || hasControlCharacter) {
+    throw new Response('Invalid filename', { status: 400 })
+  }
+  if (mediaType !== 'text/plain') throw new Response('Only text files are accepted', { status: 415 })
+  return { filename, mediaType }
+}

package/examples/full-stack/src/start.ts

@@ -0,0 +1,12 @@
+import { createStart } from '@tanstack/react-start'
+import { canonicalHostMiddleware } from 'ras-stack/tanstack/middleware'
+
+// The Centrifugo connect proxy is deliberately absent from this set: it calls in over the loopback interface,
+// which canonicalRedirect leaves alone. Listing it here would hide a regression in that behaviour from the
+// end-to-end run, which exercises a real Centrifugo against a real container.
+const canonicalHost = canonicalHostMiddleware(() => ({
+  canonicalUrl: process.env.APP_URL,
+  pathsServedOnAnyHost: new Set(['/api/live', '/api/ready', '/api/health']),
+}))
+
+export const startInstance = createStart(() => ({ requestMiddleware: [canonicalHost] }))

package/examples/full-stack/src/styles.css

@@ -0,0 +1,42 @@
+:root {
+  font-family: ui-sans-serif, system-ui, sans-serif;
+  color: #172033;
+  background: #f4f7fb;
+}
+body {
+  margin: 0;
+}
+main {
+  width: min(42rem, calc(100% - 2rem));
+  margin: 3rem auto;
+}
+section,
+form {
+  padding: 1rem;
+  margin-block: 1rem;
+  border: 1px solid #cad3e0;
+  border-radius: 0.75rem;
+  background: white;
+}
+label {
+  display: grid;
+  gap: 0.35rem;
+  margin-block: 0.75rem;
+}
+input,
+button {
+  font: inherit;
+  padding: 0.6rem 0.75rem;
+}
+button {
+  cursor: pointer;
+}
+ul {
+  padding-left: 1.25rem;
+}
+.status {
+  color: #526174;
+}
+.error {
+  color: #a11;
+}

package/examples/full-stack/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "ras-stack/config/typescript/tanstack",
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"] },
+    "types": ["node", "vite/client", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "scripts/**/*.ts", "vite.config.ts", "vitest.config.ts"]
+}

package/examples/full-stack/vite.config.ts

@@ -0,0 +1,31 @@
+import path from 'node:path'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+import { nitro } from 'nitro/vite'
+import { defineConfig, loadEnv } from 'vite'
+import { postHogEnvironment } from 'ras-stack/posthog'
+import { postHogIngestProxy } from 'ras-stack/posthog/proxy'
+
+export default defineConfig(({ mode }) => {
+  const values = loadEnv(mode, process.cwd(), '')
+  const posthog = postHogEnvironment({ projectToken: values.VITE_POSTHOG_PROJECT_TOKEN, host: values.VITE_POSTHOG_HOST })
+  const proxy = posthog ? postHogIngestProxy(posthog) : undefined
+  const securityHeaders = {
+    'Content-Security-Policy':
+      "default-src 'self'; connect-src 'self' ws: wss:; img-src 'self' data:; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'",
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+  }
+  return {
+    resolve: { alias: { '@': path.resolve(import.meta.dirname, 'src') } },
+    server: { port: 3100, proxy: { '/connection': { target: 'ws://localhost:8100', ws: true }, ...proxy?.vite } },
+    build: {
+      rollupOptions: {
+        output: { codeSplitting: { groups: [{ name: 'posthog', test: /node_modules[\\/]posthog-js/ }] } },
+      },
+    },
+    plugins: [tanstackStart(), nitro({ routeRules: { '/**': { headers: securityHeaders }, ...proxy?.nitro } }), viteReact()],
+  }
+})

package/examples/full-stack/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({ test: { environment: 'node', include: ['src/**/*.test.ts', 'scripts/**/*.test.ts'] } })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.39.4",
+  "version": "0.40.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -21,7 +21,8 @@
   },
   "files": [
     "dist",
-    "config"
+    "config",
+    "examples/full-stack"
   ],
   "type": "module",
   "sideEffects": false,
@@ -152,6 +153,7 @@
     "format:check": "oxfmt --check .",
     "test": "vitest run --config vitest.config.ts",
     "package:check": "node scripts/checkPackedPackage.mjs",
+    "peer:floor": "node scripts/checkPeerFloor.mjs",
     "check": "pnpm format:check && pnpm lint && pnpm config:check && pnpm typecheck && pnpm test && pnpm build && pnpm package:check && pnpm --filter @ras-stack/example-full-stack check && node dist/cli.js policy check",
     "version-packages": "changeset version"
   },
@@ -171,16 +173,16 @@
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-start": "^1.168.32",
     "@types/better-sqlite3": "9.6.0",
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.2.0",
     "@types/nodemailer": "^8.0.1",
     "@types/react": "19.2.18",
     "@types/react-test-renderer": "19.1.0",
     "@vitest/coverage-v8": "^4.1.10",
-    "better-sqlite3": "13.0.2",
+    "better-sqlite3": "12.11.1",
     "centrifuge": "5.7.0",
     "drizzle-orm": "0.45.2",
     "nodemailer": "^9.0.3",
-    "oxfmt": "^0.61.0",
+    "oxfmt": "^0.62.0",
     "oxlint": "^1.74.0",
     "oxlint-tsgolint": "^7.0.2001",
     "postgres": "3.4.9",
@@ -198,9 +200,9 @@
     "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
     "@opentelemetry/resources": "^2.10.0",
     "@opentelemetry/sdk-logs": "^0.221.0",
-    "@posthog/react": ">=1 <2",
-    "@tanstack/react-query": ">=5 <6",
-    "@tanstack/react-start": ">=1 <2",
+    "@posthog/react": ">=1.1 <2",
+    "@tanstack/react-query": ">=5.62.8 <6",
+    "@tanstack/react-start": ">=1.168.10 <2",
     "better-sqlite3": ">=12 <14",
     "centrifuge": ">=5 <6",
     "drizzle-orm": ">=0.45 <1",