@serve.zone/dcrouter 18.9.2 → 18.9.4

package/ts/dns/manager.dns.ts

@@ -836,7 +836,15 @@ export class DnsManager {
       this.providerClients.delete(id);
     }
     doc.updatedAt = Date.now();
-    await doc.save();
+    const persisted = await DnsProviderDoc.atomicUpdate({ id }, {
+      $set: {
+        name: doc.name,
+        updatedAt: doc.updatedAt,
+        ...(args.credentials !== undefined ? { credentials: doc.credentials, status: doc.status } : {}),
+      },
+      ...(args.credentials !== undefined ? { $unset: { lastError: true } } : {}),
+    });
+    if (persisted.matchedCount !== 1) throw new Error('DNS provider disappeared during update');
     return true;
   }
 
@@ -889,7 +897,15 @@ export class DnsManager {
     doc.status = result.ok ? 'ok' : 'error';
     doc.lastTestedAt = Date.now();
     doc.lastError = result.ok ? undefined : result.error;
-    await doc.save();
+    const persisted = await DnsProviderDoc.atomicUpdate({ id, credentials: { $eq: doc.credentials } }, {
+      $set: {
+        status: doc.status,
+        lastTestedAt: doc.lastTestedAt,
+        ...(doc.lastError !== undefined ? { lastError: doc.lastError } : {}),
+      },
+      ...(doc.lastError === undefined ? { $unset: { lastError: true } } : {}),
+    });
+    if (persisted.matchedCount !== 1) throw new Error('DNS provider disappeared during connection test');
     if (result.ok) {
       this.providerClients.set(id, client); // cache the working client
     }
@@ -1774,8 +1790,8 @@ export class DnsManager {
       name: doc.name,
       type: doc.type,
       status: doc.status,
-      lastTestedAt: doc.lastTestedAt,
-      lastError: doc.lastError,
+      lastTestedAt: doc.lastTestedAt ?? undefined,
+      lastError: doc.lastError ?? undefined,
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
       createdBy: doc.createdBy,

package/ts/email/classes.email-domain.manager.ts

@@ -268,7 +268,17 @@ export class EmailDomainManager {
       }
       doc.reconciliation = this.invalidateReconciliation(doc, 'EMAIL_DOMAIN_CONFIGURATION_CHANGED');
       doc.updatedAt = new Date().toISOString();
-      await doc.save();
+      const persisted = await EmailDomainDoc.atomicUpdate({ id }, {
+        $set: {
+          dkim: doc.dkim,
+          reconciliation: doc.reconciliation,
+          updatedAt: doc.updatedAt,
+          ...(changes.rateLimits !== undefined ? { rateLimits: doc.rateLimits! } : {}),
+          ...(doc.remoteIngress != null ? { remoteIngress: doc.remoteIngress } : {}),
+        },
+        ...(changes.remoteIngress === null ? { $unset: { remoteIngress: true } } : {}),
+      });
+      if (persisted.matchedCount !== 1) throw new Error('Email domain disappeared during update');
       await this.syncManagedDomainsToRuntime();
       return { kind: 'sync' as const, domainName: doc.domain };
     });
