@serve.zone/dcrouter 16.4.0 → 16.5.0

package/ts/opsserver/handlers/email-domain.handler.ts

@@ -3,6 +3,91 @@ import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
 import { requireOpsAuth } from '../helpers/auth.js';
 
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  return typeof valueArg === 'object' && valueArg !== null;
+};
+
+const normalizeActionErrors = (
+  valueArg: unknown,
+): interfaces.requests.IEmailDomainActionError[] | undefined => {
+  if (!Array.isArray(valueArg)) return undefined;
+
+  const errors: interfaces.requests.IEmailDomainActionError[] = [];
+  for (const entry of valueArg) {
+    if (!isRecord(entry) || typeof entry.message !== 'string') continue;
+    errors.push({
+      code: typeof entry.code === 'string' ? entry.code : 'EMAIL_DOMAIN_ACTION_FAILED',
+      message: entry.message,
+      recordKey: typeof entry.recordKey === 'string' ? entry.recordKey : undefined,
+      retryable: typeof entry.retryable === 'boolean' ? entry.retryable : undefined,
+    });
+  }
+  return errors.length > 0 ? errors : undefined;
+};
+
+const normalizeEmailDomainActionResult = (
+  valueArg: unknown,
+  defaultSuccess = true,
+): interfaces.requests.IEmailDomainActionResult => {
+  const value = isRecord(valueArg) ? valueArg : {};
+  const directDomain = isRecord(value.domain)
+    ? value.domain
+    : typeof value.id === 'string' && typeof value.domain === 'string'
+      ? value
+      : undefined;
+  const reconciliation = isRecord(directDomain?.reconciliation)
+    ? directDomain.reconciliation
+    : undefined;
+  const rawLifecycle = value.lifecycleStatus ?? reconciliation?.lifecycleStatus;
+  const lifecycleStatus =
+    rawLifecycle === 'active' ||
+    rawLifecycle === 'pending' ||
+    rawLifecycle === 'failed' ||
+    rawLifecycle === 'deleting'
+      ? rawLifecycle
+      : undefined;
+  const reconciliationCapability = isRecord(reconciliation?.capability)
+    ? reconciliation.capability.egressIdentityProof
+    : undefined;
+  const rawCapability = value.capability ?? reconciliationCapability;
+  const capability =
+    rawCapability === 'supported' || rawCapability === 'unsupported'
+      ? rawCapability
+      : undefined;
+  const errors = normalizeActionErrors(value.errors ?? reconciliation?.errors);
+
+  return {
+    success: typeof value.success === 'boolean'
+      ? value.success
+      : lifecycleStatus === 'failed'
+        ? false
+        : defaultSuccess,
+    message: typeof value.message === 'string' ? value.message : errors?.[0]?.message,
+    lifecycleStatus,
+    code: typeof value.code === 'string' ? value.code : errors?.[0]?.code,
+    errors,
+    retryAt: typeof value.retryAt === 'string'
+      ? value.retryAt
+      : typeof reconciliation?.retryAt === 'string'
+        ? reconciliation.retryAt
+        : undefined,
+    capability,
+  };
+};
+
+const normalizeEmailDomainActionFailure = (
+  errorArg: unknown,
+  fallbackMessageArg: string,
+): interfaces.requests.IEmailDomainActionResult => {
+  const result = normalizeEmailDomainActionResult(errorArg, false);
+  const errorMessage = errorArg instanceof Error ? errorArg.message : undefined;
+  return {
+    ...result,
+    success: false,
+    message: result.message || errorMessage || result.errors?.[0]?.message || fallbackMessageArg,
+  };
+};
+
 /**
  * CRUD + DNS provisioning handler for email domains.
  *
@@ -31,6 +116,23 @@ export class EmailDomainHandler {
     return this.opsServerRef.dcRouterRef.emailDomainManager;
   }
 
+  private managerUnavailable(): interfaces.requests.IEmailDomainActionResult {
+    const message = 'EmailDomainManager not initialized';
+    return {
+      success: false,
+      message,
+      code: 'EMAIL_DOMAIN_MANAGER_UNAVAILABLE',
+      capability: 'unsupported',
+      errors: [
+        {
+          code: 'EMAIL_DOMAIN_MANAGER_UNAVAILABLE',
+          message,
+          retryable: true,
+        },
+      ],
+    };
+  }
+
   private registerHandlers(): void {
     // List all email domains
     this.typedrouter.addTypedHandler(
@@ -63,10 +165,10 @@ export class EmailDomainHandler {
         async (dataArg) => {
           await this.requireAuth(dataArg, 'email-domains:write' as any);
           if (!this.manager) {
-            return { success: false, message: 'EmailDomainManager not initialized' };
+            return this.managerUnavailable();
           }
           try {
-            const domain = await this.manager.createEmailDomain({
+            const rawResult: unknown = await this.manager.createEmailDomain({
               linkedDomainId: dataArg.linkedDomainId,
               subdomain: dataArg.subdomain,
               dkimSelector: dataArg.dkimSelector,
@@ -75,9 +177,18 @@ export class EmailDomainHandler {
               rotationIntervalDays: dataArg.rotationIntervalDays,
               remoteIngress: dataArg.remoteIngress,
             });
-            return { success: true, domain };
+            const result = normalizeEmailDomainActionResult(rawResult);
+            if (!result.success) return result;
+
+            const resultRecord = isRecord(rawResult) ? rawResult : undefined;
+            const domain = isRecord(resultRecord?.domain)
+              ? resultRecord.domain as unknown as interfaces.data.IEmailDomain
+              : typeof resultRecord?.id === 'string'
+                ? rawResult as interfaces.data.IEmailDomain
+                : undefined;
+            return { ...result, domain };
           } catch (err: unknown) {
-            return { success: false, message: (err as Error).message };
+            return normalizeEmailDomainActionFailure(err, 'Failed to create email domain');
           }
         },
       ),
@@ -90,18 +201,18 @@ export class EmailDomainHandler {
         async (dataArg) => {
           await this.requireAuth(dataArg, 'email-domains:write' as any);
           if (!this.manager) {
-            return { success: false, message: 'EmailDomainManager not initialized' };
+            return this.managerUnavailable();
           }
           try {
-            await this.manager.updateEmailDomain(dataArg.id, {
+            const rawResult: unknown = await this.manager.updateEmailDomain(dataArg.id, {
               rotateKeys: dataArg.rotateKeys,
               rotationIntervalDays: dataArg.rotationIntervalDays,
               rateLimits: dataArg.rateLimits,
               remoteIngress: dataArg.remoteIngress,
             });
-            return { success: true };
+            return normalizeEmailDomainActionResult(rawResult);
           } catch (err: unknown) {
-            return { success: false, message: (err as Error).message };
+            return normalizeEmailDomainActionFailure(err, 'Failed to update email domain');
           }
         },
       ),
@@ -114,13 +225,13 @@ export class EmailDomainHandler {
         async (dataArg) => {
           await this.requireAuth(dataArg, 'email-domains:write' as any);
           if (!this.manager) {
-            return { success: false, message: 'EmailDomainManager not initialized' };
+            return this.managerUnavailable();
           }
           try {
-            await this.manager.deleteEmailDomain(dataArg.id);
-            return { success: true };
+            const rawResult: unknown = await this.manager.deleteEmailDomain(dataArg.id);
+            return normalizeEmailDomainActionResult(rawResult);
           } catch (err: unknown) {
-            return { success: false, message: (err as Error).message };
+            return normalizeEmailDomainActionFailure(err, 'Failed to delete email domain');
           }
         },
       ),
@@ -133,14 +244,27 @@ export class EmailDomainHandler {
         async (dataArg) => {
           await this.requireAuth(dataArg, 'email-domains:read' as any);
           if (!this.manager) {
-            return { success: false, message: 'EmailDomainManager not initialized' };
+            return this.managerUnavailable();
           }
           try {
-            const records = await this.manager.validateDns(dataArg.id);
-            const domain = await this.manager.getById(dataArg.id);
-            return { success: true, domain: domain ?? undefined, records };
+            const rawResult: unknown = await this.manager.validateDns(dataArg.id);
+            const result = normalizeEmailDomainActionResult(rawResult);
+            if (!result.success) return result;
+
+            const resultRecord = isRecord(rawResult) ? rawResult : undefined;
+            const records = (
+              Array.isArray(rawResult)
+                ? rawResult
+                : Array.isArray(resultRecord?.records)
+                  ? resultRecord.records
+                  : undefined
+            ) as interfaces.data.IEmailDnsRecord[] | undefined;
+            const domain = isRecord(resultRecord?.domain)
+              ? resultRecord.domain as unknown as interfaces.data.IEmailDomain
+              : await this.manager.getById(dataArg.id) ?? undefined;
+            return { ...result, domain, records };
           } catch (err: unknown) {
-            return { success: false, message: (err as Error).message };
+            return normalizeEmailDomainActionFailure(err, 'Failed to validate email domain DNS');
           }
         },
       ),
@@ -165,13 +289,22 @@ export class EmailDomainHandler {
         async (dataArg) => {
           await this.requireAuth(dataArg, 'email-domains:write' as any);
           if (!this.manager) {
-            return { success: false, message: 'EmailDomainManager not initialized' };
+            return this.managerUnavailable();
           }
           try {
-            const provisioned = await this.manager.provisionDnsRecords(dataArg.id);
-            return { success: true, provisioned };
+            const rawResult: unknown = await this.manager.provisionDnsRecords(dataArg.id);
+            const result = normalizeEmailDomainActionResult(rawResult);
+            if (!result.success) return result;
+
+            const resultRecord = isRecord(rawResult) ? rawResult : undefined;
+            const provisioned = typeof rawResult === 'number'
+              ? rawResult
+              : typeof resultRecord?.provisioned === 'number'
+                ? resultRecord.provisioned
+                : undefined;
+            return { ...result, provisioned };
           } catch (err: unknown) {
-            return { success: false, message: (err as Error).message };
+            return normalizeEmailDomainActionFailure(err, 'Failed to provision email domain DNS');
           }
         },
       ),

package/ts/remoteingress/classes.hub-lifecycle.ts

@@ -223,6 +223,7 @@ export class RemoteIngressHubLifecycle {
       tls: tlsConfig,
       performance: manager.getHubPerformanceConfig(),
     });
+    tunnelManager.setOnTopologyChanged((reason) => this.dcRouterRef.mailDnsSync.requestSync(reason));
     try {
       await tunnelManager.start();
     } catch (err) {

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

@@ -20,8 +20,14 @@ export type TRemoteIngressEgressProxyRequest = Omit<plugins.remoteingress.IEgres
   edgeFilter?: string[];
 };
 
+export type TRemoteIngressHubStatus = Awaited<ReturnType<
+  InstanceType<typeof plugins.remoteingress.RemoteIngressHub>['getStatus']
+>>;
+type TRemoteIngressHubEdgeStatus = TRemoteIngressHubStatus['connectedEdges'][number];
+
 /** Cooldown applied to an edge after a failed egress open before it is deprioritized. */
 const egressFailureCooldownMs = 30_000;
