@opengeni/api-router 2.3.2-canary.2 → 2.5.0

package/dist/fatal-process-boundary.d.ts

@@ -0,0 +1,25 @@
+import type { Observability } from "@opengeni/observability";
+export type ApiFatalEvent = "startup_failure" | "unhandled_rejection" | "uncaught_exception";
+export type ApiFatalPhase = "startup" | "running";
+export type ApiFatalReasonKind = "bigint" | "boolean" | "error" | "function" | "null" | "number" | "object" | "string" | "symbol" | "undefined";
+type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan">;
+type ApiFatalProcess = {
+    on: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
+    off: (event: "unhandledRejection" | "uncaughtException", listener: (reason: unknown) => void) => void;
+    exit: (code: number) => void;
+};
+export type ApiFatalProcessBoundaryOptions = {
+    process?: ApiFatalProcess;
+    observability?: ApiFatalObservability;
+    flushTimeoutMs?: number;
+    correlationId?: () => string;
+    fallbackLog?: (message: string) => void;
+};
+export type ApiFatalProcessBoundary = {
+    attachObservability: (observability: ApiFatalObservability) => void;
+    markRunning: () => void;
+    reportStartupFailure: (reason: unknown) => Promise<void>;
+    dispose: () => void;
+};
+export declare function installApiFatalProcessBoundary(options?: ApiFatalProcessBoundaryOptions): ApiFatalProcessBoundary;
+export {};

package/dist/http/sse.d.ts

@@ -84,5 +84,7 @@ export type SseDeliveryOptions = {
     /** Current ACL re-check, run even while the event stream is idle. */
     reauthorize?: (() => Promise<void>) | undefined;
     reauthorizeAfterMs?: number | undefined;
+    /** Exact selected actor emitted on the stream response for cross-tab fencing. */
+    actorEpoch?: string | undefined;
 };
 export type SessionSseDeliveryOptions = SseDeliveryOptions;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { getSettings } from "@opengeni/config";
 import type { ScheduledTaskOverlapPolicy, ScheduledTaskScheduleSpec } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
+import { type Observability } from "@opengeni/observability";
 import { ScheduleOverlapPolicy } from "@temporalio/client";
 import type { ScheduleSpec } from "@temporalio/client";
 import { type DocumentIndexClient, type SessionWorkflowClient } from "./app.js";
@@ -9,7 +10,10 @@ export declare function createTemporalWorkflowClient(settings: ReturnType<typeof
     documentIndexer: DocumentIndexClient;
     close: () => Promise<void>;
 }>;
