@proteinjs/db 1.55.0 → 1.56.0

package/test/reusable/TableWatcherAuthorityTests.ts

@@ -0,0 +1,204 @@
+import { Db, DbDriver, Table, TableWatcher, DefaultTransactionContextFactory } from '@proteinjs/db';
+import { QueryBuilder } from '@proteinjs/db-query';
+import { SourceRepository } from '@proteinjs/reflection';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import { TableWatcherRunner } from '../../src/TableWatcherRunner';
+import {
+  GuardedJournal,
+  tableWatcherAuthorityTestTables,
+  WATCHER_GUARDED_REFUSAL,
+  WatchedNote,
+} from '../util/tables/tableWatcherAuthorityTestTables';
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+const resetTableWatcherMap = () => {
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+};
+
+/** The watcher's refusal when a hook arrives without the write's Db — the contract's first half. */
+export const HOOK_HANDED_NO_DB = 'the hook was handed no Db';
+
+const HOOKS = ['beforeInsert', 'afterInsert', 'beforeUpdate', 'afterUpdate', 'beforeDelete', 'afterDelete'];
+
+/**
+ * Journals every hook run through the HANDED Db and nothing else — the way a watcher is written
+ * once the Db hands one (chat's topic watcher deleting a deleted message's topic links, the media
+ * watcher deleting a deleted row's file, the activity watcher bumping the chat a message landed
+ * in). The journal is a guarded table, so the hook's write and read succeed only with a system
+ * Db: the one the write made, carrying its own authority.
+ */
+class JournalingWatcher implements TableWatcher<WatchedNote> {
+  name(): string {
+    return 'JournalingWatcher';
+  }
+
+  table(): Table<WatchedNote> {
+    return tableWatcherAuthorityTestTables.WatchedNote;
+  }
+
+  async beforeInsert<T extends WatchedNote>(
+    record: Omit<T, keyof WatchedNote>,
+    db?: Db
+  ): Promise<Omit<T, keyof WatchedNote>> {
+    await this.journal(db, (record as unknown as WatchedNote).id, 'beforeInsert');
+    return record;
+  }
+
+  async afterInsert<T extends WatchedNote>(record: T, db?: Db): Promise<void> {
+    await this.journal(db, record.id, 'afterInsert');
+  }
+
+  async beforeUpdate<T extends WatchedNote>(record: Partial<T>, qb: QueryBuilder<T>, db?: Db): Promise<Partial<T>> {
+    for (const row of await this.handed(db).query(this.table(), qb as unknown as QueryBuilder<WatchedNote>)) {
+      await this.journal(db, row.id, 'beforeUpdate');
+    }
+    return record;
+  }
+
+  async afterUpdate<T extends WatchedNote>(
+    recordUpdateCount: number,
+    record: Partial<T>,
+    qb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of await this.handed(db).query(this.table(), qb as unknown as QueryBuilder<WatchedNote>)) {
+      await this.journal(db, row.id, 'afterUpdate');
+    }
+  }
+
+  async beforeDelete<T extends WatchedNote>(
+    recordsToDelete: T[],
+    _initialQb: QueryBuilder<T>,
+    _deleteQb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of recordsToDelete) {
+      await this.journal(db, row.id, 'beforeDelete');
+    }
+  }
+
+  async afterDelete<T extends WatchedNote>(
+    _recordDeleteCount: number,
+    deletedRecords: T[],
+    _initialQb: QueryBuilder<T>,
+    _deleteQb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of deletedRecords) {
+      await this.journal(db, row.id, 'afterDelete');
+      // The read half of the contract: a query through the handed Db over the guarded table.
+      await this.handed(db).query(tableWatcherAuthorityTestTables.GuardedJournal, { note: row.id });
+    }
+  }
+
+  private async journal(db: Db | undefined, note: string, hook: string): Promise<void> {
+    await this.handed(db).insert(tableWatcherAuthorityTestTables.GuardedJournal, {
+      note,
+      hook,
+      principal: 'the write',
+    });
+  }
+
+  private handed(db: Db | undefined): Db {
+    if (!db) {
+      throw new Error(HOOK_HANDED_NO_DB);
+    }
+    return db;
+  }
+}
+
+/**
+ * A table watcher's hooks run with the authority of the write that fired them: the Db hands every
+ * hook a Db carrying its driver, tables, transaction context and system mode. Before this the
+ * hooks were handed nothing and each watcher opened a session-scoped Db of its own, which a system
+ * write in a session-less context (an account purge, a sweep) could not use — the topic links of a
+ * purged message and the file of a system-deleted media row stayed behind, and the activity bump
+ * of a system-inserted message threw.
+ */
+export const tableWatcherAuthorityTests = (
+  driver: DbDriver,
+  transactionContextFactory: DefaultTransactionContextFactory,
+  dropTable: (table: Table<any>) => Promise<void>
+) => {
+  return () => {
+    const testEnv = new DbTestEnvironment(driver, dropTable);
+    const notes = tableWatcherAuthorityTestTables.WatchedNote;
+    const journal = tableWatcherAuthorityTestTables.GuardedJournal;
+    // Constructed in beforeAll, AFTER the watcher registration below: a Db's construction builds
+    // the runner's static watcher map, and the map must be built from the registered watcher.
+    let systemDb: Db;
+    let sessionDb: Db;
+    let originalWatchers: unknown[] | undefined;
+
+    /** A fresh async hop — the shape of a background context that inherits no caller's state. */
+    const inFreshContext = <T>(fn: () => Promise<T>): Promise<T> =>
+      new Promise<T>((resolve, reject) => {
+        setImmediate(() => {
+          fn().then(resolve, reject);
+        });
+      });
+
+    const journalHooksFor = async (noteId: string): Promise<string[]> =>
+      (await systemDb.query(journal, { note: noteId })).map((row: GuardedJournal) => row.hook).sort();
+
+    beforeAll(async () => {
+      originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+      objectCache()['@proteinjs/db/TableWatcher'] = [new JournalingWatcher()];
+      resetTableWatcherMap();
+      systemDb = new Db(driver, undefined, transactionContextFactory, true);
+      sessionDb = new Db(driver, undefined, transactionContextFactory);
+      await testEnv.beforeAll();
+    }, 120000);
+
+    afterAll(async () => {
+      await testEnv.afterAll();
+      if (originalWatchers) {
+        objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+      } else {
+        delete objectCache()['@proteinjs/db/TableWatcher'];
+      }
+      resetTableWatcherMap();
+    }, 120000);
+
+    beforeEach(async () => {
+      await systemDb.delete(journal, {});
+      await systemDb.delete(notes, {});
+    });
+
+    describe('Table watchers carry the write’s authority', () => {
+      test('a system insert, update and delete in a session-less context: all six hooks write and read the guarded journal through the handed Db', async () => {
+        const noteId = await inFreshContext(async () => {
+          const note = await systemDb.insert(notes, { title: 'Kept' });
+          await systemDb.update(notes, { title: 'Kept, renamed' }, { id: note.id });
+          await systemDb.delete(notes, { id: note.id });
+          return note.id;
+        });
+
+        expect(await systemDb.query(notes, { id: noteId })).toHaveLength(0);
+        expect(await journalHooksFor(noteId)).toEqual([...HOOKS].sort());
+      });
+
+      test('a session write’s hooks run as the session, never as system: the guarded journal refuses the first hook and the write with it', async () => {
+        await expect(sessionDb.insert(notes, { title: 'Refused' })).rejects.toThrow(WATCHER_GUARDED_REFUSAL);
+        expect(await systemDb.query(notes, { title: 'Refused' })).toHaveLength(0);
+      });
+
+      test('the handed Db rides the write’s transaction: a rolled-back system insert leaves no journal row', async () => {
+        let noteId: string | undefined;
+        await expect(
+          systemDb.runTransaction(async () => {
+            const note = await systemDb.insert(notes, { title: 'Rolled back' });
+            noteId = note.id;
+            throw new Error('roll back');
+          })
+        ).rejects.toThrow('roll back');
+
+        expect(noteId).toBeDefined();
+        expect(await systemDb.query(notes, { id: noteId })).toHaveLength(0);
+        expect(await journalHooksFor(noteId!)).toEqual([]);
+      });
+    });
+  };
+};

