@proteinjs/db-driver-spanner 1.12.3 → 1.13.0

package/src/SpannerDriver.ts

@@ -219,9 +219,14 @@ export class SpannerDriver implements DbDriver {
       'spanner dml transaction',
       '(runTransactionAsync)',
       this.getSpannerDb().runTransactionAsync(async (transaction) => {
-        const rowCount = await this.executeDml(generateStatement, transaction);
-        await transaction.commit();
-        return rowCount;
+        try {
+          const rowCount = await this.executeDml(generateStatement, transaction);
+          await transaction.commit();
+          return rowCount;
+        } catch (error) {
+          await this.rollbackQuietly(transaction);
+          throw error;
+        }
       })
     );
   }
@@ -277,13 +282,37 @@ export class SpannerDriver implements DbDriver {
       'spanner transaction',
       '(runTransactionAsync)',
       this.getSpannerDb().runTransactionAsync(async (transaction) => {
-        const result = await fn(transaction);
-        await transaction.commit();
-        return result;
+        try {
+          const result = await fn(transaction);
+          await transaction.commit();
+          return result;
+        } catch (error) {
+          await this.rollbackQuietly(transaction);
+          throw error;
+        }
       })
     );
   }
 
+  /**
+   * Release a transaction whose work errored. The client library's runner does NOT roll back on
+   * non-retryable errors — it just rethrows — so a thrown `fn` (e.g. an application rollback, or
+   * a failed statement) left the read-write transaction OPEN until session timeout. Real Spanner
+   * tolerates that (locks expire); the emulator serializes on its single read-write transaction,
+   * so one leaked transaction blocks every subsequent DDL with FAILED_PRECONDITION ("a
+   * read-write transaction is already in progress") — poisoning whole test runs. Rollback of an
+   * already-invalid transaction (e.g. ABORTED, about to be retried by the runner with a fresh
+   * transaction) is expected to fail; that failure is logged and swallowed so the ORIGINAL error
+   * — the one that carries retry semantics — always propagates.
+   */
+  private async rollbackQuietly(transaction: Transaction): Promise<void> {
+    try {
+      await transaction.rollback();
+    } catch (rollbackError: any) {
+      this.logger.debug({ message: `Rollback after transaction error failed`, obj: { rollbackError } });
+    }
+  }
+
   /**
    * Stall diagnostics (2026-07-10 flow-hang investigation): background flow tasks intermittently
    * wedge between model calls with every model-layer guard silent — the remaining awaits on that

package/src/SpannerLivenessMonitor.ts

@@ -4,6 +4,16 @@ import { Logger } from '@proteinjs/logger';
 /** grpc status codes that indicate connectivity trouble rather than an application error */
 const CONNECTIVITY_GRPC_CODES = [4 /* DEADLINE_EXCEEDED */, 14 /* UNAVAILABLE */];
 
+/**
+ * Restart-requested exit code — the supervision contract shared with @proteinjs/build's
+ * serve-package (ServePackageSupervisor.RESTART_REQUEST_EXIT_CODE): a supervised process
+ * exiting with this code is respawned with bounded backoff instead of being treated as a plain
+ * failure (which the supervisor mirrors, i.e. stays down). Orchestrators that restart on any
+ * nonzero exit (systemd, Kubernetes) treat it like any other failure code, so it is safe
+ * everywhere. Hard-coded by design: the contract crosses a process boundary, like a signal.
+ */
+const RESTART_REQUEST_EXIT_CODE = 86;
+
 export class SpannerLivenessMonitor {
   private static readonly PROBE_SQL = 'SELECT 1';
   private static readonly PROBE_TIMEOUT_MS = 10_000;
@@ -56,7 +66,7 @@ export class SpannerLivenessMonitor {
         }
       }
       this.logger.error({
-        message: `Db unreachable after sustained probing; exiting so supervision can restart into a valid state`,
+        message: `Db unreachable after sustained probing; exiting restart-requested (code ${RESTART_REQUEST_EXIT_CODE}) so supervision respawns into a valid state`,
       });
       this.exit();
     } finally {
@@ -76,6 +86,6 @@ export class SpannerLivenessMonitor {
   }
 
   private exit(): void {
-    process.exit(1);
+    process.exit(RESTART_REQUEST_EXIT_CODE);
   }
 }