@@ -833,7 +843,7 @@ export class EmailDomainManager {
       subdomain: doc.subdomain,
       dkim: doc.dkim,
       rateLimits: doc.rateLimits,
-      remoteIngress: doc.remoteIngress,
+      remoteIngress: doc.remoteIngress ?? undefined,
       dnsStatus: doc.dnsStatus,
       reconciliation: doc.reconciliation,
       activeDkim: doc.activeDkim,

package/ts/email/classes.email-settings.manager.ts

@@ -129,8 +129,8 @@ export class EmailSettingsManager {
     }
 
     const nextEnabled = hasOwn(updates, 'enabled') ? Boolean(updates.enabled) : doc.enabled;
-    const nextEmailConfig = this.patchEmailConfig(doc.emailConfig, updates, nextEnabled);
-    const nextEmailPortConfig = this.patchEmailPortConfig(doc.emailPortConfig, updates);
+    const nextEmailConfig = this.patchEmailConfig(doc.emailConfig ?? undefined, updates, nextEnabled);
+    const nextEmailPortConfig = this.patchEmailPortConfig(doc.emailPortConfig ?? undefined, updates);
     const nextOutboundMode = this.patchOutboundMode(doc.outboundMode, updates);
 
     doc.enabled = nextEnabled;
@@ -139,7 +139,25 @@ export class EmailSettingsManager {
     doc.outboundMode = nextOutboundMode;
     doc.updatedAt = Date.now();
     doc.updatedBy = updatedBy;
-    await doc.save();
+    if (doc.creationStatus === 'new') {
+      await doc.save();
+    } else {
+      const persisted = await EmailServerSettingsDoc.atomicUpdate({ settingsId: doc.settingsId }, {
+        $set: {
+          enabled: doc.enabled,
+          outboundMode: doc.outboundMode,
+          updatedAt: doc.updatedAt,
+          updatedBy: doc.updatedBy,
+          ...(doc.emailConfig !== undefined ? { emailConfig: doc.emailConfig } : {}),
+          ...(doc.emailPortConfig !== undefined ? { emailPortConfig: doc.emailPortConfig } : {}),
+        },
+        $unset: {
+          ...((hasOwn(updates, 'portMapping') || hasOwn(updates, 'receivedEmailsPath'))
+            && doc.emailPortConfig === undefined ? { emailPortConfig: true } : {}),
+        },
+      });
+      if (persisted.matchedCount !== 1) throw new Error('Email server settings disappeared during update');
+    }
 
     this.loadFromDoc(doc);
     this.applyToRuntimeOptions();
@@ -148,8 +166,8 @@ export class EmailSettingsManager {
 
   private loadFromDoc(doc: EmailServerSettingsDoc): void {
     this.enabled = doc.enabled;
-    this.cachedEmailConfig = clonePlain(doc.emailConfig);
-    this.cachedEmailPortConfig = clonePlain(doc.emailPortConfig);
+    this.cachedEmailConfig = clonePlain(doc.emailConfig ?? undefined);
+    this.cachedEmailPortConfig = clonePlain(doc.emailPortConfig ?? undefined);
     this.outboundMode = this.normalizeOutboundMode(doc.outboundMode);
     this.updatedAt = doc.updatedAt;
     this.updatedBy = doc.updatedBy;

package/ts/email/classes.mail-dns-sync.ts

@@ -1494,6 +1494,7 @@ export class MailDnsSync {
       mxSlots: plan.revision.mxSlots,
     });
     const now = new Date().toISOString();
+    const promotedMaterial = canActivate ? plan.doc.pendingDkim : undefined;
     if (canActivate && plan.doc.pendingDkim) {
       this.promotePendingDkim(plan.doc, now);
     }
@@ -1534,7 +1535,28 @@ export class MailDnsSync {
       lastCheckedAt: now,
     };
     plan.doc.updatedAt = now;
-    await plan.doc.save();
+    if (promotedMaterial) {
+      // Publish the replacement signer and clear its staged material in one write.
+      const result = await EmailDomainDoc.atomicUpdate(
+        { id: plan.doc.id, pendingDkim: { $eq: promotedMaterial } },
+        {
+          $set: {
+            activeDkim: plan.doc.activeDkim!,
+            retiringDkim: plan.doc.retiringDkim!,
+            dkim: plan.doc.dkim,
+            reconciliation: plan.doc.reconciliation,
+            dnsStatus: plan.doc.dnsStatus,
+            updatedAt: now,
+          },
+          $unset: { pendingDkim: true },
+        },
+      );
+      if (result.matchedCount !== 1) {
+        throw new Error('Staged DKIM material changed before promotion');
+      }
+    } else {
+      await plan.doc.save();
+    }
     if (canActivate && topologyChanged) {
       // The transition SPF intentionally authorizes old + new identities. Run
       // one immediate follow-up to contract it to the newly active revision.

package/ts/monitoring/classes.metricscache.ts

@@ -1,103 +1,157 @@
+import * as plugins from '../plugins.js';
+
 export interface ICacheEntry<T> {
   data: T;
   timestamp: number;
   ttl: number;
 }
 
-export class MetricsCache {
-  private cache = new Map<string, ICacheEntry<any>>();
-  private inFlight = new Map<string, Promise<any>>();
-  private readonly defaultTTL: number;
-  
-  constructor(defaultTTL: number = 500) {
-    this.defaultTTL = defaultTTL;
+export interface IMetricsCacheOptions {
+  maxAggregateEntries?: number;
+  maxSnapshotEntries?: number;
+  maxEstimatedBytes?: number;
+  maxInFlight?: number;
+}
+
+type TCacheCategory = 'aggregate' | 'snapshot';
+
+/** Uses the existing TypedRequest error envelope; polling callers retain their last result. */
+export class MetricsCapacityError extends plugins.typedrequest.TypedResponseError {
+  constructor() {
+    super('Metrics are busy; retry after 500 ms', { code: 'METRICS_CAPACITY', retryAfterMs: 500 });
   }
-  
-  /**
-   * Get cached data or compute and cache it
-   */
-  public get<T>(key: string, computeFn: () => T | Promise<T>, ttl?: number): T | Promise<T> {
-    const cached = this.cache.get(key);
-    const now = Date.now();
-    const actualTTL = ttl ?? this.defaultTTL;
-    
-    if (cached && (now - cached.timestamp) < cached.ttl) {
-      return cached.data;
-    }
+}
 
-    if (cached) {
-      this.cache.delete(key);
+/** Conservative retained-payload estimate, including Maps and shared object graphs. */
+function estimateBytes(value: unknown, budget: number, seen = new Set<object>()): number {
+  if (budget <= 0) return 1;
+  if (typeof value === 'string') return 24 + value.length * 2;
+  if (typeof value !== 'object' || value === null) return 16;
+  if (seen.has(value)) return 8;
+  seen.add(value);
+  if (ArrayBuffer.isView(value)) return 64 + value.byteLength;
+  if (value instanceof ArrayBuffer) return 64 + value.byteLength;
+  let size = 64;
+  if (value instanceof Map) {
+    for (const [key, entry] of value) {
+      size += 32 + estimateBytes(key, budget - size, seen) + estimateBytes(entry, budget - size, seen);
+      if (size > budget) break;
     }
-
-    const pending = this.inFlight.get(key) as Promise<T> | undefined;
-    if (pending) {
-      return pending;
+  } else if (value instanceof Set) {
+    for (const entry of value) {
+      size += 16 + estimateBytes(entry, budget - size, seen);
+      if (size > budget) break;
     }
-    
-    const result = computeFn();
-    
-    // Handle both sync and async compute functions
-    if (result instanceof Promise) {
-      let inFlightPromise: Promise<T>;
-      inFlightPromise = result.then(
-        (data) => {
-          if (this.inFlight.get(key) === inFlightPromise) {
-            this.inFlight.delete(key);
-            this.cache.set(key, { data, timestamp: Date.now(), ttl: actualTTL });
-          }
-          return data;
-        },
-        (error: unknown) => {
-          if (this.inFlight.get(key) === inFlightPromise) {
-            this.inFlight.delete(key);
-            this.cache.delete(key);
-          }
-          throw error;
-        },
-      );
-      this.inFlight.set(key, inFlightPromise);
-      return inFlightPromise;
-    } else {
-      this.cache.set(key, { data: result, timestamp: now, ttl: actualTTL });
+  } else {
+    for (const key of Object.keys(value)) {
+      size += 24 + key.length * 2 + estimateBytes((value as Record<string, unknown>)[key], budget - size, seen);
+      if (size > budget) break;
+    }
+  }
+  return size;
+}
+
+export class MetricsCache {
+  private readonly caches: Record<TCacheCategory, plugins.lruCache.LRUCache<string, ICacheEntry<unknown>>>;
+  private readonly inFlight = new Map<string, Promise<unknown>>();
+  private readonly admitted = new Set<Promise<unknown>>();
+  private readonly maxInFlight: number;
+  private readonly maxEstimatedBytes: number;
+  private stopped = false;
+  private generation = 0;
+  private activeComputations = 0;
+
+  constructor(private readonly defaultTTL = 500, options: IMetricsCacheOptions = {}) {
+    this.maxInFlight = options.maxInFlight ?? 32;
+    this.maxEstimatedBytes = options.maxEstimatedBytes ?? 8 * 1024 * 1024;
+    this.caches = {
+      aggregate: this.createCache(options.maxAggregateEntries ?? 256),
+      snapshot: this.createCache(options.maxSnapshotEntries ?? 64),
+    };
+  }
+
+  private createCache(max: number): plugins.lruCache.LRUCache<string, ICacheEntry<unknown>> {
+    return new plugins.lruCache.LRUCache({
+      max,
+      maxSize: this.maxEstimatedBytes,
+      // lru-cache owns bounded, unref'ed expiry timers, including idle keys.
+      ttlAutopurge: true,
+      ttlResolution: 0,
+      sizeCalculation: (entry, key) => 64 + key.length * 2 + estimateBytes(entry.data, this.maxEstimatedBytes),
+    });
+  }
+
+  public get<T>(key: string, computeFn: () => T | Promise<T>, ttl = this.defaultTTL, category: TCacheCategory = 'aggregate'): T | Promise<T> {
+    if (this.stopped) throw new Error('Metrics cache is stopped');
+    const cache = this.caches[category];
+    const cached = cache.get(key);
+    if (cached && Date.now() - cached.timestamp < cached.ttl) return cached.data as T;
+    cache.delete(key);
+    const flightKey = JSON.stringify([category, key]);
+    const pending = this.inFlight.get(flightKey);
+    if (pending) return pending as Promise<T>;
+    if (this.activeComputations >= this.maxInFlight) throw new MetricsCapacityError();
+    const generation = this.generation;
+    this.activeComputations++;
+    let result: T | Promise<T>;
+    try { result = computeFn(); } catch (error) { this.activeComputations--; throw error; }
+    const remember = (data: T) => {
+      if (!this.stopped && generation === this.generation && ttl > 0) {
+        cache.set(key, { data, timestamp: Date.now(), ttl }, { ttl });
+      }
+    };
+    if (!(result instanceof Promise)) {
+      this.activeComputations--;
+      remember(result);
       return result;
     }
+    const run = result.then((data) => {
+      if (this.inFlight.get(flightKey) === run) remember(data);
+      return data;
+    }).finally(() => {
+      this.activeComputations--;
+      this.admitted.delete(run);
+      if (this.inFlight.get(flightKey) === run) this.inFlight.delete(flightKey);
+    });
+    this.admitted.add(run);
+    this.inFlight.set(flightKey, run);
+    return run;
   }
-  
-  /**
-   * Invalidate a specific cache entry
-   */
+
   public invalidate(key: string): void {
-    this.cache.delete(key);
-    this.inFlight.delete(key);
+    for (const category of ['aggregate', 'snapshot'] as const) {
+      this.caches[category].delete(key);
+      this.inFlight.delete(JSON.stringify([category, key]));
+    }
   }
-  
-  /**
-   * Clear all cache entries
-   */
+
   public clear(): void {
-    this.cache.clear();
+    this.generation++;
+    this.caches.aggregate.clear();
+    this.caches.snapshot.clear();
     this.inFlight.clear();
+    // Invalidated work retains its admission slot until it actually settles.
   }
-  
-  /**
-   * Get cache statistics
-   */
-  public getStats(): { size: number; keys: string[] } {
+
+  public start(): void { this.stopped = false; }
+
+  public async stop(): Promise<void> {
+    this.stopped = true;
+    this.clear();
+    await Promise.allSettled(this.admitted);
+  }
+
+  public getStats(): { size: number; keys: string[]; inFlight: number; estimatedBytes: number } {
     return {
-      size: this.cache.size,
-      keys: Array.from(this.cache.keys())
+      size: this.caches.aggregate.size + this.caches.snapshot.size,
+      keys: [...this.caches.aggregate.keys(), ...this.caches.snapshot.keys()],
+      inFlight: this.activeComputations,
+      estimatedBytes: this.caches.aggregate.calculatedSize + this.caches.snapshot.calculatedSize,
     };
   }
-  
-  /**
-   * Clean up expired entries
-   */
+
   public cleanup(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache.entries()) {
-      if (now - entry.timestamp > entry.ttl) {
-        this.cache.delete(key);
-      }
-    }
+    this.caches.aggregate.purgeStale();
+    this.caches.snapshot.purgeStale();
   }
 }

package/ts/monitoring/classes.metricsmanager.ts

@@ -100,6 +100,7 @@ export class MetricsManager {
   }
   
   public async start(): Promise<void> {
+    this.metricsCache.start();
     if (this.canPersistEmailTraffic()) {
       await this.loadEmailTrafficBuckets();
       await this.prunePersistedMetrics();
@@ -166,6 +167,7 @@ export class MetricsManager {
   }
 
   public async stop(): Promise<void> {
+    await this.metricsCache.stop();
     if (this.resetInterval) {
       clearInterval(this.resetInterval);
       this.resetInterval = undefined;
@@ -400,13 +402,13 @@ export class MetricsManager {
       limit: Math.min(Math.max(options.limit ?? MAX_SNAPSHOT_LIMIT, 1), MAX_SNAPSHOT_LIMIT),
     };
     const afterId = (normalizedOptions as typeof normalizedOptions & { afterId?: string }).afterId ?? '';
-    const cacheKey = `activeConnectionSnapshots:${normalizedOptions.limit}:${normalizedOptions.routeId ?? ''}:${afterId}`;
+    const cacheKey = JSON.stringify(['activeConnectionSnapshots', normalizedOptions.limit, normalizedOptions.routeId ?? '', afterId]);
     return await this.metricsCache.get<plugins.smartproxy.IActiveConnectionSnapshot[]>(cacheKey, async () => {
       if (!this.dcRouter.smartProxy) {
         return [];
       }
       return this.dcRouter.smartProxy.getActiveConnectionSnapshots(normalizedOptions);
-    }, ACTIVE_CONNECTION_SNAPSHOT_CACHE_TTL_MS);
+    }, ACTIVE_CONNECTION_SNAPSHOT_CACHE_TTL_MS, 'snapshot');
   }
 
   public async getActiveConnectionSnapshotPage(
@@ -417,13 +419,13 @@ export class MetricsManager {
       limit: Math.min(Math.max(options.limit ?? MAX_SNAPSHOT_LIMIT, 1), MAX_SNAPSHOT_LIMIT),
     };
     const afterId = normalizedOptions.afterId ?? '';
-    const cacheKey = `activeConnectionSnapshotPage:${normalizedOptions.limit}:${normalizedOptions.routeId ?? ''}:${afterId}`;
+    const cacheKey = JSON.stringify(['activeConnectionSnapshotPage', normalizedOptions.limit, normalizedOptions.routeId ?? '', afterId]);
     return await this.metricsCache.get<plugins.smartproxy.IActiveConnectionSnapshotPage>(cacheKey, async () => {
       if (!this.dcRouter.smartProxy) {
         return { snapshots: [], hasMore: false, nextCursor: null };
       }
       return this.dcRouter.smartProxy.getActiveConnectionSnapshotPage(normalizedOptions);
-    }, ACTIVE_CONNECTION_SNAPSHOT_CACHE_TTL_MS);
+    }, ACTIVE_CONNECTION_SNAPSHOT_CACHE_TTL_MS, 'snapshot');
   }
 
   // Get connection info from SmartProxy

package/ts/plugins.ts

@@ -101,11 +101,13 @@ export {
 }
 
 // third party
+import * as lruCache from 'lru-cache';
 import ipaddr from 'ipaddr.js';
 import * as uuid from 'uuid';
 import webpush from 'web-push';
 
 export {
+  lruCache,
   ipaddr,
   uuid,
   webpush,

package/ts/remoteingress/classes.remoteingress-manager.ts

@@ -115,12 +115,12 @@ export class RemoteIngressManager {
         listenPortsUdp: doc.listenPortsUdp,
         enabled: doc.enabled,
         autoDerivePorts: doc.autoDerivePorts,
-        performance: doc.performance,
+        performance: doc.performance ?? undefined,
         egress: this.normalizeEgressPolicy(doc.egress),
         tags: doc.tags,
-        publicIp: doc.publicIp,
-        publicIpV6: doc.publicIpV6,
-        mailHostname: doc.mailHostname,
+        publicIp: doc.publicIp ?? undefined,
+        publicIpV6: doc.publicIpV6 ?? undefined,
+        mailHostname: doc.mailHostname ?? undefined,
         createdAt: doc.createdAt,
         updatedAt: doc.updatedAt,
       };
@@ -200,7 +200,22 @@ export class RemoteIngressManager {
     }
     doc.updatedAt = Date.now();
     doc.updatedBy = updatedBy;
-    await doc.save();
+    if (doc.creationStatus === 'new') {
+      await doc.save();
+    } else {
+      const persisted = await RemoteIngressHubSettingsDoc.atomicUpdate({ settingsId: doc.settingsId }, {
+        $set: {
+          updatedAt: doc.updatedAt,
+          updatedBy: doc.updatedBy,
+          ...(hasOwn(normalized, 'enabled') ? { enabled: doc.enabled! } : {}),
+          ...(hasOwn(normalized, 'tunnelPort') ? { tunnelPort: doc.tunnelPort! } : {}),
+          ...(hasOwn(updates, 'hubDomain') ? { hubDomain: doc.hubDomain! } : {}),
+          ...(hasOwn(updates, 'performance') && doc.performance != null ? { performance: doc.performance } : {}),
+        },
+        ...(hasOwn(updates, 'performance') && doc.performance == null ? { $unset: { performance: true } } : {}),
+      });
+      if (persisted.matchedCount !== 1) throw new Error('RemoteIngress hub settings disappeared during update');
+    }
 
     this.hubSettings = this.toHubSettings(doc);
     return this.getHubSettings();
@@ -415,8 +430,27 @@ export class RemoteIngressManager {
 
     const doc = await RemoteIngressEdgeDoc.findById(id);
     if (doc) {
-      Object.assign(doc, edge);
-      await doc.save();
+      const persisted = await RemoteIngressEdgeDoc.atomicUpdate({ id }, {
+        $set: {
+          name: edge.name,
+          listenPorts: edge.listenPorts,
+          autoDerivePorts: edge.autoDerivePorts,
+          enabled: edge.enabled,
+          tags: edge.tags,
+          updatedAt: edge.updatedAt,
+          ...(edge.performance !== undefined ? { performance: edge.performance } : {}),
+          ...(edge.egress !== undefined ? { egress: edge.egress } : {}),
+          ...(updates.publicIp !== undefined && edge.publicIp !== undefined ? { publicIp: edge.publicIp } : {}),
+          ...(updates.publicIpV6 !== undefined && edge.publicIpV6 !== undefined ? { publicIpV6: edge.publicIpV6 } : {}),
+          ...(updates.mailHostname !== undefined && edge.mailHostname !== undefined ? { mailHostname: edge.mailHostname } : {}),
+        },
+        $unset: {
+          ...(updates.publicIp !== undefined && edge.publicIp === undefined ? { publicIp: true } : {}),
+          ...(updates.publicIpV6 !== undefined && edge.publicIpV6 === undefined ? { publicIpV6: true } : {}),
+          ...(updates.mailHostname !== undefined && edge.mailHostname === undefined ? { mailHostname: true } : {}),
+        },
+      });
+      if (persisted.matchedCount !== 1) throw new Error('RemoteIngress edge disappeared during update');
     }
     this.edges.set(id, edge);
     this.notifyEdgesChanged(`edge updated: ${edge.name}`);
@@ -740,7 +774,7 @@ export class RemoteIngressManager {
       enabled: doc.enabled ?? false,
       tunnelPort: doc.tunnelPort ?? defaultTunnelPort,
       hubDomain: doc.hubDomain || undefined,
-      performance: doc.performance,
+      performance: doc.performance ?? undefined,
       updatedAt: doc.updatedAt,
       updatedBy: doc.updatedBy,
     };

package/ts/security/classes.authentication-event-manager.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
 import type { DcRouter } from '../classes.dcrouter.js';
+import { MetricsCache } from '../monitoring/classes.metricscache.js';
 import { AuthenticationEventDoc } from '../db/documents/classes.authentication-event.doc.js';
 import type {
   IAuthenticationEvent,
@@ -29,16 +30,23 @@ export class AuthenticationEventManager {
   private recentEvents = new Map<string, IAuthenticationEvent>();
   private flushInFlight?: Promise<void>;
   private pruneInFlight?: Promise<number>;
-  private windowStatsInFlight = new Map<string, Promise<IAuthenticationWindowStats>>();
+  private windowStatsCache = new MetricsCache(1_000, { maxAggregateEntries: 8, maxInFlight: 8 });
+  private lastPersistenceAvailable?: boolean;
 
   constructor(private dcRouterRef: DcRouter) {}
 
+  public start(): void { this.windowStatsCache.start(); }
+
+  /** Drain observer reads; MetricsManager still owns the final persistence flush. */
+  public async stop(): Promise<void> { await this.windowStatsCache.stop(); }
+
   private canPersist(): boolean {
     return this.dcRouterRef.options.dbConfig?.enabled !== false
       && Boolean(this.dcRouterRef.dcRouterDb?.isReady());
   }
 
   private rememberEvent(eventArg: IAuthenticationEvent): void {
+    this.windowStatsCache.clear();
     this.pendingEvents.set(eventArg.id, eventArg);
     this.recentEvents.set(eventArg.id, eventArg);
     while (this.pendingEvents.size > MAX_IN_MEMORY_EVENTS) {
@@ -108,7 +116,11 @@ export class AuthenticationEventManager {
 
   public flushBuffered(): Promise<void> {
     if (this.flushInFlight) return this.flushInFlight;
-    const run = this.flushBufferedUnlocked();
+    const mutates = this.canPersist() && this.pendingEvents.size > 0;
+    if (mutates) this.windowStatsCache.clear();
+    const run = this.flushBufferedUnlocked().finally(() => {
+      if (mutates) this.windowStatsCache.clear();
+    });
     this.flushInFlight = run;
     run.then(
       () => { if (this.flushInFlight === run) this.flushInFlight = undefined; },
@@ -119,9 +131,10 @@ export class AuthenticationEventManager {
 
   public pruneBefore(cutoffArg: number): Promise<number> {
     if (this.pruneInFlight) return this.pruneInFlight;
-    const run = this.canPersist()
+    this.windowStatsCache.clear();
+    const run = (this.canPersist()
       ? AuthenticationEventDoc.pruneBefore(cutoffArg)
-      : Promise.resolve(0);
+      : Promise.resolve(0)).finally(() => { this.windowStatsCache.clear(); });
     this.pruneInFlight = run;
     run.then(
       () => { if (this.pruneInFlight === run) this.pruneInFlight = undefined; },
@@ -151,12 +164,6 @@ export class AuthenticationEventManager {
       return this.getInMemoryWindow(cutoff, limitArg);
     }
 
-    try {
-      await this.flushBuffered();
-    } catch (error) {
-      logger.log('warn', `Unable to flush authentication event buffer: ${(error as Error).message}`);
-    }
-
     try {
       const durable = await AuthenticationEventDoc.getWindowSummary(cutoff, limitArg);
       const buffered = [...this.pendingEvents.values()]
@@ -190,7 +197,7 @@ export class AuthenticationEventManager {
     }
   }
 
-  public getWindowStats(
+  public async getWindowStats(
     windowMsArg = 24 * 60 * 60 * 1000,
     limitArg = 100,
   ): Promise<IAuthenticationWindowStats> {
@@ -200,21 +207,25 @@ export class AuthenticationEventManager {
     if (!Number.isSafeInteger(limitArg) || limitArg <= 0 || limitArg > 500) {
       return Promise.reject(new Error('Authentication event limit must be from 1 to 500'));
     }
-    const key = `${windowMsArg}:${limitArg}`;
-    const existing = this.windowStatsInFlight.get(key);
-    if (existing) return existing;
-    const run = this.getWindowStatsUnlocked(windowMsArg, limitArg);
-    this.windowStatsInFlight.set(key, run);
-    run.then(
-      () => { if (this.windowStatsInFlight.get(key) === run) this.windowStatsInFlight.delete(key); },
-      () => { if (this.windowStatsInFlight.get(key) === run) this.windowStatsInFlight.delete(key); },
+    const persistenceAvailable = this.canPersist();
+    if (this.lastPersistenceAvailable !== persistenceAvailable) this.windowStatsCache.clear();
+    this.lastPersistenceAvailable = persistenceAvailable;
+    // Drain before entering the shared read boundary. Recording authentication itself never waits here.
+    try {
+      await this.flushBuffered();
+    } catch (error) {
+      logger.log('warn', `Unable to flush authentication event buffer: ${(error as Error).message}`);
+    }
+    return await this.windowStatsCache.get(
+      `${windowMsArg}:${limitArg}`,
+      () => this.getWindowStatsUnlocked(windowMsArg, limitArg),
     );
-    return run;
   }
 
   /** Test-only reset for the DcRouter-owned in-process buffers. */
   public async resetForTests(): Promise<void> {
     await this.flushInFlight?.catch(() => undefined);
+    this.windowStatsCache.clear();
     this.pendingEvents.clear();
     this.recentEvents.clear();
   }