@cadenza.io/service 2.17.4 → 2.17.6

package/dist/index.d.mts

@@ -282,6 +282,10 @@ declare class ServiceRegistry {
     getInquiryResponderDescriptor(task: Task): InquiryResponderDescriptor;
     private getInstance;
     private getLocalInstance;
+    private summarizeTransportForDebug;
+    private summarizeInstanceForRuntimeStatusFallback;
+    private summarizeRuntimeStatusInquiryReports;
+    private createRuntimeStatusFallbackError;
     resolveLocalStatusCheck(ctx?: AnyObject): {
         __status: string;
         __error: string;
@@ -316,6 +320,7 @@ declare class ServiceRegistry {
     private markTransportClientCreated;
     private registerDependee;
     private unregisterDependee;
+    private reconcileBootstrapPlaceholderInstance;
     private getHeartbeatMisses;
     private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
@@ -23162,6 +23167,7 @@ interface ServiceInstanceDescriptor {
     health: AnyObject;
     isFrontend: boolean;
     isDatabase?: boolean;
+    isBootstrapPlaceholder?: boolean;
     transports: ServiceTransportDescriptor[];
     clientCreatedTransportIds?: string[];
 }

package/dist/index.d.ts

@@ -282,6 +282,10 @@ declare class ServiceRegistry {
     getInquiryResponderDescriptor(task: Task): InquiryResponderDescriptor;
     private getInstance;
     private getLocalInstance;
+    private summarizeTransportForDebug;
+    private summarizeInstanceForRuntimeStatusFallback;
+    private summarizeRuntimeStatusInquiryReports;
+    private createRuntimeStatusFallbackError;
     resolveLocalStatusCheck(ctx?: AnyObject): {
         __status: string;
         __error: string;
@@ -316,6 +320,7 @@ declare class ServiceRegistry {
     private markTransportClientCreated;
     private registerDependee;
     private unregisterDependee;
+    private reconcileBootstrapPlaceholderInstance;
     private getHeartbeatMisses;
     private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
@@ -23162,6 +23167,7 @@ interface ServiceInstanceDescriptor {
     health: AnyObject;
     isFrontend: boolean;
     isDatabase?: boolean;
+    isBootstrapPlaceholder?: boolean;
     transports: ServiceTransportDescriptor[];
     clientCreatedTransportIds?: string[];
 }

package/dist/index.js

@@ -531,6 +531,9 @@ function normalizeServiceInstanceDescriptor(value) {
     health: raw.health ?? {},
     isFrontend: Boolean(raw.isFrontend ?? raw.is_frontend ?? false),
     isDatabase: Boolean(raw.isDatabase ?? raw.is_database ?? false),
+    isBootstrapPlaceholder: Boolean(
+      raw.isBootstrapPlaceholder ?? raw.is_bootstrap_placeholder ?? false
+    ),
     transports,
     clientCreatedTransportIds: Array.isArray(raw.clientCreatedTransportIds) ? raw.clientCreatedTransportIds.map((entry) => normalizeString2(entry)).filter((entry) => entry.length > 0) : void 0
   };
@@ -944,6 +947,7 @@ var ServiceRegistry = class _ServiceRegistry {
             health: ctx.health ?? ctx.__health ?? {},
             numberOfRunningGraphs: ctx.numberOfRunningGraphs ?? ctx.__numberOfRunningGraphs ?? 0,
             isPrimary: false,
+            isBootstrapPlaceholder: !!ctx.isBootstrapPlaceholder,
             transports: ctx.transports ?? []
           } : void 0)
         );
@@ -998,6 +1002,9 @@ var ServiceRegistry = class _ServiceRegistry {
           trackedInstance.acceptingWork = snapshot.acceptingWork;
           trackedInstance.reportedAt = trackedInstance.reportedAt ?? (/* @__PURE__ */ new Date()).toISOString();
         }
+        if (!serviceInstance.isBootstrapPlaceholder) {
+          this.reconcileBootstrapPlaceholderInstance(serviceName, uuid5, emit);
+        }
         if (this.serviceName === serviceName) {
           return false;
         }
@@ -1844,12 +1851,14 @@ var ServiceRegistry = class _ServiceRegistry {
             this.useSocket ? "socket" : "rest"
           ) : void 0;
           const message = error instanceof Error ? error.message : String(error);
+          const diagnostics = error && typeof error === "object" && "runtimeStatusFallback" in error && error.runtimeStatusFallback && typeof error.runtimeStatusFallback === "object" ? error.runtimeStatusFallback : void 0;
           CadenzaService.log(
             "Runtime status fallback inquiry failed.",
             {
               serviceName,
               serviceInstanceId,
-              error: message
+              error: message,
+              diagnostics
             },
             "warning"
           );
@@ -2339,6 +2348,67 @@ var ServiceRegistry = class _ServiceRegistry {
     }
     return this.getInstance(this.serviceName, this.serviceInstanceId);
   }
+  summarizeTransportForDebug(transport) {
+    if (!transport) {
+      return void 0;
+    }
+    return {
+      uuid: transport.uuid,
+      role: transport.role,
+      origin: transport.origin,
+      protocols: transport.protocols,
+      clientCreated: transport.clientCreated
+    };
+  }
+  summarizeInstanceForRuntimeStatusFallback(instance) {
+    return {
+      exists: Boolean(instance),
+      runtimeState: instance?.runtimeState,
+      acceptingWork: instance?.acceptingWork,
+      reportedAt: instance?.reportedAt ?? null,
+      isDatabase: instance?.isDatabase,
+      isFrontend: instance?.isFrontend,
+      isBootstrapPlaceholder: instance?.isBootstrapPlaceholder,
+      transports: (instance?.transports ?? []).map((transport) => ({
+        uuid: transport.uuid,
+        role: transport.role,
+        origin: transport.origin,
+        protocols: transport.protocols,
+        clientCreated: transport.clientCreated
+      }))
+    };
+  }
+  summarizeRuntimeStatusInquiryReports(inquiryResult) {
+    const reports = Array.isArray(inquiryResult.runtimeStatusReports) ? inquiryResult.runtimeStatusReports : [];
+    return reports.map((candidate) => {
+      const normalized = this.normalizeRuntimeStatusReport(candidate);
+      if (normalized) {
+        return {
+          serviceName: normalized.serviceName,
+          serviceInstanceId: normalized.serviceInstanceId,
+          transportId: normalized.transportId,
+          state: normalized.state,
+          acceptingWork: normalized.acceptingWork,
+          reportedAt: normalized.reportedAt
+        };
+      }
+      const raw = candidate && typeof candidate === "object" ? candidate : {};
+      const rawState = raw.state === "healthy" || raw.state === "degraded" || raw.state === "overloaded" || raw.state === "unavailable" ? raw.state : void 0;
+      return {
+        serviceName: typeof raw.serviceName === "string" ? raw.serviceName : typeof raw.__serviceName === "string" ? raw.__serviceName : void 0,
+        serviceInstanceId: typeof raw.serviceInstanceId === "string" ? raw.serviceInstanceId : typeof raw.__serviceInstanceId === "string" ? raw.__serviceInstanceId : void 0,
+        transportId: typeof raw.transportId === "string" ? raw.transportId : typeof raw.serviceTransportId === "string" ? raw.serviceTransportId : void 0,
+        state: rawState,
+        acceptingWork: typeof raw.acceptingWork === "boolean" ? raw.acceptingWork : void 0,
+        reportedAt: typeof raw.reportedAt === "string" ? raw.reportedAt : void 0
+      };
+    });
+  }
+  createRuntimeStatusFallbackError(message, diagnostics) {
+    return Object.assign(new Error(message), {
+      runtimeStatusFallback: diagnostics
+    });
+  }
   resolveLocalStatusCheck(ctx = {}) {
     if (!this.serviceName) {
       return {
@@ -2465,6 +2535,39 @@ var ServiceRegistry = class _ServiceRegistry {
     this.missedHeartbeatsByInstance.delete(serviceInstanceId);
     this.runtimeStatusFallbackInFlightByInstance.delete(serviceInstanceId);
   }
+  reconcileBootstrapPlaceholderInstance(serviceName, resolvedInstanceId, emit) {
+    const instances = this.instances.get(serviceName);
+    if (!instances?.length) {
+      return;
+    }
+    const placeholders = instances.filter(
+      (instance) => instance.uuid !== resolvedInstanceId && instance.isBootstrapPlaceholder
+    );
+    if (!placeholders.length) {
+      return;
+    }
+    for (const placeholder of placeholders) {
+      const wasDependee = this.dependeeByInstance.has(placeholder.uuid);
+      const requiredForReadiness = this.readinessDependeeByInstance.has(
+        placeholder.uuid
+      );
+      for (const transport of placeholder.transports) {
+        const transportKey = buildTransportClientKey(transport);
+        emit(`meta.socket_shutdown_requested:${transportKey}`, {});
+        emit(`meta.fetch.destroy_requested:${transportKey}`, {});
+      }
+      this.unregisterDependee(placeholder.uuid, serviceName);
+      if (wasDependee) {
+        this.registerDependee(serviceName, resolvedInstanceId, {
+          requiredForReadiness
+        });
+      }
+    }
+    this.instances.set(
+      serviceName,
+      instances.filter((instance) => !instance.isBootstrapPlaceholder)
+    );
+  }
   getHeartbeatMisses(serviceInstanceId, now = Date.now()) {
     const observedMisses = this.missedHeartbeatsByInstance.get(serviceInstanceId) ?? 0;
     const lastHeartbeatAt = this.lastHeartbeatAtByInstance.get(serviceInstanceId) ?? 0;
@@ -2658,32 +2761,48 @@ var ServiceRegistry = class _ServiceRegistry {
   }
   async resolveRuntimeStatusFallbackInquiry(serviceName, serviceInstanceId, options = {}) {
     const instance = this.getInstance(serviceName, serviceInstanceId);
-    if (instance) {
-      const directReport = await this.requestRuntimeStatusViaRest(
-        instance,
-        serviceName,
-        serviceInstanceId
-      );
-      if (directReport) {
-        if (!this.applyRuntimeStatusReport(directReport)) {
-          throw new Error(
-            `No tracked instance for runtime fallback ${serviceName}/${serviceInstanceId}`
-          );
-        }
-        this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
-        this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
-        return {
-          report: directReport,
-          inquiryMeta: {
-            inquiry: META_RUNTIME_STATUS_INTENT,
-            responded: 1,
-            failed: 0,
-            timedOut: 0,
-            pending: 0,
-            directStatusCheck: true
+    const directStatusCheck = instance ? await this.requestRuntimeStatusViaRest(
+      instance,
+      serviceName,
+      serviceInstanceId
+    ) : {
+      report: null,
+      diagnostic: {
+        attempted: false,
+        outcome: "instance_missing"
+      }
+    };
+    if (directStatusCheck.report) {
+      if (!this.applyRuntimeStatusReport(directStatusCheck.report)) {
+        throw this.createRuntimeStatusFallbackError(
+          `No tracked instance for runtime fallback ${serviceName}/${serviceInstanceId}`,
+          {
+            target: {
+              serviceName,
+              serviceInstanceId
+            },
+            instance: this.summarizeInstanceForRuntimeStatusFallback(instance),
+            directStatusCheck: directStatusCheck.diagnostic,
+            inquiry: {
+              meta: {},
+              reportTargets: []
+            }
           }
-        };
+        );
       }
+      this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
+      this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
+      return {
+        report: directStatusCheck.report,
+        inquiryMeta: {
+          inquiry: META_RUNTIME_STATUS_INTENT,
+          responded: 1,
+          failed: 0,
+          timedOut: 0,
+          pending: 0,
+          directStatusCheck: true
+        }
+      };
     }
     const inquiryResult = await CadenzaService.inquire(
       META_RUNTIME_STATUS_INTENT,
@@ -2705,13 +2824,37 @@ var ServiceRegistry = class _ServiceRegistry {
       serviceInstanceId
     );
     if (!report) {
-      throw new Error(
-        `No runtime status report for ${serviceName}/${serviceInstanceId}`
+      throw this.createRuntimeStatusFallbackError(
+        `No runtime status report for ${serviceName}/${serviceInstanceId}`,
+        {
+          target: {
+            serviceName,
+            serviceInstanceId
+          },
+          instance: this.summarizeInstanceForRuntimeStatusFallback(instance),
+          directStatusCheck: directStatusCheck.diagnostic,
+          inquiry: {
+            meta: inquiryResult.__inquiryMeta && typeof inquiryResult.__inquiryMeta === "object" ? inquiryResult.__inquiryMeta : {},
+            reportTargets: this.summarizeRuntimeStatusInquiryReports(inquiryResult)
+          }
+        }
       );
     }
     if (!this.applyRuntimeStatusReport(report)) {
-      throw new Error(
-        `No tracked instance for runtime fallback ${serviceName}/${serviceInstanceId}`
+      throw this.createRuntimeStatusFallbackError(
+        `No tracked instance for runtime fallback ${serviceName}/${serviceInstanceId}`,
+        {
+          target: {
+            serviceName,
+            serviceInstanceId
+          },
+          instance: this.summarizeInstanceForRuntimeStatusFallback(instance),
+          directStatusCheck: directStatusCheck.diagnostic,
+          inquiry: {
+            meta: inquiryResult.__inquiryMeta && typeof inquiryResult.__inquiryMeta === "object" ? inquiryResult.__inquiryMeta : {},
+            reportTargets: this.summarizeRuntimeStatusInquiryReports(inquiryResult)
+          }
+        }
       );
     }
     this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
@@ -2723,11 +2866,23 @@ var ServiceRegistry = class _ServiceRegistry {
   }
   async requestRuntimeStatusViaRest(instance, serviceName, serviceInstanceId) {
     if (typeof globalThis.fetch !== "function") {
-      return null;
+      return {
+        report: null,
+        diagnostic: {
+          attempted: false,
+          outcome: "fetch_unavailable"
+        }
+      };
     }
     const transport = this.getRouteableTransport(instance, "rest");
     if (!transport) {
-      return null;
+      return {
+        report: null,
+        diagnostic: {
+          attempted: false,
+          outcome: "no_rest_transport"
+        }
+      };
     }
     const controller = typeof AbortController === "function" ? new AbortController() : null;
     const timeoutId = controller ? setTimeout(() => controller.abort(), this.runtimeStatusFallbackTimeoutMs) : null;
@@ -2737,7 +2892,16 @@ var ServiceRegistry = class _ServiceRegistry {
         signal: controller?.signal
       });
       if ("ok" in response && response.ok === false) {
-        return null;
+        return {
+          report: null,
+          diagnostic: {
+            attempted: true,
+            outcome: "http_error",
+            transport: this.summarizeTransportForDebug(transport),
+            responseStatus: typeof response.status === "number" ? response.status : void 0,
+            responseStatusText: typeof response.statusText === "string" ? response.statusText : void 0
+          }
+        };
       }
       const payload = typeof response.json === "function" ? await response.json() : response;
       const report = this.normalizeRuntimeStatusReport({
@@ -2747,14 +2911,46 @@ var ServiceRegistry = class _ServiceRegistry {
         transportProtocols: payload?.transportProtocols ?? transport.protocols
       });
       if (!report) {
-        return null;
+        return {
+          report: null,
+          diagnostic: {
+            attempted: true,
+            outcome: "invalid_report",
+            transport: this.summarizeTransportForDebug(transport),
+            payloadKeys: payload && typeof payload === "object" ? Object.keys(payload).sort() : []
+          }
+        };
       }
       if (report.serviceName !== serviceName || report.serviceInstanceId !== serviceInstanceId) {
-        return null;
+        return {
+          report: null,
+          diagnostic: {
+            attempted: true,
+            outcome: "identity_mismatch",
+            transport: this.summarizeTransportForDebug(transport),
+            payloadServiceName: report.serviceName,
+            payloadServiceInstanceId: report.serviceInstanceId
+          }
+        };
       }
-      return report;
-    } catch {
-      return null;
+      return {
+        report,
+        diagnostic: {
+          attempted: true,
+          outcome: "matched",
+          transport: this.summarizeTransportForDebug(transport)
+        }
+      };
+    } catch (error) {
+      return {
+        report: null,
+        diagnostic: {
+          attempted: true,
+          outcome: "fetch_error",
+          transport: this.summarizeTransportForDebug(transport),
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
     } finally {
       if (timeoutId) {
         clearTimeout(timeoutId);
@@ -9460,6 +9656,7 @@ var CadenzaService = class {
           isBlocked: false,
           health: {},
           isFrontend: false,
+          isBootstrapPlaceholder: true,
           transports: resolvedBootstrapEndpoint ? [
             this.createBootstrapTransport(
               "cadenza-db",
@@ -9487,6 +9684,7 @@ var CadenzaService = class {
           isBlocked: false,
           health: {},
           isFrontend: false,
+          isBootstrapPlaceholder: true,
           transports: relatedTransport ? [
             {
               uuid: `${service[0]}-${relatedTransport.role}`,