@phystack/device-simulator 6.3.0

package/src/simulator/__tests__/message-router.test.ts

@@ -0,0 +1,782 @@
+import { describe, expect, test } from "bun:test";
+import { MessageRouter } from "../message-router";
+import { TwinCache } from "../twin-cache";
+import { EventPayload, TwinResponse, TwinTypeEnum } from "../types";
+
+// --- Fakes -----------------------------------------------------------------
+
+interface EmitRecord {
+  room: string | null;
+  event: string;
+  args: any[];
+}
+
+/**
+ * Minimal socket.io server fake. Records every emit (both broadcast
+ * `io.emit(...)` and room-scoped `io.to(room).emit(...)`) so tests can assert
+ * what the router published, without standing up a real Socket.IO server.
+ */
+function makeFakeIo() {
+  const emits: EmitRecord[] = [];
+  const rooms = new Map<string, Set<string>>();
+  const socketsById = new Map<string, any>();
+  const fakeIo: any = {
+    emits,
+    emit(event: string, ...args: any[]) {
+      emits.push({ room: null, event, args });
+    },
+    to(room: string) {
+      return {
+        emit(event: string, ...args: any[]) {
+          emits.push({ room, event, args });
+        },
+      };
+    },
+    sockets: {
+      adapter: { rooms },
+      sockets: socketsById,
+    },
+  };
+  return { fakeIo, emits, rooms, socketsById };
+}
+
+/**
+ * Minimal socket.io Socket fake: records `.join()` calls so we can assert
+ * subscription wiring.
+ */
+function makeFakeSocket() {
+  const joined: string[] = [];
+  const fakeSocket: any = {
+    joined,
+    join(room: string) {
+      joined.push(room);
+    },
+    emit() {},
+    to() {
+      return { emit() {} };
+    },
+  };
+  return { fakeSocket, joined };
+}
+
+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,
+  };
+}
+
+/** Capture the value passed to the ack callback. */
+function captureCallback() {
+  const calls: any[] = [];
+  const callback = (result: any) => {
+    calls.push(result);
+  };
+  return { callback, calls };
+}
+
+describe("MessageRouter — guard clauses", () => {
+  test("missing method → error ack and undefined return", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    const result = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      {} as EventPayload,
+      callback,
+    );
+
+    expect(result).toBeUndefined();
+    expect(calls).toEqual([
+      { status: "error", message: "No method specified" },
+    ]);
+  });
+
+  test("unsupported method → error result and ack", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    const result = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      { method: "reboot" },
+      callback,
+    );
+
+    const expected = {
+      status: "error",
+      message: "reboot is not supported in simulator mode",
+    };
+    expect(result).toEqual(expected);
+    expect(calls).toEqual([expected]);
+  });
+
+  test("signal method → success no-op", async () => {
+    const cache = new TwinCache();
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    const result = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      { method: "sendEventSignal", data: { kind: "demo" } },
+      callback,
+    );
+
+    expect(result).toEqual({ status: "success" });
+    expect(calls).toEqual([{ status: "success" }]);
+    expect(emits).toHaveLength(0);
+  });
+
+  test("unknown method → error result naming the method", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    const result = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      { method: "doesNotExist" },
+      callback,
+    );
+
+    expect(result).toEqual({
+      status: "error",
+      message: "Unknown method: doesNotExist",
+    });
+    expect(calls).toEqual([
+      { status: "error", message: "Unknown method: doesNotExist" },
+    ]);
+  });
+
+  test("ping → pong", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    await router.handleMessage(
+      fakeSocket,
+      "caller",
+      { method: "ping" },
+      callback,
+    );
+
+    expect(calls).toEqual([{ status: "success", message: "pong" }]);
+  });
+});
+
+describe("MessageRouter — device status & instance", () => {
+  test("getDeviceStatus reflects the device twin desired/reported props", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("dev-twin", TwinTypeEnum.Device, {
+        deviceId: "device-abc",
+        tenantId: "tenant-xyz",
+        properties: {
+          desired: {
+            displayName: "My Sim",
+            spaceId: "space-1",
+            env: "staging",
+            accessKey: "key-123",
+            deviceSerial: "SIM-XYZ",
+          },
+          reported: { os: { osVersion: "9.9" }, ip: [{ interface: "eth0" }] },
+        },
+      }),
+    );
+    cache.addTwin(makeTwin("screen-1", TwinTypeEnum.Screen));
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    const result = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      { method: "getDeviceStatus" },
+      callback,
+    );
+
+    expect(result.status).toBe("success");
+    expect(result.socketConnected).toBe(true);
+    expect(result.socketAuthenticated).toBe(true);
+    expect(result.deviceId).toBe("device-abc");
+    expect(result.tenantId).toBe("tenant-xyz");
+    expect(result.displayName).toBe("My Sim");
+    expect(result.spaceId).toBe("space-1");
+    expect(result.gridEnv).toBe("staging");
+    expect(result.accessKey).toBe("key-123");
+    expect(result.deviceSerial).toBe("SIM-XYZ");
+    expect(result.osVersion).toBe("9.9");
+    expect(result.dataResidency).toBe("DEV");
+    expect(result.isConnected).toBe("true");
+    expect(result.twins).toEqual({
+      Device: ["dev-twin"],
+      Screen: ["screen-1"],
+    });
+    expect(calls).toEqual([result]);
+  });
+
+  test("getDeviceStatus falls back to defaults when no device twin exists", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "getDeviceStatus",
+    });
+
+    expect(result.displayName).toBe("Simulator");
+    expect(result.spaceId).toBe("");
+    expect(result.gridEnv).toBe("development");
+    expect(result.accessKey).toBe("simulator-local-key");
+    expect(result.deviceSerial).toBe("SIM-LOCAL");
+    expect(result.osVersion).toBe("Simulator");
+    expect(result.deviceId).toBeUndefined();
+    expect(result.ip).toEqual([
+      { interface: "lo", ipv4: "127.0.0.1", ipv6: "::1" },
+    ]);
+  });
+
+  test("getInstance / getDeviceInstance return the device twin or an error", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const missing = await router.handleMessage(fakeSocket, "caller", {
+      method: "getDeviceInstance",
+    });
+    expect(missing).toEqual({
+      status: "error",
+      message: "Device twin not found",
+    });
+
+    const device = makeTwin("dev-twin", TwinTypeEnum.Device);
+    cache.addTwin(device);
+
+    const viaGetInstance = await router.handleMessage(fakeSocket, "caller", {
+      method: "getInstance",
+    });
+    expect(viaGetInstance).toEqual({ status: "success", twin: device });
+
+    const viaGetDeviceInstance = await router.handleMessage(
+      fakeSocket,
+      "caller",
+      {
+        method: "getDeviceInstance",
+      },
+    );
+    expect(viaGetDeviceInstance).toEqual({ status: "success", twin: device });
+  });
+
+  test("getTwinById returns the twin, or errors on missing/absent id", async () => {
+    const cache = new TwinCache();
+    const target = makeTwin("twin-x", TwinTypeEnum.Screen);
+    cache.addTwin(target);
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "getTwinById",
+        data: { twinId: "twin-x" },
+      }),
+    ).toEqual({ status: "success", twin: target });
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "getTwinById",
+        data: { twinId: "nope" },
+      }),
+    ).toEqual({ status: "error", message: "Twin not found" });
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "getTwinById",
+        data: {},
+      }),
+    ).toEqual({ status: "error", message: "Twin ID is required" });
+  });
+});
+
+describe("MessageRouter — twin creation", () => {
+  test("createInstanceTwin adds a twin, broadcasts twinCreated, reuses given id", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("dev-twin", TwinTypeEnum.Device, {
+        deviceId: "dev-id",
+        tenantId: "ten-id",
+      }),
+    );
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "createInstanceTwin",
+      data: {
+        type: TwinTypeEnum.Edge,
+        desiredProperties: { appName: "demo" },
+        id: "fixed-id",
+      },
+    });
+
+    expect(result.status).toBe("success");
+    expect(result.twin.id).toBe("fixed-id");
+    expect(result.twin.type).toBe(TwinTypeEnum.Edge);
+    expect(result.twin.deviceId).toBe("dev-id");
+    expect(result.twin.tenantId).toBe("ten-id");
+    expect(result.twin.properties).toEqual({
+      desired: { appName: "demo" },
+      reported: {},
+    });
+    expect(cache.getTwin("fixed-id")).toEqual(result.twin);
+    expect(emits).toEqual([
+      { room: null, event: "twinCreated", args: [{ data: result.twin }] },
+    ]);
+  });
+
+  test("createInstanceTwin defaults to Screen type when none supplied", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "createInstanceTwin",
+      data: {},
+    });
+
+    expect(result.twin.type).toBe(TwinTypeEnum.Screen);
+    // No device twin → deviceId/tenantId are freshly generated uuids
+    expect(typeof result.twin.deviceId).toBe("string");
+    expect(result.twin.deviceId).toHaveLength(36);
+  });
+
+  test("createPeripheralTwin stores descriptors and broadcasts twinCreated", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("dev-twin", TwinTypeEnum.Device, {
+        deviceId: "dev-id",
+        tenantId: "ten-id",
+      }),
+    );
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "createPeripheralTwin",
+      data: {
+        instanceId: "inst-1",
+        name: "camera",
+        hardwareId: "hw-9",
+        desiredProperties: { fps: 30 },
+      },
+    });
+
+    expect(result.status).toBe("success");
+    expect(result.twin.type).toBe(TwinTypeEnum.Peripheral);
+    expect(result.twin.deviceId).toBe("dev-id");
+    expect(result.twin.descriptors).toEqual({
+      instanceId: "inst-1",
+      name: "camera",
+      hardwareId: "hw-9",
+    });
+    expect(result.twin.properties.desired).toEqual({
+      fps: 30,
+      instanceId: "inst-1",
+      name: "camera",
+      hardwareId: "hw-9",
+    });
+    expect(cache.getTwin(result.twin.id)).toEqual(result.twin);
+    expect(emits).toEqual([
+      { room: null, event: "twinCreated", args: [{ data: result.twin }] },
+    ]);
+  });
+});
+
+describe("MessageRouter — peripheral twin lifecycle", () => {
+  test("deletePeripheralTwin removes the twin and broadcasts twinDeleted", async () => {
+    const cache = new TwinCache();
+    const peripheral = makeTwin("per-1", TwinTypeEnum.Peripheral);
+    cache.addTwin(peripheral);
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "deletePeripheralTwin",
+      data: { twinId: "per-1" },
+    });
+
+    expect(result).toEqual({ status: "success" });
+    expect(cache.hasTwin("per-1")).toBe(false);
+    expect(emits).toEqual([
+      { room: null, event: "twinDeleted", args: [{ data: peripheral }] },
+    ]);
+  });
+
+  test("deletePeripheralTwin errors on missing id and on unknown twin", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "deletePeripheralTwin",
+        data: {},
+      }),
+    ).toEqual({ status: "error", message: "Twin ID is required" });
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "deletePeripheralTwin",
+        data: { twinId: "ghost" },
+      }),
+    ).toEqual({ status: "error", message: "Twin not found" });
+  });
+
+  test("getPeripheralTwins lists all, then filters by instanceId", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("per-1", TwinTypeEnum.Peripheral, {
+        descriptors: { instanceId: "inst-A" },
+      }),
+    );
+    cache.addTwin(
+      makeTwin("per-2", TwinTypeEnum.Peripheral, {
+        descriptors: { instanceId: "inst-B" },
+      }),
+    );
+    cache.addTwin(makeTwin("screen-1", TwinTypeEnum.Screen));
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const all = await router.handleMessage(fakeSocket, "caller", {
+      method: "getPeripheralTwins",
+    });
+    expect(all.status).toBe("success");
+    expect(all.twins.map((twin: TwinResponse) => twin.id).sort()).toEqual([
+      "per-1",
+      "per-2",
+    ]);
+
+    const filtered = await router.handleMessage(fakeSocket, "caller", {
+      method: "getPeripheralTwins",
+      data: { instanceId: "inst-A" },
+    });
+    expect(filtered.twins.map((twin: TwinResponse) => twin.id)).toEqual([
+      "per-1",
+    ]);
+  });
+});
+
+describe("MessageRouter — reported property patches", () => {
+  test.each([
+    "reportScreenTwinProperties",
+    "reportEdgeTwinProperties",
+    "reportPeripheralTwinProperties",
+  ])(
+    "%s merges reported props and emits twinUpdated to the twin room",
+    async (method) => {
+      const cache = new TwinCache();
+      cache.addTwin(
+        makeTwin("twin-1", TwinTypeEnum.Screen, {
+          properties: { desired: {}, reported: { keep: 1 } },
+        }),
+      );
+      const { fakeIo, emits } = makeFakeIo();
+      const router = new MessageRouter(cache, fakeIo);
+      const { fakeSocket } = makeFakeSocket();
+
+      const result = await router.handleMessage(fakeSocket, "caller", {
+        method,
+        twinId: "twin-1",
+        data: { added: 2 },
+      });
+
+      expect(result.status).toBe("success");
+      expect(result.twin.properties.reported).toEqual({ keep: 1, added: 2 });
+      expect(cache.getTwin("twin-1")!.properties.reported).toEqual({
+        keep: 1,
+        added: 2,
+      });
+      // handleIncomingTwinUpdated emits twinMessage/twinUpdated to room = twin id
+      expect(emits).toEqual([
+        {
+          room: "twin-1",
+          event: "twinMessage",
+          args: [
+            {
+              method: "twinUpdated",
+              twinId: "twin-1",
+              data: cache.getTwin("twin-1"),
+            },
+          ],
+        },
+      ]);
+    },
+  );
+
+  test("reportScreenTwinProperties errors without a twinId or on unknown twin", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "reportScreenTwinProperties",
+        data: { x: 1 },
+      }),
+    ).toEqual({ status: "error", message: "Twin ID is required" });
+
+    expect(
+      await router.handleMessage(fakeSocket, "caller", {
+        method: "reportScreenTwinProperties",
+        twinId: "ghost",
+        data: { x: 1 },
+      }),
+    ).toEqual({ status: "error", message: "Twin not found" });
+  });
+
+  test("reportDeviceTwinProperties merges into the device twin (properties key)", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("dev-twin", TwinTypeEnum.Device, {
+        properties: { desired: {}, reported: { boot: 1 } },
+      }),
+    );
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "reportDeviceTwinProperties",
+      data: { properties: { uptime: 42 } },
+    });
+
+    expect(result).toEqual({ status: "success" });
+    expect(cache.getDeviceTwin()!.properties.reported).toEqual({
+      boot: 1,
+      uptime: 42,
+    });
+    expect(emits[0].event).toBe("twinMessage");
+    expect(emits[0].room).toBe("dev-twin");
+  });
+
+  test("reportDeviceTwinProperties also accepts a `reported` key", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(
+      makeTwin("dev-twin", TwinTypeEnum.Device, {
+        properties: { desired: {}, reported: {} },
+      }),
+    );
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    await router.handleMessage(fakeSocket, "caller", {
+      method: "reportDeviceTwinProperties",
+      data: { reported: { ram: 8 } },
+    });
+
+    expect(cache.getDeviceTwin()!.properties.reported).toEqual({ ram: 8 });
+  });
+
+  test("reportDeviceJob is a success no-op (no twin mutation, no emit)", async () => {
+    const cache = new TwinCache();
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "reportDeviceJob",
+    });
+    expect(result).toEqual({ status: "success" });
+    expect(emits).toHaveLength(0);
+  });
+});
+
+describe("MessageRouter — subscriptions & twinMessage routing", () => {
+  test("twinSubscribe joins the socket to the target room and acks success", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket, joined } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    await router.handleMessage(
+      fakeSocket,
+      "subscriber-twin",
+      { method: "twinSubscribe", twinId: "target-twin" },
+      callback,
+    );
+
+    expect(joined).toEqual(["target-twin"]);
+    expect(calls).toEqual([{ status: "success" }]);
+  });
+
+  test("twinUnsubscribe acks success without throwing when no prior subscription", async () => {
+    const cache = new TwinCache();
+    const { fakeIo } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+    const { callback, calls } = captureCallback();
+
+    await router.handleMessage(
+      fakeSocket,
+      "subscriber-twin",
+      { method: "twinUnsubscribe", twinId: "target-twin" },
+      callback,
+    );
+
+    expect(calls).toEqual([{ status: "success" }]);
+  });
+
+  test("twinMessage with no target twinId is dropped (no emit)", async () => {
+    const cache = new TwinCache();
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const result = await router.handleMessage(fakeSocket, "caller", {
+      method: "twinMessage",
+    });
+    expect(result).toBeUndefined();
+    expect(emits).toHaveLength(0);
+  });
+
+  test("twinMessage to an Edge twin routes via direct type-based delivery", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("edge-1", TwinTypeEnum.Edge));
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const payload: EventPayload = {
+      method: "twinMessage",
+      twinId: "edge-1",
+      sourceTwinId: "screen-1",
+      data: { type: "cmd", value: 1 },
+    };
+    await router.handleMessage(fakeSocket, "screen-1", payload);
+
+    const routed = emits.filter(
+      (entry) => entry.room === "edge-1" && entry.event === "twinMessage",
+    );
+    expect(routed).toHaveLength(1);
+    expect(routed[0].args[0]).toEqual(payload);
+  });
+
+  test("twinMessage to a Screen twin routes via direct type-based delivery", async () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("screen-1", TwinTypeEnum.Screen));
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const payload: EventPayload = {
+      method: "twinMessage",
+      twinId: "screen-1",
+      sourceTwinId: "edge-1",
+      data: { type: "cmd" },
+    };
+    await router.handleMessage(fakeSocket, "edge-1", payload);
+
+    const routed = emits.filter(
+      (entry) => entry.room === "screen-1" && entry.event === "twinMessage",
+    );
+    expect(routed).toHaveLength(1);
+  });
+
+  test("twinMessage delivery is deduplicated per (messageId, recipient)", async () => {
+    // Two twins with the same id can't coexist in cache; instead assert that
+    // re-delivering the identical payload within the 3s message-id window does
+    // not double-emit to the same recipient.
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("edge-1", TwinTypeEnum.Edge));
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+    const { fakeSocket } = makeFakeSocket();
+
+    const payload: EventPayload = {
+      method: "twinMessage",
+      twinId: "edge-1",
+      sourceTwinId: "screen-1",
+      data: { type: "cmd", value: 7 },
+    };
+    await router.handleMessage(fakeSocket, "screen-1", payload);
+    await router.handleMessage(fakeSocket, "screen-1", payload);
+
+    const routed = emits.filter(
+      (entry) => entry.room === "edge-1" && entry.event === "twinMessage",
+    );
+    expect(routed).toHaveLength(1);
+  });
+
+  test("handleIncomingTwinUpdated caches the twin and emits twinUpdated to its room", () => {
+    const cache = new TwinCache();
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+
+    const twin = makeTwin("twin-1", TwinTypeEnum.Screen, {
+      properties: { desired: {}, reported: { changed: true } },
+    });
+    router.handleIncomingTwinUpdated(twin);
+
+    expect(cache.getTwin("twin-1")).toEqual(twin);
+    expect(emits).toEqual([
+      {
+        room: "twin-1",
+        event: "twinMessage",
+        args: [{ method: "twinUpdated", twinId: "twin-1", data: twin }],
+      },
+    ]);
+  });
+
+  test("handleIncomingTwinMessage delivers a standalone twinMessage to the target room", () => {
+    const cache = new TwinCache();
+    cache.addTwin(makeTwin("edge-1", TwinTypeEnum.Edge));
+    const { fakeIo, emits } = makeFakeIo();
+    const router = new MessageRouter(cache, fakeIo);
+
+    router.handleIncomingTwinMessage({
+      twinId: "edge-1",
+      sourceTwinId: "cloud",
+      data: { type: "cmd" },
+    });
+
+    const routed = emits.filter(
+      (entry) => entry.room === "edge-1" && entry.event === "twinMessage",
+    );
+    expect(routed).toHaveLength(1);
+  });
+});