@igstack/app-catalog-backend-core 0.15.0 → 0.17.0

package/src/__tests__/dbSchemaAdapter.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Regression tests for preview-env schema isolation (#82).
+ *
+ * A `search_path` on the pool is not enough: Prisma 7 driver adapters qualify
+ * every table name with the schema the adapter reports, so a preview env whose
+ * adapter reports nothing reads and writes `public` no matter what the pool's
+ * `current_schema()` says. These tests pin the schema all the way to the
+ * `PrismaPg` constructor for every core call site.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const poolCtor = vi.fn()
+const adapterCtor = vi.fn()
+
+vi.mock('pg', () => ({
+  default: {
+    Pool: class {
+      constructor(config: unknown) {
+        poolCtor(config)
+      }
+    },
+  },
+}))
+
+vi.mock('@prisma/adapter-pg', () => ({
+  PrismaPg: class {
+    constructor(pool: unknown, options: unknown) {
+      adapterCtor(pool, options)
+    }
+  },
+}))
+
+vi.mock('../generated/prisma/client', () => ({
+  PrismaClient: class {
+    $connect = vi.fn()
+    $disconnect = vi.fn()
+  },
+}))
+
+const original = process.env.DB_SCHEMA
+const originalUrl = process.env.AC_CORE_DATABASE_URL
+
+beforeEach(() => {
+  vi.resetModules()
+  poolCtor.mockClear()
+  adapterCtor.mockClear()
+  process.env.DB_SCHEMA = 'preview_feat-my-branch'
+})
+
+afterEach(() => {
+  if (original === undefined) delete process.env.DB_SCHEMA
+  else process.env.DB_SCHEMA = original
+  if (originalUrl === undefined) delete process.env.AC_CORE_DATABASE_URL
+  else process.env.AC_CORE_DATABASE_URL = originalUrl
+})
+
+const adapterSchema = () => adapterCtor.mock.calls[0]?.[1]
+const poolOptions = () =>
+  (poolCtor.mock.calls[0]?.[0] as { options?: string } | undefined)?.options
+
+describe('preview-env schema reaches the Prisma adapter (#82)', () => {
+  it('getDbClient() passes DB_SCHEMA to the adapter, not just the pool', async () => {
+    process.env.AC_CORE_DATABASE_URL = 'postgresql://u:p@h:5432/db'
+    const { getDbClient } = await import('../db/client')
+
+    getDbClient()
+
+    expect(poolOptions()).toBe('-c search_path=preview_feat-my-branch')
+    expect(adapterSchema()).toEqual({ schema: 'preview_feat-my-branch' })
+  })
+
+  it('the middleware pool - the one the app uses - carries the schema too', async () => {
+    const { AcDatabaseManager } = await import('../middleware/database')
+
+    new AcDatabaseManager({
+      host: 'h',
+      port: 5432,
+      database: 'db',
+      username: 'u',
+      password: 'p',
+      schema: 'public',
+    }).getClient()
+
+    expect(poolOptions()).toBe('-c search_path=preview_feat-my-branch')
+    expect(adapterSchema()).toEqual({ schema: 'preview_feat-my-branch' })
+  })
+
+  it('the AI tools client reads the preview schema, not the shared catalog', async () => {
+    const { createAppCatalogAITools } =
+      await import('../modules/lighthouseKeeper/tools')
+
+    createAppCatalogAITools({
+      host: 'h',
+      port: 5432,
+      database: 'db',
+      username: 'u',
+      password: 'p',
+      schema: 'public',
+    })
+
+    expect(poolOptions()).toBe('-c search_path=preview_feat-my-branch')
+    expect(adapterSchema()).toEqual({ schema: 'preview_feat-my-branch' })
+  })
+
+  it('leaves the adapter schema unset when DB_SCHEMA is not configured', async () => {
+    delete process.env.DB_SCHEMA
+    process.env.AC_CORE_DATABASE_URL = 'postgresql://u:p@h:5432/db'
+    const { getDbClient } = await import('../db/client')
+
+    getDbClient()
+
+    expect(poolOptions()).toBeUndefined()
+    // Not toEqual({ schema: undefined }) - that also passes for {}, and an
+    // explicit undefined is what keeps the adapter on its own default.
+    expect(adapterSchema()).toHaveProperty('schema', undefined)
+    expect(adapterSchema()?.schema).toBeUndefined()
+  })
+})

package/src/__tests__/freshness.test.ts

@@ -9,55 +9,94 @@ const iso = (msFromNow: number) => new Date(NOW + msFromNow).toISOString()
 const DAY = 24 * 60 * 60 * 1000
 
 describe('computeFreshness', () => {
-  it('returns null date and not-stale when never checked', () => {
-    expect(computeFreshness(null, null, NOW)).toEqual({
+  it('returns null dates and not-stale when never checked', () => {
+    expect(computeFreshness({}, NOW)).toEqual({
       lastCheckedAt: null,
+      lastContentChangeAt: null,
       isStale: false,
     })
     // nextCheckAfter present but never checked → still nothing to show
-    expect(computeFreshness(null, iso(-30 * DAY), NOW)).toEqual({
+    expect(computeFreshness({ nextCheckAfter: iso(-30 * DAY) }, NOW)).toEqual({
       lastCheckedAt: null,
+      lastContentChangeAt: null,
       isStale: false,
     })
   })
 
   it('is fresh when the next check is still in the future', () => {
-    const r = computeFreshness(iso(-DAY), iso(DAY), NOW)
+    const r = computeFreshness(
+      { lastCheckedAt: iso(-DAY), nextCheckAfter: iso(DAY) },
+      NOW,
+    )
     expect(r.isStale).toBe(false)
     expect(r.lastCheckedAt).toBe(iso(-DAY))
   })
 
   it('is fresh when overdue but within the grace period', () => {
     // due 3 days ago, grace is 7 days → not stale yet
-    expect(computeFreshness(iso(-10 * DAY), iso(-3 * DAY), NOW).isStale).toBe(
-      false,
-    )
+    expect(
+      computeFreshness(
+        { lastCheckedAt: iso(-10 * DAY), nextCheckAfter: iso(-3 * DAY) },
+        NOW,
+      ).isStale,
+    ).toBe(false)
   })
 
   it('is stale once past due by more than the grace period', () => {
     // due 8 days ago > 7-day grace → stale
-    expect(computeFreshness(iso(-15 * DAY), iso(-8 * DAY), NOW).isStale).toBe(
-      true,
-    )
+    expect(
+      computeFreshness(
+        { lastCheckedAt: iso(-15 * DAY), nextCheckAfter: iso(-8 * DAY) },
+        NOW,
+      ).isStale,
+    ).toBe(true)
   })
 
   it('treats exactly-grace as not yet stale (strictly greater than)', () => {
-    const dueAt = iso(-0) // due now
-    // now - due === 0; push due back exactly grace → boundary is not stale
     const atBoundary = computeFreshness(
-      iso(-8 * DAY),
-      new Date(NOW - STALE_GRACE_MS).toISOString(),
+      {
+        lastCheckedAt: iso(-8 * DAY),
+        nextCheckAfter: new Date(NOW - STALE_GRACE_MS).toISOString(),
+      },
       NOW,
     )
     expect(atBoundary.isStale).toBe(false)
-    void dueAt
   })
 
   it('is not stale when nextCheckAfter is missing (cannot judge overdue)', () => {
-    expect(computeFreshness(iso(-100 * DAY), null, NOW).isStale).toBe(false)
+    expect(
+      computeFreshness({ lastCheckedAt: iso(-100 * DAY) }, NOW).isStale,
+    ).toBe(false)
   })
 
   it('ignores an unparseable nextCheckAfter', () => {
-    expect(computeFreshness(iso(-DAY), 'not-a-date', NOW).isStale).toBe(false)
+    expect(
+      computeFreshness(
+        { lastCheckedAt: iso(-DAY), nextCheckAfter: 'not-a-date' },
+        NOW,
+      ).isStale,
+    ).toBe(false)
+  })
+
+  it('passes through when the content last actually changed', () => {
+    // The UI shows this instead of lastCheckedAt: a source re-read 20 times
+    // without changing was still "Updated" 90 days ago.
+    const r = computeFreshness(
+      {
+        lastCheckedAt: iso(-DAY),
+        nextCheckAfter: iso(DAY),
+        lastContentChangeAt: iso(-90 * DAY),
+      },
+      NOW,
+    )
+    expect(r.lastContentChangeAt).toBe(iso(-90 * DAY))
+    expect(r.lastCheckedAt).toBe(iso(-DAY))
+  })
+
+  it('leaves lastContentChangeAt null for entries predating the field', () => {
+    // Older rows have no content-change timestamp; the frontend falls back to
+    // lastCheckedAt rather than showing nothing.
+    const r = computeFreshness({ lastCheckedAt: iso(-DAY) }, NOW)
+    expect(r.lastContentChangeAt).toBeNull()
   })
 })

package/src/__tests__/iconCache.test.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerIconRestController } from '../modules/icons/iconRestController'
+import * as dbClient from '../db/client'
+import type { PrismaClient } from '../generated/prisma/client'
+import type { Request, Response, Router } from 'express'
+
+const ICON = {
+  content: Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>'),
+  mimeType: 'image/svg+xml',
+  name: 'example-icon',
+  checksum: 'abc123',
+}
+
+/**
+ * Captures the `GET {basePath}/:name` handler the controller registers, so the
+ * test can drive it directly instead of standing up an HTTP server.
+ */
+const captureBinaryHandler = () => {
+  let handler!: (req: Request, res: Response) => Promise<void>
+  const router = {
+    get: (path: string, fn: (req: Request, res: Response) => Promise<void>) => {
+      if (path === '/api/icons/:name') handler = fn
+    },
+    post: () => {},
+  } as unknown as Router
+
+  registerIconRestController(router, { basePath: '/api/icons' })
+  return handler
+}
+
+const fakeRes = () => {
+  const headers: Record<string, string> = {}
+  const res = {
+    setHeader: (k: string, v: string) => {
+      headers[k] = v
+    },
+    status: vi.fn().mockReturnThis(),
+    json: vi.fn().mockReturnThis(),
+    send: vi.fn().mockReturnThis(),
+    end: vi.fn().mockReturnThis(),
+    sendStatus: vi.fn().mockReturnThis(),
+  }
+  return { res: res as unknown as Response, headers, spy: res }
+}
+
+describe('icon binary caching', () => {
+  beforeEach(() => {
+    vi.spyOn(dbClient, 'getDbClient').mockReturnValue({
+      dbAsset: { findFirst: vi.fn().mockResolvedValue(ICON) },
+    } as unknown as PrismaClient)
+  })
+
+  it('requires revalidation so a replaced icon is not masked by a stale cache', async () => {
+    const handler = captureBinaryHandler()
+    const { res, headers } = fakeRes()
+
+    await handler(
+      { params: { name: 'example-icon' }, headers: {} } as unknown as Request,
+      res,
+    )
+
+    expect(headers['Cache-Control']).toBe('public, max-age=0, must-revalidate')
+    expect(headers['ETag']).toBe(`"${ICON.checksum}"`)
+  })
+
+  it('answers a matching If-None-Match with 304 and no body', async () => {
+    const handler = captureBinaryHandler()
+    const { res, spy } = fakeRes()
+
+    await handler(
+      {
+        params: { name: 'example-icon' },
+        headers: { 'if-none-match': `"${ICON.checksum}"` },
+      } as unknown as Request,
+      res,
+    )
+
+    expect(spy.status).toHaveBeenCalledWith(304)
+    expect(spy.send).not.toHaveBeenCalled()
+  })
+})

package/src/db/client.ts

@@ -6,6 +6,120 @@ import { buildPgSslConfig } from './sslConfig'
 let prismaClient: PrismaClient | null = null
 let pool: pg.Pool | null = null
 
+type PrismaLogOption = NonNullable<
+  ConstructorParameters<typeof PrismaClient>[0]
+>['log']
+
+/**
+ * The schema a deployment should be reading and writing.
+ *
+ * DB_SCHEMA is set per deployment, so it outranks a schema baked into the app
+ * config - otherwise a config that names `public` would pin a preview env back
+ * to the shared tables it was meant to be isolated from.
+ */
+export function resolveDbSchema(configuredSchema?: string): string | undefined {
+  return process.env.DB_SCHEMA || configuredSchema || undefined
+}
+
+/**
+ * `search_path` startup options for a schema-isolated deployment.
+ *
+ * node-postgres ignores Prisma's `?schema=` URL parameter, so a preview env's
+ * schema has to be injected as a connection option instead. This half covers
+ * raw SQL and the migrations; Prisma's own queries need the adapter half too,
+ * which is why every core connection goes through createCorePrismaClient.
+ */
+export function buildPgSchemaOptions(configuredSchema?: string): {
+  options?: string
+} {
+  const schema = resolveDbSchema(configuredSchema)
+  return schema ? { options: `-c search_path=${schema}` } : {}
+}
+
+/**
+ * The one way to open a connection to the core database.
+ *
+ * Schema isolation takes two halves and both live here:
+ * - the pool's `search_path`, which raw SQL and the migrations follow;
+ * - the adapter's `schema`, which is what Prisma qualifies its table names
+ *   with. A client built without it emits `"public"."DbResource"` however
+ *   correct the pool's `current_schema()` is, so a preview env silently reads
+ *   and overwrites the shared canonical tables.
+ *
+ * A pool built outside this factory gets neither half, so don't build one.
+ */
+export function createCorePrismaClient(params: {
+  connectionString: string
+  configuredSchema?: string
+  log?: PrismaLogOption
+}): { client: PrismaClient; pool: pg.Pool; schema: string | undefined } {
+  const schema = resolveDbSchema(params.configuredSchema)
+  // SSL comes from PGSSLMODE/PGSSLROOTCERT via our helper (node-postgres
+  // doesn't honor those correctly for a connection-string pool - see
+  // buildPgSslConfig).
+  const ssl = buildPgSslConfig()
+  const newPool = new pg.Pool({
+    connectionString: params.connectionString,
+    ...(ssl === undefined ? {} : { ssl }),
+    ...buildPgSchemaOptions(params.configuredSchema),
+  })
+  const adapter = new PrismaPg(newPool, { schema })
+  const client = new PrismaClient({
+    adapter,
+    ...(params.log === undefined ? {} : { log: params.log }),
+  })
+  return { client, pool: newPool, schema }
+}
+
+/** Postgres NAMEDATALEN - 1: identifiers are truncated to this many bytes. */
+const PG_MAX_IDENTIFIER_BYTES = 63
+
+/**
+ * How Postgres will have stored an identifier this long.
+ *
+ * A schema name over the limit is truncated identically wherever it appears - at
+ * CREATE SCHEMA and in `search_path` alike - so the isolation still holds and
+ * current_schema() merely reports the shortened name. Comparing raw strings would
+ * fail a correctly isolated deployment, so compare what Postgres kept.
+ */
+function truncateIdentifier(name: string): string {
+  const bytes = Buffer.from(name, 'utf8')
+  if (bytes.length <= PG_MAX_IDENTIFIER_BYTES) return name
+  return bytes.subarray(0, PG_MAX_IDENTIFIER_BYTES).toString('utf8')
+}
+
+/**
+ * Fails a deployment that believes it is schema-isolated but is not.
+ *
+ * Speaks up whenever a schema was resolved at all - the same resolution feeds the
+ * pool's `search_path`, so the expectation and the connection can never disagree
+ * by construction, and a deployment that configures isolation without setting
+ * DB_SCHEMA is checked too. The case worth catching is a missing schema: Postgres
+ * silently skips a `search_path` entry that does not exist and falls through to
+ * `public`, which is the shared-catalog corruption this is here to prevent.
+ */
+export async function verifyDbSchema(
+  poolToCheck: pg.Pool,
+  configuredSchema?: string,
+): Promise<void> {
+  const resolved = resolveDbSchema(configuredSchema)
+  const result = await poolToCheck.query<{ schema: string | null }>(
+    'SELECT current_schema() AS schema',
+  )
+  const actual = result.rows[0]?.schema ?? null
+  console.log(
+    `[db] core schema: resolved=${resolved ?? '(none)'} current_schema=${actual ?? '(none)'}`,
+  )
+  if (!resolved) return
+  if (actual !== truncateIdentifier(resolved)) {
+    throw new Error(
+      `The configured schema is "${resolved}" but the database resolved current_schema() to ` +
+        `"${actual}". The schema is most likely missing, so every query would fall through to ` +
+        `the shared catalog tables. Migrate this schema before starting the app.`,
+    )
+  }
+}
+
 /**
  * Gets the internal Prisma client instance.
  * Creates one if it doesn't exist.
@@ -20,18 +134,9 @@ export function getDbClient(): PrismaClient {
       )
     }
 
-    // Prisma 7 with adapter: Create pg pool and wrap with adapter.
-    // SSL comes from PGSSLMODE/PGSSLROOTCERT via our helper (node-postgres
-    // doesn't honor those correctly for a connection-string pool — see
-    // buildPgSslConfig).
-    const ssl = buildPgSslConfig()
-    pool = new pg.Pool({
-      connectionString: databaseUrl,
-      ...(ssl === undefined ? {} : { ssl }),
-    })
-    const adapter = new PrismaPg(pool)
-
-    prismaClient = new PrismaClient({ adapter })
+    const created = createCorePrismaClient({ connectionString: databaseUrl })
+    pool = created.pool
+    prismaClient = created.client
   }
   return prismaClient
 }
@@ -51,6 +156,7 @@ export function setDbClient(client: PrismaClient): void {
 export async function connectDb(): Promise<void> {
   const client = getDbClient()
   await client.$connect()
+  if (pool) await verifyDbSchema(pool)
 }
 
 /**

package/src/db/index.ts

@@ -1,5 +1,14 @@
 // Database connection
-export { connectDb, disconnectDb, getDbClient, setDbClient } from './client'
+export {
+  buildPgSchemaOptions,
+  connectDb,
+  createCorePrismaClient,
+  disconnectDb,
+  getDbClient,
+  resolveDbSchema,
+  setDbClient,
+  verifyDbSchema,
+} from './client'
 export { buildPgSslConfig } from './sslConfig'
 
 // Table sync utilities

package/src/db/syncAppCatalog.ts

@@ -313,6 +313,9 @@ export async function syncAppCatalog(
         nextCheckAfter: resource.nextCheckAfter
           ? new Date(resource.nextCheckAfter)
           : null,
+        lastContentChangeAt: resource.lastContentChangeAt
+          ? new Date(resource.lastContentChangeAt)
+          : null,
       }
     })