@phystack/device-simulator 6.3.0

package/src/simulator/__tests__/twin-cache.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "bun:test";
+import { TwinCache } from "../twin-cache";
+import { TwinResponse, TwinTypeEnum } from "../types";
+
+function makeTwin(
+  id: string,
+  type: TwinTypeEnum,
+  overrides: Partial<TwinResponse> = {},
+): TwinResponse {
+  return {
+    id,
+    deviceId: overrides.deviceId ?? `device-${id}`,
+    tenantId: overrides.tenantId ?? `tenant-${id}`,
+    type,
+    properties: overrides.properties ?? { desired: {}, reported: {} },
+    descriptors: overrides.descriptors,
+    status: overrides.status,
+  };
+}
+
+describe("TwinCache", () => {
+  test("addTwin / getTwin round-trips a twin by id", () => {
+    const cache = new TwinCache();
+    const twin = makeTwin("screen-1", TwinTypeEnum.Screen);
+    cache.addTwin(twin);
+    expect(cache.getTwin("screen-1")).toEqual(twin);
+  });
+
+  test("getTwin returns undefined for an unknown id", () => {
+    const cache = new TwinCache();
+    expect(cache.getTwin("missing")).toBeUndefined();
+  });
+
+  test("addTwin overwrites an existing twin with the same id", () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("twin-1", TwinTypeEnum.Screen));
+    const replacement = makeTwin("twin-1", TwinTypeEnum.Edge);
+    cache.addTwin(replacement);
+    expect(cache.getTwin("twin-1")).toEqual(replacement);
+    expect(cache.getAllTwins()).toHaveLength(1);
+  });
+
+  test("updateTwin behaves identically to addTwin (set by id)", () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("twin-1", TwinTypeEnum.Screen));
+    const updated = makeTwin("twin-1", TwinTypeEnum.Screen, {
+      properties: { desired: {}, reported: { foo: "bar" } },
+    });
+    cache.updateTwin(updated);
+    expect(cache.getTwin("twin-1")).toEqual(updated);
+  });
+
+  test("populate inserts multiple twins keyed by id", () => {
+    const cache = new TwinCache();
+    cache.populate([
+      makeTwin("a", TwinTypeEnum.Screen),
+      makeTwin("b", TwinTypeEnum.Edge),
+    ]);
+    expect(cache.getAllTwinIds().sort()).toEqual(["a", "b"]);
+  });
+
+  test("removeTwin deletes by id; removing a missing id is a no-op", () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("twin-1", TwinTypeEnum.Screen));
+    cache.removeTwin("twin-1");
+    expect(cache.getTwin("twin-1")).toBeUndefined();
+    expect(cache.hasTwin("twin-1")).toBe(false);
+    // removing again does not throw
+    cache.removeTwin("twin-1");
+    expect(cache.getAllTwins()).toHaveLength(0);
+  });
+
+  test("hasTwin reflects presence", () => {
+    const cache = new TwinCache();
+    expect(cache.hasTwin("twin-1")).toBe(false);
+    cache.addTwin(makeTwin("twin-1", TwinTypeEnum.Screen));
+    expect(cache.hasTwin("twin-1")).toBe(true);
+  });
+
+  test("getAllTwins / getAllTwinIds list every twin in insertion order", () => {
+    const cache = new TwinCache();
+    const first = makeTwin("first", TwinTypeEnum.Screen);
+    const second = makeTwin("second", TwinTypeEnum.Edge);
+    cache.addTwin(first);
+    cache.addTwin(second);
+    expect(cache.getAllTwins()).toEqual([first, second]);
+    expect(cache.getAllTwinIds()).toEqual(["first", "second"]);
+  });
+
+  test("getDeviceTwin returns the first Device-type twin, undefined when none", () => {
+    const cache = new TwinCache();
+    expect(cache.getDeviceTwin()).toBeUndefined();
+    const device = makeTwin("dev-1", TwinTypeEnum.Device);
+    cache.addTwin(makeTwin("screen-1", TwinTypeEnum.Screen));
+    cache.addTwin(device);
+    expect(cache.getDeviceTwin()).toEqual(device);
+  });
+
+  test("getTwinsByType filters by twin type", () => {
+    const cache = new TwinCache();
+    const screenOne = makeTwin("s1", TwinTypeEnum.Screen);
+    const screenTwo = makeTwin("s2", TwinTypeEnum.Screen);
+    cache.addTwin(screenOne);
+    cache.addTwin(screenTwo);
+    cache.addTwin(makeTwin("e1", TwinTypeEnum.Edge));
+    expect(cache.getTwinsByType(TwinTypeEnum.Screen)).toEqual([
+      screenOne,
+      screenTwo,
+    ]);
+    expect(cache.getTwinsByType(TwinTypeEnum.Peripheral)).toEqual([]);
+  });
+
+  test("getGroupedByType groups twin ids by type", () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("dev", TwinTypeEnum.Device));
+    cache.addTwin(makeTwin("s1", TwinTypeEnum.Screen));
+    cache.addTwin(makeTwin("s2", TwinTypeEnum.Screen));
+    cache.addTwin(makeTwin("e1", TwinTypeEnum.Edge));
+    expect(cache.getGroupedByType()).toEqual({
+      Device: ["dev"],
+      Screen: ["s1", "s2"],
+      Edge: ["e1"],
+    });
+  });
+
+  test("getGroupedByType returns an empty object for an empty cache", () => {
+    expect(new TwinCache().getGroupedByType()).toEqual({});
+  });
+});

