@reactor-team/js-sdk 1.0.1

package/src/core/Reactor.ts

@@ -0,0 +1,407 @@
+import type {
+  ApplicationMessage,
+  InternalConnectionStatus,
+  GPUMachineAssignmentData,
+} from "./types";
+import type {
+  ReactorEvent,
+  ReactorStatus,
+  ReactorState,
+  ReactorError,
+  ReactorWaitingInfo,
+} from "../types";
+import { CoordinatorClient } from "./CoordinatorClient";
+import { GPUMachineClient } from "./GPUMachineClient";
+import { z } from "zod";
+
+const OptionsSchema = z
+  .object({
+    directConnection: z
+      .object({
+        livekitJwtToken: z.string(),
+        livekitWsUrl: z.string(),
+      })
+      .optional(),
+    insecureApiKey: z.string().optional(),
+    jwtToken: z.string().optional(),
+    coordinatorUrl: z.string().optional(),
+    modelName: z.string(),
+  })
+  .refine(
+    (data) => data.directConnection || data.insecureApiKey || data.jwtToken,
+    {
+      message:
+        "At least one of directConnection, insecureApiKey, or jwtToken must be provided.",
+    }
+  );
+export type Options = z.input<typeof OptionsSchema>;
+
+type EventHandler = (...args: any[]) => void;
+
+export class Reactor {
+  private coordinatorClient: CoordinatorClient | undefined; //client for the coordinator
+  private machineClient: GPUMachineClient | undefined; //client for the machine instance
+  private status: ReactorStatus = "disconnected";
+  private coordinatorUrl: string;
+  private lastError?: ReactorError;
+  private waitingInfo?: ReactorWaitingInfo;
+  private jwtToken?: string;
+  private insecureApiKey?: string;
+  private directConnection?: {
+    livekitJwtToken: string;
+    livekitWsUrl: string;
+  };
+  private modelName: string;
+  private modelVersion: string;
+
+  constructor(options: Options) {
+    const validatedOptions = OptionsSchema.parse(options);
+    this.coordinatorUrl =
+      validatedOptions.coordinatorUrl || "ws://localhost:8080/ws";
+    this.jwtToken = validatedOptions.jwtToken;
+    this.insecureApiKey = validatedOptions.insecureApiKey;
+    this.directConnection = validatedOptions.directConnection;
+    this.modelName = validatedOptions.modelName;
+    // TODO: Use the model version from the options once we have a way to handle multiple versions
+    this.modelVersion = "1.0.0";
+  }
+
+  // Generic event map
+  private eventListeners: Map<ReactorEvent, Set<EventHandler>> = new Map();
+
+  // Event Emitter API
+  on(event: ReactorEvent, handler: EventHandler) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    this.eventListeners.get(event)!.add(handler);
+  }
+
+  off(event: ReactorEvent, handler: EventHandler) {
+    this.eventListeners.get(event)?.delete(handler);
+  }
+
+  emit(event: ReactorEvent, ...args: any[]) {
+    this.eventListeners.get(event)?.forEach((handler) => handler(...args));
+  }
+
+  /**
+   * Public method to send a message to the machine.
+   * Automatically wraps the message in an application message.
+   * @param message The message to send to the machine.
+   * @throws Error if not in ready state
+   */
+  sendMessage(message: any) {
+    // Synchronous validation - throw immediately
+    if (process.env.NODE_ENV !== "development" && this.status !== "ready") {
+      const errorMessage = `Cannot send message, status is ${this.status}`;
+      console.error("[Reactor] Not ready, cannot send message");
+      throw new Error(errorMessage);
+    }
+
+    try {
+      // Automatically wrap the user-message in an application message.
+      const applicationMessage: ApplicationMessage = {
+        type: "application",
+        data: message,
+      };
+      this.machineClient?.sendMessage(applicationMessage);
+    } catch (error) {
+      // Async operational error - emit event only
+      console.error("[Reactor] Failed to send message:", error);
+      this.createError(
+        "MESSAGE_SEND_FAILED",
+        `Failed to send message: ${error}`,
+        "gpu",
+        true
+      );
+      // Don't re-throw - let the error event handle it
+    }
+  }
+
+  /**
+   * Connects to the machine via LiveKit and waits for the gpu machine to be ready.
+   * Once the machine is ready, the Reactor will establish the LiveKit connection.
+   * @param livekitJwtToken The JWT token for LiveKit authentication
+   * @param livekitWsUrl The WebSocket URL for LiveKit connection
+   */
+  private async connectToGPUMachine(
+    livekitJwtToken: string,
+    livekitWsUrl: string
+  ) {
+    console.debug("[Reactor] Connecting to machine room...");
+
+    try {
+      this.machineClient = new GPUMachineClient(livekitJwtToken, livekitWsUrl);
+
+      this.machineClient.on("application", (message: any) => {
+        // escalate the message event through the instance, so that the user can listen to it.
+        this.emit("newMessage", message);
+      });
+
+      this.machineClient.on(
+        "statusChanged",
+        (status: InternalConnectionStatus) => {
+          switch (status) {
+            case "connected":
+              this.setStatus("ready");
+              break;
+            case "disconnected":
+              // gpu machine has disconnected. Close any other connection to any other entity
+              // such as the coordinator or the LiveKit connection.
+              this.disconnect();
+              break;
+            case "error":
+              // gpu machine has errored. Close any other connection to any other entity
+              // such as the coordinator or the LiveKit connection.
+              this.createError(
+                "GPU_CONNECTION_ERROR",
+                "GPU machine connection failed",
+                "gpu",
+                true
+              );
+              this.disconnect();
+              break;
+          }
+        }
+      );
+
+      this.machineClient.on("fps", (fps: number) => {
+        this.emit("fps", fps);
+      });
+
+      this.machineClient.on("streamChanged", (videoTrack) => {
+        this.emit("streamChanged", videoTrack);
+      });
+
+      console.debug("[Reactor] About to connect to machine");
+      await this.machineClient.connect();
+    } catch (error) {
+      // For private methods, we can still throw since the caller will handle it appropriately
+      throw error;
+    }
+  }
+
+  /**
+   * Connects to the coordinator and waits for a GPU to be assigned.
+   * Once a GPU is assigned, the Reactor will connect to the gpu machine via LiveKit.
+   */
+  async connect(): Promise<void> {
+    console.debug("[Reactor] Connecting, status:", this.status);
+
+    // Synchronous validation - throw immediately
+    if (this.status !== "disconnected")
+      throw new Error("Already connected or connecting");
+
+    if (this.directConnection) {
+      return this.connectToGPUMachine(
+        this.directConnection.livekitJwtToken,
+        this.directConnection.livekitWsUrl
+      );
+    }
+
+    this.setStatus("connecting");
+
+    try {
+      console.debug(
+        "[Reactor] Connecting to coordinator with authenticated URL"
+      );
+
+      this.coordinatorClient = new CoordinatorClient({
+        wsUrl: this.coordinatorUrl,
+        jwtToken: this.jwtToken,
+        insecureApiKey: this.insecureApiKey,
+        modelName: this.modelName,
+        modelVersion: this.modelVersion,
+      });
+
+      this.coordinatorClient.on(
+        "gpu-machine-assigned",
+        async (assignmentData: GPUMachineAssignmentData) => {
+          console.debug(
+            "[Reactor] GPU machine assigned by coordinator:",
+            assignmentData
+          );
+          try {
+            await this.connectToGPUMachine(
+              assignmentData.livekitJwtToken,
+              assignmentData.livekitWsUrl
+            );
+          } catch (error) {
+            console.error("[Reactor] Failed to connect to GPU machine:", error);
+            // Emit error event for async GPU connection failure
+            this.createError(
+              "GPU_CONNECTION_FAILED",
+              `Failed to connect to GPU machine: ${error}`,
+              "gpu",
+              true
+            );
+            this.disconnect();
+          }
+        }
+      );
+
+      this.coordinatorClient.on(
+        "waiting-info",
+        (waitingData: ReactorWaitingInfo) => {
+          console.debug("[Reactor] Waiting info update received:", waitingData);
+          // Update waiting info
+          this.setWaitingInfo({
+            ...this.waitingInfo,
+            ...waitingData,
+          });
+        }
+      );
+
+      this.coordinatorClient.on(
+        "statusChanged",
+        (newStatus: InternalConnectionStatus) => {
+          switch (newStatus) {
+            case "connected":
+              this.setStatus("waiting");
+              // Initialize waiting info when entering waiting state
+              this.setWaitingInfo({
+                position: undefined,
+                estimatedWaitTime: undefined,
+                averageWaitTime: undefined,
+              });
+              break;
+            case "disconnected":
+              this.disconnect();
+              break;
+            case "error":
+              this.createError(
+                "COORDINATOR_CONNECTION_ERROR",
+                "Coordinator connection failed",
+                "coordinator",
+                true
+              );
+              this.disconnect();
+              break;
+          }
+        }
+      );
+
+      await this.coordinatorClient.connect();
+    } catch (error) {
+      console.error("[Reactor] Authentication failed:", error);
+      this.createError(
+        "AUTHENTICATION_FAILED",
+        `Authentication failed: ${error}`,
+        "coordinator",
+        true
+      );
+      this.setStatus("disconnected");
+      // Keep throwing for authentication failures as these are immediate/sync failures
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnects from the coordinator and the gpu machine.
+   * Ensures cleanup completes even if individual disconnections fail.
+   */
+  async disconnect() {
+    if (this.status === "disconnected") return;
+
+    // Disconnect coordinator client with error handling
+    if (this.coordinatorClient) {
+      try {
+        this.coordinatorClient.disconnect();
+      } catch (error) {
+        console.error("[Reactor] Error disconnecting from coordinator:", error);
+        // Continue with cleanup even if coordinator disconnect fails
+      }
+      this.coordinatorClient = undefined;
+    }
+
+    // Disconnect machine client with error handling
+    if (this.machineClient) {
+      try {
+        await this.machineClient.disconnect();
+      } catch (error) {
+        console.error("[Reactor] Error disconnecting from GPU machine:", error);
+        // Continue with cleanup even if machine disconnect fails
+      }
+      this.machineClient = undefined;
+    }
+
+    this.setStatus("disconnected");
+
+    // Clear waiting info when disconnecting
+    this.waitingInfo = undefined;
+  }
+
+  private setStatus(newStatus: ReactorStatus) {
+    console.debug("[Reactor] Setting status:", newStatus, "from", this.status);
+    if (this.status !== newStatus) {
+      this.status = newStatus;
+      this.emit("statusChanged", newStatus);
+    }
+  }
+
+  private setWaitingInfo(newWaitingInfo: ReactorWaitingInfo) {
+    console.debug(
+      "[Reactor] Setting waiting info:",
+      newWaitingInfo,
+      "from",
+      this.waitingInfo
+    );
+    if (this.waitingInfo !== newWaitingInfo) {
+      this.waitingInfo = newWaitingInfo;
+      this.emit("waitingInfoChanged", newWaitingInfo);
+    }
+  }
+
+  getStatus(): ReactorStatus {
+    return this.status;
+  }
+
+  /**
+   * Get the current state including status, error, and waiting info
+   */
+  getState(): ReactorState {
+    return {
+      status: this.status,
+      waitingInfo: this.waitingInfo,
+      lastError: this.lastError,
+    };
+  }
+
+  /**
+   * Get waiting information when status is 'waiting'
+   */
+  getWaitingInfo(): ReactorWaitingInfo | undefined {
+    return this.waitingInfo;
+  }
+
+  /**
+   * Get the last error that occurred
+   */
+  getLastError(): ReactorError | undefined {
+    return this.lastError;
+  }
+
+  /**
+   * Create and store an error
+   */
+  private createError(
+    code: string,
+    message: string,
+    component: "coordinator" | "gpu" | "livekit",
+    recoverable: boolean,
+    retryAfter?: number
+  ) {
+    this.lastError = {
+      code,
+      message,
+      timestamp: Date.now(),
+      recoverable,
+      component,
+      retryAfter,
+    };
+
+    // Emit error event
+    this.emit("error", this.lastError);
+  }
+}

package/src/core/store.ts

@@ -0,0 +1,163 @@
+import { StoreApi } from "zustand";
+import type { ReactorStatus, ReactorWaitingInfo, ReactorError } from "../types";
+import { Reactor, type Options as ReactorOptions } from "./Reactor";
+import { create } from "zustand/react";
+import { createContext } from "react";
+import type { RemoteVideoTrack } from "livekit-client";
+
+export type ReactorStoreApi = ReturnType<typeof createReactorStore>;
+
+export interface ReactorState {
+  status: ReactorStatus;
+  videoTrack: RemoteVideoTrack | null;
+  //These are the machine FPS. The machine internally reports to the client the rate at which the frames are
+  //being generated. This can be useful for the client to calcolate at which rate to run commands.
+  fps?: number;
+  waitingInfo?: ReactorWaitingInfo;
+  lastError?: ReactorError;
+}
+
+export interface ReactorActions {
+  sendMessage(message: any): void;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+// Internal state not exposed to components
+interface ReactorInternalState {
+  reactor: Reactor;
+}
+
+export const ReactorContext = createContext<ReactorStoreApi | undefined>(
+  undefined
+);
+
+export type ReactorStore = ReactorState &
+  ReactorActions & {
+    internal: ReactorInternalState;
+  };
+
+export const defaultInitState: ReactorState = {
+  status: "disconnected",
+  videoTrack: null,
+  fps: undefined,
+  waitingInfo: undefined,
+  lastError: undefined,
+};
+
+export interface ReactorInitializationProps extends ReactorOptions {}
+
+export const initReactorStore = (
+  props: ReactorInitializationProps
+): ReactorState & ReactorInitializationProps => {
+  return {
+    ...defaultInitState,
+    // These are only used for dev initialization, not exposed in the store
+    ...props,
+  };
+};
+
+export const createReactorStore = (
+  initProps: ReactorInitializationProps,
+  publicState: ReactorState = defaultInitState
+): StoreApi<ReactorStore> => {
+  console.debug("[ReactorStore] Creating store", {
+    coordinatorUrl: initProps.coordinatorUrl,
+    initialState: publicState,
+  });
+
+  return create<ReactorStore>()((set, get) => {
+    const reactor = new Reactor(initProps);
+
+    console.debug("[ReactorStore] Setting up event listeners");
+
+    reactor.on("statusChanged", (newStatus: ReactorStatus) => {
+      console.debug("[ReactorStore] Status changed", {
+        oldStatus: get().status,
+        newStatus,
+      });
+      set({ status: newStatus });
+    });
+
+    reactor.on("waitingInfoChanged", (newWaitingInfo: ReactorWaitingInfo) => {
+      console.debug("[ReactorStore] Waiting info changed", {
+        oldWaitingInfo: get().waitingInfo,
+        newWaitingInfo,
+      });
+      set({ waitingInfo: newWaitingInfo });
+    });
+
+    reactor.on("streamChanged", (videoTrack: RemoteVideoTrack | null) => {
+      console.debug("[ReactorStore] Stream changed", {
+        hasVideoTrack: !!videoTrack,
+        videoTrackKind: videoTrack?.kind,
+        videoTrackSid: videoTrack?.sid,
+      });
+      set({ videoTrack: videoTrack });
+    });
+
+    reactor.on("fps", (fps: number) => {
+      console.debug("[ReactorStore] FPS updated", { fps });
+      set({ fps: fps });
+    });
+
+    reactor.on("error", (error: ReactorError) => {
+      console.debug("[ReactorStore] Error occurred", error);
+      set({ lastError: error });
+    });
+
+    return {
+      ...publicState,
+      internal: { reactor },
+
+      // actions
+      onMessage: (handler: (message: any) => void) => {
+        console.debug("[ReactorStore] Registering message handler");
+
+        // Simply register the handler
+        get().internal.reactor.on("newMessage", handler);
+
+        // Return a cleanup function that can be called to unregister
+        return () => {
+          console.debug("[ReactorStore] Cleaning up message handler");
+          get().internal.reactor.off("newMessage", handler);
+        };
+      },
+      sendMessage: (mess: any) => {
+        console.debug("[ReactorStore] Sending message", { message: mess });
+
+        try {
+          get().internal.reactor.sendMessage(mess);
+          console.debug("[ReactorStore] Message sent successfully");
+        } catch (error) {
+          console.error("[ReactorStore] Failed to send message:", error);
+          throw error;
+        }
+      },
+      connect: async () => {
+        console.debug("[ReactorStore] Connect called");
+
+        try {
+          await get().internal.reactor.connect();
+          console.debug("[ReactorStore] Connect completed successfully");
+        } catch (error) {
+          console.error("[ReactorStore] Connect failed:", error);
+          throw error;
+        }
+      },
+      disconnect: async () => {
+        console.debug("[ReactorStore] Disconnect called", {
+          currentStatus: get().status,
+        });
+
+        try {
+          await get().internal.reactor.disconnect();
+          console.debug("[ReactorStore] Disconnect completed successfully");
+        } catch (error) {
+          console.error("[ReactorStore] Disconnect failed:", error);
+          throw error;
+        }
+      },
+    };
+  });
+};

package/src/core/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Internal types for the Reactor SDK.
+ */
+
+import { z } from "zod";
+
+// Base message schemas corresponding to Python Pydantic models
+
+export const ApplicationMessageSchema = z.object({
+  type: z.literal("application"),
+  data: z.any(), // Can be any JSON-serializable data
+});
+
+// Internal message that notifies the client of the current push rate of the machine
+export const FPSMessageSchema = z.object({
+  type: z.literal("fps"),
+  data: z.number(),
+});
+
+export const GPUMachineReceiveMessageSchema = z.discriminatedUnion("type", [
+  ApplicationMessageSchema,
+  FPSMessageSchema,
+]);
+
+export const WelcomeMessageSchema = z.object({
+  type: z.literal("welcome"),
+  data: z.record(z.string(), z.any()),
+});
+
+export const GPUMachineAssignmentDataSchema = z.object({
+  livekitWsUrl: z.string(),
+  livekitJwtToken: z.string(),
+});
+
+export const GPUMachineAssignmentMessageSchema = z.object({
+  type: z.literal("gpu-machine-assigned"),
+  data: GPUMachineAssignmentDataSchema,
+});
+
+export const EchoMessageSchema = z.object({
+  type: z.literal("echo"),
+  data: z.record(z.string(), z.any()),
+});
+
+export const WaitingInfoDataSchema = z.object({
+  position: z.number().optional(),
+  estimatedWaitTime: z.number().optional(),
+  averageWaitTime: z.number().optional(),
+});
+
+export const WaitingInfoMessageSchema = z.object({
+  type: z.literal("waiting-info"),
+  data: WaitingInfoDataSchema,
+});
+
+export const CoordinatorMessageSchema = z.discriminatedUnion("type", [
+  WelcomeMessageSchema,
+  GPUMachineAssignmentMessageSchema,
+  EchoMessageSchema,
+  WaitingInfoMessageSchema,
+]);
+
+export const GPUMachineSendMessageSchema = z.discriminatedUnion("type", [
+  ApplicationMessageSchema,
+]);
+
+export const SessionSetupMessageSchema = z.object({
+  type: z.literal("sessionSetup"),
+  data: z.object({
+    modelName: z.string(),
+    modelVersion: z.string().default("latest"),
+  }),
+});
+
+// TypeScript types derived from schemas
+export type ApplicationMessage = z.infer<typeof ApplicationMessageSchema>;
+export type GPUMachineReceiveMessageSchema = z.infer<
+  typeof GPUMachineReceiveMessageSchema
+>;
+export type WelcomeMessage = z.infer<typeof WelcomeMessageSchema>;
+export type GPUMachineAssignmentData = z.infer<
+  typeof GPUMachineAssignmentDataSchema
+>;
+export type GPUMachineAssignmentMessage = z.infer<
+  typeof GPUMachineAssignmentMessageSchema
+>;
+export type EchoMessage = z.infer<typeof EchoMessageSchema>;
+export type WaitingInfoData = z.infer<typeof WaitingInfoDataSchema>;
+export type WaitingInfoMessage = z.infer<typeof WaitingInfoMessageSchema>;
+export type CoordinatorMessage = z.infer<typeof CoordinatorMessageSchema>;
+export type GPUMachineSendMessage = z.infer<typeof GPUMachineSendMessageSchema>;
+export type SessionSetupMessage = z.infer<typeof SessionSetupMessageSchema>;
+
+// Internal connection status for individual components
+export type InternalConnectionStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "error";

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./core/Reactor";
+export * from "./react/ReactorProvider";
+export * from "./react/ReactorView";
+export * from "./react/hooks";
+export * from "./types";