@mh-gg/cli 0.1.1-alpha.20260613T085325975Z

package/runtime/host/relayPeerSignals.cjs

@@ -0,0 +1,175 @@
+const { sendMessage } = require("@mh-gg/relay-core");
+
+function clientPeerSignalMessage(message) {
+  const outbound = {
+    type: "client/peer-signal",
+    protocol: 1,
+    roomName: message.roomName,
+    targetClientId: message.targetClientId,
+    targetPeerId: message.targetPeerId,
+    sourceClientId: message.sourceClientId,
+    sourcePeerId: message.sourcePeerId,
+    signal: message.signal,
+    auth: message.auth
+  };
+  if (message.encryptedSignal !== undefined) outbound.encryptedSignal = message.encryptedSignal;
+  return outbound;
+}
+
+function debugPeerSignal(message, details = {}) {
+  if (process.env.MATTERHORN_DEBUG !== "1") return;
+  console.log(`[relay-peer-signal] ${message} ${JSON.stringify(details)}`);
+}
+
+function profileTransferDetails(message) {
+  const signal = message?.signal;
+  if (!signal || (signal.type !== "profile.transfer.chunk" && signal.type !== "profile.transfer.repair-chunk")) return undefined;
+  return {
+    roomName: message.roomName,
+    signalType: signal.type,
+    sourceClientId: message.sourceClientId,
+    targetClientId: message.targetClientId,
+    targetPeerId: message.targetPeerId,
+    sessionId: signal.sessionId,
+    messageId: signal.messageId,
+    payloadKind: signal.payloadKind,
+    chunk: `${Number(signal.index) + 1}/${signal.total}`
+  };
+}
+
+function logProfileTransfer(message, phase) {
+  const details = profileTransferDetails(message);
+  if (!details) return;
+  console.log(`[profile-transfer-relay] ${phase} ${JSON.stringify(details)}`);
+}
+
+function routeUsesRelayConnection(mesh, conn) {
+  return Boolean(
+    (typeof mesh.hasRelayConnection === "function" && mesh.hasRelayConnection(conn))
+    || (typeof mesh.connectionHasRelayMetadata === "function" && mesh.connectionHasRelayMetadata(conn))
+    || conn?.MatterhornRelayAddress
+    || conn?.MatterhornExpectedRelayAddress
+  );
+}
+
+function createRelayPeerSignalRouter({
+  config,
+  clientConnections,
+  mesh,
+  sfu
+}) {
+  function sendPeerSignalToRoute(route, message, originConn) {
+    if (!route?.conn || route.conn.open === false || route.conn === originConn) return false;
+    const routeIsRelay = routeUsesRelayConnection(mesh, route.conn);
+    if (routeIsRelay) {
+      logProfileTransfer(message, "forward-relay-route");
+      debugPeerSignal("forward-relay-route", { roomName: message.roomName, targetClientId: message.targetClientId, peerId: route.peerId });
+      sendMessage(route.conn, {
+        ...message,
+        id: message.id || mesh.nextMessageId("relay.peer-signal")
+      });
+      return true;
+    }
+    if (!routeIsRelay && (clientConnections.get(route.peerId) === route.conn || typeof mesh.hasRelayConnection === "function")) {
+      logProfileTransfer(message, "deliver-client-route");
+      debugPeerSignal("deliver-client-route", { roomName: message.roomName, targetClientId: message.targetClientId, peerId: route.peerId });
+      sendMessage(route.conn, clientPeerSignalMessage(message));
+      return true;
+    }
+    logProfileTransfer(message, "forward-route");
+    debugPeerSignal("forward-route", { roomName: message.roomName, targetClientId: message.targetClientId, peerId: route.peerId, routeIsRelay });
+    sendMessage(route.conn, {
+      ...message,
+      id: message.id || mesh.nextMessageId("relay.peer-signal")
+    });
+    return true;
+  }
+
+  function sendPeerSignalToClient(message, originConn) {
+    if (typeof message.targetPeerId === "string") {
+      const directClient = clientConnections.get(message.targetPeerId);
+      if (directClient && directClient.open !== false && directClient !== originConn) {
+        logProfileTransfer(message, "deliver-target-peer");
+        debugPeerSignal("deliver-target-peer", { roomName: message.roomName, targetClientId: message.targetClientId, targetPeerId: message.targetPeerId });
+        sendMessage(directClient, clientPeerSignalMessage(message));
+        return true;
+      }
+    }
+
+    const latestRoute = mesh.latestClientRoute(message.roomName, message.targetClientId);
+    if (sendPeerSignalToRoute(latestRoute, message, originConn)) return true;
+
+    if (typeof message.targetPeerId === "string") {
+      const relayConn = mesh.remoteClientRoute(message.targetPeerId);
+      if (relayConn && relayConn !== originConn && relayConn.open !== false) {
+        logProfileTransfer(message, "forward-remote-peer");
+        sendMessage(relayConn, {
+          ...message,
+          id: message.id || mesh.nextMessageId("relay.peer-signal")
+        });
+        debugPeerSignal("forward-remote-peer", { roomName: message.roomName, targetClientId: message.targetClientId, targetPeerId: message.targetPeerId });
+        return true;
+      }
+      if (mesh.sendPeerSignalToDiscoveredRoute(message.targetPeerId, message, originConn)) return true;
+    }
+
+    return false;
+  }
+
+  function routePeerSignalMessage(conn, message) {
+    const roomName = typeof message.roomName === "string" ? message.roomName : undefined;
+    const sourceClientId = conn.MatterhornClientId || (typeof message.clientId === "string" ? message.clientId : undefined);
+    const targetClientId = typeof message.targetClientId === "string" ? message.targetClientId : undefined;
+    const targetPeerId = typeof message.targetPeerId === "string" ? message.targetPeerId : undefined;
+    if (!roomName || !sourceClientId || (!targetClientId && !targetPeerId)) return;
+
+    const sourcePeerId = mesh.scopedPeerId(conn);
+    clientConnections.set(sourcePeerId, conn);
+    mesh.rememberClientRoute(conn, roomName, sourceClientId, sourcePeerId);
+    if (targetClientId === `sfu:${config.sfuPeerId}`) {
+      if (message.encryptedSignal) return;
+      if (sfu.handleSignal({
+        roomName,
+        sourceClientId,
+        signal: message.signal,
+        auth: message.auth
+      })) return;
+    }
+
+    const envelope = {
+      type: "relay.peer-signal",
+      roomName,
+      sourceClientId,
+      sourcePeerId,
+      targetClientId,
+      targetPeerId,
+      signal: message.signal,
+      auth: message.auth
+    };
+    if (message.encryptedSignal !== undefined) envelope.encryptedSignal = message.encryptedSignal;
+
+    if (sendPeerSignalToClient(envelope, conn)) return;
+    const sent = mesh.sendEnvelope(envelope, conn);
+    logProfileTransfer(envelope, `broadcast-envelope:${sent}`);
+    debugPeerSignal("broadcast-envelope", { roomName, sourceClientId, targetClientId, targetPeerId, sent });
+    if (sent > 0 || conn.open === false) return;
+    logProfileTransfer(envelope, "peer-unavailable");
+    sendMessage(conn, {
+      type: "client/peer-signal.error",
+      protocol: 1,
+      roomName,
+      code: "peer-unavailable",
+      message: "The target peer is not connected."
+    });
+  }
+
+  return {
+    routePeerSignalMessage,
+    sendPeerSignalToClient
+  };
+}
+
+module.exports = {
+  clientPeerSignalMessage,
+  createRelayPeerSignalRouter
+};