package/src/simulator/index.ts

@@ -0,0 +1,200 @@
+/* eslint-disable import/prefer-default-export */
+import crypto from "crypto";
+import chalk from "chalk";
+import { v4 as uuidv4 } from "uuid";
+import { TwinResponse, TwinTypeEnum } from "./types";
+import { TwinCache } from "./twin-cache";
+import { LocalServer, InstanceConnectionEvent } from "./local-server";
+import { MessageRouter } from "./message-router";
+import { simulatorLog } from "./logger";
+import { getDeviceConfig, saveDeviceConfig } from "../utils/simulator-config";
+import { getPackageVersion } from "../utils";
+
+/**
+ * Generate a deterministic 24-char hex string (MongoDB ObjectID format)
+ * from a human-readable name. Same input always produces same output.
+ */
+function mockObjectId(name: string): string {
+  return crypto.createHash("sha256").update(name).digest("hex").slice(0, 24);
+}
+
+export class DeviceSimulator {
+  private twinCache: TwinCache;
+
+  private localServer: LocalServer;
+
+  private router: MessageRouter | null = null;
+
+  private port: number;
+
+  private deviceDisplayName: string;
+
+  private deviceId: string = "";
+
+  private tenantId: string = "";
+
+  constructor(port = 55000, deviceDisplayName = "Local Simulator") {
+    this.port = port;
+    this.deviceDisplayName = deviceDisplayName;
+    this.twinCache = new TwinCache();
+    this.localServer = new LocalServer(port);
+  }
+
+  async start(): Promise<void> {
+    // 1. Load or create device identity
+    // Config storage uses this as directory name. Twins need a 24-char hex ID
+    // to pass hub-client validation (e.g. signals zod schemas), so we derive
+    // one deterministically via mockObjectId.
+    const tenantLabel = "local";
+    const tenantObjectId = mockObjectId(tenantLabel);
+    this.tenantId = tenantObjectId;
+    const existingConfig = await getDeviceConfig(tenantLabel);
+    let deviceTwinId: string;
+
+    if (existingConfig) {
+      this.deviceId = existingConfig.deviceId;
+      deviceTwinId = existingConfig.deviceTwinId;
+    } else {
+      this.deviceId = uuidv4();
+      deviceTwinId = uuidv4();
+      await saveDeviceConfig(tenantLabel, {
+        deviceId: this.deviceId,
+        tenantId: this.tenantId,
+        deviceTwinId,
+      });
+    }
+
+    // 2. Create a local Device twin in cache
+    const deviceTwin: TwinResponse = {
+      id: deviceTwinId,
+      deviceId: this.deviceId,
+      tenantId: this.tenantId,
+      type: TwinTypeEnum.Device,
+      properties: {
+        desired: {
+          displayName: this.deviceDisplayName,
+          spaceId: tenantObjectId,
+          env: "development",
+          deviceSerial: `SIM-${this.deviceId.slice(0, 8)}`,
+          accessKey: "simulator-local-key",
+        },
+        reported: {
+          ip: [{ interface: "lo", ipv4: "127.0.0.1", ipv6: "::1" }],
+          os: { osVersion: "Simulator" },
+          env: { gridEnv: "development" },
+        },
+      },
+    };
+    this.twinCache.addTwin(deviceTwin);
+
+    // 3. Start local server
+    await this.localServer.start();
+    const io = this.localServer.getIO();
+
+    this.localServer.on(
+      "instanceConnected",
+      (event: InstanceConnectionEvent) => {
+        const twin = this.twinCache.getTwin(event.twinId);
+        const label = twin?.properties?.desired?.appName || "unknown";
+        simulatorLog.success(
+          `Instance connected: ${label} (${event.twinId}) — ${event.activeCount} active`,
+        );
+      },
+    );
+
+    this.localServer.on(
+      "instanceDisconnected",
+      (event: InstanceConnectionEvent) => {
+        const twin = this.twinCache.getTwin(event.twinId);
+        const label = twin?.properties?.desired?.appName || "unknown";
+        simulatorLog.warn(
+          `Instance disconnected: ${label} (${event.twinId}) — ${event.activeCount} active`,
+        );
+      },
+    );
+
+    // 4. Create router (no upstream)
+    this.router = new MessageRouter(this.twinCache, io);
+    this.localServer.setRouter(this.router);
+
+    // 5. Print banner
+    this.printBanner();
+
+    if (existingConfig) {
+      simulatorLog.dim(`Reusing device identity ${this.deviceId}`);
+    }
+    simulatorLog.dim(`Apps connect to http://localhost:${this.port}`);
+  }
+
+  async stop(): Promise<void> {
+    simulatorLog.dim("Shutting down simulator...");
+    await this.localServer.stop();
+    simulatorLog.dim("Simulator stopped.");
+  }
+
+  async createTwinForApp(
+    type: TwinTypeEnum.Screen | TwinTypeEnum.Edge,
+    desiredProperties?: Record<string, any>,
+    reuseId?: string,
+  ): Promise<TwinResponse> {
+    const twin: TwinResponse = {
+      id: reuseId || uuidv4(),
+      deviceId: this.deviceId,
+      tenantId: this.tenantId,
+      type,
+      properties: {
+        desired: desiredProperties || {},
+        reported: {},
+      },
+    };
+    this.twinCache.addTwin(twin);
+    return twin;
+  }
+
+  createPeripheralTwin(
+    instanceId: string,
+    name: string,
+    hardwareId: string,
+    desiredProperties?: Record<string, any>,
+  ): TwinResponse {
+    const twin: TwinResponse = {
+      id: uuidv4(),
+      deviceId: this.deviceId,
+      tenantId: this.tenantId,
+      type: TwinTypeEnum.Peripheral,
+      properties: {
+        desired: { ...desiredProperties, instanceId, name, hardwareId },
+        reported: {},
+      },
+      descriptors: { instanceId, name, hardwareId },
+    };
+    this.twinCache.addTwin(twin);
+    return twin;
+  }
+
+  verifyTwinExists(twinId: string): boolean {
+    return this.twinCache.hasTwin(twinId);
+  }
+
+  getDeviceId(): string {
+    return this.deviceId;
+  }
+
+  private printBanner(): void {
+    simulatorLog.printBanner([
+      "",
+      chalk.hex("#00e676")(" ██▀▀▄ █  █ █  █ ▄▀▀▀ ▀▀█▀▀ ▄▀▀█ ▄▀▀▀ █ ▄▀"),
+      chalk.hex("#00c853")(" █▄▄▀  █▄▄█  ▀█   ▀▀▄   █   █▄▄█ █    █▀▄ "),
+      chalk.hex("#00a846")(" █     █  █   █  ▀▄▄▀   █   █  █ ▀▄▄▀ █  ▀▄"),
+      chalk.dim(` Device Simulator v${getPackageVersion()}`),
+      chalk.dim("─".repeat(50)),
+      `  ${chalk.cyan("Mode:")}        ${chalk.yellow("local")}`,
+      `  ${chalk.cyan("Port:")}        ${this.port}`,
+      `  ${chalk.cyan("Device:")}      ${this.deviceDisplayName}`,
+      `  ${chalk.cyan("Device ID:")}   ${chalk.dim(this.deviceId)} ${chalk.yellow("(local)")}`,
+      `  ${chalk.cyan("Tenant:")}      ${chalk.dim(this.tenantId)} ${chalk.yellow("(local)")}`,
+      chalk.dim("─".repeat(50)),
+      "",
+    ]);
+  }
+}

