@serve.zone/dcrouter 32.1.1 → 32.1.2

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '32.1.1',
+    version: '32.1.2',
     description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfd2ViLzAwX2NvbW1pdGluZm9fZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRztJQUN4QixJQUFJLEVBQUUsc0JBQXNCO0lBQzVCLE9BQU8sRUFBRSxRQUFRO0lBQ2pCLFdBQVcsRUFBRSwwRUFBMEU7Q0FDeEYsQ0FBQSJ9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "32.1.1",
+  "version": "32.1.2",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
     "@git.zone/tsbuild": "^4.5.0",
     "@git.zone/tsbundle": "^2.13.0",
     "@git.zone/tsdeno": "^1.8.0",
-    "@git.zone/tsdocker": "^3.5.8",
+    "@git.zone/tsdocker": "^3.6.0",
     "@git.zone/tsrun": "^2.0.6",
     "@git.zone/tstest": "^6.1.1",
     "@git.zone/tswatch": "^3.3.5",
@@ -36,7 +36,7 @@
     "@design.estate/dees-catalog": "^10.0.0",
     "@design.estate/dees-element": "^3.1.1",
     "@idp.global/sdk": "18.0.0",
-    "@lossless.org/client": "1.0.0",
+    "@lossless.org/client": "1.1.0",
     "@push.rocks/lik": "^6.4.1",
     "@push.rocks/projectinfo": "^5.1.0",
     "@push.rocks/qenv": "^6.1.4",

package/readme.md

@@ -350,6 +350,7 @@ Operational behavior:
 - Payloads are limited to 3,500 UTF-8 bytes, TTL must be from 1 through 86,400 seconds, delivery makes at most eight attempts, and each retry sends the remaining TTL. Terminal rows retain only non-secret delivery metadata for seven days.
 - Subscription endpoints must be public HTTPS hostnames on port 443. DNS is bounded and pinned for the request; IP literals, credentials, fragments, and any answer containing a non-global address are rejected.
 - App credential rotation has a 15-minute overlap. VAPID rotation retains retiring keys for 90 days and, if necessary, until old queued items have terminally drained, with four VAPID keys maximum. Rotate before reaching that bound.
+- Startup asserts the index topology of `web_push_binding`, `web_push_admission` and `web_push_spool` against the declared model and requires an exact match: a declared index that is missing is re-created on bind, while a renamed or altered index, or an index nobody declared, fails startup closed. Remedy for a hand-added index: drop it (`db.<collection>.dropIndex('<name>')`) or add it to the `web-push-provider-schema` migration and the model declaration.
 - Upgrading to 32.0.0 reseals every stored Web Push envelope under new associated data, so `DCROUTER_WEB_PUSH_MASTER_KEY_RING` must hold the key each existing envelope names before the first 32.0.0 start; otherwise the `webpush-encryption-context` migration refuses by name and dcrouter does not start. The push payload also loses its `schemaVersion` member with `@serve.zone/interfaces` 32, so a service worker that reads it must stop expecting the field.
 - For a key-ring rotation, add new unique key material, set `currentKeyId`, restart, and keep old encryption keys until every VAPID, delivery, and credential-recovery envelope using them has been rotated or purged. Keep each old HMAC key only until no current or overlap credential references its key id; terminal and idempotency retention does not require the old HMAC key. Remove old keys only after those conditions are true.
 - `deleteWebPushBinding` is a destructive tombstone operation: it revokes and removes all credential hashes, prior credentials, credential-recovery envelopes, and encrypted VAPID private keys; cancels and scrubs queued work; and clears admission state. Queued work is terminalized immediately, but an already sending request remains `sending` until the remote response wins or its lease expires. An expired lease after cancellation is recorded as a failed delivery with an unknown remote outcome, never as a confirmed cancellation. Delete/disable reports success only after that lifecycle drains; a bounded drain timeout returns a retryable failure, and the same controller operation resumes cleanup. Re-enabling the same owner creates a new lifecycle, credential, and VAPID key. Clients must recreate browser push subscriptions and must not reuse deleted credentials.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '32.1.1',
+  version: '32.1.2',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