package/test/util/DbTestEnvironment.ts

@@ -8,6 +8,7 @@ import { recordIteratorTestTables } from './tables/recordIteratorTestTables';
 import { sourceRecordSyncTestTables } from './tables/sourceRecordSyncTestTables';
 import { storedValueContractTestTables } from './tables/storedValueContractTestTables';
 import { tableManagerTestTables } from './tables/tableManagerTestTables';
+import { tableWatcherAuthorityTestTables } from './tables/tableWatcherAuthorityTestTables';
 import { transactionTestTables } from './tables/transactionTestTables';
 
 const TABLES: Table<any>[] = [
@@ -20,6 +21,7 @@ const TABLES: Table<any>[] = [
   // The member tables are the stored-value suite's own: it builds each physical column order itself.
   storedValueContractTestTables.Mixed,
   ...Object.values(tableManagerTestTables),
+  ...Object.values(tableWatcherAuthorityTestTables),
   ...Object.values(transactionTestTables),
 ];
 

package/test/util/tables/cascadeDeleteTestTables.ts

@@ -80,6 +80,28 @@ export interface Mission extends Record {
   assigneeRef?: Reference<Pilot | Robot> | null;
 }
 
+// --- Cascade under the write's authority: a guarded child (GuardedHolder* -> GuardedMember)
+// The child's table refuses every non-system query, the shape of a scoped table (its column adds
+// the caller's scope to each query and throws when the context carries no user). A holder deleted
+// AS SYSTEM must take its children with it: the cascade runs with the authority of the write that
+// fired it, never as whoever happens to be in the session.
+export interface GuardedMember extends Record {
+  name: string;
+}
+export interface GuardedHolderRef extends Record {
+  holderName: string;
+  memberRef?: Reference<GuardedMember> | null;
+}
+export interface GuardedHolderArr extends Record {
+  holderName: string;
+  memberRefs?: ReferenceArray<GuardedMember> | null;
+}
+export interface GuardedHolderDyn extends Record {
+  holderName: string;
+  memberDynTableName?: string | null;
+  memberDynRef?: Reference<GuardedMember> | null;
+}
+
 /**
  * ---------- Table Names ----------
  */
@@ -112,6 +134,15 @@ const PILOT_TABLE = 'db_test_cd_pilots';
 const ROBOT_TABLE = 'db_test_cd_robots';
 const MISSION_TABLE = 'db_test_cd_missions';
 
+// Cascade under the write's authority (guarded child)
+const GUARDED_MEMBER_TABLE = 'db_test_cd_guarded_members';
+const GUARDED_HOLDER_REF_TABLE = 'db_test_cd_guarded_holders_ref';
+const GUARDED_HOLDER_ARR_TABLE = 'db_test_cd_guarded_holders_arr';
+const GUARDED_HOLDER_DYN_TABLE = 'db_test_cd_guarded_holders_dyn';
+
+/** The guarded table's refusal of a non-system query — the words a suite asserts on. */
+export const GUARDED_QUERY_REFUSAL = 'no user in scope';
+
 /**
  * ---------- Table Classes ----------
  */
@@ -261,6 +292,56 @@ export class MissionTable extends Table<Mission> {
   });
 }
 
