@pollen-robotics/reachy-mini-sdk 1.10.0-dev.0.main.b50d97e → 1.10.0-dev.0.main.c8367cd

package/dist/lib/session-supervisor.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Session resilience supervisor for the ReachyMini SDK.
+ *
+ * Owns the three transport-resilience mechanisms so the main class only
+ * has to forward browser/pc events and expose narrow accessors:
+ *
+ *   1. ICE-blip debounce + network awareness — grace windows around
+ *      `iceConnectionState` transitions (visibility-deferred while the
+ *      tab is hidden) and `online`/`offline`/`connection.change`
+ *      forwarding as public events.
+ *   2. Automatic session re-dial — the daemon's `webrtcbin` cannot do a
+ *      standards ICE restart (missing upstream support), so the recovery
+ *      unit is the whole SESSION: tear down the dead RTCPeerConnection
+ *      and dial the same robot again through central. Runs inside the
+ *      SDK so every consumer (host embed, mobile app, third-party apps)
+ *      inherits it.
+ *   3. Data-channel silence watchdog — application-level heartbeat
+ *      without any daemon change: a streaming session already receives
+ *      constant inbound traffic (get_state poll replies and/or pushed
+ *      pose frames), so prolonged TOTAL silence is a dead transport that
+ *      ICE hasn't noticed yet.
+ *
+ * The supervisor never touches the RTCPeerConnection, data channel or
+ * pending promises directly: every side effect goes through
+ * `SessionSupervisorDeps`, implemented by `ReachyMini` as closures over
+ * its own private state. That keeps the ownership boundary honest — the
+ * class owns the transport, the supervisor owns the RECOVERY POLICY.
+ */
+import type { ReachyMiniEventMap } from './types.js';
+/**
+ * Everything the supervisor needs from `ReachyMini`, as read accessors
+ * and side-effect callbacks. Implemented with arrow closures so every
+ * call reads the CURRENT class state (tests stub instance methods and
+ * the closures pick the stubs up transparently).
+ */
+export interface SessionSupervisorDeps {
+    /** Live ICE state, or `null` when no RTCPeerConnection exists. */
+    iceState(): RTCIceConnectionState | null;
+    /** True while a live RTCPeerConnection exists. */
+    hasPc(): boolean;
+    /** True once the session reached `streaming`. */
+    isStreaming(): boolean;
+    /** True while startSession() is mid-handshake (resolvers armed). */
+    isMidSetup(): boolean;
+    /** True when the signaling SSE feed is down (`state === 'disconnected'`). */
+    isSignalingDown(): boolean;
+    /** Robot id of the current / last dialed session. */
+    selectedRobotId(): string | null;
+    /**
+     * Reject the pending startSession() promise, if armed, and clear the
+     * resolvers. Returns `true` when one was actually pending — the
+     * supervisor then leaves the retry decision to the original caller.
+     */
+    rejectPendingSession(err: Error): boolean;
+    /** Re-establish the signaling feed (the SSE died with the network). */
+    reconnectSignaling(): Promise<void>;
+    /** One dial attempt: the class's full startSession() flow. */
+    dial(robotId: string): Promise<void>;
+    /** Transport-only teardown between attempts (owned by the class). */
+    teardownForRedial(): void;
+    /** Send one `get_state` probe over the data channel. */
+    nudgeState(): void;
+    /** Emit one public event on the instance. */
+    emit<K extends keyof ReachyMiniEventMap>(name: K, detail: ReachyMiniEventMap[K]['detail']): void;
+}
+export declare class SessionSupervisor {
+    private readonly _deps;
+    private _iceGraceTimer;
+    private _iceGraceReason;
+    private _pendingVisibilityHandler;
+    private _onlineHandler;
+    private _offlineHandler;
+    private _connectionChangeHandler;
+    private _autoReconnect;
+    private _redialing;
+    private _redialWake;
+    private _dcWatchdogId;
+    private _lastDcInboundAt;
+    private _dcWatchdogLastTickAt;
+    private _dcSilenceNudged;
+    constructor(deps: SessionSupervisorDeps, options: {
+        autoReconnect: boolean;
+    });
+    /** True while the re-dial loop is running. */
+    get redialing(): boolean;
+    /**
+     * Enable/disable the automatic session re-dial at runtime.
+     * Disabling also aborts any re-dial already in flight.
+     */
+    setAutoReconnect(enabled: boolean): void;
+    /** Fatal errors carry the classic webrtc `error` payload shape. */
+    private _emitError;
+    /** ICE healed back to `connected`/`completed`. */
+    onIceHealed(): void;
+    /**
+     * ICE hit `disconnected` — TRANSIENT per spec, debounce before
+     * escalating. If the tab is hidden, JS timers are throttled and
+     * would fire unpredictably late, so defer the grace window to the
+     * next foreground frame.
+     */
+    onIceDisconnected(): void;
+    /**
+     * ICE hit `failed` — terminal per spec, but in practice we've seen
+     * `failed → connected` on rapid AP roams / BT route changes on iOS.
+     * Give the ICE agent a short window to surprise us before rejecting
+     * the session.
+     */
+    onIceFailed(): void;
+    /**
+     * Cancel any pending ICE grace timer and visibility handler. Called
+     * on a healed `connected`/`completed` transition AND from the
+     * lifecycle teardown paths so a callback can't fire after the pc
+     * is closed.
+     */
+    clearIceGrace(): void;
+    /**
+     * Start a grace window. After `ms`, re-check the live ICE state:
+     *   - If we healed back to `connected`/`completed`, the timer was
+     *     already cancelled in the pc's state handler, so we never get
+     *     here.
+     *   - If we're still in the originally-observed bad state (or
+     *     worse), surface the error and reject any pending session
+     *     promise. The original code path is preserved verbatim so
+     *     downstream consumers see the same `error` payload shape.
+     */
+    private _scheduleIceGrace;
+    /**
+     * `disconnected` while the tab is hidden. JS timers are throttled
+     * in background tabs (Chrome clamps to ~1 Hz, Safari can pause
+     * altogether), so a foreground grace timer would either miss the
+     * window or fire long after the connection healed. Wait for the
+     * tab to come back, then re-evaluate.
+     */
+    private _armIceGraceOnVisibility;
+    /**
+     * Install browser-level network listeners and forward them as
+     * public `networkOnline` / `networkOffline` / `networkChange`
+     * events on the instance. Idempotent: called from `startSession()`,
+     * removed by `uninstallNetworkListeners` on teardown. Reachable
+     * only when there's a live `window` (defensive guard for SSR /
+     * test environments).
+     *
+     * `online` / `offline` are semantically about CONNECTIVITY:
+     * "does the OS think we can reach the internet". They flip
+     * symmetrically.
+     *
+     * `connection.change` (NetworkInformation API, Chrome / Android
+     * WebView only) is semantically about the TRANSPORT: it fires
+     * on Wi-Fi → 4G swaps, AP roams, etc. without necessarily going
+     * through `offline`. We forward it as its own `networkChange`
+     * event rather than aliasing it onto `networkOnline`, so
+     * consumers don't have to guess whether they're seeing a real
+     * connectivity recovery or a silent transport swap.
+     */
+    installNetworkListeners(): void;
+    /** Counterpart to `installNetworkListeners`. */
+    uninstallNetworkListeners(): void;
+    /**
+     * Escalation funnel for dead-transport signals. Returns `true` when
+     * the failure is being handled by a re-dial (callers should then skip
+     * their fatal `error` emit). Only fires for an ESTABLISHED session:
+     * mid-setup failures keep rejecting the startSession() promise so the
+     * original caller stays in charge of retries.
+     */
+    maybeBeginRedial(cause: string): boolean;
+    /**
+     * The re-dial loop. One teardown, then up to REDIAL_BACKOFF_MS.length
+     * attempts, each preceded by its backoff slot. Every attempt re-runs
+     * the normal startSession() flow (and connect() first if the SSE feed
+     * died with the network), so a success is indistinguishable from a
+     * fresh session: `streaming` re-fires, videoTrack re-attaches, the
+     * pose subscription is re-asserted by the session-ready path.
+     *
+     * Exits early — without emitting anything further — when the user
+     * calls stopSession()/disconnect() or dials another robot, all of
+     * which flip `_redialing` off via `cancelRedial`.
+     */
+    private _runRedialLoop;
+    /**
+     * Cancellable backoff sleep — `cancelRedial` wakes it immediately.
+     * A timer firing after a cancel is harmless: the loop re-checks
+     * `_redialing` right after every sleep.
+     */
+    private _redialSleep;
+    /**
+     * Abort a pending re-dial. Called from stopSession(), disconnect()
+     * and an external startSession() — every path where the user (or the
+     * consumer app) takes over the session lifecycle.
+     */
+    cancelRedial(): void;
+    /** (Re)start the watchdog. Called when a session reaches ready. */
+    startDcWatchdog(): void;
+    stopDcWatchdog(): void;
+    /**
+     * Liveness stamp: every inbound data-channel message — control
+     * replies, broadcasts, pose frames — proves the transport is alive.
+     */
+    stampDcInbound(): void;
+    private _dcWatchdogTick;
+}
+//# sourceMappingURL=session-supervisor.d.ts.map

