@mh-gg/host-ipc 0.1.1-alpha.20260613T085325975Z

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@mh-gg/host-ipc",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Relay IPC framing helpers for matterhorn hosts.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/relay-core": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/*.cjs test/*.test.cjs"
+  }
+}

package/src/index.cjs

@@ -0,0 +1,198 @@
+const { createRelayChunkAssembler, messageJsonByteLength, sendMessage } = require("@mh-gg/relay-core");
+
+const OPEN_READY_STATE = 1;
+const relaySocketConnections = new WeakMap();
+
+function relaySocketConnection(socket) {
+  let conn = relaySocketConnections.get(socket);
+  if (conn) return conn;
+  conn = {
+    get open() {
+      return socket.readyState === OPEN_READY_STATE;
+    },
+    send(message) {
+      if (socket.readyState !== OPEN_READY_STATE) return;
+      socket.send(JSON.stringify(message));
+    }
+  };
+  relaySocketConnections.set(socket, conn);
+  return conn;
+}
+
+function sendToRelay(socket, message) {
+  sendMessage(relaySocketConnection(socket), message);
+}
+
+function hostDebugEnabled() {
+  return process.env.MATTERHORN_DEBUG === "1";
+}
+
+function record(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function safeDebugDetails(peerId, message) {
+  const value = record(message);
+  const details = {
+    peerId,
+    messageType: typeof value.type === "string" ? value.type : undefined,
+    keys: Object.keys(value).sort()
+  };
+  for (const key of ["roomName", "clientId", "frontendId", "operationId", "acceptedMutationId", "code"]) {
+    if (typeof value[key] === "string") details[key] = value[key];
+  }
+  for (const key of ["offset", "byteLength", "totalBytes"]) {
+    if (Number.isFinite(value[key])) details[key] = value[key];
+  }
+  if (typeof value.done === "boolean") details.done = value.done;
+  return details;
+}
+
+function hostDebugMessage(peerId, action, message) {
+  const details = safeDebugDetails(peerId, message);
+  return {
+    type: "host/debug",
+    protocol: 1,
+    scope: "host",
+    message: `${action} ${details.messageType || "message"}`,
+    details,
+    createdAt: Date.now()
+  };
+}
+
+function mirrorsHostDebug(message) {
+  return hostDebugEnabled()
+    && message?.type !== "host/debug"
+    && message?.type !== "host/frontend-chunk";
+}
+
+function sendToClient(socket, peerId, message) {
+  if (mirrorsHostDebug(message)) {
+    sendToRelay(socket, {
+      type: "host.send",
+      peerId,
+      message: hostDebugMessage(peerId, "host.send", message)
+    });
+  }
+  sendToRelay(socket, {
+    type: "host.send",
+    peerId,
+    message
+  });
+}
+
+function closeClient(socket, peerId) {
+  if (hostDebugEnabled()) {
+    sendToRelay(socket, {
+      type: "host.send",
+      peerId,
+      message: hostDebugMessage(peerId, "host.close", { type: "host.close" })
+    });
+  }
+  sendToRelay(socket, {
+    type: "host.close",
+    peerId
+  });
+}
+
+function parseRelayMessage(data) {
+  try {
+    return JSON.parse(data.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function dataByteLength(data) {
+  if (typeof data === "string") return Buffer.byteLength(data, "utf8");
+  if (Buffer.isBuffer(data)) return data.length;
+  if (Array.isArray(data)) return data.reduce((total, item) => total + dataByteLength(item), 0);
+  return Buffer.byteLength(String(data || ""), "utf8");
+}
+
+function createRelayMessageReceiver(options = {}) {
+  const assembler = createRelayChunkAssembler(options);
+  const maxMessageBytes = Number.isInteger(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : undefined;
+  return function receiveRelayMessage(data) {
+    if (maxMessageBytes && dataByteLength(data) > maxMessageBytes) return undefined;
+    const message = typeof data === "object" && !Buffer.isBuffer(data) ? data : parseRelayMessage(data);
+    if (!message) return undefined;
+    return assembler.accept(message);
+  };
+}
+
+let ipcClientSeq = 0;
+
+class WebSocketRelayConnection {
+  constructor(socket, options = {}) {
+    this.socket = socket;
+    this.open = true;
+    this.peer = `ipc_${++ipcClientSeq}`;
+    this.maxMessageBytes = Number.isInteger(options.maxMessageBytes) && options.maxMessageBytes > 0
+      ? options.maxMessageBytes
+      : undefined;
+    this.receiveRelayMessage = createRelayMessageReceiver({ maxBytes: this.maxMessageBytes });
+    this.handlers = {
+      data: [],
+      close: [],
+      error: []
+    };
+
+    socket.on("message", (data) => {
+      if (this.maxMessageBytes && dataByteLength(data) > this.maxMessageBytes) {
+        this.send({
+          type: "host.message.error",
+          code: "message-too-large",
+          message: "Host IPC message is too large"
+        });
+        this.close();
+        return;
+      }
+      const message = this.receiveRelayMessage(data);
+      if (!message) {
+        if (dataByteLength(data) > 0 && !parseRelayMessage(data)) this.send(["NOTICE", "Invalid JSON"]);
+        return;
+      }
+      const byteLength = messageJsonByteLength(message);
+      if (this.maxMessageBytes && (byteLength === undefined || byteLength > this.maxMessageBytes)) {
+        this.send({
+          type: "host.message.error",
+          code: "message-too-large",
+          message: "Host IPC message is too large"
+        });
+        return;
+      }
+      for (const handler of this.handlers.data) handler(message);
+    });
+    socket.on("close", () => {
+      this.open = false;
+      for (const handler of this.handlers.close) handler();
+    });
+    socket.on("error", (error) => {
+      this.open = false;
+      for (const handler of this.handlers.error) handler(error);
+    });
+  }
+
+  send(message) {
+    sendToRelay(this.socket, message);
+  }
+
+  close() {
+    this.socket.close();
+  }
+
+  on(event, callback) {
+    this.handlers[event]?.push(callback);
+  }
+}
+
+module.exports = {
+  WebSocketRelayConnection,
+  closeClient,
+  createRelayMessageReceiver,
+  hostDebugMessage,
+  parseRelayMessage,
+  sendToClient,
+  sendToRelay
+};

package/test/host-ipc.test.cjs

@@ -0,0 +1,193 @@
+const assert = require("node:assert/strict");
+const { EventEmitter } = require("node:events");
+const test = require("node:test");
+const { WebSocketRelayConnection, closeClient, createRelayMessageReceiver, parseRelayMessage, sendToClient, sendToRelay } = require("..");
+
+function socket(readyState = 1) {
+  return {
+    readyState,
+    sent: [],
+    send(raw) {
+      this.sent.push(raw);
+    }
+  };
+}
+
+test("sends relay messages only while the socket is open", () => {
+  const open = socket();
+  const closed = socket(3);
+  sendToRelay(open, { type: "host.register" });
+  sendToRelay(closed, { type: "host.register" });
+
+  assert.deepEqual(open.sent.map((raw) => JSON.parse(raw)), [{ type: "host.register" }]);
+  assert.deepEqual(closed.sent, []);
+});
+
+test("sendToRelay keeps small IPC messages direct and chunks large messages", async () => {
+  const open = socket();
+  sendToRelay(open, { type: "host.register" });
+  assert.deepEqual(open.sent.map((raw) => JSON.parse(raw)), [{ type: "host.register" }]);
+
+  open.sent.length = 0;
+  sendToRelay(open, { type: "host.snapshot", store: { body: "x".repeat(12 * 1024) } });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  const sent = open.sent.map((raw) => JSON.parse(raw));
+  assert.equal(sent.every((message) => message.type === "relay.chunk"), true);
+  const receive = createRelayMessageReceiver();
+  const received = sent.map((message) => receive(message)).find(Boolean);
+  assert.equal(received.type, "host.snapshot");
+  assert.equal(received.store.body.length, 12 * 1024);
+});
+
+test("frames host send and close messages", () => {
+  const relaySocket = socket();
+  sendToClient(relaySocket, "peer-1", { type: "host/welcome" });
+  closeClient(relaySocket, "peer-1");
+
+  assert.deepEqual(relaySocket.sent.map((raw) => JSON.parse(raw)), [
+    { type: "host.send", peerId: "peer-1", message: { type: "host/welcome" } },
+    { type: "host.close", peerId: "peer-1" }
+  ]);
+});
+
+test("mirrors safe host debug messages when host debug mode is enabled", () => {
+  const previous = process.env.MATTERHORN_DEBUG;
+  process.env.MATTERHORN_DEBUG = "1";
+  try {
+    const relaySocket = socket();
+    sendToClient(relaySocket, "peer-1", {
+      type: "host/welcome",
+      protocol: 1,
+      roomName: "team-chat",
+      clientId: "client-1",
+      adminToken: "secret-admin-token",
+      memberCredentials: { memberSecret: "secret-member-token" }
+    });
+    closeClient(relaySocket, "peer-1");
+    const sent = relaySocket.sent.map((raw) => JSON.parse(raw));
+
+    assert.equal(sent[0].message.type, "host/debug");
+    assert.equal(sent[0].message.message, "host.send host/welcome");
+    assert.deepEqual(sent[0].message.details.peerId, "peer-1");
+    assert.deepEqual(sent[0].message.details.roomName, "team-chat");
+    assert.deepEqual(sent[0].message.details.clientId, "client-1");
+    assert.equal(JSON.stringify(sent[0].message).includes("secret-admin-token"), false);
+    assert.equal(JSON.stringify(sent[0].message).includes("secret-member-token"), false);
+    assert.deepEqual(sent[1].message.type, "host/welcome");
+    assert.equal(sent[2].message.type, "host/debug");
+    assert.equal(sent[2].message.message, "host.close host.close");
+    assert.equal(sent[3].type, "host.close");
+  } finally {
+    if (previous === undefined) delete process.env.MATTERHORN_DEBUG;
+    else process.env.MATTERHORN_DEBUG = previous;
+  }
+});
+
+test("does not mirror per-chunk host debug messages", () => {
+  const previous = process.env.MATTERHORN_DEBUG;
+  process.env.MATTERHORN_DEBUG = "1";
+  try {
+    const relaySocket = socket();
+    sendToClient(relaySocket, "peer-1", {
+      type: "host/frontend-chunk",
+      protocol: 1,
+      roomName: "team-chat",
+      frontendId: "player",
+      offset: 0,
+      byteLength: 4,
+      totalBytes: 4,
+      data: "YWJjZA==",
+      done: true
+    });
+
+    assert.deepEqual(relaySocket.sent.map((raw) => JSON.parse(raw)), [{
+      type: "host.send",
+      peerId: "peer-1",
+      message: {
+        type: "host/frontend-chunk",
+        protocol: 1,
+        roomName: "team-chat",
+        frontendId: "player",
+        offset: 0,
+        byteLength: 4,
+        totalBytes: 4,
+        data: "YWJjZA==",
+        done: true
+      }
+    }]);
+  } finally {
+    if (previous === undefined) delete process.env.MATTERHORN_DEBUG;
+    else process.env.MATTERHORN_DEBUG = previous;
+  }
+});
+
+test("parses relay JSON and ignores malformed data", () => {
+  assert.deepEqual(parseRelayMessage(Buffer.from('{"type":"relay/client-close"}')), { type: "relay/client-close" });
+  assert.equal(parseRelayMessage(Buffer.from("{nope")), undefined);
+});
+
+class FakeWebSocket extends EventEmitter {
+  constructor() {
+    super();
+    this.readyState = 1;
+    this.sent = [];
+    this.closed = false;
+  }
+
+  send(raw) {
+    this.sent.push(raw);
+  }
+
+  close() {
+    this.closed = true;
+    this.readyState = 3;
+    this.emit("close");
+  }
+}
+
+test("WebSocketRelayConnection parses messages and tracks lifecycle", () => {
+  const socket = new FakeWebSocket();
+  const conn = new WebSocketRelayConnection(socket);
+  const messages = [];
+  const errors = [];
+  let closed = false;
+  conn.on("data", (message) => messages.push(message));
+  conn.on("error", (error) => errors.push(error.message));
+  conn.on("close", () => {
+    closed = true;
+  });
+
+  socket.emit("message", Buffer.from('{"type":"client/hello"}'));
+  socket.emit("message", Buffer.from("{nope"));
+  conn.send({ type: "host/welcome" });
+  socket.emit("error", new Error("socket failed"));
+  conn.close();
+
+  assert.match(conn.peer, /^ipc_/);
+  assert.deepEqual(messages, [{ type: "client/hello" }]);
+  assert.deepEqual(socket.sent.map((raw) => JSON.parse(raw)), [
+    ["NOTICE", "Invalid JSON"],
+    { type: "host/welcome" }
+  ]);
+  assert.deepEqual(errors, ["socket failed"]);
+  assert.equal(closed, true);
+  assert.equal(conn.open, false);
+});
+
+test("WebSocketRelayConnection rejects oversized messages before dispatch", () => {
+  const socket = new FakeWebSocket();
+  const conn = new WebSocketRelayConnection(socket, { maxMessageBytes: 16 });
+  const messages = [];
+  conn.on("data", (message) => messages.push(message));
+
+  socket.emit("message", Buffer.from('{"type":"client/hello","padding":"too-large"}'));
+
+  assert.deepEqual(messages, []);
+  assert.deepEqual(socket.sent.map((raw) => JSON.parse(raw)), [{
+    type: "host.message.error",
+    code: "message-too-large",
+    message: "Host IPC message is too large"
+  }]);
+  assert.equal(socket.closed, true);
+});