package/test/ServiceUpdateVerbs.test.ts

@@ -0,0 +1,188 @@
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import {
+  ArrayMembershipUpdate,
+  computeArrayMembershipOps,
+  Db,
+  isTable,
+  PreservedPath,
+  ReferenceArray,
+  Table,
+  tableByName,
+} from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import {
+  ServiceVerbsDoc,
+  ServiceVerbsDocTable,
+  serviceVerbsScopeContext as scope,
+} from './util/serviceUpdateVerbsTestTables';
+import '../generated/test/index';
+
+/**
+ * The RMW update verbs (`updateArrayMembership`, `updatePreserving`) over the DbService RPC
+ * path, against real Spanner transaction semantics.
+ *
+ * The service path differs from bespoke server code in three load-bearing ways, each pinned here:
+ * - ONE long-lived `Db` instance serves every request (ServiceRouter builds its executor map
+ *   once), so the verbs' self-wrapped transactions must not couple concurrent callers through
+ *   instance state.
+ * - args cross a serialization boundary: `Table` as `{ tableName }` resolved via `tableByName`,
+ *   the op payloads (`ArrayMembershipUpdate`, `PreservedPath`) as plain JSON.
+ * - authorization is the `TableServiceAuth.canAccess(methodName, args)` gate plus scoped/column
+ *   query injection inside the verb's read-modify-write — an out-of-scope row must behave as
+ *   nonexistent.
+ */
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+describe('DbService RMW update verbs (updateArrayMembership / updatePreserving)', () => {
+  const docTable = new ServiceVerbsDocTable() as Table<ServiceVerbsDoc>;
+  const dropTable = getDropTestTable(spannerDriver);
+  // Service-singleton shaped: one shared instance, default table resolution (tableByName).
+  const db = new Db<ServiceVerbsDoc>(spannerDriver, undefined, new TransactionContext());
+
+  /**
+   * The wire forms the Serializer produces for DbService args: `Table` crosses as its name and is
+   * resolved via `tableByName` server-side (TableSerializer); the op payloads are plain JSON.
+   */
+  const overWire = (args: any[]) =>
+    args.map((arg) => (isTable(arg) ? tableByName((arg as Table<any>).name) : JSON.parse(JSON.stringify(arg))));
+
+  /** Invoke like ServiceExecutor does: deserialize wire args, run the canAccess gate, call the method. */
+  const rpc = async (methodName: string, args: any[]) => {
+    const wireArgs = overWire(args);
+    if (!db.serviceMetadata!.auth!.canAccess!(methodName, wireArgs)) {
+      throw new Error(`User not authorized to run service: DbService.${methodName}`);
+    }
+    return await (db as any)[methodName](...wireArgs);
+  };
+
+  const memberIds = async (id: string) => {
+    const row = await db.get(docTable, { id });
+    return row?.members?._ids;
+  };
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(docTable);
+    await spannerDriver.getTableManager().loadTable(docTable);
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(docTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 30000);
+
+  beforeEach(() => {
+    scope.current = 'scope-a';
+  });
+
+  test('membership ops apply against committed truth, not the caller list snapshot', async () => {
+    const doc = await db.insert(docTable, {
+      title: 'd1',
+      members: new ReferenceArray(docTable.name, ['a', 'b', 'c']),
+    });
+    // Another writer's committed wholesale update adds `d` — the caller's snapshot is now stale.
+    await db.update(docTable, { id: doc.id, members: new ReferenceArray(docTable.name, ['a', 'b', 'c', 'd']) });
+
+    // The caller computed remove(b) against the stale base [a, b, c].
+    const update: ArrayMembershipUpdate = {
+      recordId: doc.id,
+      columnPropertyName: 'members',
+      ops: computeArrayMembershipOps(['a', 'b', 'c'], ['a', 'c']),
+    };
+    expect(await rpc('updateArrayMembership', [docTable, update])).toBe(1);
+
+    // Both writers' effects survive; a wholesale write of the stale list would have erased `d`.
+    expect(await memberIds(doc.id)).toEqual(['a', 'c', 'd']);
+  });
+
+  test('a scoped caller cannot touch another scope’s row via updateArrayMembership', async () => {
+    const doc = await db.insert(docTable, { title: 'd2', members: new ReferenceArray(docTable.name, ['a', 'b']) });
+
+    scope.current = 'scope-b';
+    const removeA: ArrayMembershipUpdate = {
+      recordId: doc.id,
+      columnPropertyName: 'members',
+      ops: [{ op: 'remove', id: 'a' }],
+    };
+    expect(await rpc('updateArrayMembership', [docTable, removeA])).toBe(0);
+
+    scope.current = 'scope-a';
+    expect(await memberIds(doc.id)).toEqual(['a', 'b']);
+
+    // The owning scope can perform the identical op.
+    expect(await rpc('updateArrayMembership', [docTable, removeA])).toBe(1);
+    expect(await memberIds(doc.id)).toEqual(['b']);
+  });
+
+  test('a scoped caller cannot touch another scope’s row via updatePreserving', async () => {
+    const doc = await db.insert(docTable, { title: 'd3', body: { content: 'v1', style: { color: 'blue' } } });
+
+    scope.current = 'scope-b';
+    const preserve: PreservedPath[] = [{ columnPropertyName: 'body', paths: ['content'], whenType: 'string' }];
+    const foreignWrite = { id: doc.id, body: { content: 'hijack', style: { color: 'red' } } };
+    expect(await rpc('updatePreserving', [docTable, foreignWrite, preserve])).toBe(0);
+
+    scope.current = 'scope-a';
+    const row = await db.get(docTable, { id: doc.id });
+    expect(row.body).toEqual({ content: 'v1', style: { color: 'blue' } });
+  });
+
+  test('updatePreserving over the service preserves the committed sub-path while writing owned paths', async () => {
+    const doc = await db.insert(docTable, { title: 'd4', body: { content: 'v1', style: { color: 'blue' } } });
+    // The owning writer's committed text save; the structural writer's payload still carries v1.
+    await db.update(docTable, { id: doc.id, body: { content: 'v2', style: { color: 'blue' } } });
+
+    const preserve: PreservedPath[] = [{ columnPropertyName: 'body', paths: ['content'], whenType: 'string' }];
+    const stalePayload = { id: doc.id, body: { content: 'v1', style: { color: 'red' } } };
+    expect(await rpc('updatePreserving', [docTable, stalePayload, preserve])).toBe(1);
+
+    const row = await db.get(docTable, { id: doc.id });
+    expect(row.body).toEqual({ content: 'v2', style: { color: 'red' } });
+  });
+
+  test('concurrent RPCs on the shared service instance get isolated transactions', async () => {
+    const doc = await db.insert(docTable, { title: 'd5', members: new ReferenceArray(docTable.name, ['seed']) });
+
+    // The service singleton serves concurrent requests; each self-wrapped RMW transaction must be
+    // isolated (no cross-request transaction bleed through shared instance state), and every
+    // membership add must land. Issuance is STAGGERED so later requests arrive while an earlier
+    // request's transaction is open — the shape that makes shared instance state bleed: a
+    // simultaneous burst would let every call check the (still unset) transaction state before
+    // any transaction opens, masking the coupling.
+    const addedIds = ['m1', 'm2', 'm3', 'm4', 'm5', 'm6'];
+    const inFlight: Promise<unknown>[] = [];
+    for (const id of addedIds) {
+      inFlight.push(
+        rpc('updateArrayMembership', [
+          docTable,
+          { recordId: doc.id, columnPropertyName: 'members', ops: [{ op: 'add', id, afterId: 'seed' }] },
+        ])
+      );
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    await Promise.all(inFlight);
+
+    expect([...((await memberIds(doc.id)) ?? [])].sort()).toEqual([...addedIds, 'seed'].sort());
+  }, 60000);
+
+  test('updateArrayMembership rejects a non-ReferenceArrayColumn target', async () => {
+    const doc = await db.insert(docTable, { title: 'd6' });
+    await expect(
+      rpc('updateArrayMembership', [
+        docTable,
+        { recordId: doc.id, columnPropertyName: 'title', ops: [{ op: 'add', id: 'x', afterId: null }] },
+      ])
+    ).rejects.toThrow('requires a ReferenceArrayColumn');
+  });
+});

package/test/SessionRecordTableQuery.test.ts

@@ -0,0 +1,118 @@
+import moment from 'moment';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { Db, DateColumn, QueryBuilderFactory, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+/**
+ * Proves the generic record-table query path over the session table shape.
+ *
+ * The admin Sessions record table (settings menu → Sessions) runs EXACTLY this query through
+ * DbService: rows written by DbSessionStore (system db, Table layer), read back with the
+ * QueryTableLoader query — sort `updated desc`, paginate. When it showed zero rows on a server
+ * with live sessions (2026-08), the suspects were the query shape itself: a physical table the
+ * Table def can't read, scope filtering dropping every row, or a default sort on an unpopulated
+ * column. This test pins the query shape against real Spanner semantics: store-shaped rows come
+ * back, all of them, newest-first — so an empty result at that surface means the query never ran
+ * (it was denied; the UI rendered the failure as "no rows"), not that the data is unreadable.
+ */
+
+interface SessionShape extends Record {
+  sessionId: string;
+  session: string;
+  expires: Date;
+  userEmail: string;
+}
+
+/** Mirrors @proteinjs/user SessionTable column-for-column (namespaced test table name). */
+class SessionShapeTable extends Table<SessionShape> {
+  name = 'db_test_session_record_table_query';
+  columns = withRecordColumns<SessionShape>({
+    sessionId: new StringColumn('session_id'),
+    session: new StringColumn('serialized_session', {}, 4000),
+    expires: new DateColumn('expires'),
+    userEmail: new StringColumn('user_email'),
+  });
+}
+
+const table = new SessionShapeTable();
+const getTable = (tableName: string) => {
+  if (tableName === table.name) {
+    return table;
+  }
+  throw new Error(`Unexpected table lookup in test: ${tableName}`);
+};
+
+const spannerDriver = new SpannerDriver(
+  {
+    projectId: 'proteinjs-test',
+    instanceName: 'proteinjs-test',
+    databaseName: 'test',
+  },
+  getTable
+);
+
+/**
+ * What DbSessionStore serializes into a row (shape from a real dev session). `updated` is
+ * stamped explicitly for deterministic newest-first assertions: the insert-time default takes
+ * moment() per row, and rows landing in the same millisecond would make the order ambiguous.
+ */
+const storeShapedRow = (n: number, updatedMs: number) => ({
+  sessionId: `test-session-${n}`,
+  session: JSON.stringify({
+    cookie: { originalMaxAge: 5184000000, expires: '2026-10-01T00:00:00.000Z', httpOnly: true, path: '/' },
+    passport: { user: `user-${n}@test.local` },
+  }),
+  expires: new Date(Date.now() + 5184000000),
+  userEmail: `user-${n}@test.local`,
+  updated: moment(updatedMs),
+});
+
+describe('Session-shaped record table query (the admin Sessions table path)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  // Writes as the session store writes (system db), reads as the record table reads.
+  const systemDb = new Db(spannerDriver, getTable, new TransactionContext(), true);
+  const db = new Db(spannerDriver, getTable, new TransactionContext());
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(table);
+    await spannerDriver.getTableManager().loadTable(table);
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(table);
+    await SpannerEmulatorProvisioner.release();
+  }, 30000);
+
+  test('store-written session rows all come back through the record-table query, newest-first', async () => {
+    // Insert like DbSessionStore.insertOrUpdate: system db, store-shaped fields, staggered updates.
+    const base = Date.now() - 60_000;
+    for (let n = 1; n <= 3; n++) {
+      await systemDb.insert(table, storeShapedRow(n, base + n * 1000) as any);
+    }
+
+    // EXACTLY QueryTableLoader.load's query: sort updated desc, paginate the first window.
+    const qb = new QueryBuilderFactory()
+      .createQueryBuilder<SessionShape>(table)
+      .sort([{ field: 'updated', desc: true }])
+      .paginate({ start: 0, end: 10 });
+    const rows = await db.query(table, qb);
+
+    expect(rows.map((row) => row.sessionId)).toEqual(['test-session-3', 'test-session-2', 'test-session-1']);
+    // Round-trip fidelity of the store-shaped fields the table displays.
+    expect(rows[0].userEmail).toBe('user-3@test.local');
+    expect(JSON.parse(rows[0].session).passport.user).toBe('user-3@test.local');
+    expect(rows[0].expires).toBeTruthy();
+
+    // The pagination variant of the loader also asks for the row count.
+    const countQb = new QueryBuilderFactory().createQueryBuilder<SessionShape>(table);
+    expect(await db.getRowCount(table, countQb)).toBe(3);
+  }, 60000);
+});