package/dist/lib/session-supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-supervisor.d.ts","sourceRoot":"","sources":["../../lib/session-supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgDrD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC,kEAAkE;IAClE,QAAQ,IAAI,qBAAqB,GAAG,IAAI,CAAC;IACzC,kDAAkD;IAClD,KAAK,IAAI,OAAO,CAAC;IACjB,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC;IACvB,oEAAoE;IACpE,UAAU,IAAI,OAAO,CAAC;IACtB,6EAA6E;IAC7E,eAAe,IAAI,OAAO,CAAC;IAC3B,qDAAqD;IACrD,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,oBAAoB,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC;IAC1C,uEAAuE;IACvE,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,8DAA8D;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,qEAAqE;IACrE,iBAAiB,IAAI,IAAI,CAAC;IAC1B,wDAAwD;IACxD,UAAU,IAAI,IAAI,CAAC;IACnB,6CAA6C;IAC7C,IAAI,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACnC,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACxC,IAAI,CAAC;CACX;AAID,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAK9C,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,yBAAyB,CAA6B;IAG9D,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,wBAAwB,CAA6B;IAK7D,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAA6B;IAGhD,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,OAAO,CAAA;KAAE;IAK5E,8CAA8C;IAC9C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKxC,mEAAmE;IACnE,OAAO,CAAC,UAAU;IAYlB,kDAAkD;IAClD,WAAW,IAAI,IAAI;IAInB;;;;;OAKG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;;;;OAKG;IACH,WAAW,IAAI,IAAI;IAInB;;;;;OAKG;IACH,aAAa,IAAI,IAAI;IAYrB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAwCzB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA6ChC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAAuB,IAAI,IAAI;IA+B/B,gDAAgD;IAChD,yBAAyB,IAAI,IAAI;IAwBjC;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAYxC;;;;;;;;;;;OAWG;YACW,cAAc;IA6C5B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAYpB,mEAAmE;IACnE,eAAe,IAAI,IAAI;IASvB,cAAc,IAAI,IAAI;IAOtB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAKtB,OAAO,CAAC,eAAe;CA+C1B"}