@qontinui/ui-bridge-native 0.6.9 → 0.6.10

package/dist/server/bind-retry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Resilient TCP-bind helper for native UI Bridge server adapters.
+ *
+ * Background: the on-device bridge binds a TCP server on a fixed port (8087).
+ * On hot-reload, app foreground/background cycles, or a crash-restart, the OS
+ * can leave the previous socket in a lingering state, so the fresh bind fails
+ * with `EADDRINUSE`. The original adapter gave up after 3 fixed retries
+ * (~5s total), after which the bridge was permanently dead until the app was
+ * fully restarted — a single transient stale socket bricked automation.
+ *
+ * This helper centralises a robust bind loop so every adapter (and a unit
+ * test) shares one implementation:
+ *   - SO_REUSEADDR is requested on bind where the platform/library supports it
+ *     (passed through to the caller's `attempt` via `reuseAddress: true`), so
+ *     a lingering TIME_WAIT socket doesn't block rebind.
+ *   - On `EADDRINUSE` it retries with exponential backoff (capped) for at
+ *     least `minTotalMs` (default 30s) instead of bailing after a fixed count.
+ *   - Every retry is logged so operators can see the bridge recovering.
+ *   - Non-`EADDRINUSE` errors fail fast (a wrong-permission / bad-host error
+ *     won't fix itself by waiting).
+ *
+ * The helper is transport-agnostic: the caller supplies an `attempt` thunk
+ * that performs ONE bind attempt and resolves on `listening` / rejects on
+ * error. This keeps the package free of any concrete TCP library dependency
+ * (the same reason `ServerAdapter` is an interface).
+ */
+/** True when an error looks like an address-already-in-use bind failure. */
+export declare function isAddrInUseError(err: unknown): boolean;
+export interface BindWithRetryOptions {
+    /**
+     * Minimum total wall-clock time to keep retrying `EADDRINUSE` before giving
+     * up, in milliseconds. The loop always makes at least one attempt and keeps
+     * retrying until this budget is exhausted. Default 30_000 (30s).
+     *
+     * Pass `Infinity` to retry indefinitely (with capped backoff) — appropriate
+     * for an always-on device bridge that should self-heal whenever the stale
+     * socket finally clears.
+     */
+    minTotalMs?: number;
+    /** Initial backoff delay between retries, in ms. Default 500. */
+    initialDelayMs?: number;
+    /** Maximum backoff delay (cap for exponential growth), in ms. Default 5_000. */
+    maxDelayMs?: number;
+    /** Multiplier applied to the delay after each retry. Default 2. */
+    backoffFactor?: number;
+    /** Logger for retry diagnostics. Defaults to `console`. */
+    logger?: Pick<Console, 'warn' | 'error'>;
+    /** Injectable sleep — overridable in tests to avoid real timers. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable clock — overridable in tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Run `attempt()` repeatedly until it resolves, retrying on `EADDRINUSE` with
+ * exponential backoff for at least `minTotalMs`. Non-address-in-use errors
+ * reject immediately. Resolves once a bind attempt succeeds.
+ *
+ * @param attempt One bind attempt. Receives the attempt index (0-based) and
+ *   MUST resolve on a successful `listening` event or reject on error. The
+ *   caller is responsible for tearing down any half-bound server before the
+ *   next attempt (see the adapter's `recreate` thunk).
+ */
+export declare function bindWithRetry(attempt: (attemptIndex: number) => Promise<void>, options?: BindWithRetryOptions): Promise<void>;
+//# sourceMappingURL=bind-retry.d.ts.map

package/dist/server/bind-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-retry.d.ts","sourceRoot":"","sources":["../../src/server/bind-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAWtD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACzC,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAChD,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/server/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,sBAAsB,EAG5B,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAQV,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAyThF;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D,GACA,oBAAoB,CAg8BtB"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EACL,KAAK,sBAAsB,EAG5B,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAQV,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA4VhF;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D,GACA,oBAAoB,CA09BtB"}

package/dist/server/index.d.ts

@@ -13,4 +13,6 @@ export { WebSocketConnection } from './ws-connection';
 export type { WebSocketMessageHandler } from './ws-connection';
 export { WebSocketEventBridge } from './ws-event-bridge';
 export { ConsoleErrorBuffer, NetworkRequestBuffer } from './observability';
+export { bindWithRetry, isAddrInUseError } from './bind-retry';
+export type { BindWithRetryOptions } from './bind-retry';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/server/index.js

@@ -960,6 +960,13 @@ function matchElementsByText(registry, text, opts) {
   scored.sort((a, b) => a.rank - b.rank);
   return scored.map((s) => s.element);
 }
+function resolveElementState(element) {
+  const state = element.getState();
+  if (element.type === "input" && state.value === void 0 && typeof element.props?.value === "string") {
+    return { ...state, value: element.props.value };
+  }
+  return state;
+}
 async function executeWorkflowStep(step, registry, executor) {
   const startTime = Date.now();
   try {
@@ -1196,7 +1203,7 @@ function createServerHandlers(registry, executor, config) {
           type: element.type,
           label: element.label,
           identifier: element.getIdentifier(),
-          state: element.getState(),
+          state: resolveElementState(element),
           actions: element.actions,
           customActions: element.customActions ? Object.keys(element.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
@@ -1210,18 +1217,19 @@ function createServerHandlers(registry, executor, config) {
       if (!element) {
         return error2(`Element not found: ${id}`, "ELEMENT_NOT_FOUND");
       }
-      return success2({ state: element.getState() });
+      return success2({ state: resolveElementState(element) });
     },
     executeAction: async (ctx) => {
-      const { id } = ctx.params;
-      const body = ctx.body;
-      if (!body?.action) {
+      const rawBody = ctx.body ?? {};
+      const envelope = rawBody.request && typeof rawBody.request === "object" ? rawBody.request : rawBody;
+      const id = ctx.params.id ?? rawBody.id ?? "";
+      if (!envelope?.action) {
         return error2("Action is required", "INVALID_REQUEST");
       }
       const response = await executor.executeAction(id, {
-        action: body.action,
-        params: body.params,
-        waitOptions: body.waitOptions
+        action: envelope.action,
+        params: envelope.params,
+        waitOptions: envelope.waitOptions
       });
       if (!response.success) {
         return error2(response.error || "Action failed", "ACTION_FAILED");
@@ -1860,7 +1868,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.3.0",
+          version: "0.6.10",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -3986,6 +3994,46 @@ var WebSocketConnection = class {
   }
 };
 
+// src/server/bind-retry.ts
+function isAddrInUseError(err) {
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+  const code = err?.code;
+  return message.includes("EADDRINUSE") || message.toLowerCase().includes("address already in use") || code === "EADDRINUSE";
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function bindWithRetry(attempt, options = {}) {
+  const {
+    minTotalMs = 3e4,
+    initialDelayMs = 500,
+    maxDelayMs = 5e3,
+    backoffFactor = 2,
+    logger = console,
+    sleep = defaultSleep,
+    now = Date.now
+  } = options;
+  const startedAt = now();
+  let delay = initialDelayMs;
+  let attemptIndex = 0;
+  for (; ; ) {
+    try {
+      await attempt(attemptIndex);
+      return;
+    } catch (err) {
+      const elapsed = now() - startedAt;
+      const budgetExhausted = elapsed + delay >= minTotalMs;
+      if (!isAddrInUseError(err) || budgetExhausted) {
+        throw err;
+      }
+      logger.warn(
+        `[ui-bridge-native] bind failed with EADDRINUSE (attempt ${attemptIndex + 1}); retrying in ${delay}ms (elapsed ${elapsed}ms / budget ${minTotalMs === Infinity ? "\u221E" : minTotalMs}ms)`
+      );
+      await sleep(delay);
+      delay = Math.min(delay * backoffFactor, maxDelayMs);
+      attemptIndex += 1;
+    }
+  }
+}
+
 exports.ConsoleErrorBuffer = ConsoleErrorBuffer;
 exports.NativeUIBridgeServer = NativeUIBridgeServer;
 exports.NetworkRequestBuffer = NetworkRequestBuffer;
@@ -3998,6 +4046,7 @@ exports.OPCODE_TEXT = OPCODE_TEXT;
 exports.UI_BRIDGE_NATIVE_ROUTES = UI_BRIDGE_NATIVE_ROUTES;
 exports.WebSocketConnection = WebSocketConnection;
 exports.WebSocketEventBridge = WebSocketEventBridge;
+exports.bindWithRetry = bindWithRetry;
 exports.buildUpgradeResponse = buildUpgradeResponse;
 exports.computeAcceptKey = computeAcceptKey;
 exports.createDesignHandlers = createDesignHandlers;
@@ -4009,6 +4058,7 @@ exports.encodeCloseFrame = encodeCloseFrame;
 exports.encodePingFrame = encodePingFrame;
 exports.encodePongFrame = encodePongFrame;
 exports.encodeTextFrame = encodeTextFrame;
+exports.isAddrInUseError = isAddrInUseError;
 exports.isBatchRequest = isBatchRequest;
 exports.isSubscribe = isSubscribe;
 exports.isUnsubscribe = isUnsubscribe;