package/runtime/host/relayRoomRuntimePersistence.cjs

@@ -0,0 +1,129 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function runtimeDirectory(storagePath) {
+  return path.join(storagePath, "room-runtime");
+}
+
+function roomRuntimeFile(storagePath, roomName) {
+  if (typeof roomName !== "string" || !roomName) throw new Error("roomName is required");
+  return path.join(runtimeDirectory(storagePath), `${encodeURIComponent(roomName)}.json`);
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function writeJsonFileAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmpPath, filePath);
+}
+
+function loadRelayRoomRuntimeSnapshot(storagePath, roomName) {
+  if (!storagePath || !roomName) return undefined;
+  const record = readJsonFile(roomRuntimeFile(storagePath, roomName));
+  if (!record || record.schemaVersion !== 1 || record.roomName !== roomName) return undefined;
+  return {
+    schemaVersion: 1,
+    roomName,
+    savedAt: Number.isFinite(record.savedAt) ? record.savedAt : 0,
+    state: clone(record.state),
+    operations: Array.isArray(record.operations) ? record.operations.map(clone) : []
+  };
+}
+
+function createRelayRoomRuntimePersistence({ storagePath, roomName, initialState = null, initialOperations = [] } = {}) {
+  if (!storagePath) throw new Error("storagePath is required");
+  if (!roomName) throw new Error("roomName is required");
+
+  const filePath = roomRuntimeFile(storagePath, roomName);
+  let state = clone(initialState);
+  let operations = Array.isArray(initialOperations) ? initialOperations.map(clone) : [];
+
+  function persist() {
+    writeJsonFileAtomic(filePath, {
+      schemaVersion: 1,
+      roomName,
+      savedAt: Date.now(),
+      state: clone(state),
+      operations: operations.map(clone)
+    });
+  }
+
+  const store = {
+    async load() {
+      return clone(state);
+    },
+    async save(nextState) {
+      state = clone(nextState);
+      persist();
+    },
+    async commitStateAndOperation({ operation, nextState, expectedPreviousVersion }) {
+      if (operation?.id && operations.some((entry) => entry?.id === operation.id)) throw new Error(`Duplicate operation id ${operation.id}`);
+      if (Number.isInteger(expectedPreviousVersion)) {
+        const currentVersion = Number.isInteger(state?.version) ? state.version : 0;
+        if (currentVersion !== expectedPreviousVersion) throw new Error(`Expected previous room version ${expectedPreviousVersion}, found ${currentVersion}`);
+        if (nextState?.version !== expectedPreviousVersion + 1) throw new Error("Next room state version must advance by one");
+      }
+      state = clone(nextState);
+      operations.push(clone(operation));
+      persist();
+    }
+  };
+
+  const operationLog = {
+    entries: operations,
+    async append(operation) {
+      if (operation?.id && operations.some((entry) => entry?.id === operation.id)) throw new Error(`Duplicate operation id ${operation.id}`);
+      operations.push(clone(operation));
+      persist();
+    },
+    async removeById(operationId) {
+      const index = operations.findIndex((entry) => entry?.id === operationId);
+      if (index < 0) return false;
+      operations.splice(index, 1);
+      persist();
+      return true;
+    },
+    async list() {
+      return operations.map(clone);
+    },
+    async findById(operationId) {
+      const found = operations.find((entry) => entry?.id === operationId || entry?.clientOperationId === operationId);
+      return found ? clone(found) : null;
+    },
+    async persist() {
+      persist();
+    }
+  };
+
+  return {
+    filePath,
+    store,
+    operationLog,
+    persist,
+    snapshot() {
+      return {
+        state: clone(state),
+        operations: operations.map(clone)
+      };
+    }
+  };
+}
+
+module.exports = {
+  createRelayRoomRuntimePersistence,
+  loadRelayRoomRuntimeSnapshot,
+  roomRuntimeFile
+};

