@phystack/device-simulator 6.3.0

package/src/simulator/message-router.ts

@@ -0,0 +1,525 @@
+/* eslint-disable import/prefer-default-export */
+import { createHash } from "crypto";
+import { v4 as uuidv4 } from "uuid";
+import { Socket } from "socket.io";
+import { TwinCache } from "./twin-cache";
+import { EventPayload, TwinResponse, TwinTypeEnum } from "./types";
+import { simulatorLog } from "./logger";
+
+// Methods unsupported in simulator
+const UNSUPPORTED_METHODS = new Set([
+  "setWirelessNetwork",
+  "setLanNetwork",
+  "reboot",
+  "setEnv",
+]);
+
+// Signal methods — logged but no-op in local mode
+const SIGNAL_METHODS = new Set([
+  "sendEventSignal",
+  "sendSessionSignal",
+  "sendClientSignal",
+]);
+
+export class MessageRouter {
+  private twinCache: TwinCache;
+
+  private twinSubscriptions: Map<string, Set<string>> = new Map();
+
+  private messageDeliveryTracker: Map<string, Set<string>> = new Map();
+
+  private readonly MAX_TRACKED_MESSAGES = 1000;
+
+  private io: any; // socket.io server instance
+
+  constructor(twinCache: TwinCache, io: any) {
+    this.twinCache = twinCache;
+    this.io = io;
+  }
+
+  async handleMessage(
+    socket: Socket,
+    callerTwinId: string,
+    payload: EventPayload,
+    callback?: Function,
+  ): Promise<any> {
+    const { method } = payload;
+    simulatorLog.dim(
+      `← ${callerTwinId} ${method || "(no method)"} ${payload.twinId ? `→ ${payload.twinId}` : ""}`,
+    );
+
+    if (!method) {
+      simulatorLog.warn(
+        `Received event without method from ${callerTwinId}, ignoring`,
+      );
+      if (callback)
+        callback({ status: "error", message: "No method specified" });
+      return undefined;
+    }
+
+    if (UNSUPPORTED_METHODS.has(method)) {
+      const result = {
+        status: "error",
+        message: `${method} is not supported in simulator mode`,
+      };
+      if (callback) callback(result);
+      return result;
+    }
+
+    if (SIGNAL_METHODS.has(method)) {
+      const signalData = payload.data || {};
+      simulatorLog.info(
+        `Signal [${method}] from ${callerTwinId}: ${JSON.stringify(signalData)}`,
+      );
+      const result = { status: "success" };
+      if (callback) callback(result);
+      return result;
+    }
+
+    switch (method) {
+      case "getDeviceStatus":
+        return this.respond(callback, this.handleGetDeviceStatus());
+
+      case "getInstance":
+      case "getDeviceInstance":
+        return this.respond(callback, this.handleGetDeviceInstance());
+
+      case "getTwinById":
+        return this.respond(callback, this.handleGetTwinById(payload));
+
+      case "ping":
+        return this.respond(callback, { status: "success", message: "pong" });
+
+      case "twinMessage":
+        this.deliverTwinMessageLocally(callerTwinId, payload, callback);
+        return undefined;
+
+      case "twinSubscribe":
+        if (payload.twinId) {
+          this.handleTwinSubscribe(socket, callerTwinId, payload.twinId);
+          simulatorLog.info(
+            `twinSubscribe: ${callerTwinId} now listening to ${payload.twinId}`,
+          );
+        }
+        if (callback) callback({ status: "success" });
+        return undefined;
+
+      case "twinUnsubscribe":
+        if (payload.twinId) {
+          this.handleTwinUnsubscribe(callerTwinId, payload.twinId);
+        }
+        if (callback) callback({ status: "success" });
+        return undefined;
+
+      case "createInstanceTwin":
+        return this.respond(callback, this.handleCreateInstanceTwin(payload));
+
+      case "createPeripheralTwin":
+        return this.respond(callback, this.handleCreatePeripheralTwin(payload));
+
+      case "deletePeripheralTwin":
+        return this.respond(callback, this.handleDeletePeripheralTwin(payload));
+
+      case "getPeripheralTwins":
+        return this.respond(callback, this.handleGetPeripheralTwins(payload));
+
+      case "reportScreenTwinProperties":
+      case "reportEdgeTwinProperties":
+      case "reportPeripheralTwinProperties":
+        return this.respond(
+          callback,
+          this.handleReportProperties(method, payload),
+        );
+
+      case "reportDeviceTwinProperties":
+        return this.respond(
+          callback,
+          this.handleReportDeviceProperties(payload),
+        );
+
+      case "reportDeviceJob":
+        simulatorLog.dim("Device job reported (local mode, no-op)");
+        return this.respond(callback, { status: "success" });
+
+      default:
+        simulatorLog.warn(`Unknown method: ${method}`);
+        return this.respond(callback, {
+          status: "error",
+          message: `Unknown method: ${method}`,
+        });
+    }
+  }
+
+  /** Handle incoming twinMessage for local delivery (used internally) */
+  handleIncomingTwinMessage(payload: EventPayload): void {
+    this.deliverTwinMessageLocally("", payload);
+  }
+
+  /** Handle twinUpdated for local delivery */
+  handleIncomingTwinUpdated(twin: TwinResponse): void {
+    this.twinCache.updateTwin(twin);
+    this.io.to(twin.id).emit("twinMessage", {
+      method: "twinUpdated",
+      twinId: twin.id,
+      data: twin,
+    });
+  }
+
+  private respond(callback: Function | undefined, result: any): any {
+    if (callback) callback(result);
+    return result;
+  }
+
+  private handleGetDeviceStatus(): any {
+    const deviceTwin = this.twinCache.getDeviceTwin();
+    const desired = deviceTwin?.properties?.desired || {};
+    const reported = deviceTwin?.properties?.reported || {};
+    return {
+      status: "success",
+      socketConnected: true,
+      socketAuthenticated: true,
+      twins: this.twinCache.getGroupedByType(),
+      deviceId: deviceTwin?.deviceId,
+      tenantId: deviceTwin?.tenantId,
+      displayName: desired.displayName || "Simulator",
+      spaceId: desired.spaceId || "",
+      gridEnv: desired.env || "development",
+      dataResidency: "DEV",
+      accessKey: desired.accessKey || "simulator-local-key",
+      deviceSerial: desired.deviceSerial || "SIM-LOCAL",
+      osVersion: reported.os?.osVersion || "Simulator",
+      deviceEnv: desired.env || "development",
+      ip: reported.ip || [{ interface: "lo", ipv4: "127.0.0.1", ipv6: "::1" }],
+      isConnected: "true",
+      provisioningCode: "",
+    };
+  }
+
+  private handleGetDeviceInstance(): any {
+    const deviceTwin = this.twinCache.getDeviceTwin();
+    if (deviceTwin) {
+      return { status: "success", twin: deviceTwin };
+    }
+    return { status: "error", message: "Device twin not found" };
+  }
+
+  private handleGetTwinById(payload: EventPayload): any {
+    const twinId = (payload.data as any)?.twinId;
+    if (!twinId) {
+      return { status: "error", message: "Twin ID is required" };
+    }
+    const twin = this.twinCache.getTwin(twinId);
+    if (twin) {
+      return { status: "success", twin };
+    }
+    return { status: "error", message: "Twin not found" };
+  }
+
+  private handleCreateInstanceTwin(payload: EventPayload): any {
+    const { type, desiredProperties, id } = payload.data || {};
+    const deviceTwin = this.twinCache.getDeviceTwin();
+    const twin = this.createLocalTwin(
+      type || TwinTypeEnum.Screen,
+      desiredProperties || {},
+      deviceTwin,
+      id,
+    );
+    this.twinCache.addTwin(twin);
+    this.io.emit("twinCreated", { data: twin });
+    simulatorLog.info(`Twin created: ${JSON.stringify(twin)}`);
+    return { status: "success", twin };
+  }
+
+  private handleCreatePeripheralTwin(payload: EventPayload): any {
+    const { instanceId, name, hardwareId, desiredProperties } =
+      payload.data || {};
+    const deviceTwin = this.twinCache.getDeviceTwin();
+    const twin: TwinResponse = {
+      id: uuidv4(),
+      deviceId: deviceTwin?.deviceId || uuidv4(),
+      tenantId: deviceTwin?.tenantId || uuidv4(),
+      type: TwinTypeEnum.Peripheral,
+      properties: {
+        desired: { ...desiredProperties, instanceId, name, hardwareId },
+        reported: {},
+      },
+      descriptors: { instanceId, name, hardwareId },
+    };
+    this.twinCache.addTwin(twin);
+    this.io.emit("twinCreated", { data: twin });
+    return { status: "success", twin };
+  }
+
+  private handleDeletePeripheralTwin(payload: EventPayload): any {
+    const twinId = (payload.data as any)?.twinId || payload.twinId;
+    if (!twinId) {
+      return { status: "error", message: "Twin ID is required" };
+    }
+    const twin = this.twinCache.getTwin(twinId);
+    if (!twin) {
+      return { status: "error", message: "Twin not found" };
+    }
+    this.twinCache.removeTwin(twinId);
+    this.io.emit("twinDeleted", { data: twin });
+    return { status: "success" };
+  }
+
+  private handleGetPeripheralTwins(payload: EventPayload): any {
+    const instanceId = (payload.data as any)?.instanceId;
+    let peripherals = this.twinCache.getTwinsByType(TwinTypeEnum.Peripheral);
+    if (instanceId) {
+      peripherals = peripherals.filter(
+        (t) => t.descriptors?.instanceId === instanceId,
+      );
+    }
+    return { status: "success", twins: peripherals };
+  }
+
+  private handleReportProperties(method: string, payload: EventPayload): any {
+    const twinId = payload.twinId;
+    const properties = payload.data as Record<string, any>;
+    if (!twinId) {
+      return { status: "error", message: "Twin ID is required" };
+    }
+    const twin = this.twinCache.getTwin(twinId);
+    if (!twin) {
+      return { status: "error", message: "Twin not found" };
+    }
+    if (properties) {
+      twin.properties.reported = { ...twin.properties.reported, ...properties };
+      this.twinCache.updateTwin(twin);
+      this.handleIncomingTwinUpdated(twin);
+    }
+    return { status: "success", twin };
+  }
+
+  private handleReportDeviceProperties(payload: EventPayload): any {
+    const properties =
+      (payload.data as any)?.properties || (payload.data as any)?.reported;
+    const deviceTwin = this.twinCache.getDeviceTwin();
+    if (deviceTwin && properties) {
+      deviceTwin.properties.reported = {
+        ...deviceTwin.properties.reported,
+        ...properties,
+      };
+      this.twinCache.updateTwin(deviceTwin);
+      simulatorLog.dim("Device twin properties reported");
+      this.handleIncomingTwinUpdated(deviceTwin);
+    }
+    return { status: "success" };
+  }
+
+  private handleTwinSubscribe(
+    socket: Socket,
+    subscriberTwinId: string,
+    targetTwinId: string,
+  ): void {
+    if (!this.twinSubscriptions.has(subscriberTwinId)) {
+      this.twinSubscriptions.set(subscriberTwinId, new Set());
+    }
+    this.twinSubscriptions.get(subscriberTwinId)!.add(targetTwinId);
+    socket.join(targetTwinId);
+    simulatorLog.dim(`Twin ${subscriberTwinId} subscribed to ${targetTwinId}`);
+  }
+
+  private handleTwinUnsubscribe(
+    subscriberTwinId: string,
+    targetTwinId: string,
+  ): void {
+    const subscriptions = this.twinSubscriptions.get(subscriberTwinId);
+    if (subscriptions) {
+      subscriptions.delete(targetTwinId);
+      if (subscriptions.size === 0) {
+        this.twinSubscriptions.delete(subscriberTwinId);
+      }
+    }
+    simulatorLog.dim(
+      `Twin ${subscriberTwinId} unsubscribed from ${targetTwinId}`,
+    );
+  }
+
+  private getSocketsFromARoom(roomName: string): any[] {
+    const sockets: any[] = [];
+    const socketIds = this.io.sockets?.adapter?.rooms?.get(roomName);
+    socketIds?.forEach((socketId: string) => {
+      const socket = this.io.sockets?.sockets?.get(socketId);
+      if (socket) sockets.push(socket);
+    });
+    return sockets;
+  }
+
+  private generateMessageId(payload: EventPayload): string {
+    const { twinId, sourceTwinId, method, data } = payload;
+    const timestamp = Math.floor(Date.now() / 3000) * 3; // Round to nearest 3 seconds
+
+    const dataString = data
+      ? JSON.stringify(data, (_, value) =>
+          Buffer.isBuffer(value) ? value.toString("base64") : value,
+        )
+      : "";
+
+    const hash = createHash("sha256")
+      .update(`${twinId}-${sourceTwinId}-${method}-${dataString}-${timestamp}`)
+      .digest("hex");
+
+    return hash;
+  }
+
+  private trackMessageDelivery(messageId: string, recipientId: string): void {
+    if (!this.messageDeliveryTracker.has(messageId)) {
+      this.messageDeliveryTracker.set(messageId, new Set());
+
+      if (this.messageDeliveryTracker.size > this.MAX_TRACKED_MESSAGES) {
+        const oldestKey = this.messageDeliveryTracker.keys().next().value;
+        if (oldestKey) {
+          this.messageDeliveryTracker.delete(oldestKey);
+        }
+      }
+    }
+
+    this.messageDeliveryTracker.get(messageId)!.add(recipientId);
+  }
+
+  private hasMessageBeenDelivered(
+    messageId: string,
+    recipientId: string,
+  ): boolean {
+    return (
+      this.messageDeliveryTracker.get(messageId)?.has(recipientId) || false
+    );
+  }
+
+  private handleTwinMessageFromSubscription(
+    subscriberTwinId: string,
+    payload: EventPayload,
+    callback?: Function,
+  ): void {
+    const { twinId } = payload;
+    const roomSockets = this.getSocketsFromARoom(subscriberTwinId);
+
+    roomSockets.forEach((roomSocket) => {
+      roomSocket.emit("twinMessage", payload, (response: any) => {
+        // Response broadcasting: notify other sockets in the target twin's room
+        if (twinId && payload.data?.type) {
+          roomSocket.to(twinId).emit(payload.data.type, response);
+        }
+        if (callback) callback(response);
+      });
+    });
+  }
+
+  private deliverTwinMessageLocally(
+    callerTwinId: string,
+    payload: EventPayload,
+    callback?: Function,
+  ): void {
+    const { twinId, sourceTwinId } = payload;
+    if (!twinId) {
+      simulatorLog.warn("twinMessage: no target twinId, dropping");
+      return;
+    }
+
+    const dataType = (payload.data as any)?.type || "(no type)";
+
+    // Detect WebRTC signaling messages
+    const webrtcMatch = dataType.match(/^(.+):(offer|answer|ice)$/);
+    if (webrtcMatch) {
+      const [, channelPrefix, signalType] = webrtcMatch;
+      const isData = channelPrefix.startsWith("dc-");
+      const kind = isData ? "DataChannel" : "MediaStream";
+      simulatorLog.info(
+        `⚡ WebRTC ${signalType} (${kind}): ${sourceTwinId || "?"} → ${twinId}`,
+      );
+    } else {
+      simulatorLog.info(
+        `twinMessage: ${sourceTwinId || "?"} → ${twinId} [${dataType}]`,
+      );
+    }
+
+    const messageId = this.generateMessageId(payload);
+
+    // Layer 1: Subscription-based delivery (with dedup)
+    this.twinSubscriptions.forEach((subscribedTwins, subscriberTwinId) => {
+      if (
+        subscribedTwins.has(twinId) &&
+        !this.hasMessageBeenDelivered(messageId, subscriberTwinId)
+      ) {
+        this.handleTwinMessageFromSubscription(
+          subscriberTwinId,
+          payload,
+          callback,
+        );
+        this.trackMessageDelivery(messageId, subscriberTwinId);
+      }
+    });
+
+    // Layer 2: Type-based direct routing for Edge and Screen twins
+    const deviceTwins = this.twinCache.getGroupedByType();
+
+    if (deviceTwins[TwinTypeEnum.Edge]) {
+      for (const edgeTwinId of deviceTwins[TwinTypeEnum.Edge]) {
+        const edgeTwin = this.twinCache.getTwin(edgeTwinId);
+        if (
+          edgeTwin &&
+          edgeTwin.id === twinId &&
+          !this.hasMessageBeenDelivered(messageId, edgeTwin.id)
+        ) {
+          this.io.to(edgeTwin.id).emit("twinMessage", payload, callback);
+          this.trackMessageDelivery(messageId, edgeTwin.id);
+        }
+      }
+    }
+
+    if (deviceTwins[TwinTypeEnum.Screen]) {
+      for (const screenTwinId of deviceTwins[TwinTypeEnum.Screen]) {
+        const screenTwin = this.twinCache.getTwin(screenTwinId);
+        if (
+          screenTwin &&
+          screenTwin.id === twinId &&
+          !this.hasMessageBeenDelivered(messageId, screenTwin.id)
+        ) {
+          this.io.to(screenTwin.id).emit("twinMessage", payload, callback);
+          this.trackMessageDelivery(messageId, screenTwin.id);
+        }
+      }
+    }
+
+    // Layer 3: Peripheral → parent Edge routing
+    if (
+      deviceTwins[TwinTypeEnum.Peripheral] &&
+      deviceTwins[TwinTypeEnum.Edge]
+    ) {
+      for (const peripheralTwinId of deviceTwins[TwinTypeEnum.Peripheral]) {
+        const peripheralTwin = this.twinCache.getTwin(peripheralTwinId);
+        const instanceId = peripheralTwin?.properties?.desired?.instanceId;
+
+        if (
+          instanceId &&
+          deviceTwins[TwinTypeEnum.Edge].includes(instanceId) &&
+          !this.hasMessageBeenDelivered(messageId, instanceId)
+        ) {
+          this.io.to(instanceId).emit("twinMessage", payload);
+          this.trackMessageDelivery(messageId, instanceId);
+        }
+      }
+    }
+  }
+
+  private createLocalTwin(
+    type: TwinTypeEnum.Screen | TwinTypeEnum.Edge,
+    desiredProperties: Record<string, any>,
+    deviceTwin?: TwinResponse,
+    reuseId?: string,
+  ): TwinResponse {
+    return {
+      id: reuseId || uuidv4(),
+      deviceId: deviceTwin?.deviceId || uuidv4(),
+      tenantId: deviceTwin?.tenantId || uuidv4(),
+      type,
+      properties: {
+        desired: desiredProperties,
+        reported: {},
+      },
+    };
+  }
+}

