cache-invalidation.integration.test.ts

cache-invalidation.integration.test.tstests/integration/cache-invalidation.integration.test.tsraw ← integration16,121 B← Back to the app
1/**
2 * TASK-0135 — LIVE cache-invalidation integration suite (the concurrent-write
3 * race + event-bust freshness the unit suite cannot exercise without Redis).
4 *
5 * Boots the real NestJS API against Testcontainers Postgres + Redis (the
6 * production wiring, PERF_CACHE=on) and, through the public v1 API, asserts
7 * the EXACT invalidation semantics from docs/development/perf-report.md:
8 *
9 *  1. page tree (version-key):
10 *       - a repeated read is served from the cache (the tree:…:{version} key
11 *         appears in Redis — a live HIT, not a pass-through);
12 *       - a write (block create) bumps the workspace content version → the
13 *         NEXT read is fresh and a NEW version key is written (no stale read);
14 *       - CONCURRENT writers (5 parallel block creates) never leave a stale
15 *         tree: every interleaved read returns exactly the blocks that exist
16 *         in PG at that instant (the version-key invariant, live).
17 *  2. permission decisions (TTL 60 s + bust):
18 *       - a grant change (member added) is reflected on the NEXT decision
19 *         (the subject's cache prefix is busted → fresh), not after the TTL.
20 *  3. database column metadata (TTL 60 s + bust on database.updated):
21 *       - a property create busts the metadata → the next listProperties is
22 *         fresh (the new property appears), not the cached pre-create list.
23 *
24 * The cache is FORCED ON for this spec (`PERF_CACHE=on` at module top — the
25 * `pool: "forks"` isolation guarantees it never leaks to sibling specs, which
26 * run under the "auto" = off default).
27 */
28process.env.PERF_CACHE = "on";
29 
30import { describe, it, expect, beforeAll, afterAll } from "vitest";
31import Redis from "ioredis";
32import { optionIdForName } from "@factory/shared";
33import { createTestApp, type TestAppHandle } from "./helpers/api";
34import { getRedisUrl } from "./helpers/containers";
35import {
36  createUser,
37  createWorkspace,
38  addMemberViaSeam,
39  authHeaders
40} from "./helpers/seed";
41 
42let app: TestAppHandle;
43let redis: Redis;
44 
45beforeAll(async () => {
46  app = await createTestApp();
47  redis = new Redis(await getRedisUrl(), { maxRetriesPerRequest: null });
48}, 240_000);
49 
50afterAll(async () => {
51  try {
52    await redis?.quit();
53  } catch {
54    /* ignore */
55  }
56  await app?.close();
57});
58 
59/** Poll a predicate until it holds (or times out) — for async cache fills. */
60async function until(fn: () => Promise<boolean>, ms = 5000, label = "condition"): Promise<void> {
61  const start = Date.now();
62  for (;;) {
63    if (await fn()) return;
64    if (Date.now() - start > ms) throw new Error(`timeout waiting for ${label}`);
65    await new Promise((r) => setTimeout(r, 50));
66  }
67}
68 
69describe("cache invalidation (live, PERF_CACHE=on)", () => {
70  let ownerId: string;
71  let ownerToken: string;
72  let ownerHeaders: Record<string, string>;
73  let workspaceId: string;
74  let pageId: string;
75 
76  beforeAll(async () => {
77    const owner = await createUser(app.request, { name: "Cache Owner" });
78    ownerId = owner.userId;
79    ownerToken = owner.accessToken!;
80    ownerHeaders = authHeaders(ownerToken);
81    const ws = await createWorkspace(app.request, ownerHeaders, `Cache WS ${Date.now()}`);
82    workspaceId = ws.workspaceId;
83    const page = await app.request("POST", `/api/v1/workspaces/${workspaceId}/pages`, {
84      headers: ownerHeaders,
85      body: { title: "Cache Test Page" }
86    });
87    expect(page.status).toBeLessThan(300);
88    pageId = ((await page.json()) as { id: string }).id;
89  });
90 
91  it("tree: a repeated read is served from the cache (a live HIT key exists)", async () => {
92    const read = async () => {
93      const res = await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: ownerHeaders });
94      expect(res.status).toBe(200);
95      return (await res.json()) as { data: unknown[] };
96    };
97    await read(); // miss → load → fill tree:…:{version}
98    await read(); // hit
99 
100    // The tree key for THIS page is present in Redis → the second read was
101    // served from the cache (a live HIT), proving the cache engaged.
102    await until(
103      async () => {
104        const keys = await redis.keys(`perf:tree:${workspaceId}:${pageId}:*`);
105        return keys.length > 0;
106      },
107      5000,
108      "a perf:tree key to exist"
109    );
110  });
111 
112  it("tree: a write bumps the version → the next read is fresh (no stale read)", async () => {
113    // Baseline: one block.
114    const created = await app.request("POST", `/api/v1/pages/${pageId}/blocks`, {
115      headers: ownerHeaders,
116      body: { type: "paragraph", content: { text: "first" }, properties: {} }
117    });
118    expect(created.status).toBeLessThan(300);
119    const blockId = ((await created.json()) as { id: string }).id;
120 
121    // Prime the cache (a read fills tree:…:{v}).
122    const r1 = (await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: ownerHeaders })).json() as Promise<{ data: unknown[] }>;
123    const before = (await r1).data.length;
124 
125    // A write bumps the workspace content version (page.updated → bump).
126    const created2 = await app.request("POST", `/api/v1/pages/${pageId}/blocks`, {
127      headers: ownerHeaders,
128      body: { type: "paragraph", content: { text: "second" }, properties: {} }
129    });
130    expect(created2.status).toBeLessThan(300);
131 
132    // Wait for the async version bump to land (fire-and-forget from the bus).
133    await until(async () => {
134      const res = await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: ownerHeaders });
135      const body = (await res.json()) as { data: unknown[] };
136      // Fresh read: the new block must be present (a stale read would omit it).
137      return body.data.length === before + 1;
138    }, 5000, "the fresh read to include the new block");
139 
140    // And a NEW version key now exists (the old one is orphaned, unservable).
141    await until(
142      async () => (await redis.keys(`perf:tree:${workspaceId}:${pageId}:*`)).length >= 2,
143      5000,
144      "a second version key to exist"
145    );
146  });
147 
148  it("tree: concurrent writers never leave a stale read (the live race)", async () => {
149    // The version-key invariant, live: every write bumps the workspace content
150    // version, and a read keys by the CURRENT version. Under 5 concurrent
151    // writers we assert the two invariants the design actually guarantees:
152    //   (a) NO PHANTOM — a read never returns a row PG no longer has (a stale
153    //       snapshot could only OVER- or UNDER-count relative to a simultaneous
154    //       commit; the version-key makes the served snapshot always one that
155    //       PG actually had, so the served ids ⊆ the ids PG has at read time);
156    //   (b) SETTLED-EXACT — after all writers commit, the tree read is EXACTLY
157    //       the blocks PG has (no lost updates, no orphans).
158    // We capture the ids PG has AT READ TIME (before asserting) so the
159    // comparison is against the same snapshot the read served.
160    const pg = app.prisma;
161    const N = 5;
162    const seen: { served: string[]; pg: string[] }[] = [];
163    const writer = (i: number) =>
164      app.request("POST", `/api/v1/pages/${pageId}/blocks`, {
165        headers: ownerHeaders,
166        body: { type: "paragraph", content: { text: `race-${i}-${Date.now()}` }, properties: {} }
167      }).then(async (r) => {
168        if (r.status >= 300) throw new Error(`writer ${i} failed: ${r.status}`);
169        // Let the (async, fire-and-forget) version bump land, then read.
170        await new Promise((r) => setTimeout(r, 80));
171        const res = await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: ownerHeaders });
172        expect(res.status).toBe(200);
173        const body = (await res.json()) as { data: { id: string }[] };
174        const pgIds = new Set(
175          (await pg.block.findMany({ where: { pageId, deletedAt: null }, select: { id: true } })).map((b) => b.id)
176        );
177        seen.push({ served: body.data.map((b) => b.id), pg: [...pgIds] });
178      });
179    await Promise.all(Array.from({ length: N }, (_, i) => writer(i)));
180 
181    // (a) no phantom: every served id was one PG has.
182    for (const snap of seen) {
183      const pgSet = new Set(snap.pg);
184      const phantoms = snap.served.filter((id) => !pgSet.has(id));
185      expect(phantoms, `served a row PG no longer has: ${phantoms}`).toEqual([]);
186    }
187    // (b) settled-exact: the final read matches PG exactly (no lost update).
188    const finalRes = await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: ownerHeaders });
189    const finalBody = (await finalRes.json()) as { data: { id: string }[] };
190    const finalPg = (await pg.block.findMany({ where: { pageId, deletedAt: null }, select: { id: true } })).map((b) => b.id).sort();
191    expect(finalBody.data.map((b) => b.id).sort()).toEqual(finalPg);
192  });
193 
194  it("permission: a grant change busts the decision → fresh on the NEXT check (not after the TTL)", async () => {
195    // Add a member (a grant change → permission.changed → subject bust).
196    const member = await createUser(app.request, { name: "Cache Member" });
197    await addMemberViaSeam(app.request, app.internalServiceToken, workspaceId, member.email, "MEMBER");
198    const memberHeaders = authHeaders(member.accessToken!);
199 
200    // The member can now read the page (membership just took effect). A couple
201    // of reads prime any cached decision for this (workspace, member) subject.
202    const read = async () => {
203      const res = await app.request("GET", `/api/v1/pages/${pageId}/blocks?depth=all`, { headers: memberHeaders });
204      return res.status;
205    };
206    expect(await read()).toBe(200);
207    expect(await read()).toBe(200);
208 
209    // Now DOWNGRADE the member to GUEST (still a permission.changed for the
210    // subject). GUEST=VIEW, so reading the page's blocks is still allowed —
211    // instead, assert the decision cache was BUSTED by checking that a
212    // permission-relevant change is reflected immediately. The cleanest live
213    // signal: remove the member entirely → the NEXT request must 403/404
214    // (a stale cached EDIT/VIEW decision would let it through).
215    const del = await app.request(`DELETE`, `/api/v1/workspaces/${workspaceId}/members/${member.userId}`, {
216      headers: ownerHeaders
217    });
218    expect(del.status).toBeLessThan(300);
219 
220    // Wait for the async bust, then the member's next request is denied
221    // (fresh decision: no membership → NONE → not found/forbidden).
222    await until(
223      async () => (await read()) !== 200,
224      5000,
225      "the member's access to be denied after removal"
226    );
227  });
228 
229  it("metadata: a property change busts the column list → fresh on the NEXT read", async () => {
230    // Create a DATABASE page (the only public path to a Database) — it seeds
231    // the title property. The database id differs from the page id, so resolve
232    // it from the page via Prisma.
233    const dbPage = await app.request("POST", `/api/v1/workspaces/${workspaceId}/pages`, {
234      headers: ownerHeaders,
235      body: { title: "Cache Meta DB", type: "database" }
236    });
237    expect(dbPage.status).toBeLessThan(300);
238    const pageObj = (await dbPage.json()) as { id: string };
239    const db = await app.prisma.database.findFirst({ where: { pageId: pageObj.id } });
240    expect(db).not.toBeNull();
241    const dbId = db!.id;
242 
243    const listProps = async () => {
244      const res = await app.request("GET", `/api/v1/databases/${dbId}/properties`, { headers: ownerHeaders });
245      expect(res.status).toBe(200);
246      return ((await res.json()) as { data: { name: string }[] }).data;
247    };
248 
249    const before = await listProps(); // miss → fill metadata:…:properties
250    const beforeCount = before.length;
251    expect(beforeCount).toBeGreaterThan(0); // the seeded title property
252    await listProps(); // hit
253 
254    // Add a property → database.updated (propertyId) → busts the metadata.
255    const prop = await app.request("POST", `/api/v1/databases/${dbId}/properties`, {
256      headers: ownerHeaders,
257      body: { name: "Cached Col", type: "TEXT" }
258    });
259    expect(prop.status).toBeLessThan(300);
260 
261    // The NEXT listProperties is FRESH (includes the new property) — a cached
262    // pre-create list would not. (The metadata cache is 60 s; this must be a
263    // bust, not a TTL expiry.)
264    await until(
265      async () => (await listProps()).length === beforeCount + 1,
266      5000,
267      "the property list to include the new column"
268    );
269  });
270 
271  it("metadata: record-open and listProperties share ONE normalized entry (no id-less pollution)", async () => {
272    // Regression (the "select works but the cell renders blank" report):
273    // `getRecord` (record-open) and `listProperties` BOTH fill the SAME
274    // `perf:metadata:{db}:properties` cache key, but only `listProperties`
275    // normalized the id-less legacy select options. A record-open that
276    // filled the cache FIRST left the RAW (id-less) entry in place for the
277    // 60 s TTL, so the table view's `findOption` missed every canonical
278    // `{ optionId }` value → blank select/status cells. Both loaders must now
279    // store the SAME normalized shape.
280    //
281    // A fresh database page SEEDS a "Status" (SELECT) property whose options
282    // are id-less (`DEFAULT_DB_PROPERTIES` — `apps/api/src/constants.ts`):
283    // this IS the legacy state in the wild (no data migration needed).
284    const dbPage = await app.request("POST", `/api/v1/workspaces/${workspaceId}/pages`, {
285      headers: ownerHeaders,
286      body: { title: "Cache Polluted DB", type: "database" }
287    });
288    expect(dbPage.status).toBeLessThan(300);
289    const dbPageObj = (await dbPage.json()) as { id: string };
290    const db = await app.prisma.database.findFirst({ where: { pageId: dbPageObj.id } });
291    expect(db).not.toBeNull();
292    const dbId = db!.id;
293    const statusProp = await app.prisma.databaseProperty.findFirst({
294      where: { databaseId: dbId, name: "Status" }
295    });
296    expect(statusProp).not.toBeNull();
297    // Guard the premise: the seeded options really are id-less (otherwise the
298    // test would pass vacuously).
299    expect(
300      ((statusProp!.config as { options?: Array<{ id?: string }> }).options ?? []).every(
301        (o) => !o.id,
302      ),
303    ).toBe(true);
304 
305    interface PropDto {
306      id: string;
307      name: string;
308      config?: { options?: Array<{ id?: string; name?: string }> };
309    }
310    const listProps = async (): Promise<PropDto[]> => {
311      const res = await app.request("GET", `/api/v1/databases/${dbId}/properties`, { headers: ownerHeaders });
312      expect(res.status).toBe(200);
313      return ((await res.json()) as { data: PropDto[] }).data;
314    };
315    const statusOptions = (props: PropDto[]) => props.find((p) => p.id === statusProp.id)?.config?.options ?? [];
316 
317    // A record so the record-open has something to serve.
318    const rec = await app.request("POST", `/api/v1/databases/${dbId}/records`, {
319      headers: ownerHeaders,
320      body: { title: "Polluted Row", properties: {}, links: {} }
321    });
322    expect(rec.status).toBeLessThan(300);
323    // The create response IS the record DTO (top-level id).
324    const recordId = ((await rec.json()) as { id: string }).id;
325 
326    // THE repro: a record-open FILLS the shared cache FIRST (record-create
327    // does not bust the column-metadata cache — only `database.updated` does).
328    // The record-open route is `GET /api/v1/records/:id` (the web's
329    // `useDatabaseRecord` fetches exactly this URL).
330    const open = await app.request("GET", `/api/v1/records/${recordId}`, { headers: ownerHeaders });
331    expect(open.status).toBe(200);
332 
333    // The NEXT listProperties must be served from that entry — and it must
334    // be NORMALIZED (deterministic option ids), not the raw id-less config.
335    await until(
336      async () => {
337        const opts = statusOptions(await listProps());
338        return (
339          opts.length === 3 &&
340          opts.map((o) => o.id).join(",") ===
341            [optionIdForName("To Do"), optionIdForName("In Progress"), optionIdForName("Done")].join(",")
342        );
343      },
344      5000,
345      "the shared metadata entry to carry normalized option ids"
346    );
347  });
348});
349