@modelprofile.com/flexharness 11.0.0 → 11.1.0

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -2,6 +2,7 @@ import * as plugins from './plugins.js';
 import {
   FlexHarnessStoreCommitUncertainError,
   FlexHarnessStoreFormatError,
+  FlexHarnessStorePurgedError,
   FlexHarnessValidationError,
 } from '../ts/errors.js';
 
@@ -40,6 +41,7 @@ export interface IFlexRecordMutation<TValue> {
 
 export const FLEX_RECORD_COLLECTION = 'flexharness_records';
 export const FLEX_CHUNK_COLLECTION = 'flexharness_chunks';
+export const FLEX_NAMESPACE_COLLECTION = 'flexharness_namespaces';
 
 /**
  * UTF-16 code units a record holds inline, and the size of each chunk of a longer payload. A
@@ -89,12 +91,31 @@ export class FlexChunkDocument extends plugins.SmartDataDbDoc<FlexChunkDocument,
   public data!: string;
 }
 
+/**
+ * One storage namespace. Every record creation in the namespace increments `creationCount` in
+ * its transaction, so a concurrent fenced purge, which sets `fenced`, conflicts with it. A fenced
+ * namespace accepts no new record.
+ */
+export class FlexNamespaceDocument extends plugins.SmartDataDbDoc<FlexNamespaceDocument, FlexNamespaceDocument> {
+  public namespaceKey!: string;
+  public fenced!: boolean;
+  public creationCount!: number;
+}
+
 type TRecordModel = typeof FlexRecordDocument;
 type TChunkModel = typeof FlexChunkDocument;
+type TNamespaceModel = typeof FlexNamespaceDocument;
 
-function bindModels(db: plugins.SmartdataDb): { records: TRecordModel; chunks: TChunkModel } {
+interface IBoundModels {
+  records: TRecordModel;
+  chunks: TChunkModel;
+  namespaces: TNamespaceModel;
+}
+
+function bindModels(db: plugins.SmartdataDb): IBoundModels {
   class BoundRecord extends FlexRecordDocument {}
   class BoundChunk extends FlexChunkDocument {}
+  class BoundNamespace extends FlexNamespaceDocument {}
   plugins.defineCollectionModel(BoundRecord, db, {
     collectionName: FLEX_RECORD_COLLECTION,
     persistedFields: [
@@ -142,7 +163,16 @@ function bindModels(db: plugins.SmartdataDb): { records: TRecordModel; chunks: T
       { name: 'flexharness_chunk_namespace', key: { namespaceKey: 1, domain: 1 } },
     ],
   });
-  return { records: BoundRecord, chunks: BoundChunk };
+  plugins.defineCollectionModel(BoundNamespace, db, {
+    collectionName: FLEX_NAMESPACE_COLLECTION,
+    persistedFields: ['namespaceKey', 'fenced', 'creationCount'],
+    numericFields: ['creationCount'],
+    identityFields: ['namespaceKey'],
+    indexes: [
+      { name: 'flexharness_namespace_key', key: { namespaceKey: 1 }, options: { unique: true } },
+    ],
+  });
+  return { records: BoundRecord, chunks: BoundChunk, namespaces: BoundNamespace };
 }
 
 interface IResolvedAddress {
@@ -208,13 +238,15 @@ export interface IFlexRecordStoreOptions {
  * Compare-and-swap records on `@lossless.org/client/nosqldb`. A write reads the head, decides,
  * writes any chunks, and swaps the head only while its `writeToken` is unchanged. Chunks of a
  * replaced or abandoned payload are swept in a transaction that also touches the head, so a
- * concurrent deletion or writer can never lose chunks its head references.
+ * concurrent deletion or writer can never lose chunks its head references. A head is created in
+ * a transaction that checks its namespace document, so a fenced namespace gains no record.
  */
 export class FlexRecordStore {
   private readonly db: plugins.SmartdataDb;
   private readonly timeoutMs: number;
   private readonly records: TRecordModel;
   private readonly chunks: TChunkModel;
+  private readonly namespaces: TNamespaceModel;
   private preparation?: Promise<void>;
 
   constructor(options: IFlexRecordStoreOptions) {
@@ -224,10 +256,10 @@ export class FlexRecordStore {
     }
     this.db = options.db;
     this.timeoutMs = timeoutMs;
-    ({ records: this.records, chunks: this.chunks } = bindModels(options.db));
+    ({ records: this.records, chunks: this.chunks, namespaces: this.namespaces } = bindModels(options.db));
   }
 
-  /** Creates or verifies both collections and their indexes once; a failed attempt is retried. */
+  /** Creates or verifies the collections and their indexes once; a failed attempt is retried. */
   public prepare(): Promise<void> {
     this.preparation ??= this.prepareCollections().catch((error: unknown) => {
       this.preparation = undefined;
@@ -251,6 +283,7 @@ export class FlexRecordStore {
     const options = { mode: 'ensureCompatible' as const, timeoutMs: this.timeoutMs };
     await this.records.prepareCollection(options);
     await this.chunks.prepareCollection(options);
+    await this.namespaces.prepareCollection(options);
   }
 
   private resolve(address: IFlexRecordAddress): IResolvedAddress {
@@ -318,26 +351,57 @@ export class FlexRecordStore {
     );
   }
 
-  /** Deletes every record and chunk of a storage namespace, in one domain or in every domain. */
+  /**
+   * Deletes every record and chunk of a storage namespace in one domain, or in every domain
+   * together with its namespace document unless a fence holds it.
+   */
   public async purgeNamespace(storageKey: string, domain?: TFlexRecordDomain): Promise<void> {
     await this.prepare();
     const namespaceKey = digest(storageKey);
     await this.deleteInTransaction(
       `${FLEX_RECORD_COLLECTION}/${domain ?? 'all'}/namespace/${namespaceKey}`,
       domain ? { namespaceKey, domain } : { namespaceKey },
+      domain
+        ? undefined
+        : (transaction) => this.namespaces.atomicDeleteMany(
+          { namespaceKey, fenced: false },
+          { session: transaction },
+        ),
+    );
+  }
+
+  /**
+   * Fences a storage namespace and deletes every record and chunk of it in one transaction. The
+   * fence is permanent: every later record creation in the namespace is refused, and a creation
+   * that runs concurrently either commits first and is deleted, or conflicts and is refused.
+   */
+  public async fenceNamespace(storageKey: string): Promise<void> {
+    await this.prepare();
+    const namespaceKey = digest(storageKey);
+    await this.deleteInTransaction(
+      `${FLEX_RECORD_COLLECTION}/all/namespace/${namespaceKey}`,
+      { namespaceKey },
+      (transaction) => this.namespaces.atomicUpdate(
+        { namespaceKey },
+        { $set: { fenced: true }, $setOnInsert: { creationCount: 0 } },
+        { upsert: true, session: transaction },
+      ),
     );
   }
 
+  /** Deletes the selected records and chunks, after `namespace` changes the namespace document. */
   private async deleteInTransaction(
     path: string,
     selector:
       | { recordId: string; domain: TFlexRecordDomain }
       | { ownerKey: string; domain: { $in: TFlexRecordDomain[] } }
       | { namespaceKey: string; domain?: TFlexRecordDomain },
+    namespace?: (transaction: plugins.SmartdataSession) => Promise<unknown>,
   ): Promise<void> {
     const session = this.db.createSession();
     try {
       await session.withTransaction(async (transaction) => {
+        await namespace?.(transaction);
         await this.records.atomicDeleteMany(selector, { session: transaction });
         await this.chunks.atomicDeleteMany(selector, { session: transaction });
       }, { timeoutMS: this.timeoutMs });
@@ -480,11 +544,9 @@ export class FlexRecordStore {
     head.payload = text;
     head.chunked = false;
     try {
-      await this.records.insert(head, { timeoutMS: this.timeoutMs });
-      return true;
+      return await this.create(resolved, head);
     } catch (error) {
-      if (isUniqueConflict(error)) return false;
-      if (isDefiniteRejection(error)) throw error;
+      if (plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed') throw error;
       throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
     }
   }
@@ -497,12 +559,42 @@ export class FlexRecordStore {
     head.revision = 0;
     head.payload = null;
     head.chunked = true;
+    return await this.create(resolved, head) ? head : undefined;
+  }
+
+  /**
+   * Inserts a new head unless a fence holds its namespace. The transaction also increments the
+   * namespace document, so it conflicts with a concurrent fenced purge: whichever commits second
+   * retries on a snapshot that holds the other. Returns false when another writer created the
+   * record first.
+   */
+  private async create(resolved: IResolvedAddress, head: FlexRecordDocument): Promise<boolean> {
+    const session = this.db.createSession();
     try {
-      await this.records.insert(head, { timeoutMS: this.timeoutMs });
-      return head;
+      await session.withTransaction(async (transaction) => {
+        const namespace = await this.namespaces.getInstance(
+          { namespaceKey: resolved.namespaceKey },
+          { session: transaction },
+        );
+        if (namespace?.fenced) throw new FlexHarnessStorePurgedError(resolved.path);
+        await this.namespaces.atomicUpdate(
+          { namespaceKey: resolved.namespaceKey },
+          { $inc: { creationCount: 1 }, $setOnInsert: { fenced: false } },
+          { upsert: true, session: transaction },
+        );
+        await this.records.insert(head, { session: transaction });
+      }, { timeoutMS: this.timeoutMs });
+      return true;
     } catch (error) {
-      if (isUniqueConflict(error)) return undefined;
+      if (
+        isUniqueConflict(error) &&
+        plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed'
+      ) {
+        return false;
+      }
       throw error;
+    } finally {
+      await session.close();
     }
   }
 

package/ts_stores_nosqldb/index.ts

@@ -1,9 +1,11 @@
 export {
   NoSqlFlexHarnessStores,
+  type INoSqlFlexHarnessPurgeOptions,
   type INoSqlFlexHarnessStoresOptions,
 } from './classes.nosqldbstores.js';
 export {
   FLEX_CHUNK_COLLECTION,
+  FLEX_NAMESPACE_COLLECTION,
   FLEX_RECORD_CHUNK_CODE_UNITS,
   FLEX_RECORD_COLLECTION,
 } from './classes.recordstore.js';

package/ts_stores_nosqldb/readme.md

@@ -19,17 +19,25 @@ const harness = new FlexHarness({ scopeResolver, modelResolver, stores });
 
 `NoSqlFlexHarnessStores` implements every `IFlexHarnessStores` domain: scopes, projections with undo and redo history, remembered permissions, project management, Agent events with their archives, and background jobs. Several processes may open the same database; every save is a compare-and-swap on the stored record, so a stale writer gets the domain's conflict error instead of overwriting a newer snapshot.
 
-The database is the application's. The stores never close it, and they need NoSQLDB or a MongoDB deployment with transactions. `prepare()` creates or verifies the `flexharness_records` and `flexharness_chunks` collections and their indexes; every store operation awaits the same preparation, so calling it at startup only moves that work and its failure forward. `operationTimeoutMs` (1 to 120000, default 30000) bounds every database call and transaction.
+The database is the application's. The stores never close it, and they need NoSQLDB or a MongoDB deployment with transactions. `prepare()` creates or verifies the `flexharness_records`, `flexharness_chunks` and `flexharness_namespaces` collections and their indexes; every store operation awaits the same preparation, so calling it at startup only moves that work and its failure forward. `operationTimeoutMs` (1 to 120000, default 30000) bounds every database call and transaction.
 
 A snapshot of up to `FLEX_RECORD_CHUNK_CODE_UNITS` UTF-16 code units of JSON is stored inside its record. A longer one is split into chunks of that size, each below 3 MiB of UTF-8, so a snapshot may exceed the 16 MiB document limit of NoSQLDB and MongoDB. Chunks are written before the record swaps to them. The chunks a record no longer references are removed by a later write of that record, in a transaction that also touches the record, and deleting a session or purging a namespace removes its records and chunks in one transaction. A writer that crashes between writing its chunks and swapping the record leaves only unreferenced chunks, never a record that points at missing ones. They are written against the record's current write token, which a concurrent writer may still win with, so the write after the next one removes them, or the deletion of the session or namespace does.
 
-`stores.purgeNamespace(storageKey)` is the durable deletion of a scope: it removes every record and chunk of that storage namespace in every domain, including the scope snapshot and the project-management tombstones that deleting its sessions keeps, in one transaction. Deleting every session alone leaves those records, keyed by the storage key. Call it only after stopping new admission for every alias of the scope and awaiting `harness.retireScope()` on every harness that owns it:
+`stores.purgeNamespace(storageKey)` is the durable deletion of a scope: it removes every record and chunk of that storage namespace in every domain, including the scope snapshot and the project-management tombstones that deleting its sessions keeps, in one transaction. Deleting every session alone leaves those records, keyed by the storage key. Stop new admission for every alias of the scope first. A plain purge must then wait until `harness.retireScope()` has returned on every harness that owns the scope: a harness that still holds it can write records back, because the purge removed the revisions its writes would conflict with.
 
 ```typescript
 await harness.retireScope(scopeId);
 await stores.purgeNamespace(storageKey);
 ```
 
+When a harness may still hold the scope, such as one on another server, purge with `{ fence: true }`. The same transaction fences the namespace in `flexharness_namespaces`: every later record creation in it, from any process, is refused with `FlexHarnessStorePurgedError`, and a write that extends a purged record conflicts, so nothing a stale harness writes lands. A creation that races the purge either commits first and is removed with the rest, or is refused. The fence is permanent, so the storage key is never usable again, and a later purge without the fence does not lift it. FlexHarness reports a refused write of a session operation through `externalErrorProjector`, like every other store failure there.
+
+```typescript
+await stores.purgeNamespace(storageKey, { fence: true });
+```
+
+Every record creation is a transaction that checks the namespace's fence document and writes to it, so concurrent creations in one namespace contend on that document and the driver retries the ones that conflict.
+
 A record swap that loses to a concurrent writer is decided again against the newer record, up to eight times, with a bounded exponential backoff between attempts; a writer that still loses gets the domain's conflict error.
 
 A save that may have reached the database without a confirmation, such as a timed-out or interrupted record write or a deletion transaction with an unknown commit outcome, rejects with `FlexHarnessStoreCommitUncertainError` (operation `write` or `delete`). FlexHarness then fences the namespace, as it does for the JSON file stores.