+// Cascade under the write's authority: the guarded child and its three holders
+export class GuardedMemberTable extends Table<GuardedMember> {
+  name = GUARDED_MEMBER_TABLE;
+  columns: Table<GuardedMember>['columns'] = withRecordColumns<GuardedMember>({
+    name: new StringColumn('name', {
+      // The scoped-table contract without a dependency on it: a non-system query of this table
+      // would need the context's user to scope it to, and there is none — refuse it by name.
+      addToQuery: async (qb, runAsSystem) => {
+        if (!runAsSystem) {
+          throw new Error(GUARDED_QUERY_REFUSAL);
+        }
+      },
+    }),
+  });
+}
+export class GuardedHolderRefTable extends Table<GuardedHolderRef> {
+  name = GUARDED_HOLDER_REF_TABLE;
+  columns: Table<GuardedHolderRef>['columns'] = withRecordColumns<GuardedHolderRef>({
+    holderName: new StringColumn('holder_name'),
+    memberRef: new ReferenceColumn<GuardedMember>(
+      'member_id',
+      GUARDED_MEMBER_TABLE,
+      true // cascade: deleting the holder deletes the referenced GuardedMember
+    ),
+  });
+}
+export class GuardedHolderArrTable extends Table<GuardedHolderArr> {
+  name = GUARDED_HOLDER_ARR_TABLE;
+  columns: Table<GuardedHolderArr>['columns'] = withRecordColumns<GuardedHolderArr>({
+    holderName: new StringColumn('holder_name'),
+    memberRefs: new ReferenceArrayColumn<GuardedMember>(
+      'member_ids',
+      GUARDED_MEMBER_TABLE,
+      true // cascade: deleting the holder deletes every referenced GuardedMember
+    ),
+  });
+}
+export class GuardedHolderDynTable extends Table<GuardedHolderDyn> {
+  name = GUARDED_HOLDER_DYN_TABLE;
+  columns: Table<GuardedHolderDyn>['columns'] = withRecordColumns<GuardedHolderDyn>({
+    holderName: new StringColumn('holder_name'),
+    memberDynTableName: new DynamicReferenceTableNameColumn('member_dyn_table_name', 'member_dyn_ref'),
+    memberDynRef: new DynamicReferenceColumn<GuardedMember>(
+      'member_dyn_ref',
+      'member_dyn_table_name',
+      true // cascade: deleting the holder deletes the dynamically referenced GuardedMember
+    ),
+  });
+}
+
 export const cascadeDeleteTestTables = {
   MemberRef: new MemberRefTable() as Table<MemberRef>,
   GroupRef: new GroupRefTable() as Table<GroupRef>,
@@ -277,4 +358,8 @@ export const cascadeDeleteTestTables = {
   Pilot: new PilotTable() as Table<Pilot>,
   Robot: new RobotTable() as Table<Robot>,
   Mission: new MissionTable() as Table<Mission>,
+  GuardedMember: new GuardedMemberTable() as Table<GuardedMember>,
+  GuardedHolderRef: new GuardedHolderRefTable() as Table<GuardedHolderRef>,
+  GuardedHolderArr: new GuardedHolderArrTable() as Table<GuardedHolderArr>,
+  GuardedHolderDyn: new GuardedHolderDynTable() as Table<GuardedHolderDyn>,
 };

package/test/util/tables/tableWatcherAuthorityTestTables.ts

@@ -0,0 +1,61 @@
+import { StringColumn, Table, withRecordColumns, Record } from '@proteinjs/db';
+
+// --- Table watchers run with the authority of the write that fired them (WatchedNote -> GuardedJournal)
+
+/** The watched table: a plain row whose writes fire the suite's journaling watcher. */
+export interface WatchedNote extends Record {
+  title: string;
+}
+
+/** The watcher's journal: one row per hook run, writable and readable as system only. */
+export interface GuardedJournal extends Record {
+  /** The watched row's id. */
+  note: string;
+  /** The hook that wrote the row (`beforeInsert` … `afterDelete`). */
+  hook: string;
+  /** The scoped-table contract in miniature — see {@link GuardedJournalTable}. */
+  principal: string;
+}
+
+const WATCHED_NOTE_TABLE = 'db_test_tw_notes';
+const GUARDED_JOURNAL_TABLE = 'db_test_tw_guarded_journal';
+
+/** The journal's refusal of a non-system write or query, by name. */
+export const WATCHER_GUARDED_REFUSAL = 'no user in scope (journal)';
+
+export class WatchedNoteTable extends Table<WatchedNote> {
+  name = WATCHED_NOTE_TABLE;
+  columns: Table<WatchedNote>['columns'] = withRecordColumns<WatchedNote>({
+    title: new StringColumn('title'),
+  });
+}
+
+/**
+ * A scoped table's shape without a dependency on one: a non-system write needs the context's
+ * user to stamp the row with, a non-system query needs it to scope the query to — there is none
+ * in a session-less context, so both refuse by name. A system write supplies the principal itself
+ * and a system query is not scoped, exactly as `@proteinjs/user`'s ScopedRecord columns behave.
+ */
+export class GuardedJournalTable extends Table<GuardedJournal> {
+  name = GUARDED_JOURNAL_TABLE;
+  columns: Table<GuardedJournal>['columns'] = withRecordColumns<GuardedJournal>({
+    note: new StringColumn('note'),
+    hook: new StringColumn('hook'),
+    principal: new StringColumn('principal', {
+      defaultValue: async () => {
+        throw new Error(WATCHER_GUARDED_REFUSAL);
+      },
+      forceDefaultValue: (runAsSystem) => !runAsSystem,
+      addToQuery: async (qb, runAsSystem) => {
+        if (!runAsSystem) {
+          throw new Error(WATCHER_GUARDED_REFUSAL);
+        }
+      },
+    }),
+  });
+}
+
+export const tableWatcherAuthorityTestTables = {
+  WatchedNote: new WatchedNoteTable() as Table<WatchedNote>,
+  GuardedJournal: new GuardedJournalTable() as Table<GuardedJournal>,
+};