package/ts/classes.dcrouter.ts

@@ -1353,7 +1353,7 @@ export class DcRouter {
         logger.log('info', `smartmigration: fresh install stamped to ${migrationResult.currentVersionAfter}`);
       }
 
-      this.storageManager = new SmartMtaStorageManager(this.dcRouterDb.getDb());
+      this.storageManager = new SmartMtaStorageManager();
 
       // Start the cache cleaner for TTL-based document cleanup
       const cleanupIntervalMs = (dbConfig.cleanupIntervalHours || 1) * 60 * 60 * 1000;

package/ts/config/classes.gateway-client-manager.ts

@@ -2,6 +2,8 @@ import * as plugins from '../plugins.js';
 import {
   GatewayClientDoc,
   type IGatewayClientPendingProvisioning,
+  type TGatewayClientMutableSet,
+  type TGatewayClientUnsettableField,
 } from '../db/index.js';
 import type { IGatewayClient } from '../../ts_interfaces/data/workhoster.js';
 import type { IGatewayCredentialLifecycle } from '../../ts_interfaces/data/route-management.js';
@@ -293,12 +295,12 @@ export class GatewayClientManager {
       stagedAt: now,
       stagedBy,
     };
-    const set: Record<string, unknown> = {
+    const set: TGatewayClientMutableSet = {
       credentialSequence,
       pendingProvisioning,
       updatedAt: now,
     };
-    const unset: string[] = [];
+    const unset: TGatewayClientUnsettableField[] = [];
     if (policyUnchanged) {
       set.name = normalized.name;
       if (normalized.description) {

package/ts/db/documents/classes.cached.email.ts

@@ -401,25 +401,19 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
   }
 
   private static async findLimited(
-    filter: Record<string, any>,
+    filter: plugins.smartdata.MongoFilter<CachedEmail>,
     limit: number,
-    sort?: Record<string, 1 | -1>,
+    sort?: plugins.smartdata.TSmartdataSort<CachedEmail>,
   ): Promise<CachedEmail[]> {
     const safeLimit = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 25;
     if (safeLimit === 0) {
       return [];
     }
-    const collection = (CachedEmail as typeof CachedEmail & {
-      collection: plugins.smartdata.SmartdataCollection<CachedEmail>;
-    }).collection;
-    const cursor = await collection.getCursor(
-      filter,
-      CachedEmail as unknown as typeof plugins.smartdata.SmartDataDbDoc,
-    );
-    if (sort) {
-      cursor.mongodbCursor.sort(sort);
-    }
-    cursor.mongodbCursor.limit(safeLimit);
+    const cursor = await CachedEmail.getCursor<CachedEmail>(filter, {
+      ...(sort ? { sort } : {}),
+      limit: safeLimit,
+      maxTimeMS: DB_OPERATION_TIMEOUT_MS,
+    });
     try {
       return await cursor.toArray();
     } finally {
@@ -427,10 +421,6 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
     }
   }
 
-  private static getNativeCollection() {
-    return getDb().mongoDb.collection('CachedEmail');
-  }
-
   private static buildListQuery(filterArg: ICachedEmailListFilter): Record<string, any> {
     const query: Record<string, any> = {};
     if (filterArg.direction) {
@@ -487,16 +477,21 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
     }
     const query = CachedEmail.buildListQuery(filterArg);
     query.acceptedAt = { $gte: cutoffArg };
-    const collection = await CachedEmail.getNativeCollection();
-    const row = await collection.findOne(
-      query,
-      {
-        projection: { acceptedAt: 1 },
-        sort: { acceptedAt: 1 },
-        timeoutMS: DB_OPERATION_TIMEOUT_MS,
-      },
-    );
-    const acceptedAt = Number(row?.acceptedAt);
+    // The oldest retained message is the first row of an ascending, single-field scan;
+    // the projection keeps the read off the message bodies.
+    const cursor = await CachedEmail.getCursor<CachedEmail>(query, {
+      projection: { acceptedAt: 1 },
+      sort: { acceptedAt: 1 },
+      limit: 1,
+      maxTimeMS: DB_OPERATION_TIMEOUT_MS,
+    });
+    let oldest: CachedEmail | null;
+    try {
+      oldest = await cursor.next(false);
+    } finally {
+      await cursor.close();
+    }
+    const acceptedAt = Number(oldest?.acceptedAt);
     return Number.isSafeInteger(acceptedAt) && acceptedAt >= 0 ? acceptedAt : null;
   }
 
@@ -518,46 +513,36 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
     }
     const query = CachedEmail.buildListQuery(filterArg);
     query.acceptedAt = { $gte: windowStartArg, $lte: windowEndArg };
-    const collection = await CachedEmail.getNativeCollection();
-    const cursor = collection.find(
-      query,
-      {
-        projection: { acceptedAt: 1, direction: 1, status: 1 },
-        batchSize: 1000,
-        timeoutMS: DB_OPERATION_TIMEOUT_MS,
-      },
-    );
-    try {
-      const buckets = new Map<number, ICachedEmailTrafficBucket>();
-      while (await cursor.hasNext()) {
-        const row = await cursor.next();
-        if (!row) {
-          continue;
-        }
-        const acceptedAt = Number(row.acceptedAt);
-        if (!Number.isSafeInteger(acceptedAt)) {
-          continue;
-        }
-        const bucketStart = Math.floor(acceptedAt / bucketSizeMsArg) * bucketSizeMsArg;
-        let bucket = buckets.get(bucketStart);
-        if (!bucket) {
-          bucket = { bucketStart, sent: 0, received: 0, failed: 0 };
-          buckets.set(bucketStart, bucket);
-        }
-        if (row.status === 'failed' || row.status === 'rejected') {
-          bucket.failed++;
-        } else if (row.direction === 'outbound') {
-          bucket.sent++;
-        } else if (row.direction === 'inbound') {
-          bucket.received++;
-        }
+    // Time buckets are derived per row, which no grouped-totals aggregation expresses,
+    // so the rows are streamed with a projection instead of being materialized.
+    const cursor = await CachedEmail.getCursor<CachedEmail>(query, {
+      projection: { acceptedAt: 1, direction: 1, status: 1 },
+      batchSize: 1000,
+      maxTimeMS: DB_OPERATION_TIMEOUT_MS,
+    });
+    const buckets = new Map<number, ICachedEmailTrafficBucket>();
+    await cursor.forEach(async (rowArg) => {
+      const acceptedAt = Number(rowArg.acceptedAt);
+      if (!Number.isSafeInteger(acceptedAt)) {
+        return;
       }
-      return [...buckets.values()].sort((firstArg, secondArg) => (
-        firstArg.bucketStart - secondArg.bucketStart
-      ));
-    } finally {
-      await cursor.close({ timeoutMS: DB_OPERATION_TIMEOUT_MS });
-    }
+      const bucketStart = Math.floor(acceptedAt / bucketSizeMsArg) * bucketSizeMsArg;
+      let bucket = buckets.get(bucketStart);
+      if (!bucket) {
+        bucket = { bucketStart, sent: 0, received: 0, failed: 0 };
+        buckets.set(bucketStart, bucket);
+      }
+      if (rowArg.status === 'failed' || rowArg.status === 'rejected') {
+        bucket.failed++;
+      } else if (rowArg.direction === 'outbound') {
+        bucket.sent++;
+      } else if (rowArg.direction === 'inbound') {
+        bucket.received++;
+      }
+    });
+    return [...buckets.values()].sort((firstArg, secondArg) => (
+      firstArg.bucketStart - secondArg.bucketStart
+    ));
   }
 
   public static async findRecentSecurityCandidates(

package/ts/db/documents/classes.email-traffic-bucket.doc.ts

@@ -2,6 +2,9 @@ import * as plugins from '../../plugins.js';
 import { DcRouterDb } from '../classes.dcrouter-db.js';
 
 const DB_OPERATION_TIMEOUT_MS = 5_000;
+const PRUNE_BATCH_SIZE = 500;
+/** One bucket per minute; retention is 24 hours, so this is a wide safety bound. */
+const MAX_LOADED_BUCKETS = 10_000;
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
@@ -37,17 +40,6 @@ export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
     super();
   }
 
-  private static async getNativeCollection() {
-    const smartdataCollection = (EmailTrafficBucketDoc as typeof EmailTrafficBucketDoc & {
-      collection: plugins.smartdata.SmartdataCollection<EmailTrafficBucketDoc>;
-    }).collection;
-    await smartdataCollection.init();
-    const probe = new EmailTrafficBucketDoc();
-    await smartdataCollection.markUniqueIndexes(probe.uniqueIndexes || []);
-    await smartdataCollection.createRegularIndexes(probe.regularIndexes || []);
-    return smartdataCollection.mongoDbCollection;
-  }
-
   private static validateSnapshot(snapshotArg: IEmailTrafficBucketSnapshot): void {
     const counts = [snapshotArg.sent, snapshotArg.received, snapshotArg.failed];
     if (
@@ -69,34 +61,33 @@ export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
     for (const snapshot of snapshotsArg) {
       EmailTrafficBucketDoc.validateSnapshot(snapshot);
     }
-    const collection = await EmailTrafficBucketDoc.getNativeCollection();
     const now = Date.now();
-    const updatedAt = new Date(now).toISOString();
-    await collection.bulkWrite(
+    // One bounded unordered batch (the client accepts 1..1000 operations and 16 MiB, so a
+    // 500-bucket flush always fits). Each operation is anchored on `bucketStart`, whose
+    // declared unique index makes the upsert idempotent under a retry, and `$max` is the
+    // server-side compare-and-write that lets a replayed absolute snapshot never lower a
+    // counter. `$setOnInsert` seeds the `@unI()` identity on the insert branch only; the
+    // client refuses an identity seed that contradicts an identity anchor in the filter.
+    await EmailTrafficBucketDoc.atomicUpsertMany<EmailTrafficBucketDoc>(
       snapshotsArg.map((snapshot) => ({
-        updateOne: {
-          filter: { bucketStart: snapshot.bucketStart },
-          update: {
-            $max: {
-              sent: snapshot.sent,
-              received: snapshot.received,
-              failed: snapshot.failed,
-            },
-            $set: {
-              updatedAt: now,
-              _updatedAt: updatedAt,
-            },
-            $setOnInsert: {
-              id: `email-traffic-${snapshot.bucketStart}`,
-              bucketStart: snapshot.bucketStart,
-              createdAt: now,
-              _createdAt: updatedAt,
-            },
+        filter: { bucketStart: snapshot.bucketStart },
+        update: {
+          $max: {
+            sent: snapshot.sent,
+            received: snapshot.received,
+            failed: snapshot.failed,
+          },
+          $set: {
+            updatedAt: now,
+          },
+          $setOnInsert: {
+            id: `email-traffic-${snapshot.bucketStart}`,
+            bucketStart: snapshot.bucketStart,
+            createdAt: now,
           },
-          upsert: true,
         },
       })),
-      { ordered: false, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      { timeoutMS: DB_OPERATION_TIMEOUT_MS },
     );
   }
 
@@ -104,23 +95,24 @@ export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
     if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
       throw new Error('EmailTrafficBucketDoc.loadSince requires a valid cutoff');
     }
-    const collection = await EmailTrafficBucketDoc.getNativeCollection();
-    const cursor = collection
-      .find(
-        { bucketStart: { $gte: cutoffArg } },
-        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
-      )
-      .sort({ bucketStart: 1 });
+    const cursor = await EmailTrafficBucketDoc.getCursor<EmailTrafficBucketDoc>(
+      { bucketStart: { $gte: cutoffArg } },
+      {
+        sort: { bucketStart: 1 },
+        limit: MAX_LOADED_BUCKETS,
+        maxTimeMS: DB_OPERATION_TIMEOUT_MS,
+      },
+    );
     try {
       const rows = await cursor.toArray();
-      return rows.map((row) => ({
-        bucketStart: Number(row.bucketStart),
-        sent: Number(row.sent || 0),
-        received: Number(row.received || 0),
-        failed: Number(row.failed || 0),
+      return rows.map((rowArg) => ({
+        bucketStart: Number(rowArg.bucketStart),
+        sent: Number(rowArg.sent || 0),
+        received: Number(rowArg.received || 0),
+        failed: Number(rowArg.failed || 0),
       }));
     } finally {
-      await cursor.close({ timeoutMS: DB_OPERATION_TIMEOUT_MS });
+      await cursor.close();
     }
   }
 
@@ -128,24 +120,38 @@ export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
     if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
       throw new Error('EmailTrafficBucketDoc.pruneBefore requires a valid cutoff');
     }
-    const collection = await EmailTrafficBucketDoc.getNativeCollection();
     let deletedCount = 0;
     while (true) {
-      const rows = await collection
-        .find(
-          { bucketStart: { $lt: cutoffArg } },
-          { projection: { _id: 1 }, timeoutMS: DB_OPERATION_TIMEOUT_MS },
-        )
-        .sort({ bucketStart: 1, _id: 1 })
-        .limit(500)
-        .toArray();
+      const cursor = await EmailTrafficBucketDoc.getCursor<EmailTrafficBucketDoc>(
+        { bucketStart: { $lt: cutoffArg } },
+        {
+          projection: { id: 1 },
+          sort: { bucketStart: 1, id: 1 },
+          limit: PRUNE_BATCH_SIZE,
+          maxTimeMS: DB_OPERATION_TIMEOUT_MS,
+        },
+      );
+      let rows: EmailTrafficBucketDoc[];
+      try {
+        rows = await cursor.toArray();
+      } finally {
+        await cursor.close();
+      }
       if (rows.length === 0) break;
-      const result = await collection.deleteMany(
-        { _id: { $in: rows.map((row) => row._id) } },
+      // The identity `$or` is the equality anchor a plural delete requires; the range
+      // guard is re-evaluated server-side so a bucket written after the scan survives.
+      const result = await EmailTrafficBucketDoc.atomicDeleteMany<EmailTrafficBucketDoc>(
+        {
+          $or: rows.map((rowArg) => ({ id: rowArg.id })),
+          bucketStart: { $lt: cutoffArg },
+        },
         { timeoutMS: DB_OPERATION_TIMEOUT_MS },
       );
+      // A batch the scan matched but the server-side guard did not would otherwise be
+      // rescanned forever; no progress ends the sweep the same way it does for events.
+      if (result.deletedCount === 0) break;
       deletedCount += result.deletedCount;
-      if (rows.length < 500) break;
+      if (rows.length < PRUNE_BATCH_SIZE) break;
     }
     return deletedCount;
   }

package/ts/db/documents/classes.gateway-client.doc.ts

@@ -19,6 +19,26 @@ export interface IGatewayClientPendingProvisioning {
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
+/** Fields a compare-and-set mutation may write; the revision is owned by the fence. */
+export type TGatewayClientMutableSet = Partial<Pick<
+  GatewayClientDoc,
+  | 'type'
+  | 'name'
+  | 'description'
+  | 'hostnamePatterns'
+  | 'allowedRouteTargets'
+  | 'capabilities'
+  | 'enabled'
+  | 'policyGeneration'
+  | 'credentialSequence'
+  | 'activeCredentialSequence'
+  | 'pendingProvisioning'
+  | 'updatedAt'
+>>;
+
+/** Optional fields a compare-and-set mutation may remove from the stored document. */
+export type TGatewayClientUnsettableField = 'description' | 'pendingProvisioning';
+
 @plugins.smartdata.Collection(() => getDb())
 export class GatewayClientDoc extends plugins.smartdata.SmartDataDbDoc<GatewayClientDoc, GatewayClientDoc> {
   @plugins.smartdata.unI()
@@ -80,15 +100,14 @@ export class GatewayClientDoc extends plugins.smartdata.SmartDataDbDoc<GatewayCl
     return await GatewayClientDoc.getInstance({ id });
   }
 
-  private static async getNativeCollection() {
-    const smartdataCollection = (GatewayClientDoc as typeof GatewayClientDoc & {
-      collection: plugins.smartdata.SmartdataCollection<GatewayClientDoc>;
-    }).collection;
-    await smartdataCollection.init();
-    return smartdataCollection.mongoDbCollection;
-  }
-
-  private static buildRevisionSelector(idArg: string, revisionArg: number): Record<string, unknown> {
+  /**
+   * Compare-and-set selector. Revision 0 also matches documents written before the
+   * revision field existed, so a first mutation fences them exactly once.
+   */
+  private static buildRevisionSelector(
+    idArg: string,
+    revisionArg: number,
+  ): plugins.smartdata.TSmartdataAtomicFilter<GatewayClientDoc> {
     if (revisionArg === 0) {
       return {
         id: idArg,
@@ -104,21 +123,23 @@ export class GatewayClientDoc extends plugins.smartdata.SmartDataDbDoc<GatewayCl
   public static async compareAndSet(
     idArg: string,
     expectedRevisionArg: number,
-    setArg: Record<string, unknown>,
-    unsetArg: string[] = [],
+    setArg: TGatewayClientMutableSet,
+    unsetArg: TGatewayClientUnsettableField[] = [],
   ): Promise<GatewayClientDoc | null> {
-    const collection = await GatewayClientDoc.getNativeCollection();
-    const update: Record<string, unknown> = {
+    const update: plugins.smartdata.ISmartdataAtomicUpdate<GatewayClientDoc> = {
       $set: {
         ...setArg,
         mutationRevision: expectedRevisionArg + 1,
-        _updatedAt: new Date().toISOString(),
       },
     };
     if (unsetArg.length > 0) {
-      update.$unset = Object.fromEntries(unsetArg.map((fieldArg) => [fieldArg, '']));
+      update.$unset = Object.fromEntries(
+        unsetArg.map((fieldArg) => [fieldArg, '' as const]),
+      );
     }
-    const result = await collection.updateOne(
+    // One fenced write: a mismatched revision matches nothing and the caller learns the
+    // document changed concurrently.
+    const result = await GatewayClientDoc.atomicUpdate<GatewayClientDoc>(
       GatewayClientDoc.buildRevisionSelector(idArg, expectedRevisionArg),
       update,
     );
@@ -127,8 +148,7 @@ export class GatewayClientDoc extends plugins.smartdata.SmartDataDbDoc<GatewayCl
   }
 
   public static async deleteIfRevision(idArg: string, expectedRevisionArg: number): Promise<boolean> {
-    const collection = await GatewayClientDoc.getNativeCollection();
-    const result = await collection.deleteOne(
+    const result = await GatewayClientDoc.atomicDelete<GatewayClientDoc>(
       GatewayClientDoc.buildRevisionSelector(idArg, expectedRevisionArg),
     );
     return result.deletedCount === 1;

package/ts/db/documents/classes.ip-intelligence.doc.ts

@@ -7,6 +7,8 @@ import type {
 
 const getDb = () => DcRouterDb.getInstance().getDb();
 
+const MAX_DELETE_BATCH_SIZE = 500;
+
 @plugins.smartdata.Collection(() => getDb())
 export class IpIntelligenceDoc extends plugins.smartdata.SmartDataDbDoc<IpIntelligenceDoc, IpIntelligenceDoc> implements IIpIntelligenceRecord {
   @plugins.smartdata.unI()
@@ -111,18 +113,14 @@ export class IpIntelligenceDoc extends plugins.smartdata.SmartDataDbDoc<IpIntell
       throw new Error('IpIntelligenceDoc.findRecent requires a positive integer limit');
     }
 
-    const filter = options.ipAddresses
+    const filter: plugins.smartdata.MongoFilter<IpIntelligenceDoc> = options.ipAddresses
       ? { ipAddress: { $in: options.ipAddresses } }
       : {};
-    const collection = (IpIntelligenceDoc as typeof IpIntelligenceDoc & {
-      collection: plugins.smartdata.SmartdataCollection<IpIntelligenceDoc>;
-    }).collection;
-    const cursor = await collection.getCursor(
-      filter,
-      IpIntelligenceDoc as unknown as typeof plugins.smartdata.SmartDataDbDoc,
-    );
-    cursor.mongodbCursor.sort({ lastSeenAt: -1, _id: -1 });
-    cursor.mongodbCursor.limit(options.limit);
+    const cursor = await IpIntelligenceDoc.getCursor<IpIntelligenceDoc>(filter, {
+      // ipAddress is the immutable identity, so it is the deterministic tiebreaker.
+      sort: { lastSeenAt: -1, ipAddress: -1 },
+      limit: options.limit,
+    });
     try {
       return await cursor.toArray();
     } finally {
@@ -131,50 +129,49 @@ export class IpIntelligenceDoc extends plugins.smartdata.SmartDataDbDoc<IpIntell
   }
 
   public static async countAll(): Promise<number> {
-    return await DcRouterDb.getInstance()
-      .getDb()
-      .mongoDb
-      .collection('IpIntelligenceDoc')
-      .countDocuments({});
+    return await IpIntelligenceDoc.getCount<IpIntelligenceDoc>({});
   }
 
-  public static async findOldestIds(options: {
+  /** Least recently seen records first; the identity is the deterministic tiebreaker. */
+  public static async findOldestIpAddresses(options: {
     lastSeenBefore?: number;
     limit: number;
-  }): Promise<unknown[]> {
+  }): Promise<string[]> {
     if (!Number.isSafeInteger(options.limit) || options.limit <= 0) {
-      throw new Error('IpIntelligenceDoc.findOldestIds requires a positive integer limit');
+      throw new Error('IpIntelligenceDoc.findOldestIpAddresses requires a positive integer limit');
     }
-    const collection = DcRouterDb.getInstance()
-      .getDb()
-      .mongoDb
-      .collection('IpIntelligenceDoc');
-    const filter = options.lastSeenBefore === undefined
-      ? {}
-      : { lastSeenAt: { $lt: options.lastSeenBefore } };
-    const cursor = collection
-      .find(filter, { projection: { _id: 1 } })
-      .sort({ lastSeenAt: 1, _id: 1 })
-      .limit(options.limit);
+    const filter: plugins.smartdata.MongoFilter<IpIntelligenceDoc> =
+      options.lastSeenBefore === undefined
+        ? {}
+        : { lastSeenAt: { $lt: options.lastSeenBefore } };
+    const cursor = await IpIntelligenceDoc.getCursor<IpIntelligenceDoc>(filter, {
+      projection: { ipAddress: 1 },
+      sort: { lastSeenAt: 1, ipAddress: 1 },
+      limit: options.limit,
+    });
     try {
       const rows = await cursor.toArray();
-      return rows.map((row) => row._id);
+      return rows.map((rowArg) => rowArg.ipAddress);
     } finally {
       await cursor.close();
     }
   }
 
-  public static async deleteByDocumentIds(documentIds: unknown[]): Promise<number> {
-    if (documentIds.length === 0) return 0;
-    if (documentIds.length > 500 || documentIds.some((id) => id === undefined || id === null)) {
-      throw new Error('IpIntelligenceDoc.deleteByDocumentIds requires 1 to 500 document ids');
+  public static async deleteByIpAddresses(ipAddressesArg: string[]): Promise<number> {
+    if (ipAddressesArg.length === 0) return 0;
+    if (
+      ipAddressesArg.length > MAX_DELETE_BATCH_SIZE
+      || ipAddressesArg.some((ipArg) => typeof ipArg !== 'string' || !ipArg)
+    ) {
+      throw new Error(
+        `IpIntelligenceDoc.deleteByIpAddresses requires 1 to ${MAX_DELETE_BATCH_SIZE} ip addresses`,
+      );
     }
-    const deleteFilter: Record<string, any> = { _id: { $in: documentIds } };
-    const result = await DcRouterDb.getInstance()
-      .getDb()
-      .mongoDb
-      .collection('IpIntelligenceDoc')
-      .deleteMany(deleteFilter);
+    // Each `$or` branch pins the immutable identity, which is the equality anchor a
+    // plural atomic delete requires.
+    const result = await IpIntelligenceDoc.atomicDeleteMany<IpIntelligenceDoc>({
+      $or: ipAddressesArg.map((ipArg) => ({ ipAddress: ipArg })),
+    });
     return result.deletedCount;
   }
 }