package/src/simulator/twin-cache.ts

@@ -0,0 +1,61 @@
+/* eslint-disable import/prefer-default-export */
+import { TwinResponse, TwinTypeEnum } from "./types";
+
+export class TwinCache {
+  private twins: Map<string, TwinResponse> = new Map();
+
+  populate(twins: TwinResponse[]): void {
+    for (const twin of twins) {
+      this.twins.set(twin.id, twin);
+    }
+  }
+
+  getTwin(id: string): TwinResponse | undefined {
+    return this.twins.get(id);
+  }
+
+  getDeviceTwin(): TwinResponse | undefined {
+    for (const twin of this.twins.values()) {
+      if (twin.type === TwinTypeEnum.Device) return twin;
+    }
+    return undefined;
+  }
+
+  getAllTwins(): TwinResponse[] {
+    return Array.from(this.twins.values());
+  }
+
+  getAllTwinIds(): string[] {
+    return Array.from(this.twins.keys());
+  }
+
+  hasTwin(id: string): boolean {
+    return this.twins.has(id);
+  }
+
+  updateTwin(twin: TwinResponse): void {
+    this.twins.set(twin.id, twin);
+  }
+
+  addTwin(twin: TwinResponse): void {
+    this.twins.set(twin.id, twin);
+  }
+
+  removeTwin(id: string): void {
+    this.twins.delete(id);
+  }
+
+  getTwinsByType(type: string): TwinResponse[] {
+    return Array.from(this.twins.values()).filter((t) => t.type === type);
+  }
+
+  /** Returns twins grouped by type as { [type]: [twinId, ...] } — matching hub-device getCachedTwins format */
+  getGroupedByType(): Record<string, string[]> {
+    const grouped: Record<string, string[]> = {};
+    for (const twin of this.twins.values()) {
+      if (!grouped[twin.type]) grouped[twin.type] = [];
+      grouped[twin.type].push(twin.id);
+    }
+    return grouped;
+  }
+}