+const egressStatusFreshnessMs = 45_000;
 
 /**
  * Manages the RemoteIngressHub instance and tracks connected edge statuses.
@@ -38,6 +44,7 @@ export class TunnelManager {
   private egressProxyEdgeByProxyId: Map<string, string> = new Map();
   private activeEgressProxiesByEdge: Map<string, number> = new Map();
   private egressFailureCooldownUntil: Map<string, number> = new Map();
+  private onTopologyChanged?: (reason: string) => void;
 
   constructor(manager: RemoteIngressManager, config: ITunnelManagerConfig = {}) {
     this.manager = manager;
@@ -54,10 +61,12 @@ export class TunnelManager {
         lastHeartbeat: Date.now(),
         connectedAt: Date.now(),
       });
+      this.onTopologyChanged?.(`RemoteIngress edge connected: ${data.edgeId}`);
     });
 
     this.hub.on('edgeDisconnected', (data: { edgeId: string }) => {
       this.edgeStatuses.delete(data.edgeId);
+      this.onTopologyChanged?.(`RemoteIngress edge disconnected: ${data.edgeId}`);
     });
 
     this.hub.on('streamSummary', (data: {
@@ -94,6 +103,14 @@ export class TunnelManager {
         this.egressFailureCooldownUntil.set(data.edgeId, Date.now() + egressFailureCooldownMs);
       }
     });
+
+    this.hub.on('egressIdentityChanged', (data) => {
+      this.onTopologyChanged?.(`RemoteIngress egress identity changed: ${data.edgeId}`);
+    });
+  }
+
+  public setOnTopologyChanged(callback: (reason: string) => void): void {
+    this.onTopologyChanged = callback;
   }
 
   /**
@@ -165,6 +182,7 @@ export class TunnelManager {
     if (this.stopped) return;
     if (!hubStatus || !hubStatus.connectedEdges) return;
 
+    const before = this.getTopologySignature();
     const rustEdgeIds = new Set<string>();
 
     for (const rustEdge of hubStatus.connectedEdges) {
@@ -199,6 +217,10 @@ export class TunnelManager {
         this.edgeStatuses.delete(edgeId);
       }
     }
+    const after = this.getTopologySignature();
+    if (before !== after) {
+      this.onTopologyChanged?.('RemoteIngress mail egress topology changed');
+    }
   }
 
   /**
@@ -260,33 +282,43 @@ export class TunnelManager {
     );
   }
 
+  /** Authoritative hub state used by the source-bound mail identity adapter. */
+  public async getAuthoritativeHubStatus(): Promise<TRemoteIngressHubStatus | undefined> {
+    if (this.stopped) return undefined;
+    return await this.hub.getStatus();
+  }
+
   /**
    * Eligibility (connected + egressEnabled + egressTcpV1 + native QUIC), scoped by
    * edgeId/edgeFilter, capped by per-edge maxConcurrentStreams, ordered deterministically:
    * not-in-cooldown first, then fewest active tunnels, then edgeId.
    */
   private selectEgressCandidates(
-    connectedEdges: any[],
+    connectedEdges: TRemoteIngressHubEdgeStatus[],
     request: TRemoteIngressEgressProxyRequest,
   ): Array<{ edgeId: string; activeStreams: number }> {
     const eligible = connectedEdges.filter((edge: any) => {
       const hasEgressCapability = Array.isArray(edge.capabilities) && edge.capabilities.includes('egressTcpV1');
       const usesQuic = edge.transportMode === 'quic'
         || (edge.transportMode === 'quicWithFallback' && edge.fallbackUsed === false);
-      return edge.egressEnabled === true && hasEgressCapability && usesQuic;
+      const observed = this.edgeStatuses.get(edge.edgeId);
+      const fresh = observed?.connected
+        && observed.lastHeartbeat !== null
+        && Date.now() - observed.lastHeartbeat <= egressStatusFreshnessMs;
+      return edge.egressEnabled === true && hasEgressCapability && usesQuic && fresh;
     });
 
     let scoped = eligible;
     if (request.edgeId) {
-      scoped = eligible.filter((edge: any) => edge.edgeId === request.edgeId);
+      scoped = eligible.filter((edge) => edge.edgeId === request.edgeId);
     } else if (request.edgeFilter && request.edgeFilter.length > 0) {
       const allowedIds = new Set(
         this.manager.resolveEdgesByFilter(request.edgeFilter).map((edge) => edge.id),
       );
-      scoped = eligible.filter((edge: any) => allowedIds.has(edge.edgeId));
+      scoped = eligible.filter((edge) => allowedIds.has(edge.edgeId));
     }
 
-    const underCap = scoped.filter((edge: any) => {
+    const underCap = scoped.filter((edge) => {
       const cap = this.manager.getEdge(edge.edgeId)?.egress?.maxConcurrentStreams;
       if (!cap) return true;
       return (this.activeEgressProxiesByEdge.get(edge.edgeId) || 0) < cap;
@@ -295,7 +327,7 @@ export class TunnelManager {
     const now = Date.now();
     const inCooldown = (edgeId: string) => (this.egressFailureCooldownUntil.get(edgeId) || 0) > now;
     return underCap
-      .map((edge: any) => ({ edgeId: edge.edgeId as string, activeStreams: Number(edge.activeStreams) || 0 }))
+      .map((edge) => ({ edgeId: edge.edgeId, activeStreams: Number(edge.activeStreams) || 0 }))
       .sort((a, b) => {
         const cooldownDelta = Number(inCooldown(a.edgeId)) - Number(inCooldown(b.edgeId));
         if (cooldownDelta !== 0) return cooldownDelta;
@@ -355,7 +387,7 @@ export class TunnelManager {
     return await this.hub.stopEgressTcpProxy(proxyId);
   }
 
-  private applyRustStatus(status: IRemoteIngressStatus, rustEdge: any): void {
+  private applyRustStatus(status: IRemoteIngressStatus, rustEdge: TRemoteIngressHubEdgeStatus): void {
     status.transportMode = rustEdge.transportMode;
     status.fallbackUsed = rustEdge.fallbackUsed;
     status.capabilities = rustEdge.capabilities;
@@ -367,6 +399,20 @@ export class TunnelManager {
     status.udp = rustEdge.udp;
   }
 
+  private getTopologySignature(): string {
+    return [...this.edgeStatuses.values()]
+      .map((status) => [
+        status.edgeId,
+        status.connected,
+        status.egressEnabled,
+        status.transportMode,
+        status.fallbackUsed,
+        [...(status.capabilities || [])].sort().join(','),
+      ].join('|'))
+      .sort()
+      .join(';');
+  }
+
   /**
    * Get runtime statuses for all known edges.
    */

package/ts_web/00_commitinfo_data.ts

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