@serve.zone/dcrouter 17.1.4 → 17.1.6

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

@@ -18,6 +18,7 @@ import {
   MailEdgeEligibility,
   ReleasedRemoteIngressEgressIdentitySource,
   type IEligibleMailEdge,
+  type IMailEdgeEligibilityResult,
 } from './classes.mail-edge-eligibility.js';
 import {
   evaluateMailTxtIntent,
@@ -27,14 +28,17 @@ import {
   applyMailDnsVerificationResult,
   reconcileMailDnsSingleton,
 } from './reconcile-mail-dns-singleton.js';
+import { projectMailDnsIntentAggregateStatus } from './mail-dns-status.js';
 
 export const MAIL_DNS_SYNC_CREATED_BY = 'mail-dns-reconciler';
 export const MAIL_DNS_MANAGED_BY = 'mail-dns-reconciler';
 export const MAIL_DNS_RETRY_INTERVAL_MS = 5 * 60_000;
 export const MAIL_DNS_MAX_RETRY_INTERVAL_MS = 60 * 60_000;
+export const MAIL_DNS_EDGE_ELIGIBILITY_DEBOUNCE_MS = 250;
+export const MAIL_DNS_EDGE_ELIGIBILITY_COOLDOWN_MS = 5_000;
 export const MAIL_DNS_PUBLIC_RESOLVER_OPTIONS = {
-  strategy: 'doh' as const,
-  allowDohFallback: false,
+  strategy: 'prefer-udp' as const,
+  allowDohFallback: true,
   timeoutMs: 5_000,
 };
 
@@ -65,6 +69,28 @@ function normalizeHostname(value: string): string {
   return value.trim().toLowerCase().replace(/\.$/, '');
 }
 
+function mailEdgeEligibilitySignature(result: IMailEdgeEligibilityResult): string {
+  const edges = result.edges.map((candidate) => {
+    const identities = candidate.identities.map((identity) => ({
+      family: identity.family,
+      address: identity.address,
+      heloHostname: normalizeHostname(identity.heloHostname),
+      proof: identity.proof,
+    }));
+    identities.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    return {
+      id: candidate.edge.id,
+      hostname: normalizeHostname(candidate.hostname),
+      tags: [...(candidate.edge.tags || [])].sort(),
+      publicIp: candidate.edge.publicIp || '',
+      publicIpV6: candidate.edge.publicIpV6 || '',
+      identities,
+    };
+  });
+  edges.sort((left, right) => left.id.localeCompare(right.id));
+  return JSON.stringify({ supported: result.supported, edges });
+}
+
 function normalizeMx(value: string): string {
   const [priority, exchange = ''] = value.trim().split(/\s+/);
   return `${Number(priority)} ${normalizeHostname(exchange)}`;
@@ -175,7 +201,25 @@ export class SmartDnsMailVerifier implements IMailDnsVerifier {
       };
     }
     if (result.status === 'missing') {
-      return { status: 'missing', reason: result.missingReason };
+      const evidence = result.attempts.map((attempt) => {
+        if (attempt.status === 'missing') {
+          return `${attempt.transport}:missing:${attempt.missingReason}`;
+        }
+        if (attempt.status === 'error') {
+          return `${attempt.transport}:error:${attempt.error.code}`;
+        }
+        return `${attempt.transport}:success`;
+      }).join(', ');
+      const corroboratedMissing = (
+        result.attempts.length === 2
+        && result.attempts[0].transport === 'udp'
+        && result.attempts[0].status === 'missing'
+        && result.attempts[1].transport === 'doh'
+        && result.attempts[1].status === 'missing'
+      );
+      return corroboratedMissing
+        ? { status: 'missing', reason: `${result.missingReason}; attempts=${evidence}` }
+        : { status: 'error', reason: `unconfirmed ${result.missingReason}; attempts=${evidence || 'none'}` };
     }
     return {
       status: 'error',
@@ -190,7 +234,7 @@ export class SmartDnsMailVerifier implements IMailDnsVerifier {
         return { valid: false, outcome: 'lookup-error', reason: `DNS lookup failed: ${query.reason}` };
       }
       if (query.status === 'missing') {
-        return { valid: false, outcome: 'missing', reason: `${intent.type} ${intent.name} is missing` };
+        return { valid: false, outcome: 'missing', reason: `${intent.type} ${intent.name} is missing (${query.reason})` };
       }
       const values = query.values;
       if (intent.type === 'MX') {
@@ -255,7 +299,7 @@ export class SmartDnsMailVerifier implements IMailDnsVerifier {
         return { valid: false, outcome: 'lookup-error', reason: `MX lookup failed: ${query.reason}` };
       }
       if (query.status === 'missing') {
-        return { valid: false, outcome: 'missing', reason: `MX ${intents[0].name} is missing` };
+        return { valid: false, outcome: 'missing', reason: `MX ${intents[0].name} is missing (${query.reason})` };
       }
       return evaluateMailMxValues(intents, query.values, previousValues);
     } catch (error: unknown) {
@@ -319,6 +363,12 @@ interface IPlannedDomain {
   selectorCorrectSigningSupported: boolean;
 }
 
+interface IZoneReconciliationResult {
+  errors: Map<string, IEmailDomainOperationError>;
+  provenProviderZoneIds: Set<string>;
+  readyZoneIds: Set<string>;
+}
+
 /**
  * Sole owner of managed mail DNS. API, topology, timer, and startup events only
  * mark this globally serialized reconciler dirty.
@@ -334,6 +384,13 @@ export class MailDnsSync {
   private forceAll = false;
   private forcedDomainIds = new Set<string>();
   private edgeEligibility: MailEdgeEligibility;
+  private edgeEligibilitySignature?: string;
+  private edgeEligibilityCheckTimer?: ReturnType<typeof setTimeout>;
+  private edgeEligibilityCheckPromise?: Promise<void>;
+  private pendingEdgeEligibilityReason?: string;
+  private lastEdgeEligibilitySyncAt = 0;
+  private edgeEligibilityDebounceMs = MAIL_DNS_EDGE_ELIGIBILITY_DEBOUNCE_MS;
+  private edgeEligibilityCooldownMs = MAIL_DNS_EDGE_ELIGIBILITY_COOLDOWN_MS;
 
   constructor(
     private dcRouterRef: DcRouter,
@@ -352,12 +409,18 @@ export class MailDnsSync {
     }
     this.started = true;
     this.stopped = false;
+    this.edgeEligibilitySignature = undefined;
+    this.pendingEdgeEligibilityReason = undefined;
+    this.lastEdgeEligibilitySyncAt = 0;
     this.queueRequest(undefined, true);
     try {
       await this.kick('startup');
     } catch (error: unknown) {
       if (this.retryTimer) clearTimeout(this.retryTimer);
       this.retryTimer = undefined;
+      if (this.edgeEligibilityCheckTimer) clearTimeout(this.edgeEligibilityCheckTimer);
+      this.edgeEligibilityCheckTimer = undefined;
+      this.pendingEdgeEligibilityReason = undefined;
       this.started = false;
       this.dirty = false;
       throw error;
@@ -372,6 +435,12 @@ export class MailDnsSync {
       clearTimeout(this.retryTimer);
       this.retryTimer = undefined;
     }
+    if (this.edgeEligibilityCheckTimer) {
+      clearTimeout(this.edgeEligibilityCheckTimer);
+      this.edgeEligibilityCheckTimer = undefined;
+    }
+    this.pendingEdgeEligibilityReason = undefined;
+    await this.edgeEligibilityCheckPromise?.catch(() => undefined);
     await this.runPromise?.catch(() => undefined);
     this.verifier.destroy?.();
   }
@@ -385,6 +454,65 @@ export class MailDnsSync {
     });
   }
 
+  /**
+   * RemoteIngress topology events are advisory. Resolve the actual mail-edge
+   * eligibility snapshot and only reconcile DNS when its semantic shape
+   * changes. Volatile heartbeat/observation timestamps never enter the
+   * signature.
+   */
+  public requestEdgeEligibilityCheck(reason: string): void {
+    if (this.stopped || !this.started) return;
+    this.pendingEdgeEligibilityReason = reason;
+    if (this.edgeEligibilityCheckTimer || this.edgeEligibilityCheckPromise) return;
+    this.scheduleEdgeEligibilityCheck();
+  }
+
+  private scheduleEdgeEligibilityCheck(): void {
+    if (this.stopped || !this.started || !this.pendingEdgeEligibilityReason) return;
+    const cooldownRemaining = Math.max(
+      0,
+      this.lastEdgeEligibilitySyncAt + this.edgeEligibilityCooldownMs - Date.now(),
+    );
+    const delay = Math.max(this.edgeEligibilityDebounceMs, cooldownRemaining);
+    this.edgeEligibilityCheckTimer = setTimeout(() => {
+      this.edgeEligibilityCheckTimer = undefined;
+      this.runEdgeEligibilityCheck().catch((error: unknown) => {
+        logger.log('error', `MailDnsSync edge eligibility check failed: ${(error as Error).message}`);
+      });
+    }, delay);
+    this.edgeEligibilityCheckTimer.unref?.();
+  }
+
+  private async runEdgeEligibilityCheck(): Promise<void> {
+    if (this.edgeEligibilityCheckPromise) return await this.edgeEligibilityCheckPromise;
+    const reason = this.pendingEdgeEligibilityReason;
+    this.pendingEdgeEligibilityReason = undefined;
+    if (!reason || this.stopped || !this.started) return;
+
+    this.edgeEligibilityCheckPromise = (async () => {
+      const result = await this.edgeEligibility.resolveForDomain();
+      const nextSignature = mailEdgeEligibilitySignature(result);
+      const previousSignature = this.edgeEligibilitySignature;
+      this.edgeEligibilitySignature = nextSignature;
+      if (
+        previousSignature === undefined
+        || previousSignature === nextSignature
+        || this.stopped
+        || !this.started
+      ) {
+        return;
+      }
+      this.lastEdgeEligibilitySyncAt = Date.now();
+      this.requestSync(reason);
+    })().finally(() => {
+      this.edgeEligibilityCheckPromise = undefined;
+      if (this.pendingEdgeEligibilityReason && !this.stopped && this.started) {
+        this.scheduleEdgeEligibilityCheck();
+      }
+    });
+    return await this.edgeEligibilityCheckPromise;
+  }
+
   /** Coalescing entry point used by API actions that need the durable outcome. */
   public async sync(reason: string, domainIds?: string[]): Promise<void> {
     if (this.stopped) throw new Error('MailDnsSync is stopped');
@@ -477,7 +605,8 @@ export class MailDnsSync {
     if (docs.length === 0) return;
 
     // Refresh the broad operational status independently from per-domain pins.
-    await this.edgeEligibility.resolveForDomain();
+    const broadEligibility = await this.edgeEligibility.resolveForDomain();
+    this.edgeEligibilitySignature = mailEdgeEligibilitySignature(broadEligibility);
     const plans: IPlannedDomain[] = [];
     const deletingDocs: EmailDomainDoc[] = [];
     for (const loadedDoc of docs) {
@@ -520,7 +649,7 @@ export class MailDnsSync {
         if (outcome) Object.assign(intent, outcome);
         if (intent.error) errors.push(intent.error);
       }
-      await this.validateAndActivate(plan, errors, zoneResult.errors);
+      await this.validateAndActivate(plan, errors, zoneResult, zones);
     }
 
     const cleanupProof = await this.refreshProviderZonesForCleanup(
@@ -900,12 +1029,10 @@ export class MailDnsSync {
   private async reconcileZones(
     intents: IEmailDnsRecordIntent[],
     zones: DomainDoc[],
-  ): Promise<{
-    errors: Map<string, IEmailDomainOperationError>;
-    provenProviderZoneIds: Set<string>;
-  }> {
+  ): Promise<IZoneReconciliationResult> {
     const errors = new Map<string, IEmailDomainOperationError>();
     const provenProviderZoneIds = new Set<string>();
+    const readyZoneIds = new Set<string>();
     const byZone = new Map<string, IEmailDnsRecordIntent[]>();
     for (const intent of intents) {
       if (!intent.domainId || intent.error) continue;
@@ -921,6 +1048,14 @@ export class MailDnsSync {
           const result = await this.dcRouterRef.dnsManager!.syncDomain(zone.id);
           if (!result.success) throw new Error(result.message || `Failed to refresh ${zone.name}`);
           provenProviderZoneIds.add(zone.id);
+          readyZoneIds.add(zone.id);
+        }
+        if (
+          zone.source === 'dcrouter'
+          && this.dcRouterRef.dnsServer
+          && this.dcRouterRef.dnsManager?.dnsServer === this.dcRouterRef.dnsServer
+        ) {
+          readyZoneIds.add(zone.id);
         }
         for (const intent of this.sortIntents(zoneIntents)) {
           await this.reconcileIntent(intent, zoneIntents);
@@ -939,7 +1074,7 @@ export class MailDnsSync {
         }
       }
     }
-    return { errors, provenProviderZoneIds };
+    return { errors, provenProviderZoneIds, readyZoneIds };
   }
 
   private sortIntents(intents: IEmailDnsRecordIntent[]): IEmailDnsRecordIntent[] {
@@ -1104,10 +1239,29 @@ export class MailDnsSync {
   private async validateAndActivate(
     plan: IPlannedDomain,
     errors: IEmailDomainOperationError[],
-    zoneErrors: Map<string, IEmailDomainOperationError>,
+    zoneResult: IZoneReconciliationResult,
+    zones: DomainDoc[],
   ): Promise<void> {
+    for (const intent of plan.intents) {
+      if (intent.error || zoneResult.readyZoneIds.has(intent.domainId)) continue;
+      const zone = zones.find((candidate) => candidate.id === intent.domainId);
+      const providerManaged = zone?.source === 'provider';
+      const outcome: IEmailDomainOperationError = {
+        code: providerManaged ? 'DNS_PROVIDER_ZONE_UNPROVEN' : 'DNS_SERVER_NOT_READY',
+        message: providerManaged
+          ? `DNS provider zone ${zone?.name || intent.domainId} was not proven by this reconciliation pass`
+          : `Authoritative DNS runtime is not ready for ${zone?.name || intent.domainId}`,
+        retryable: true,
+      };
+      intent.status = 'pending';
+      intent.verificationOutcome = 'lookup-error';
+      intent.error = { ...outcome, recordKey: intent.key };
+      if (!errors.some((error) => error.code === outcome.code)) errors.push(outcome);
+    }
     const verifiable = plan.intents.filter((intent) => (
-      !intent.error && !zoneErrors.has(intent.domainId)
+      !intent.error
+      && !zoneResult.errors.has(intent.domainId)
+      && zoneResult.readyZoneIds.has(intent.domainId)
     ));
     const markResult = (intent: IEmailDnsRecordIntent, result: IMailDnsVerificationResult) => {
       const outcome = result.outcome || (result.valid ? 'valid' : 'propagation');
@@ -1265,13 +1419,13 @@ export class MailDnsSync {
       && plan.revision.mxSlots.length > 0;
     plan.doc.dnsStatus = {
       mx: mailPublicationReady
-        ? this.statusForIntent(plan.intents, (intent) => intent.type === 'MX')
+        ? projectMailDnsIntentAggregateStatus(plan.intents, (intent) => intent.type === 'MX')
         : 'unchecked',
       spf: mailPublicationReady
-        ? this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=spf1'))
+        ? projectMailDnsIntentAggregateStatus(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=spf1'))
         : 'unchecked',
-      dkim: this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.name.includes('._domainkey.')),
-      dmarc: this.statusForIntent(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=DMARC1')),
+      dkim: projectMailDnsIntentAggregateStatus(plan.intents, (intent) => intent.type === 'TXT' && intent.name.includes('._domainkey.')),
+      dmarc: projectMailDnsIntentAggregateStatus(plan.intents, (intent) => intent.type === 'TXT' && intent.value.startsWith('v=DMARC1')),
       lastCheckedAt: now,
     };
     plan.doc.updatedAt = now;
@@ -1307,26 +1461,6 @@ export class MailDnsSync {
     doc.dkim.lastRotatedAt = now;
   }
 
-  private statusForIntent(
-    intents: IEmailDnsRecordIntent[],
-    predicate: (intent: IEmailDnsRecordIntent) => boolean,
-  ): 'valid' | 'missing' | 'invalid' | 'unchecked' {
-    const selected = intents.filter(predicate);
-    if (selected.length === 0) return 'missing';
-    if (selected.every((intent) => intent.status === 'valid')) return 'valid';
-    if (selected.some((intent) => (
-      intent.verificationOutcome === 'duplicate'
-      || intent.verificationOutcome === 'conflict'
-      || intent.verificationOutcome === 'invalid'
-      || intent.status === 'conflict'
-      || intent.status === 'failed'
-    ))) return 'invalid';
-    if (selected.some((intent) => intent.verificationOutcome === 'lookup-error')) {
-      return 'unchecked';
-    }
-    return 'missing';
-  }
-
   private async refreshProviderZonesForCleanup(
     docs: EmailDomainDoc[],
     zones: DomainDoc[],

package/ts/email/index.ts

@@ -3,6 +3,7 @@ export * from './classes.email-domain.manager.js';
 export * from './classes.email-route-builder.js';
 export * from './classes.mail-dns-sync.js';
 export * from './mail-dns-txt-policy.js';
+export * from './mail-dns-status.js';
 export * from './reconcile-mail-dns-singleton.js';
 export * from './classes.mail-egress-coordinator.js';
 export * from './classes.mail-edge-eligibility.js';

package/ts/email/mail-dns-status.ts

@@ -0,0 +1,35 @@
+import type {
+  IEmailDnsRecordIntent,
+  TDnsRecordStatus,
+} from '../../ts_interfaces/data/email-domain.js';
+
+/** Project one durable reconciliation intent into the operator-facing DNS status. */
+export function projectMailDnsIntentStatus(
+  intent: IEmailDnsRecordIntent | undefined,
+): TDnsRecordStatus {
+  if (!intent) return 'unchecked';
+  if (
+    intent.verificationOutcome === 'duplicate'
+    || intent.verificationOutcome === 'conflict'
+    || intent.verificationOutcome === 'invalid'
+    || intent.status === 'conflict'
+    || intent.status === 'failed'
+  ) return 'invalid';
+  if (intent.verificationOutcome === 'missing') return 'missing';
+  if (intent.verificationOutcome === 'valid' && intent.status === 'valid') return 'valid';
+  return 'unchecked';
+}
+
+/** Aggregate matching intents with deterministic operator-facing precedence. */
+export function projectMailDnsIntentAggregateStatus(
+  intents: IEmailDnsRecordIntent[],
+  predicate: (intent: IEmailDnsRecordIntent) => boolean,
+): TDnsRecordStatus {
+  const selected = intents.filter(predicate);
+  if (selected.length === 0) return 'unchecked';
+  const statuses = selected.map(projectMailDnsIntentStatus);
+  if (statuses.includes('invalid')) return 'invalid';
+  if (statuses.includes('missing')) return 'missing';
+  if (statuses.includes('unchecked')) return 'unchecked';
+  return 'valid';
+}

package/ts/monitoring/classes.metricscache.ts

@@ -1,10 +1,12 @@
 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) {
@@ -19,20 +21,44 @@ export class MetricsCache {
     const now = Date.now();
     const actualTTL = ttl ?? this.defaultTTL;
     
-    if (cached && (now - cached.timestamp) < actualTTL) {
+    if (cached && (now - cached.timestamp) < cached.ttl) {
       return cached.data;
     }
+
+    if (cached) {
+      this.cache.delete(key);
+    }
+
+    const pending = this.inFlight.get(key) as Promise<T> | undefined;
+    if (pending) {
+      return pending;
+    }
     
     const result = computeFn();
     
     // Handle both sync and async compute functions
     if (result instanceof Promise) {
-      return result.then(data => {
-        this.cache.set(key, { data, timestamp: now });
-        return data;
-      });
+      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 });
+      this.cache.set(key, { data: result, timestamp: now, ttl: actualTTL });
       return result;
     }
   }
@@ -42,6 +68,7 @@ export class MetricsCache {
    */
   public invalidate(key: string): void {
     this.cache.delete(key);
+    this.inFlight.delete(key);
   }
   
   /**
@@ -49,6 +76,7 @@ export class MetricsCache {
    */
   public clear(): void {
     this.cache.clear();
+    this.inFlight.clear();
   }
   
   /**
@@ -67,9 +95,9 @@ export class MetricsCache {
   public cleanup(): void {
     const now = Date.now();
     for (const [key, entry] of this.cache.entries()) {
-      if (now - entry.timestamp > this.defaultTTL) {
+      if (now - entry.timestamp > entry.ttl) {
         this.cache.delete(key);
       }
     }
   }
-}
+}