-export declare function startApi(): Promise<{
+export declare function startApi(options?: {
+    settings?: ReturnType<typeof getSettings>;
+    observability?: Observability;
+}): Promise<{
     server: Bun.Server<Readonly<{
         attach(socket: import("./api-websocket.js").ApiWebSocketLike): void;
         receive(message: string | Uint8Array | ArrayBuffer): void;

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   createOpenGeniSlackBotInteractionClient,
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump
-} from "./chunk-IBV7Z6F4.js";
+} from "./chunk-QESX7HDK.js";
 
 // src/index.ts
 import {
@@ -26,7 +26,10 @@ import {
   runtimeDatabaseReadyCheck
 } from "@opengeni/db";
 import { createNatsEventBus } from "@opengeni/events";
-import { createObservability, logStartupDependencyRetry } from "@opengeni/observability";
+import {
+  createObservability,
+  logStartupDependencyRetry
+} from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
 import { isArtifactRuntimeConfigured } from "@opengeni/artifact-tool/runtime/development";
 import { SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID } from "@opengeni/core";
@@ -2398,6 +2401,156 @@ function rawRows(result) {
   throw new Error("Unsupported database execute result shape");
 }
 
+// src/fatal-process-boundary.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var API_FATAL_FLUSH_TIMEOUT_MS = 1e3;
+var API_FATAL_CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+var FATAL_ERROR_CODES = {
+  startup_failure: "api_startup_failed",
+  unhandled_rejection: "api_unhandled_rejection",
+  uncaught_exception: "api_uncaught_exception"
+};
+function installApiFatalProcessBoundary(options = {}) {
+  const runtimeProcess = options.process ?? defaultProcessBoundary();
+  const flushTimeoutMs = options.flushTimeoutMs ?? API_FATAL_FLUSH_TIMEOUT_MS;
+  const correlationId = options.correlationId ?? (() => `api-fatal.${randomUUID2()}`);
+  const fallbackLog = options.fallbackLog ?? ((message) => console.error(message));
+  let observability = options.observability;
+  let phase = "startup";
+  let reporting = false;
+  const report = async (event, reason) => {
+    if (reporting) return;
+    reporting = true;
+    const diagnostic = apiFatalDiagnostic(event, phase, reason, correlationId);
+    const message = apiFatalMessage(diagnostic);
+    const activeObservability = observability;
+    try {
+      if (activeObservability) {
+        let logged = false;
+        try {
+          activeObservability.error(message, diagnostic);
+          logged = true;
+        } catch {
+        }
+        if (!logged) {
+          safeFallbackLog(fallbackLog, message);
+        }
+        try {
+          const span = activeObservability.startSpan("api.process.fatal", diagnostic);
+          span.end({ error: true });
+        } catch {
+        }
+        await flushWithin(activeObservability, flushTimeoutMs);
+      } else {
+        safeFallbackLog(fallbackLog, message);
+      }
+    } finally {
+      runtimeProcess.exit(1);
+    }
+  };
+  const onUnhandledRejection = (reason) => {
+    void report("unhandled_rejection", reason);
+  };
+  const onUncaughtException = (reason) => {
+    void report("uncaught_exception", reason);
+  };
+  runtimeProcess.on("unhandledRejection", onUnhandledRejection);
+  runtimeProcess.on("uncaughtException", onUncaughtException);
+  return {
+    attachObservability: (value) => {
+      observability = value;
+    },
+    markRunning: () => {
+      phase = "running";
+    },
+    reportStartupFailure: async (reason) => {
+      await report("startup_failure", reason);
+    },
+    dispose: () => {
+      runtimeProcess.off("unhandledRejection", onUnhandledRejection);
+      runtimeProcess.off("uncaughtException", onUncaughtException);
+    }
+  };
+}
+function apiFatalDiagnostic(event, phase, reason, correlationId) {
+  let safeCorrelationId = "api-fatal.fallback";
+  try {
+    const candidate = correlationId();
+    if (API_FATAL_CORRELATION_ID_PATTERN.test(candidate)) {
+      safeCorrelationId = candidate;
+    }
+  } catch {
+  }
+  return {
+    errorClass: "ApiFatalOperationError",
+    errorCode: FATAL_ERROR_CODES[event],
+    origin: "api",
+    phase,
+    reasonKind: apiFatalReasonKind(reason),
+    correlationId: safeCorrelationId
+  };
+}
+function apiFatalReasonKind(reason) {
+  if (reason === null) return "null";
+  const kind = typeof reason;
+  if (kind !== "object") return kind;
+  try {
+    return reason instanceof Error ? "error" : "object";
+  } catch {
+    return "object";
+  }
+}
+function apiFatalMessage(diagnostic) {
+  return `OpenGeni API fatal process failure (${diagnostic.errorCode}; phase=${diagnostic.phase}; reason_kind=${diagnostic.reasonKind}; correlation_id=${diagnostic.correlationId})`;
+}
+async function flushWithin(observability, timeoutMs) {
+  let flush;
+  try {
+    flush = Promise.resolve(observability.flush()).catch(() => void 0);
+  } catch {
+    return;
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return;
+  let timeout;
+  try {
+    await Promise.race([
+      flush,
+      new Promise((resolve) => {
+        timeout = setTimeout(resolve, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeout !== void 0) clearTimeout(timeout);
+  }
+}
+function safeFallbackLog(fallbackLog, message) {
+  try {
+    fallbackLog(message);
+  } catch {
+  }
+}
+function defaultProcessBoundary() {
+  return {
+    on: (event, listener) => {
+      if (event === "unhandledRejection") {
+        process.on("unhandledRejection", listener);
+      } else {
+        process.on("uncaughtException", listener);
+      }
+    },
+    off: (event, listener) => {
+      if (event === "unhandledRejection") {
+        process.off("unhandledRejection", listener);
+      } else {
+        process.off("uncaughtException", listener);
+      }
+    },
+    exit: (code) => {
+      process.exit(code);
+    }
+  };
+}
+
 // src/index.ts
 function isWorkflowAlreadyStarted(error) {
   return error instanceof WorkflowExecutionAlreadyStartedError;
@@ -2620,9 +2773,9 @@ async function createTemporalWorkflowClient(settings, db) {
     }
   };
 }
-async function startApi() {
-  const settings = getSettings();
-  const observability = createObservability(settings, { component: "api" });
+async function startApi(options = {}) {
+  const settings = options.settings ?? getSettings();
+  const observability = options.observability ?? createObservability(settings, { component: "api" });
   const searchPath = dbSearchPath(settings);
   const dbClient = createDb(settings.databaseUrl, {
     max: 32,
@@ -2814,7 +2967,16 @@ async function startApi() {
   };
 }
 if (import.meta.main) {
-  await startApi();
+  const fatalBoundary = installApiFatalProcessBoundary();
+  try {
+    const settings = getSettings();
+    const observability = createObservability(settings, { component: "api" });
+    fatalBoundary.attachObservability(observability);
+    await startApi({ settings, observability });
+    fatalBoundary.markRunning();
+  } catch (error) {
+    await fatalBoundary.reportStartupFailure(error);
+  }
 }
 function temporalOverlapPolicy(policy) {
   if (policy === "skip") {