@kosdev-code/kos-ui-sdk 3.0.10 → 3.0.12

package/index.js

@@ -2915,6 +2915,29 @@ const isKosModelReady = (model) => {
   }
   return kosModel2.isReady();
 };
+const getKosModelActivationState = (model) => {
+  if (!model?.id) {
+    return void 0;
+  }
+  const kosModel2 = KosCore.getInstance().modelManager.getModelById(model.id);
+  if (!kosModel2) {
+    return void 0;
+  }
+  return {
+    get activeStatus() {
+      return kosModel2.activeStatus;
+    },
+    get isActivating() {
+      return kosModel2.activeStatus === KosModelState.ACTIVATING;
+    },
+    get isActive() {
+      return kosModel2.activeStatus === KosModelState.ACTIVE;
+    },
+    get isFailed() {
+      return kosModel2.activeStatus === KosModelState.FAILED;
+    }
+  };
+};
 const log$L = KosLog.createLogger({ name: "kos-model-factory" });
 const KosModelFactory = {
   byModelType: (modelType) => KosCore.getInstance().modelManager.getModelFactory(
@@ -6339,8 +6362,38 @@ const getMessageBody = (payload, skipParse) => {
     return payload.body || payload;
   }
 };
+const TRANSPORT_NOT_READY = "TRANSPORT_NOT_READY";
+class TransportNotReadyError extends Error {
+  /** Stable discriminator; see {@link TRANSPORT_NOT_READY}. */
+  code = TRANSPORT_NOT_READY;
+  /**
+   * The budget, in milliseconds, that expired while waiting. `undefined` when
+   * the wait was cut short by a caller-supplied timeout signal rather than by
+   * the request's own budget.
+   */
+  timeout;
+  /** The URL of the request that was never sent. */
+  url;
+  constructor(details = {}) {
+    super(
+      `Transport not ready${details.timeout === void 0 ? "" : ` after ${details.timeout}ms`}${details.url ? ` - url: ${details.url}` : ""}`
+    );
+    this.name = "TransportNotReadyError";
+    this.timeout = details.timeout;
+    this.url = details.url;
+  }
+}
+const isTransportNotReadyError = (error) => !!error && error.code === TRANSPORT_NOT_READY;
 const log$D = KosLog.createLogger({ name: "kos-fetch" });
-const WS_TIMEOUT = process.env.KOS_WS_TIMEOUT ? parseInt(process.env.KOS_WS_TIMEOUT) : 3e4;
+const DEFAULT_WS_TIMEOUT = 3e4;
+const WS_TIMEOUT = (() => {
+  const configured = process.env.KOS_WS_TIMEOUT ? parseInt(process.env.KOS_WS_TIMEOUT) : DEFAULT_WS_TIMEOUT;
+  return Number.isNaN(configured) ? DEFAULT_WS_TIMEOUT : configured;
+})();
+const resolveTimeoutBudget = (timeout) => {
+  const budget = timeout ?? WS_TIMEOUT;
+  return Number.isFinite(budget) && budget > 0 ? budget : void 0;
+};
 const delay = () => new Promise((resolve) => {
   setTimeout(() => {
     resolve(true);
@@ -6374,6 +6427,14 @@ const combineSignals = (signals) => {
   }
   return controller.signal;
 };
+const createRequestSignal = (budget, callerSignal) => {
+  const timeoutSignal = budget ? createTimeoutSignal(budget) : void 0;
+  if (timeoutSignal && callerSignal) {
+    return combineSignals([callerSignal, timeoutSignal]);
+  }
+  return timeoutSignal ?? callerSignal ?? new AbortController().signal;
+};
+const isTimeoutReason = (reason) => reason?.name === "TimeoutError";
 const fetchMessageFactory = (options) => {
   if (options?.studio) {
     return createStudioMessage;
@@ -6385,15 +6446,25 @@ const fetchMessageFactory = (options) => {
 };
 const kosFetchWs = async (url, options) => {
   const transport = KosCore.getInstance().transport;
-  await transport.whenReady();
   const requestId = uuid();
   const urlObj = new URL(url);
   const path = `${urlObj.pathname}${urlObj.search}`;
   log$D.debug(`path: ${path}`);
-  const TIMEOUT = options?.timeout || WS_TIMEOUT;
+  const budget = resolveTimeoutBudget(options?.timeout);
   const messageFactory = fetchMessageFactory(options);
-  const timeoutSignal = createTimeoutSignal(TIMEOUT);
-  const signal = options?.signal ? combineSignals([options.signal, timeoutSignal]) : timeoutSignal;
+  const signal = createRequestSignal(budget, options?.signal);
+  try {
+    await transport.whenReady({ signal });
+  } catch (error) {
+    if (isTimeoutReason(error)) {
+      log$D.error(
+        `Transport not ready${budget === void 0 ? "" : ` after ${budget}ms`} - request not sent - url: ${url}`
+      );
+      throw new TransportNotReadyError({ timeout: budget, url });
+    }
+    log$D.debug(`Request aborted while waiting for transport - url: ${url}`);
+    throw error;
+  }
   const processedBody = await processRequestBody(options?.body);
   const additionalHeaders = {};
   if (processedBody.contentType) {
@@ -6556,6 +6627,7 @@ const resolveBaseUrl = () => {
 };
 const log$C = KosLog.createLogger({ name: "kos-service-request" });
 const ERROR_UNKNOWN = "errUnknown";
+const ERROR_TRANSPORT_NOT_READY = "Transport not ready";
 const MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "DELETE", "PATCH"]);
 const RETRY_DEFAULTS = {
   maxAttempts: 3,
@@ -6605,6 +6677,10 @@ async function executeFetch(fullUrl, fetchOptions) {
     const payload = await response.json();
     return [null, payload.data ?? payload];
   } catch (error) {
+    if (isTransportNotReadyError(error)) {
+      log$C.error(`Transport not ready, request not sent: ${fullUrl}`);
+      return [ERROR_TRANSPORT_NOT_READY, null];
+    }
     if (error instanceof DOMException) {
       if (error.name === "TimeoutError") {
         log$C.error(`Request timed out: ${fullUrl}`);
@@ -6648,6 +6724,10 @@ async function executeFetchWithRetry(fullUrl, fetchOptions, config2) {
         await new Promise((resolve) => setTimeout(resolve, delayMs));
       }
     } catch (error) {
+      if (isTransportNotReadyError(error)) {
+        log$C.error(`Transport not ready, request not sent: ${fullUrl}`);
+        return [ERROR_TRANSPORT_NOT_READY, null];
+      }
       if (error instanceof DOMException) {
         if (error.name === "TimeoutError") {
           log$C.error(`Request timed out: ${fullUrl}`);
@@ -7459,6 +7539,38 @@ class FlowControlManager {
     return { ...this.stats };
   }
 }
+const abortReason = (signal) => signal.reason ?? new DOMException("Aborted", "AbortError");
+const abortableWhen = async (predicate, signal) => {
+  if (predicate()) {
+    return;
+  }
+  if (!signal) {
+    await when(predicate);
+    return;
+  }
+  if (signal.aborted) {
+    throw abortReason(signal);
+  }
+  const pending = when(predicate);
+  let onAbort;
+  try {
+    await Promise.race([
+      // `cancel()` below rejects this promise with MobX's WHEN_CANCELLED
+      // sentinel. That rejection *is* the cancellation, never a real failure,
+      // so it is swallowed here; the abort branch supplies the thrown reason.
+      pending.catch(() => void 0),
+      new Promise((_, reject) => {
+        onAbort = () => reject(abortReason(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+    ]);
+  } finally {
+    if (onAbort) {
+      signal.removeEventListener("abort", onAbort);
+    }
+    pending.cancel();
+  }
+};
 class WebSocketBridgeTransport extends WebSocket {
   constructor(address) {
     super(address);
@@ -8091,15 +8203,26 @@ ${dstAddr}topics:${topic}
       }
     };
   }
-  async whenReady() {
-    const that = this;
+  /**
+   * Resolves once the transport can carry requests: the socket (and the FOS
+   * socket, when used) is connected and the connection is authorized.
+   *
+   * Pass `options.signal` to bound the wait. `connectionEstablished` flips back
+   * to `false` on socket close, so an unbounded wait parks indefinitely while
+   * the transport is down — callers with a deadline must supply a signal.
+   *
+   * @param options - See {@link KosTransportReadyOptions}.
+   * @throws The signal's abort reason if it aborts before the transport is ready.
+   */
+  async whenReady(options) {
     if (!this.webSocketSupported) {
       return {
         status: `not supported`
       };
     }
-    await when(
-      () => !!that.socket?.connectionEstablished && (!that.useFosTransport || !!that.fosSocket?.connectionEstablished) && that.authorized
+    await abortableWhen(
+      () => !!this.socket?.connectionEstablished && (!this.useFosTransport || !!this.fosSocket?.connectionEstablished) && this.authorized,
+      options?.signal
     );
     return {
       status: `success`
@@ -9790,6 +9913,7 @@ var KosCoreState = /* @__PURE__ */ ((KosCoreState2) => {
   KosCoreState2["UNLOADING"] = `unloading`;
   KosCoreState2["UNLOADED"] = `unloaded`;
   KosCoreState2["RELOADING"] = `reloading`;
+  KosCoreState2["FAILED"] = `failed`;
   return KosCoreState2;
 })(KosCoreState || {});
 var KosCoreEvents = /* @__PURE__ */ ((KosCoreEvents2) => {
@@ -9802,6 +9926,15 @@ var KosCoreEvents = /* @__PURE__ */ ((KosCoreEvents2) => {
   KosCoreEvents2["RELOAD"] = `reload`;
   return KosCoreEvents2;
 })(KosCoreEvents || {});
+const reportFailure = async (step, run2) => {
+  try {
+    return await run2();
+  } catch (error) {
+    const detail = error instanceof Error ? error.stack ?? `${error.name}: ${error.message}` : String(error);
+    log$R.error(`KOS Core lifecycle step "${step}" failed. ${detail}`);
+    throw error;
+  }
+};
 const coreFsm = (core) => {
   const onlineMachine2 = createMachine("offline", {
     [
@@ -9839,6 +9972,15 @@ const coreFsm = (core) => {
     onlineMachine2,
     (_service) => log$R.debug(_service.machine.current)
   );
+  const failed = transition(
+    `error`,
+    "failed",
+    action$1(() => {
+      runInAction(() => {
+        core.status = "failed";
+      });
+    })
+  );
   const machine2 = createMachine({
     [
       "creating"
@@ -9861,12 +10003,13 @@ const coreFsm = (core) => {
       "initializing"
       /* INITIALIZING */
     ]: invoke(
-      () => core.init(),
+      () => reportFailure("initializing", () => core.init()),
       transition(
         `done`,
         "initialized"
         /* INITIALIZED */
-      )
+      ),
+      failed
     ),
     [
       "initialized"
@@ -9879,12 +10022,13 @@ const coreFsm = (core) => {
       "loading"
       /* LOADING */
     ]: invoke(
-      () => core.load(),
+      () => reportFailure("loading", () => core.load()),
       transition(
         `done`,
         "loaded"
         /* LOADED */
-      )
+      ),
+      failed
     ),
     [
       "loaded"
@@ -9904,7 +10048,7 @@ const coreFsm = (core) => {
       "readying"
       /* READYING */
     ]: invoke(
-      () => core.ready(),
+      () => reportFailure("readying", () => core.ready()),
       transition(
         `done`,
         "ready",
@@ -9913,19 +10057,25 @@ const coreFsm = (core) => {
             core.status = "ready";
           });
         })
-      )
+      ),
+      failed
     ),
     [
       "reloading"
       /* RELOADING */
     ]: invoke(
-      () => core.reload(),
+      () => reportFailure("reloading", () => core.reload()),
       transition(
         `done`,
         "loading"
         /* LOADING */
-      )
+      ),
+      failed
     ),
+    [
+      "failed"
+      /* FAILED */
+    ]: state(),
     [
       "ready"
       /* READY */
@@ -10063,6 +10213,7 @@ class KosCore {
   isOnline;
   _reloading;
   _unloading;
+  lifecycleStarted = false;
   connectionAlias;
   constructor(connectionAlias) {
     this.initialized = false;
@@ -10139,6 +10290,12 @@ class KosCore {
     }
     this._transport = ws.init();
     this.fsmService = coreFsm(this);
+  }
+  startLifecycle() {
+    if (this.lifecycleStarted) {
+      return;
+    }
+    this.lifecycleStarted = true;
     this.fsmService.service.send(KosCoreEvents.CREATE);
   }
   get onlineStatus() {
@@ -10228,6 +10385,12 @@ class KosCore {
   async ready() {
     log$w.debug("Readying KOS Core");
     await this._transport.whenReady();
+    log$w.debug("KOS Transport ready. Preloading models");
+    if (!this.modelManager) {
+      throw new Error(
+        "KOS Core reached ready() with no model manager. Its lifecycle was started without a registry."
+      );
+    }
     const promises = this.modelManager.preloadedModels.map((model) => {
       return {
         modelId: model.modelId,
@@ -10235,6 +10398,7 @@ class KosCore {
         promise: model.whenReady()
       };
     });
+    log$w.debug(`Preloaded ${promises.length} models`);
     const settled = await Promise.allSettled(
       promises.map((promise) => {
         const { promise: timeoutPromise, cancel: timeoutCancel } = rejectAfterDelay(5e3, promise.model);
@@ -10353,6 +10517,7 @@ class KosCore {
     });
     const modelManager = KosModelManager.create(registry, reset2);
     instance.modelManager = modelManager;
+    instance.startLifecycle();
     return instance;
   }
   static getInstance(data) {
@@ -26922,6 +27087,7 @@ export {
   Device,
   index$6 as DeviceServices,
   DomIntersectionStrategy,
+  ERROR_TRANSPORT_NOT_READY,
   EVENT_KOS_MODEL_READY,
   EVENT_TROUBLE_ADDED,
   EVENT_TROUBLE_REMOVED,
@@ -27104,6 +27270,7 @@ export {
   TIMER_END,
   TIMER_EVENT,
   TOPIC_TIMER_TICK_EVENT,
+  TRANSPORT_NOT_READY,
   TimerManager,
   TokenContext,
   TokenProvider,
@@ -27116,6 +27283,7 @@ export {
   TranslationContainerContext,
   TranslationContext,
   TransportFactory,
+  TransportNotReadyError,
   Trouble,
   TroubleAwareSetup,
   TroubleContainer,
@@ -27211,6 +27379,7 @@ export {
   getKosLocalizationDescriptor,
   getKosMessageLogging,
   getKosModel$1 as getKosModel,
+  getKosModelActivationState,
   getKosModelSync,
   getKosModelType,
   getKosServiceApi,
@@ -27253,6 +27422,7 @@ export {
   isLocalRefId,
   isNumber,
   isPrintable,
+  isTransportNotReadyError,
   isTroubleAware,
   isValidDate,
   kosAction,