@opengeni/react 0.48.0 → 0.57.0

package/src/hooks/use-desktop-stream.ts

@@ -6,7 +6,7 @@ import {
   type DesktopRfbLike,
   type DesktopStreamCapability,
 } from "@opengeni/sdk";
-import { type RefObject, useEffect, useRef, useState } from "react";
+import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
 import { type DesktopWebSocketFactory, useRelayFrameStream } from "./use-relay-frame-stream";
 
 export type UseDesktopStreamOptions = {
@@ -19,6 +19,8 @@ export type UseDesktopStreamOptions = {
   scaleViewport?: boolean | undefined;
   /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
   rfbFactory?: DesktopRfbFactory | undefined;
+  /** Additional WebSocket protocols for an authenticated placement proxy. */
+  webSocketProtocols?: string[] | undefined;
   /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
    *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
   webSocketFactory?: DesktopWebSocketFactory | undefined;
@@ -29,6 +31,8 @@ export type UseDesktopStreamResult = {
   error: Error | null;
   /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
   reconnect: () => void;
+  /** Synchronous input on the already-open RFB authority. */
+  sendKey?: ((keysym: number, code: string, down?: boolean) => boolean) | undefined;
 };
 
 /** Lazy-load @novnc/novnc's RFB as the default factory. Imported inside the
@@ -44,7 +48,10 @@ async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
     default: new (
       t: HTMLElement,
       u: string,
-      o: { credentials?: { password?: string | undefined } | undefined },
+      o: {
+        credentials?: { password?: string | undefined } | undefined;
+        wsProtocols?: string[] | undefined;
+      },
     ) => DesktopRfbLike;
   };
   const RFB = mod.default;
@@ -71,8 +78,15 @@ async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
  * way, so `DesktopViewer` is transport-agnostic.
  */
 export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopStreamResult {
-  const { capability, containerRef, interactive, scaleViewport, rfbFactory, webSocketFactory } =
-    options;
+  const {
+    capability,
+    containerRef,
+    interactive,
+    scaleViewport,
+    rfbFactory,
+    webSocketProtocols,
+    webSocketFactory,
+  } = options;
 
   // The self-hosted PNG-frame path. Always invoked (rules of hooks); dormant
   // unless `transport === "relay-frames"`, in which case it owns the surface.
@@ -91,6 +105,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   };
 
   const reconnect = () => setNonce((n) => n + 1);
+  const sendKey = useCallback((keysym: number, code: string, down?: boolean): boolean => {
+    const rfb = rfbRef.current;
+    if (!rfb?.sendKey || rfb.viewOnly || stateRef.current !== "connected") return false;
+    rfb.sendKey(keysym, code, down);
+    return true;
+  }, []);
 
   const url = capability?.url ?? null;
   // The credential is keyed into the connect effect so a token rotation (new
@@ -99,6 +119,14 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   const token = capability?.token ?? null;
   const transport = capability?.transport ?? null;
   const mode = capability?.mode ?? "read-only";
+  // For direct sandbox RFB, authorization is carried in WebSocket
+  // subprotocols rather than `capability.token`. The view grant rotates before
+  // expiry while the URL stays stable, so the protocol credential is a real
+  // connection boundary: keeping the old socket leaves the viewer black once
+  // browserd expires it. Key the effect on the primitive value (not the caller's
+  // array identity) so credential rotation reconnects exactly once without
+  // churning on ordinary renders.
+  const webSocketProtocolsKey = webSocketProtocols?.join("\u0000") ?? "";
 
   // The live RFB handle. Holding it in a ref lets us flip view-only (take
   // control / return control) and re-scale on the OPEN connection instead of
@@ -113,10 +141,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   const scaleViewportRef = useRef(scaleViewport);
   const modeRef = useRef(mode);
   const rfbFactoryRef = useRef(rfbFactory);
+  const webSocketProtocolsRef = useRef(webSocketProtocols);
   interactiveRef.current = interactive;
   scaleViewportRef.current = scaleViewport;
   modeRef.current = mode;
   rfbFactoryRef.current = rfbFactory;
+  webSocketProtocolsRef.current = webSocketProtocols;
 
   // read-only is forced when the server says so OR the caller didn't opt in.
   const viewOnlyFor = (m: string, want: boolean | undefined) => m === "read-only" || !want;
@@ -164,6 +194,7 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
         setBoth(nextDesktopState(stateRef.current, { type: "negotiated" }));
         rfb = factory(container, socketUrl, {
           credentials: token ? { password: token } : undefined,
+          ...(webSocketProtocolsRef.current ? { wsProtocols: webSocketProtocolsRef.current } : {}),
         });
         rfb.viewOnly = viewOnlyFor(modeRef.current, interactiveRef.current);
         // Fit-to-panel: SCALE the 1280x800 framebuffer down to the container
@@ -200,11 +231,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
       }
     };
     // ONLY a real transport change reconnects: a fresh url (rotation), a new