package/src/simulator/local-server.ts

@@ -0,0 +1,184 @@
+/* eslint-disable import/prefer-default-export */
+import { createServer } from "http";
+import { EventEmitter } from "events";
+import { Server as SocketIOServer, Socket } from "socket.io";
+import { MessageRouter } from "./message-router";
+import { EventPayload } from "./types";
+
+export interface InstanceConnectionEvent {
+  twinId: string;
+  activeCount: number;
+}
+
+export class LocalServer extends EventEmitter {
+  private httpServer: ReturnType<typeof createServer> | null = null;
+
+  private io: SocketIOServer | null = null;
+
+  private port: number;
+
+  private router: MessageRouter | null = null;
+
+  private connectedClients: Map<string, Socket[]> = new Map();
+
+  private eventDebounceTimers: Map<string, NodeJS.Timeout> = new Map();
+
+  constructor(port = 55000) {
+    super();
+    this.port = port;
+  }
+
+  getIO(): SocketIOServer | null {
+    return this.io;
+  }
+
+  setRouter(router: MessageRouter): void {
+    this.router = router;
+  }
+
+  start(): Promise<void> {
+    this.httpServer = createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", simulator: true }));
+    });
+
+    this.io = new SocketIOServer(this.httpServer, {
+      cors: { origin: "*" },
+    });
+
+    this.io.on("connection", (socket: Socket) => {
+      this.setupSocketHandlers(socket);
+    });
+
+    return new Promise<void>((resolve, reject) => {
+      // Bind to IPv4 loopback — Bun's default .listen(port) picks the IPv6
+      // wildcard, which fails on IPv6-disabled Linux hosts. The simulator
+      // is a dev-workflow local server so loopback is the right scope.
+      this.httpServer!.listen(this.port, "127.0.0.1", () => {
+        resolve();
+      });
+      this.httpServer!.on("error", reject);
+    });
+  }
+
+  private setupSocketHandlers(socket: Socket): void {
+    const auth = (socket.handshake.auth || {}) as {
+      instanceId?: string;
+      moduleName?: string;
+    };
+    const twinId = auth.instanceId || auth.moduleName;
+
+    // Generic channel for CLI utility calls (no twin ID needed)
+    socket.on(
+      "simulator",
+      async (payload: EventPayload, callback?: Function) => {
+        if (this.router) {
+          await this.router.handleMessage(socket, "", payload, callback);
+        }
+      },
+    );
+
+    socket.on("ping", (data: any) => {
+      setTimeout(() => {
+        socket.emit("pong", { count: (data?.count || 0) + 1 });
+      }, 100);
+    });
+
+    // App connections provide a twin ID via auth — set up twin-specific handlers
+    if (!twinId) return;
+
+    if (!this.connectedClients.has(twinId)) {
+      this.connectedClients.set(twinId, []);
+    }
+    this.connectedClients.get(twinId)!.push(socket);
+    this.emitDebounced(twinId);
+
+    socket.join(twinId);
+
+    socket.on("disconnect", () => {
+      const sockets = this.connectedClients.get(twinId);
+      if (sockets) {
+        const idx = sockets.indexOf(socket);
+        if (idx !== -1) sockets.splice(idx, 1);
+        if (sockets.length === 0) this.connectedClients.delete(twinId);
+      }
+      this.emitDebounced(twinId);
+    });
+
+    // Hub-client protocol: client emits on its own twin ID channel
+    socket.on(twinId, async (payload: EventPayload, callback?: Function) => {
+      if (this.router) {
+        await this.router.handleMessage(socket, twinId, payload, callback);
+      }
+    });
+
+    socket.on("reconnect", () => {
+      socket.join(twinId);
+    });
+
+    socket.on("getDeviceTwin", (callback: Function) => {
+      if (this.router) {
+        const result = (this.router as any).handleLocalMethod(
+          "getDeviceInstance",
+          {},
+        );
+        if (result && typeof result.then === "function") {
+          result.then((r: any) => callback(r?.twin || {}));
+        } else {
+          callback(result?.twin || {});
+        }
+      }
+    });
+  }
+
+  stop(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      if (this.io) {
+        this.io.disconnectSockets(true);
+        this.io.close();
+      }
+      if (this.httpServer) {
+        this.httpServer.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  getConnectedClients(): string[] {
+    return Array.from(this.connectedClients.keys());
+  }
+
+  /**
+   * Debounce connect/disconnect events per twin ID.
+   *
+   * Hub-client's getPhyHubSocket() uses a two-phase connection strategy:
+   *   1. PROBE — connects with reconnectionAttempts:1 to discover which URL works
+   *      (tries localhost:55000, phyos:55500, phyhub.eu.omborigrid.net in order)
+   *   2. DISCONNECT — kills the probe socket, extracts the winning URL from socket.io.uri
+   *   3. RECONNECT — creates a new socket to the same URL with default (production) settings
+   *
+   * In simulator mode this is redundant (URL is always localhost:55000) but hub-client
+   * doesn't know that — it runs the same code path as production. The result is 3 rapid
+   * socket events: connect → disconnect → connect, all within milliseconds.
+   *
+   * Additionally, Vite HMR can cause the browser to re-initialize the app, triggering
+   * the entire probe cycle again.
+   *
+   * We debounce per twin ID so that after the flurry settles (500ms), we emit a single
+   * event reflecting the final state — either instanceConnected or instanceDisconnected.
+   */
+  private emitDebounced(twinId: string): void {
+    const existing = this.eventDebounceTimers.get(twinId);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.eventDebounceTimers.delete(twinId);
+      const isConnected = this.connectedClients.has(twinId);
+      const event = isConnected ? "instanceConnected" : "instanceDisconnected";
+      this.emit(event, { twinId, activeCount: this.connectedClients.size });
+    }, 500);
+
+    this.eventDebounceTimers.set(twinId, timer);
+  }
+}

package/src/simulator/logger.ts

@@ -0,0 +1,44 @@
+/* eslint-disable import/prefer-default-export */
+import chalk from "chalk";
+
+function timestamp(): string {
+  const now = new Date();
+  const h = String(now.getHours()).padStart(2, "0");
+  const m = String(now.getMinutes()).padStart(2, "0");
+  const s = String(now.getSeconds()).padStart(2, "0");
+  return chalk.dim(`[${h}:${m}:${s}]`);
+}
+
+export class SimulatorLogger {
+  log(message: string): void {
+    console.log(`${timestamp()} ${message}`);
+  }
+
+  info(message: string): void {
+    this.log(message);
+  }
+
+  success(message: string): void {
+    this.log(chalk.green(message));
+  }
+
+  warn(message: string): void {
+    this.log(chalk.yellow(message));
+  }
+
+  error(message: string): void {
+    this.log(chalk.red(message));
+  }
+
+  dim(message: string): void {
+    this.log(chalk.dim(message));
+  }
+
+  printBanner(lines: string[]): void {
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
+}
+
+export const simulatorLog = new SimulatorLogger();