package/test/SpannerLivenessMonitor.test.ts

@@ -80,6 +80,21 @@ describe('SpannerLivenessMonitor', () => {
     );
   });
 
+  test('the sustained-failure exit is RESTART-REQUESTED (code 86) so supervision respawns instead of staying down', async () => {
+    // The serve-package contract (ServePackageSupervisor.RESTART_REQUEST_EXIT_CODE): 86 asks
+    // the supervisor for a respawn with backoff; a plain exit(1) is mirrored and stays down —
+    // observed as a dev server dead all night after a transient network outage.
+    exitSpy.mockRestore();
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    probeSpy.mockRejectedValue(new Error('14 UNAVAILABLE: fake'));
+
+    const check = internals.verifyLiveness();
+    await jest.advanceTimersByTimeAsync(ALL_PROBE_DELAYS_MS);
+    await check;
+
+    expect(processExitSpy).toHaveBeenCalledWith(86);
+  });
+
   test('burst coalescing: reportError while a check is in flight triggers one probe cycle', async () => {
     probeSpy.mockResolvedValue(undefined);
 

package/test/index.ts

@@ -1,2 +1,3 @@
 export * from './util/getDropTestTable';
 export * from './util/SpannerEmulatorProvisioner';
+export * from './util/serviceUpdateVerbsTestTables';

package/test/util/serviceUpdateVerbsTestTables.ts

@@ -0,0 +1,55 @@
+import {
+  ObjectColumn,
+  Record,
+  ReferenceArray,
+  ReferenceArrayColumn,
+  StringColumn,
+  Table,
+  withRecordColumns,
+} from '@proteinjs/db';
+
+/**
+ * Tables for `ServiceUpdateVerbs.test.ts` (the service-path RMW update verbs:
+ * `updateArrayMembership` / `updatePreserving`).
+ *
+ * Defined here rather than in the test file so the reflection build registers them as `Table`
+ * loadables — `tableByName` (which the db-service singleton and the `Table` wire serializer both
+ * resolve through) must be able to find them for the test's RPC-boundary simulation.
+ */
+
+/**
+ * Mutable stand-in for the ambient caller identity a scoped column reads (in production, the
+ * session's user id). Tests reassign `current` to act as different callers.
+ */
+export const serviceVerbsScopeContext = { current: 'scope-a' };
+
+export type ServiceVerbsDocBody = { content?: string; style?: { color?: string } };
+
+export interface ServiceVerbsDoc extends Record {
+  title: string;
+  scope?: string;
+  /** Self-referencing children list — the reference-array shape membership ops target. */
+  members?: ReferenceArray<ServiceVerbsDoc>;
+  /** Plain-JSON column with sub-path ownership split across writers (content vs style). */
+  body?: ServiceVerbsDocBody;
+}
+
+/** Mirrors the generic scoped-record mechanism: scope forced on insert, immutable, injected into every non-system query. */
+export class ServiceVerbsDocTable extends Table<ServiceVerbsDoc> {
+  public name = 'db_test_service_update_verbs_doc';
+  public columns = withRecordColumns<ServiceVerbsDoc>({
+    title: new StringColumn('title'),
+    scope: new StringColumn('scope', {
+      defaultValue: async () => serviceVerbsScopeContext.current,
+      forceDefaultValue: (runAsSystem) => !runAsSystem,
+      immutable: (runAsSystem) => !runAsSystem,
+      addToQuery: async (qb, runAsSystem) => {
+        if (!runAsSystem) {
+          qb.condition({ field: 'scope', operator: 'IN', value: [serviceVerbsScopeContext.current] });
+        }
+      },
+    }),
+    members: new ReferenceArrayColumn('members', 'db_test_service_update_verbs_doc', false),
+    body: new ObjectColumn<ServiceVerbsDocBody>('body'),
+  });
+}