package/src/simulator/types.ts

@@ -0,0 +1,53 @@
+export interface SimulatorConfig {
+  port: number;
+  deviceDisplayName?: string;
+}
+
+export interface DeviceConfig {
+  deviceId: string;
+  tenantId: string;
+  deviceTwinId: string;
+}
+
+export enum AppTypeEnum {
+  Screen = "screen",
+  Edge = "edge",
+}
+
+export interface AppConfig {
+  name: string;
+  type: AppTypeEnum;
+  path: string;
+  twinId?: string;
+  devCommand: string;
+}
+
+export enum TwinTypeEnum {
+  Device = "Device",
+  Screen = "Screen",
+  Edge = "Edge",
+  Peripheral = "Peripheral",
+}
+
+export interface TwinResponse {
+  id: string;
+  deviceId: string;
+  tenantId: string;
+  type: TwinTypeEnum;
+  properties: {
+    desired: Record<string, any>;
+    reported: Record<string, any>;
+  };
+  descriptors?: Record<string, any>;
+  status?: string;
+}
+
+export interface EventPayload<T = any> {
+  twinId?: string;
+  deviceId?: string;
+  sourceTwinId?: string;
+  sourceDeviceId?: string;
+  method?: string;
+  data?: T;
+  [key: string]: any;
+}