package/runtime/host/relayStatus.cjs

@@ -0,0 +1,160 @@
+function relayPeerStatus(peer, peerId, startPeer) {
+  return {
+    peerId,
+    state: !startPeer ? "disabled" : peer?.open ? "online" : "offline"
+  };
+}
+
+function relayStorageStatus(config, storage, relayStats) {
+  const name = storage?.constructor?.name;
+  return {
+    backend: name === "SqliteRelayStorage" ? "sqlite" : name ? "custom" : "memory",
+    ok: true,
+    events: relayStats.events,
+    quotas: {
+      maxEvents: config.maxEvents,
+      maxEventsPerRoom: config.maxEventsPerRoom,
+      maxBytesPerRoom: config.maxBytesPerRoom,
+      maxEventsPerPubkeyWindow: config.maxEventsPerPubkeyWindow,
+      pubkeyQuotaWindowSeconds: config.pubkeyQuotaWindowSeconds
+    }
+  };
+}
+
+function relaySfuOperationalStatus(config, sfuStats) {
+  return {
+    state: !config.sfuEnabled ? "disabled" : sfuStats.open ? "available" : "offline",
+    enabled: sfuStats.enabled,
+    participants: sfuStats.participants,
+    maxParticipants: sfuStats.maxParticipants
+  };
+}
+
+function relayClaims(config, includeKnownRelays = true) {
+  const claims = [];
+  if (config.relayClaim) claims.push(config.relayClaim);
+  if (includeKnownRelays && typeof config.relayTrustStore?.claims === "function") {
+    claims.push(...config.relayTrustStore.claims());
+  }
+  return claims;
+}
+
+function createRelayStatus(deps) {
+  const {
+    config,
+    startedAt,
+    storage,
+    mesh,
+    relay,
+    sfu,
+    peerReconnects,
+    clientConnections,
+    hostConnections,
+    roomPeer,
+    relayPeer
+  } = deps;
+
+  function relayLoad() {
+    const meshStats = mesh.stats();
+    return {
+      clients: clientConnections.size,
+      roomHosts: hostConnections.size,
+      relayConnections: meshStats.relayConnections,
+      knownRelays: meshStats.knownRelays,
+      icedRelays: meshStats.icedRelays,
+      activeRelayFanout: meshStats.activeRelayFanout,
+      relayHealth: meshStats.relayHealth || [],
+      sfu: sfu.stats(),
+      peerReconnects: peerReconnects.summary(),
+      discovery: meshStats.discovery
+    };
+  }
+
+  function operationalStatus() {
+    const meshStats = mesh.stats();
+    const relayStats = relay.stats();
+    return {
+      uptimeSeconds: Math.floor((Date.now() - startedAt) / 1000),
+      roomPeer: relayPeerStatus(roomPeer(), config.relayPeerId, config.startPeer),
+      meshPeer: relayPeerStatus(relayPeer(), config.relayMeshPeerId, config.startPeer),
+      host: {
+        state: hostConnections.size > 0 ? "online" : "offline",
+        registered: hostConnections.size
+      },
+      clients: {
+        connected: clientConnections.size
+      },
+      relays: {
+        connected: meshStats.relayConnections,
+        known: meshStats.knownRelays,
+        iced: meshStats.icedRelays,
+        health: meshStats.relayHealth || []
+      },
+      storage: relayStorageStatus(config, storage, relayStats),
+      sfu: relaySfuOperationalStatus(config, sfu.stats())
+    };
+  }
+
+  function relayStatusMessage(requestId, options = {}) {
+    const includeKnownRelays = options.includeKnownRelays !== false;
+    return {
+      type: "relay.status.ok",
+      requestId,
+      relayAddress: config.relayAddress,
+      roomPeerId: config.relayPeerId,
+      relayMeshPeerId: config.relayMeshPeerId,
+      relayClaim: config.relayClaim,
+      relayClaims: relayClaims(config, includeKnownRelays),
+      relayHints: includeKnownRelays ? mesh.relayHints() : [config.relayAddress],
+      icedRelayHints: includeKnownRelays ? mesh.icedRelayHints() : [],
+      relayHealth: includeKnownRelays ? mesh.relayHealth() : mesh.relayHealth().filter((item) => item.local),
+      sfu: sfu.status(),
+      health: operationalStatus(),
+      load: relayLoad()
+    };
+  }
+
+  function healthDocument() {
+    const status = operationalStatus();
+    return {
+      ok: true,
+      protocol: "matterhorn-peer-relay",
+      version: 1,
+      uptimeSeconds: status.uptimeSeconds,
+      relayPeerId: config.relayPeerId,
+      relayMeshPeerId: config.relayMeshPeerId,
+      relayAddress: config.relayAddress,
+      relayClaim: config.relayClaim,
+      relayClaims: relayClaims(config),
+      peerJsSignaling: config.peerJsSignaling,
+      roomPeerOpen: !config.startPeer || Boolean(roomPeer()?.open),
+      relayMeshPeerOpen: !config.startPeer || Boolean(relayPeer()?.open),
+      roomHosts: hostConnections.size,
+      clients: clientConnections.size,
+      knownRelays: mesh.stats().knownRelays,
+      icedRelays: mesh.stats().icedRelays,
+      relayHints: mesh.relayHints(),
+      icedRelayHints: mesh.icedRelayHints(),
+      relayHealth: mesh.relayHealth(),
+      sfu: sfu.status(),
+      relayLoad: relayLoad(),
+      status,
+      ...relay.stats()
+    };
+  }
+
+  return {
+    healthDocument,
+    operationalStatus,
+    relayLoad,
+    relayStatusMessage
+  };
+}
+
+module.exports = {
+  createRelayStatus,
+  relayPeerStatus,
+  relayClaims,
+  relaySfuOperationalStatus,
+  relayStorageStatus
+};