@serve.zone/dcrouter 32.1.1 → 32.1.2

package/ts/db/documents/classes.ops-config-event.doc.ts

@@ -9,6 +9,20 @@ import type {
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
+const PRUNE_BATCH_SIZE = 500;
+
+/**
+ * "Not acknowledged yet" as a typed predicate: the field is absent (how the ORM stores
+ * an unset optional field) or explicitly null (how older documents may carry it). This
+ * is exactly what the previous `{ acknowledgedAt: null }` selector matched.
+ */
+const unacknowledgedBranches = (): Array<{
+  acknowledgedAt: { $exists: false } | { $type: 'null' };
+}> => [
+  { acknowledgedAt: { $exists: false } },
+  { acknowledgedAt: { $type: 'null' } },
+];
+
 export interface IOpsConfigEventFilter {
   acknowledged?: boolean;
   severity?: TOpsConfigEventSeverity;
@@ -87,21 +101,6 @@ export class OpsConfigEventDoc extends plugins.smartdata.SmartDataDbDoc<OpsConfi
     return savable;
   }
 
-  private static async getNativeCollection() {
-    const smartdataCollection = (OpsConfigEventDoc as typeof OpsConfigEventDoc & {
-      collection: plugins.smartdata.SmartdataCollection<OpsConfigEventDoc>;
-    }).collection;
-    await smartdataCollection.init();
-    const probe = new OpsConfigEventDoc();
-    await smartdataCollection.markUniqueIndexes(probe.uniqueIndexes || []);
-    await smartdataCollection.createRegularIndexes(probe.regularIndexes || []);
-    return smartdataCollection.mongoDbCollection;
-  }
-
-  private static hydrate(rawArg: Record<string, unknown>): OpsConfigEventDoc {
-    return OpsConfigEventDoc.createInstanceFromMongoDbNativeDoc(rawArg as any);
-  }
-
   public static async upsertOpenEvent(optionsArg: {
     id: string;
     openDedupeKey: string;
@@ -112,9 +111,13 @@ export class OpsConfigEventDoc extends plugins.smartdata.SmartDataDbDoc<OpsConfi
     context: IOpsConfigEventContext;
     createdAt: number;
   }): Promise<{ event: OpsConfigEventDoc; created: boolean }> {
-    const collection = await OpsConfigEventDoc.getNativeCollection();
-    const timestamp = new Date(optionsArg.createdAt).toISOString();
-    const result = await collection.updateOne(
+    // Deduplication is arbitrated by the sparse unique `openDedupeKey` index: the filter
+    // anchors on that key, so two writers racing the same open occurrence either update
+    // it or lose the insert branch to the index. `$setOnInsert` seeds the `@unI()`
+    // identity on the insert branch only — the client refuses an identity seed without
+    // `upsert: true` and refuses a seed that contradicts an identity anchor in the
+    // filter, so the created event is addressable by `id` and immutable afterwards.
+    const result = await OpsConfigEventDoc.atomicUpdate<OpsConfigEventDoc>(
       { openDedupeKey: optionsArg.openDedupeKey },
       {
         $set: {
@@ -122,80 +125,72 @@ export class OpsConfigEventDoc extends plugins.smartdata.SmartDataDbDoc<OpsConfi
           detail: optionsArg.detail,
           context: optionsArg.context,
           createdAt: optionsArg.createdAt,
-          _updatedAt: timestamp,
         },
         $setOnInsert: {
           id: optionsArg.id,
           category: optionsArg.category,
           title: optionsArg.title,
           openDedupeKey: optionsArg.openDedupeKey,
-          _createdAt: timestamp,
         },
       },
       { upsert: true },
     );
-    const raw = await collection.findOne({ openDedupeKey: optionsArg.openDedupeKey });
-    if (!raw) throw new Error('Failed to read the recorded platform configuration event');
-    return {
-      event: OpsConfigEventDoc.hydrate(raw as Record<string, unknown>),
-      created: result.upsertedCount > 0,
-    };
+    const event = await OpsConfigEventDoc.getInstance<OpsConfigEventDoc>({
+      openDedupeKey: optionsArg.openDedupeKey,
+    });
+    if (!event) throw new Error('Failed to read the recorded platform configuration event');
+    return { event, created: result.upsertedId !== null };
   }
 
   public static async findFiltered(
     filter: IOpsConfigEventFilter = {},
   ): Promise<{ events: OpsConfigEventDoc[]; total: number; nextCursor?: IOpsConfigEventCursor }> {
-    const selector: Record<string, unknown> = {};
+    const selector: plugins.smartdata.MongoFilter<OpsConfigEventDoc> = {};
     if (filter.acknowledged === true) selector.acknowledgedAt = { $gt: 0 };
-    if (filter.acknowledged === false) selector.acknowledgedAt = null;
+    if (filter.acknowledged === false) Object.assign(selector, { $or: unacknowledgedBranches() });
     if (filter.severity) selector.severity = filter.severity;
     if (filter.category) selector.category = filter.category;
     const requestedLimit = Number.isSafeInteger(filter.limit) && filter.limit! > 0
       ? filter.limit!
       : 100;
     const limit = Math.min(requestedLimit, 200);
-    const countSelector = structuredClone(selector);
     if (filter.cursor) {
       if (!Number.isSafeInteger(filter.cursor.createdAt) || filter.cursor.createdAt < 0
         || typeof filter.cursor.id !== 'string' || !filter.cursor.id.trim()) {
         throw new Error('Invalid platform configuration event cursor');
       }
-      selector.$or = [
-        { createdAt: { $lt: filter.cursor.createdAt } },
-        { createdAt: filter.cursor.createdAt, id: { $lt: filter.cursor.id } },
-      ];
     }
-    const collection = await OpsConfigEventDoc.getNativeCollection();
-    const cursor = collection
-      .find(selector)
-      .sort({ createdAt: -1, id: -1 })
-      .limit(limit + 1);
-    try {
-      const [rawEvents, total] = await Promise.all([
-        cursor.toArray(),
-        collection.countDocuments(countSelector),
-      ]);
-      const hasMore = rawEvents.length > limit;
-      const pageRows = rawEvents.slice(0, limit);
-      const lastRow = pageRows.at(-1) as Record<string, unknown> | undefined;
-      return {
-        events: pageRows.map((rawArg) => OpsConfigEventDoc.hydrate(rawArg as Record<string, unknown>)),
-        total,
-        ...(hasMore && lastRow ? {
+    // Seek pagination over (createdAt, id) with the unique id as tiebreaker, plus the
+    // unpaged total for the same filter.
+    const page = await OpsConfigEventDoc.getPagedInstances<OpsConfigEventDoc>({
+      filter: selector,
+      sortField: 'createdAt',
+      uniqueField: 'id',
+      sortDirection: 'desc',
+      limit,
+      withTotal: true,
+      ...(filter.cursor
+        ? { cursor: { sortValue: filter.cursor.createdAt, uniqueValue: filter.cursor.id } }
+        : {}),
+    });
+    return {
+      events: page.documents,
+      total: page.total ?? 0,
+      ...(page.nextCursor
+        ? {
           nextCursor: {
-            createdAt: Number(lastRow.createdAt),
-            id: String(lastRow.id),
+            createdAt: Number(page.nextCursor.sortValue),
+            id: String(page.nextCursor.uniqueValue),
           },
-        } : {}),
-      };
-    } finally {
-      await cursor.close();
-    }
+        }
+        : {}),
+    };
   }
 
   public static async countUnacknowledged(): Promise<number> {
-    const collection = await OpsConfigEventDoc.getNativeCollection();
-    return await collection.countDocuments({ acknowledgedAt: null });
+    return await OpsConfigEventDoc.getCount<OpsConfigEventDoc>({
+      $or: unacknowledgedBranches(),
+    });
   }
 
   /** Acknowledge the given event ids; returns how many were newly acknowledged. */
@@ -208,16 +203,23 @@ export class OpsConfigEventDoc extends plugins.smartdata.SmartDataDbDoc<OpsConfi
     }
     const uniqueIds = Array.from(new Set(ids));
     if (uniqueIds.length === 0) return 0;
-    const collection = await OpsConfigEventDoc.getNativeCollection();
     const now = Date.now();
-    const result = await collection.updateMany(
-      { id: { $in: uniqueIds }, acknowledgedAt: null },
+    // The per-id `$or` is the equality anchor a plural atomic write requires; the second
+    // branch keeps the "only newly acknowledged rows count" guard.
+    const result = await OpsConfigEventDoc.atomicUpdateMany<OpsConfigEventDoc>(
+      {
+        $and: [
+          { $or: uniqueIds.map((idArg) => ({ id: idArg })) },
+          { $or: unacknowledgedBranches() },
+        ],
+      },
       {
         $set: {
           acknowledgedBy: userId,
           acknowledgedAt: now,
-          _updatedAt: new Date(now).toISOString(),
         },
+        // Presence of openDedupeKey is the open-event uniqueness authority, so
+        // acknowledging must release it.
         $unset: { openDedupeKey: '' },
       },
     );
@@ -228,27 +230,28 @@ export class OpsConfigEventDoc extends plugins.smartdata.SmartDataDbDoc<OpsConfi
   public static async pruneAcknowledged(maxAgeMs: number): Promise<number> {
     const cutoff = Date.now() - maxAgeMs;
     let pruned = 0;
-    const collection = await OpsConfigEventDoc.getNativeCollection();
     while (true) {
-      const cursor = collection
-        .find(
-          { acknowledgedAt: { $lt: cutoff } },
-          { projection: { _id: 1 } },
-        )
-        .sort({ acknowledgedAt: 1, _id: 1 })
-        .limit(500);
-      let rows: Array<{ _id: unknown }>;
+      const cursor = await OpsConfigEventDoc.getCursor<OpsConfigEventDoc>(
+        { acknowledgedAt: { $lt: cutoff } },
+        {
+          projection: { id: 1 },
+          sort: { acknowledgedAt: 1, id: 1 },
+          limit: PRUNE_BATCH_SIZE,
+        },
+      );
+      let rows: OpsConfigEventDoc[];
       try {
-        rows = await cursor.toArray() as Array<{ _id: unknown }>;
+        rows = await cursor.toArray();
       } finally {
         await cursor.close();
       }
       if (rows.length === 0) break;
-      const deleteFilter: Record<string, any> = {
-        _id: { $in: rows.map((rowArg) => rowArg._id) },
+      // Anchored on the scanned identities, with the retention guard re-evaluated
+      // server-side so an event acknowledged after the scan is never pruned early.
+      const result = await OpsConfigEventDoc.atomicDeleteMany<OpsConfigEventDoc>({
+        $or: rows.map((rowArg) => ({ id: rowArg.id })),
         acknowledgedAt: { $lt: cutoff },
-      };
-      const result = await collection.deleteMany(deleteFilter);
+      });
       if (result.deletedCount === 0) break;
       pruned += result.deletedCount;
     }

package/ts/db/documents/classes.smartmta-storage.doc.ts

@@ -3,11 +3,26 @@ import { DcRouterDb } from '../classes.dcrouter-db.js';
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
-@plugins.smartdata.Collection(() => getDb())
+/**
+ * SmartMTA's durable key/value space.
+ *
+ * Every document is content-addressed: `id` is `sha256(normalizedKey)` and owns the stored
+ * `_id`, so the primary key — not a secondary index — is the uniqueness authority that makes
+ * a write a single race-free upsert. That is what `identityAsDocumentId: 'id'` declares, and
+ * it holds for every row dcrouter ever wrote here, because the manager has always derived
+ * both `_id` and `id` from the same hash.
+ *
+ * The declaration is irreversible: from here on reads are answered through `_id`, so a row
+ * whose `_id` is not its identity would no longer resolve, and the client refuses a unique
+ * index on `id` because the primary key is the only uniqueness authority a document-id
+ * identity may have.
+ */
+@plugins.smartdata.Collection(() => getDb(), { identityAsDocumentId: 'id' })
 export class SmartMtaStorageDoc extends plugins.smartdata.SmartDataDbDoc<
   SmartMtaStorageDoc,
   SmartMtaStorageDoc
 > {
+  @plugins.smartdata.unI()
   @plugins.smartdata.svDb()
   public id!: string;
 

package/ts/db/documents/classes.webpush-admission.doc.ts

@@ -9,6 +9,20 @@ const getDb = () => DcRouterDb.getInstance().getDb();
  * A credential rotation must not reset these counters, so the stable binding
  * id and lifecycle generation are the authority rather than a credential id.
  */
+// Both indexes are declared under the exact names the released Web Push schema migration
+// created them with (`ts_migrations/index.ts` via `ts/webpush/webpush-indexes.ts`), so model
+// initialization verifies the existing topology instead of installing a second, differently
+// named index over the same key.
+@plugins.smartdata.namedIndex({
+  name: 'web_push_admission_binding_unique',
+  key: { bindingId: 1, lifecycleGeneration: 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_admission_ttl',
+  key: { purgeAt: 1 },
+  options: { expireAfterSeconds: 0 },
+})
 @plugins.smartdata.Collection(() => getDb())
 export class WebPushAdmissionDoc extends plugins.smartdata.SmartDataDbDoc<
   WebPushAdmissionDoc,
@@ -40,9 +54,4 @@ export class WebPushAdmissionDoc extends plugins.smartdata.SmartDataDbDoc<
 
   @plugins.smartdata.svDb()
   public purgeAt!: Date;
-
-  public static getNativeCollection():
-    plugins.smartdata.SmartdataCollection<WebPushAdmissionDoc>['mongoDbCollection'] {
-    return getDb().mongoDb.collection('WebPushAdmissionDoc');
-  }
 }

package/ts/db/documents/classes.webpush-binding.doc.ts

@@ -47,6 +47,53 @@ export interface IWebPushStoredControllerFence {
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
+// Every index is declared under the exact name the released Web Push schema migration created
+// it with (`ts_migrations/index.ts` via `ts/webpush/webpush-indexes.ts`), so model initialization
+// verifies the existing topology instead of installing a second, differently named index over the
+// same key. `test/test.webpush-persisted-bytes.node.ts` keeps both declarations in lockstep.
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_id_unique',
+  key: { id: 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_owner_unique',
+  key: { ownerGatewayClientType: 1, ownerGatewayClientId: 1, ownerAppInstanceId: 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_credential_unique',
+  key: { 'credential.id': 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_previous_credential_lookup',
+  key: { 'previousCredentials.id': 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_previous_credential_cleanup',
+  key: { 'previousCredentials.validUntil': 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_rotation_recovery_cleanup',
+  key: { 'credentialRotationRecovery.expiresAt': 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_vapid_status_cleanup',
+  key: { 'vapidKeys.status': 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_vapid_retire_after_cleanup',
+  key: { 'vapidKeys.retireAfter': 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_disabled_cleanup',
+  key: { enabled: 1, lifecycleGeneration: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_binding_deleted_cleanup',
+  key: { deletedAt: 1, lifecycleGeneration: 1 },
+})
 @plugins.smartdata.Collection(() => getDb())
 export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
   WebPushBindingDoc,
@@ -70,7 +117,8 @@ export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
   @plugins.smartdata.svDb()
   public status!: plugins.servezoneInterfaces.data.TWebPushBindingStatus;
 
-  @plugins.smartdata.svDb()
+  /** `credential.id` is the compare-and-set anchor of credential rotation and a unique index. */
+  @plugins.smartdata.svDb({ atomicPaths: ['id'] })
   public credential!: IWebPushStoredCredential;
 
   /** At most one still-valid overlap credential; expired entries are scrubbed. */
@@ -78,7 +126,10 @@ export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
   public previousCredentials: IWebPushStoredCredential[] = [];
 
   /** MUST BE ABSENT outside the bounded idempotent credential-rotation replay window. */
-  @plugins.smartdata.svDb()
+  @plugins.smartdata.svDb({
+    // Expiry cleanup fences on the exact recovery record it observed.
+    atomicPaths: ['requestedCredentialId', 'resultingCredentialId', 'expiresAt'],
+  })
   public credentialRotationRecovery?: IWebPushCredentialRotationRecovery;
 
   @plugins.smartdata.svDb()
@@ -107,11 +158,6 @@ export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
   @plugins.smartdata.svDb()
   public deletedAt?: number;
 
-  public static getNativeCollection():
-    plugins.smartdata.SmartdataCollection<WebPushBindingDoc>['mongoDbCollection'] {
-    return getDb().mongoDb.collection('WebPushBindingDoc');
-  }
-
   public override async createSavableObject(): Promise<WebPushBindingDoc> {
     const savable = await super.createSavableObject();
     if (savable.credential.secretHash === undefined) {

package/ts/db/documents/classes.webpush-spool.doc.ts

@@ -4,6 +4,45 @@ import type { IWebPushEncryptedEnvelope } from '../../webpush/classes.webpush-cr
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
+// Every index is declared under the exact name the released Web Push schema migration created
+// it with (`ts_migrations/index.ts` via `ts/webpush/webpush-indexes.ts`), so model initialization
+// verifies the existing topology instead of installing a second, differently named index over the
+// same key. `test/test.webpush-persisted-bytes.node.ts` keeps both declarations in lockstep.
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_id_unique',
+  key: { id: 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_idempotency_unique',
+  key: { bindingId: 1, lifecycleGeneration: 1, credentialId: 1, idempotencyKeyDigest: 1 },
+  options: { unique: true },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_delivery_scan',
+  key: { state: 1, nextAttemptAt: 1, leaseExpiresAt: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_cancellation_scan',
+  key: { bindingId: 1, lifecycleGeneration: 1, subscriptionId: 1, state: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_cancelled_lease_scan',
+  key: { state: 1, cancelRequestedAt: 1, leaseExpiresAt: 1, id: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_lifecycle_drain_scan',
+  key: { bindingId: 1, lifecycleGeneration: 1, state: 1, leaseExpiresAt: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_vapid_retirement_scan',
+  key: { bindingId: 1, lifecycleGeneration: 1, vapidKeyId: 1, state: 1 },
+})
+@plugins.smartdata.namedIndex({
+  name: 'web_push_spool_terminal_ttl',
+  key: { purgeAt: 1 },
+  options: { expireAfterSeconds: 0 },
+})
 @plugins.smartdata.Collection(() => getDb())
 export class WebPushSpoolDoc extends plugins.smartdata.SmartDataDbDoc<
   WebPushSpoolDoc,
@@ -106,11 +145,6 @@ export class WebPushSpoolDoc extends plugins.smartdata.SmartDataDbDoc<
   @plugins.smartdata.svDb()
   public purgeAt?: Date;
 
-  public static getNativeCollection():
-    plugins.smartdata.SmartdataCollection<WebPushSpoolDoc>['mongoDbCollection'] {
-    return getDb().mongoDb.collection('WebPushSpoolDoc');
-  }
-
   public override async createSavableObject(): Promise<WebPushSpoolDoc> {
     const savable = await super.createSavableObject();
     for (const field of [

package/ts/dns/manager.dns.ts

@@ -1501,7 +1501,9 @@ export class DnsManager {
           rec.providerRecordId = undefined;
           rec.updatedAt = now;
           await rec.save({ session });
-          await db.mongoDb.collection('DnsRecordDoc').updateOne(
+          // save() persists set fields only, so the provider link is removed with an
+          // explicit atomic $unset inside the same transaction.
+          await DnsRecordDoc.atomicUpdate<DnsRecordDoc>(
             { id: rec.id },
             { $unset: { providerRecordId: '' } },
             { session },
@@ -1520,7 +1522,9 @@ export class DnsManager {
         domain.updatedAt = now;
         domain.authoritative = ownership.verified;
         await domain.save({ session });
-        await db.mongoDb.collection('DomainDoc').updateOne(
+        // Same reason as above: the provider-managed fields must disappear from the
+        // stored document, which only an atomic $unset expresses.
+        await DomainDoc.atomicUpdate<DomainDoc>(
           { id: domain.id },
           {
             $unset: {