-    // credential, the transport flipping, or an explicit manual reconnect
+    // credential (RFB password OR bearer subprotocol), the transport flipping,
+    // or an explicit manual reconnect
     // (`nonce`). `interactive`/`scaleViewport`/`mode`/`rfbFactory` are read via
     // refs and applied live below — they must never re-open the socket.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [url, token, transport, nonce]);
+  }, [url, token, transport, webSocketProtocolsKey, nonce]);
 
   // Apply take-control / return-control to the OPEN connection in place. noVNC
   // honours `viewOnly` live, so flipping it neither blinks the surface nor drops
@@ -236,5 +268,5 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   // drives; for `vnc-ws` (and everything else) the noVNC path drives while the
   // frame renderer stays idle. Same public shape either way.
   if (transport === "relay-frames") return frameStream;
-  return { state, error, reconnect };
+  return { state, error, reconnect, sendKey };
 }

package/src/hooks/use-interaction-interventions.ts

@@ -0,0 +1,242 @@
+import type {
+  CreateInteractionInterventionRequest,
+  InteractionIntervention,
+  InteractionInterventionMutationResponse,
+  ResolveInteractionInterventionRequest,
+} from "@opengeni/sdk/interaction";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EmbeddedInterventionClientLike } from "../client";
+import {
+  type EmbeddedInterventionClientOverride,
+  useEmbeddedInterventions,
+} from "../session-context";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
+
+export type UseInteractionInterventionsOptions = EmbeddedInterventionClientOverride & {
+  enabled?: boolean | undefined;
+  resourceKind?: "browser_session" | "computer_session" | undefined;
+  resourceId?: string | null | undefined;
+  includeSettled?: boolean | undefined;
+  pollIntervalMs?: number | undefined;
+};
+
+export type UseInteractionInterventionsResult = {
+  interventions: InteractionIntervention[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (
+    request: Omit<CreateInteractionInterventionRequest, "operationId"> & {
+      operationId?: string;
+    },
+  ) => Promise<InteractionInterventionMutationResponse>;
+  resolve: (
+    interventionId: string,
+    request: Omit<ResolveInteractionInterventionRequest, "operationId"> & {
+      operationId?: string;
+    },
+  ) => Promise<InteractionInterventionMutationResponse>;
+};
+
+/** Human-action bridge shared by Browser and Computer surfaces. */
+export function useInteractionInterventions(
+  options: UseInteractionInterventionsOptions = {},
+): UseInteractionInterventionsResult {
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedInterventions(options);
+  const enabled = (options.enabled ?? true) && options.resourceId !== null;
+  const resourceKind = options.resourceKind;
+  const resourceId = options.resourceId ?? undefined;
+  const includeSettled = options.includeSettled ?? false;
+  const key = `${workspaceId}:${resourceKind ?? "*"}:${resourceId ?? "*"}:${includeSettled}`;
+  const [state, setState] = useState(() => emptyState(key, enabled));
+  const [mutationCount, setMutationCount] = useState(0);
+  const requestRef = useRef<{ id: number; controller: AbortController | null }>({
+    id: 0,
+    controller: null,
+  });
+  const mountedRef = useRef(true);
+  const visible = state.key === key ? state : emptyState(key, enabled);
+
+  const cancelLoad = useCallback(() => {
+    requestRef.current.controller?.abort();
+    requestRef.current = { id: requestRef.current.id + 1, controller: null };
+  }, []);
+
+  const load = useCallback(
+    async (foreground: boolean, replace = true): Promise<void> => {
+      if (!enabled) return;
+      if (requestRef.current.controller && !replace) return;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
+      if (foreground || replace) {
+        setState((current) => ({
+          ...(current.key === key ? current : emptyState(key, true)),
+          loading: foreground,
+          refreshing: !foreground,
+          error: foreground ? null : current.error,
+        }));
+      }
+      try {
+        const response = await client.listInteractionInterventions(workspaceId, {
+          ...(resourceKind ? { resourceKind } : {}),
+          ...(resourceId ? { resourceId } : {}),
+          includeSettled,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          interventions: sortInterventions(response.interventions),
+          loading: false,
+          refreshing: false,
+          error: null,
+        });
+      } catch (cause) {
+        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+          return;
+        setState((current) => ({
+          ...(current.key === key ? current : emptyState(key, true)),
+          loading: false,
+          refreshing: false,
+          error: asError(cause),
+        }));
+      } finally {
+        if (requestRef.current.id === id) requestRef.current = { id, controller: null };
+      }
+    },
+    [client, enabled, includeSettled, key, resourceId, resourceKind, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await load(false, true), [load]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(key, false));
+      return;
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, key, load]);
+
+  useInteractionInvalidation({
+    workspaceId,
+    key,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    refresh,
+    fallbackPollIntervalMs: options.pollIntervalMs ?? 2_000,
+  });
+
+  const mutate = useCallback(async <T>(operation: () => Promise<T>): Promise<T> => {
+    setMutationCount((count) => count + 1);
+    try {
+      return await operation();
+    } finally {
+      if (mountedRef.current) setMutationCount((count) => Math.max(0, count - 1));
+    }
+  }, []);
+
+  const merge = useCallback(
+    (intervention: InteractionIntervention) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const interventions = current.interventions.filter(
+          (candidate) => candidate.id !== intervention.id,
+        );
+        const matches =
+          (!resourceKind || intervention.resourceKind === resourceKind) &&
+          (!resourceId || intervention.resourceId === resourceId);
+        if (matches && (includeSettled || intervention.status === "open")) {
+          interventions.push(intervention);
+        }
+        return {
+          ...current,
+          interventions: sortInterventions(interventions),
+          error: null,
+        };
+      });
+    },
+    [includeSettled, key, resourceId, resourceKind],
+  );
+
+  const create = useCallback(
+    async (
+      request: Omit<CreateInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<InteractionInterventionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.createInteractionIntervention(workspaceId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.intervention);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const resolve = useCallback(
+    async (
+      interventionId: string,
+      request: Omit<ResolveInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<InteractionInterventionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.resolveInteractionIntervention(workspaceId, interventionId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.intervention);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    interventions: visible.interventions,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    mutating: mutationCount > 0,
+    error: visible.error,
+    refresh,
+    create,
+    resolve,
+  };
+}
+
+function emptyState(key: string, loading: boolean) {
+  return {
+    key,
+    interventions: [] as InteractionIntervention[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortInterventions(
+  interventions: readonly InteractionIntervention[],
+): InteractionIntervention[] {
+  return [...interventions].sort(
+    (left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type InteractionInterventionsClient = EmbeddedInterventionClientLike;

package/src/hooks/use-interaction-invalidation.ts

@@ -0,0 +1,66 @@
+import type { StreamConnectionState, WorkspaceInteractionRevisionEvent } from "@opengeni/sdk";
+import { useEffect, useRef } from "react";
+import { usePageLiveActivity } from "./internal";
+
+export type InteractionInvalidationOptions = {
+  workspaceId: string;
+  /** Distinguishes filtered projections of the same workspace catalog. */
+  key: string;
+  enabled: boolean;
+  event: WorkspaceInteractionRevisionEvent | null;
+  connectionState: StreamConnectionState | "idle" | "error";
+  /** Catalog responses carry the workspace revision; live-state lists do not. */
+  knownRevision?: number | undefined;
+  refresh: () => Promise<void>;
+  fallbackPollIntervalMs?: number | undefined;
+};
+
+/**
+ * Refetch authoritative lists on the shared latest-revision stream. Poll only
+ * while that stream is unavailable, preserving standalone-hook degradation
+ * without multiplying healthy-provider traffic.
+ */
+export function useInteractionInvalidation(options: InteractionInvalidationOptions): void {
+  const {
+    workspaceId,
+    key,
+    enabled,
+    event,
+    connectionState,
+    knownRevision,
+    refresh,
+    fallbackPollIntervalMs,
+  } = options;
+  const pageLive = usePageLiveActivity();
+  const lastUnversionedEvent = useRef<{ key: string; sequence: number }>({
+    key,
+    sequence: 0,
+  });
+  const eventSequence = event?.workspaceId === workspaceId ? event.sequence : 0;
+
+  useEffect(() => {
+    if (!enabled || eventSequence <= 0) return;
+    if (knownRevision !== undefined) {
+      if (eventSequence > knownRevision) void refresh();
+      return;
+    }
+    if (lastUnversionedEvent.current.key !== key) {
+      lastUnversionedEvent.current = { key, sequence: 0 };
+    }
+    if (eventSequence <= lastUnversionedEvent.current.sequence) return;
+    lastUnversionedEvent.current = { key, sequence: eventSequence };
+    void refresh();
+  }, [enabled, eventSequence, key, knownRevision, refresh]);
+
+  useEffect(() => {
+    if (!enabled || !pageLive || connectionState === "live") return;
+    const interval = boundedPollInterval(fallbackPollIntervalMs ?? 3_000);
+    const timer = setInterval(() => void refresh(), interval);
+    return () => clearInterval(timer);
+  }, [connectionState, enabled, fallbackPollIntervalMs, pageLive, refresh]);
+}
+
+function boundedPollInterval(value: number): number {
+  if (!Number.isFinite(value)) return 3_000;
+  return Math.min(60_000, Math.max(1_000, Math.floor(value)));
+}

package/src/hooks/use-machine-chip.ts

@@ -1,6 +1,8 @@
 import { useMemo } from "react";
 import type { MachineState } from "@opengeni/sdk";
 import type { SessionCapabilitiesState } from "./use-session-capabilities";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import { connectionStatusForState } from "../types/machines";
 
 /** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
@@ -53,7 +55,7 @@ export function formatAsOf(capturedAt: string, now: number): string {
  * it; the whole point is a deterministic, testable projection).
  *
  * Precedence:
- *   1. warm/draining lease → **live** (a warm box always wins).
+ *   1. warm lease → **live** (a holder-confirmed box always wins).
  *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
  *      machine) → **waking**.
  *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,
@@ -64,8 +66,18 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const asOf = input.capturedAt ?? null;
   const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
 
-  // 1. A warm (or draining) lease is live regardless of anything else.
-  if (input.liveness === "warm" || input.liveness === "draining") {
+  // A connected machine has no Modal group lease, so capability negotiation
+  // legitimately reports `cold` until a stream holder is minted. Its fleet
+  // probe is the authoritative reachability signal; do not label an online Mac
+  // "Offline" merely because there is no unrelated Modal lease.
+  const selfhostedOnline =
+    input.activeIsSelfhosted === true &&
+    input.activeMachineState != null &&
+    connectionStatusForState(input.activeMachineState) === "online";
+
+  // 1. A holder-confirmed warm provider or online connected machine is live.
+  // Draining remains teardown-owned and may already have lost its instance.
+  if (sandboxAcceptsLiveIo(input.liveness) || selfhostedOnline) {
     return { state: "live", label: "Live", asOf: null };
   }
 

package/src/hooks/use-machines.ts

@@ -1,5 +1,9 @@
 import { useCallback, useRef, useState } from "react";
-import type { RemoveEnrollmentRequest, RemoveEnrollmentResponse } from "@opengeni/sdk";
+import type {
+  RemoveEnrollmentRequest,
+  RemoveEnrollmentResponse,
+  SwapActiveSandboxResponse,
+} from "@opengeni/sdk";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { useMutationRunner, usePolledValue } from "./internal";
 import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
@@ -46,7 +50,7 @@ export type MachinesClientLike = {
     workspaceId: string,
     sessionId: string,
     request: { target: string },
-  ) => Promise<unknown>;
+  ) => Promise<SwapActiveSandboxResponse>;
   /**
    * Host-supplied swap adapter (an escape hatch). When present it wins over the
    * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.
@@ -99,6 +103,24 @@ export type UseMachinesResult = {
 
 const EMPTY: MachinesResponse = { activeSandboxId: null, activeEpoch: 0, machines: [] };
 
+function swapFailureMessage(result: SwapActiveSandboxResponse): string {
+  if (result.reason?.trim()) return result.reason;
+  switch (result.code) {
+    case "recovery_in_progress":
+      return "The managed sandbox is still recovering. Try again shortly.";
+    case "recovery_degraded":
+      return "The managed sandbox recovery is degraded and needs attention.";
+    case "recovery_unrecoverable":
+      return "The managed sandbox could not be recovered.";
+    case "offline_enrollment":
+      return "The selected machine is offline.";
+    case "concurrent_swap":
+      return "The session route changed concurrently. Refresh and try again.";
+    default:
+      return "The session stayed on its current sandbox.";
+  }
+}
+
 /**
  * The workspace Machines fleet: the selfhosted enrollments + the session's Modal
  * box, each with latest metrics + state, plus the active-sandbox pointer. Polls
@@ -171,7 +193,15 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
       const ownedIdentity = identityKey;
       setAttachState({ identity: ownedIdentity, sandboxId });
       const result = await run(async () => {
-        await runSwap();
+        const response = await runSwap();
+        if (
+          response &&
+          typeof response === "object" &&
+          "swapped" in response &&
+          response.swapped === false
+        ) {
+          throw new Error(swapFailureMessage(response as SwapActiveSandboxResponse));
+        }
         return true;
       });
       if (identityRef.current === ownedIdentity) {