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

package/runtime/host/relayMeshEnvelopes.cjs

@@ -0,0 +1,522 @@
+const { PROTOCOL } = require("@mh-gg/host-config");
+const { sendMessage } = require("@mh-gg/relay-core");
+const { validateRelayEnvelope } = require("./wireValidation/index.cjs");
+const crypto = require("node:crypto");
+const { unwrapVapidGrant, vapidPublicKeyFromPrivateKey } = require("@mh-gg/push");
+
+function sendInvalidRelayEnvelope(conn, validation) {
+  sendMessage(conn, {
+    type: "relay.error",
+    code: validation.code,
+    message: validation.message
+  });
+}
+
+function createRelayMeshEnvelopeHandler({
+  clientConnections,
+  clientRooms,
+  hostConnections,
+  mesh,
+  peerSignals,
+  relayPluginRuntimes,
+  encryptedRoomRuntimes,
+  relayStatus,
+  broadcastToRoom,
+  rememberPersonalStateFromHostMessage = () => {},
+  personalStateHostMessageForRoom = () => undefined,
+  pushStorage,
+  pushEgress,
+  eventStorage,
+  config
+}) {
+  function sendRelayHost(conn, peerId, roomName, message) {
+    sendMessage(conn, {
+      type: "relay.host",
+      id: mesh.nextMessageId("relay.host"),
+      roomName,
+      peerId,
+      message
+    });
+  }
+
+  function pendingPushTtlSeconds(message) {
+    return Number.isInteger(message?.ttlSeconds) && message.ttlSeconds > 0 ? message.ttlSeconds : 60 * 60;
+  }
+
+  function persistPendingPush(message, reason) {
+    const pushId = message?.pushId || message?.id;
+    const userId = message?.target?.userId;
+    if (!pushStorage?.upsertPendingPush || !pushId || !userId) return false;
+    pushStorage.upsertPendingPush({
+      pushId,
+      userId,
+      payload: message,
+      ttlSeconds: pendingPushTtlSeconds(message)
+    });
+    if (process.env.MATTERHORN_DEBUG === "1") console.log(`matterhorn relay debug: push pending ${pushId} ${reason || "deferred"}`);
+    return true;
+  }
+
+  function sendPushAck(conn, message, status = "accepted") {
+    if (!conn || !message?.pushId) return;
+    sendMessage(conn, {
+      type: "relay.push.ack",
+      id: mesh.nextMessageId("relay.push.ack"),
+      pushId: message.pushId,
+      status
+    });
+  }
+
+  function off(conn, event, listener) {
+    if (typeof conn.off === "function") conn.off(event, listener);
+    else if (typeof conn.removeListener === "function") conn.removeListener(event, listener);
+  }
+
+  function sendPushWithAck(targetConn, message, timeoutMs = 500) {
+    return new Promise((resolve) => {
+      let timer;
+      let done = false;
+      const finish = (ok) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        off(targetConn, "data", onData);
+        off(targetConn, "close", onClose);
+        off(targetConn, "error", onError);
+        resolve(ok);
+      };
+      const onData = (incoming) => {
+        if (incoming?.type === "relay.push.ack" && incoming.pushId === message.pushId) finish(true);
+      };
+      const onClose = () => finish(false);
+      const onError = () => finish(false);
+      timer = setTimeout(() => finish(false), timeoutMs);
+      targetConn.on("data", onData);
+      targetConn.on("close", onClose);
+      targetConn.on("error", onError);
+      try {
+        sendMessage(targetConn, message);
+      } catch {
+        finish(false);
+      }
+    });
+  }
+
+  function sendHostUnavailable(conn, peerId, roomName) {
+    sendRelayHost(conn, peerId, roomName, {
+      type: "host/error",
+      protocol: PROTOCOL,
+      code: "host-unavailable",
+      message: "The room runtime is not connected to this relay."
+    });
+  }
+
+  function roomInfoMessage(roomName) {
+    const roomApp = relayPluginRuntimes?.roomApp?.(roomName);
+    if (!roomApp) return undefined;
+    const status = relayStatus.relayStatusMessage(undefined);
+    const runtimeCapabilities = relayPluginRuntimes?.runtimeCapabilities?.(roomName);
+    return {
+      type: "room.info",
+      protocol: PROTOCOL,
+      roomName,
+      roomApp,
+      relayHints: status.relayHints || [],
+      icedRelayHints: status.icedRelayHints || [],
+      relayClaim: status.relayClaim,
+      relayClaims: status.relayClaims || [],
+      relayHealth: status.relayHealth || [],
+      ...(runtimeCapabilities ? { runtimeCapabilities } : {}),
+      sfu: status.sfu
+    };
+  }
+
+  function relayHintMessage(roomName) {
+    const status = relayStatus.relayStatusMessage(undefined);
+    const roomApp = relayPluginRuntimes?.roomApp?.(roomName);
+    const runtimeCapabilities = relayPluginRuntimes?.runtimeCapabilities?.(roomName);
+    const message = {
+      type: "relay.hints",
+      roomName,
+      relayHints: status.relayHints || [],
+      icedRelayHints: status.icedRelayHints || [],
+      relayClaim: status.relayClaim,
+      relayClaims: status.relayClaims || [],
+      relayHealth: status.relayHealth || [],
+      sfu: status.sfu
+    };
+    if (roomApp) message.roomApp = roomApp;
+    if (runtimeCapabilities) message.runtimeCapabilities = runtimeCapabilities;
+    return message;
+  }
+
+  function forwardFrontendRequest(conn, envelope) {
+    const host = hostConnections.get(envelope.roomName);
+    if (host) {
+      sendMessage(host, {
+        type: "relay/client-message",
+        peerId: envelope.peerId,
+        message: envelope.message
+      });
+      return true;
+    }
+    return mesh.sendEnvelope(envelope, conn, { alreadyRemembered: true }) > 0;
+  }
+
+  function sendSnapshot(conn, peerId, roomName) {
+    if (!relayPluginRuntimes?.hasRoom?.(roomName)) return false;
+    void relayPluginRuntimes.snapshot(roomName).then((snapshot) => {
+      if (!snapshot) {
+        sendHostUnavailable(conn, peerId, roomName);
+        return;
+      }
+      sendRelayHost(conn, peerId, roomName, {
+        type: "host/matterhorn-state",
+        protocol: PROTOCOL,
+        roomName,
+        state: snapshot.state
+      });
+    }).catch((error) => {
+      sendRelayHost(conn, peerId, roomName, {
+        type: "host/error",
+        protocol: PROTOCOL,
+        code: "matterhorn-state-unavailable",
+        message: error?.message || "Matterhorn state is unavailable."
+      });
+    });
+    return true;
+  }
+
+  function handleRuntimeOperation(conn, envelope) {
+    if (!relayPluginRuntimes?.hasRoom?.(envelope.roomName)) return false;
+    void relayPluginRuntimes.handleClientOperation({
+      roomName: envelope.roomName,
+      peerId: envelope.peerId,
+      message: envelope.message,
+      sendToClient: (peerId, message, roomName) => sendRelayHost(conn, peerId, roomName || envelope.roomName, message),
+      broadcastToRoom,
+      broadcastToMesh: (message) => mesh.sendEnvelope(message, conn)
+    }).catch((error) => {
+      sendRelayHost(conn, envelope.peerId, envelope.roomName, {
+        type: "host/error",
+        protocol: PROTOCOL,
+        code: "operation-runtime-error",
+        message: error?.message || "Relay operation runtime failed."
+      });
+    });
+    return true;
+  }
+
+  function roomIndexSearchResultsMessage(roomName, request, result) {
+    return {
+      type: "host/room-index-search-results",
+      protocol: PROTOCOL,
+      roomName,
+      clientId: request.clientId,
+      requestId: request.requestId,
+      suite: request.suite,
+      keyId: request.keyId,
+      stream: request.stream,
+      mode: request.mode || "all",
+      events: Array.isArray(result?.events) ? result.events : [],
+      matches: Array.isArray(result?.matches) ? result.matches : [],
+      total: Number.isInteger(result?.total) ? result.total : 0,
+      queryTokenCount: Number.isInteger(result?.queryTokenCount) ? result.queryTokenCount : 0
+    };
+  }
+
+  function handleRoomIndexSearch(conn, envelope) {
+    const runtime = encryptedRoomRuntimes?.getRoom?.(envelope.roomName);
+    if (!runtime || typeof runtime.searchNgrams !== "function") return false;
+    const msg = envelope.message || {};
+    const result = runtime.searchNgrams({
+      suite: msg.suite,
+      keyId: msg.keyId,
+      tokens: msg.tokens,
+      stream: msg.stream,
+      mode: msg.mode,
+      minScore: msg.minScore,
+      limit: msg.limit,
+      offset: msg.offset,
+      order: msg.order
+    });
+    sendRelayHost(conn, envelope.peerId, envelope.roomName, roomIndexSearchResultsMessage(envelope.roomName, msg, result));
+    return true;
+  }
+
+  function handleRelayClient(conn, message) {
+    if (typeof message.peerId !== "string" || typeof message.roomName !== "string") return;
+    mesh.rememberRemoteClientRoute(message.peerId, conn);
+    mesh.rememberClientRoute(conn, message.roomName, message.message?.clientId, message.peerId);
+
+    switch (message.message?.type) {
+      case "client/hello": {
+        sendRelayHost(conn, message.peerId, message.roomName, relayHintMessage(message.roomName));
+        if (relayPluginRuntimes?.hasRoom?.(message.roomName)) return;
+        const host = hostConnections.get(message.roomName);
+        if (host) {
+          sendMessage(host, {
+            type: "relay/client-message",
+            peerId: message.peerId,
+            message: message.message
+          });
+          return;
+        }
+        break;
+      }
+      case "client/room-info": {
+        const info = roomInfoMessage(message.roomName);
+        if (info) {
+          sendRelayHost(conn, message.peerId, message.roomName, info);
+          return;
+        }
+        break;
+      }
+      case "client/matterhorn-state":
+      case "client/snapshot-request":
+        if (sendSnapshot(conn, message.peerId, message.roomName)) return;
+        break;
+      case "client/operation":
+        if (handleRuntimeOperation(conn, message)) return;
+        break;
+      case "client/room-index-search":
+        if (handleRoomIndexSearch(conn, message)) return;
+        break;
+      case "client/personal-state":
+        if (message.message.action === "subscribe") {
+          sendRelayHost(conn, message.peerId, message.roomName, relayHintMessage(message.roomName));
+          const cached = personalStateHostMessageForRoom(message.roomName);
+          if (cached) sendRelayHost(conn, message.peerId, message.roomName, cached);
+        }
+        break;
+      case "client/frontend-manifest":
+      case "client/frontend-chunk":
+        if (forwardFrontendRequest(conn, message)) return;
+        break;
+      case "client/push-grant": {
+        const msg = message.message;
+        const isTargetLocal = (msg.relayId === config?.relayPeerId || msg.relayId === config?.relayMeshPeerId);
+        if (isTargetLocal) {
+          try {
+            // X25519 grant key, not the Ed25519 identity key (see relayClientRouting).
+            const relayPrivateKey = crypto.createPrivateKey(config.relayIdentity.grantPrivateKeyPem);
+            const { vapidPrivateKey } = unwrapVapidGrant({
+              grant: msg.grant,
+              relayPrivateKey
+            });
+            const vapidPublicKey = vapidPublicKeyFromPrivateKey(vapidPrivateKey);
+            pushStorage?.upsertGrant({
+              userId: msg.userId,
+              vapidPrivateKey,
+              vapidPublicKey
+            });
+            sendRelayHost(conn, message.peerId, message.roomName, {
+              type: "client/push-grant.ok",
+              protocol: PROTOCOL
+            });
+          } catch (err) {
+            if (process.env.MATTERHORN_DEBUG === "1") {
+              console.error("Failed to unwrap VAPID grant from relay.client envelope:", err);
+            }
+            sendRelayHost(conn, message.peerId, message.roomName, {
+              type: "client/push-grant.error",
+              protocol: PROTOCOL,
+              code: "grant-unwrap-failed",
+              message: err?.message || "Failed to unwrap push grant."
+            });
+          }
+        } else {
+          sendRelayHost(conn, message.peerId, message.roomName, {
+            type: "client/push-grant.ok",
+            protocol: PROTOCOL
+          });
+        }
+        return;
+      }
+      case "client/push-register": {
+        const msg = message.message;
+        pushStorage?.upsertSubscription({
+          userId: msg.userId,
+          deviceId: msg.clientId,
+          subscription: msg.subscription
+        });
+        const grant = pushStorage?.selectGrant(msg.userId);
+        sendRelayHost(conn, message.peerId, message.roomName, {
+          type: "client/push-register.ok",
+          protocol: PROTOCOL,
+          hasGrant: Boolean(grant)
+        });
+        return;
+      }
+      default:
+        break;
+    }
+
+    if (mesh.sendEnvelope(message, conn, { alreadyRemembered: true }) === 0) {
+      sendHostUnavailable(conn, message.peerId, message.roomName);
+    }
+  }
+
+  function handleRelayHost(conn, message) {
+    if (typeof message.peerId !== "string") return;
+    const client = clientConnections.get(message.peerId);
+    if (client) {
+      sendMessage(client, message.message);
+      return;
+    }
+    if (mesh.sendDiscoveredClientRoute(message.peerId, message.message, conn, message.roomName)) return;
+    const relayConn = mesh.remoteClientRoute(message.peerId);
+    if (relayConn && relayConn !== conn) {
+      sendMessage(relayConn, message);
+      return;
+    }
+    mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+  }
+
+  function handleRelayEnvelope(conn, message) {
+    if (process.env.MATTERHORN_DEBUG === "1" && message?.type === "relay.peer-signal") {
+      console.log(`[relay-peer-signal] mesh-envelope-recv ${JSON.stringify({ roomName: message.roomName, sourceClientId: message.sourceClientId, targetClientId: message.targetClientId, hasId: Boolean(message.id) })}`);
+    }
+    const validation = validateRelayEnvelope(message);
+    if (!validation.ok) {
+      if (process.env.MATTERHORN_DEBUG === "1" && message?.type === "relay.peer-signal") {
+        console.log(`[relay-peer-signal] mesh-envelope-invalid ${JSON.stringify({ message: validation.message })}`);
+      }
+      sendInvalidRelayEnvelope(conn, validation);
+      return;
+    }
+    mesh.recordRelayLiveness?.(conn, message.relayAddress);
+
+    if (message.type === "relay.ping") {
+      mesh.sendPong?.(conn, message);
+      return;
+    }
+    if (message.type === "relay.pong") return;
+
+    if (!mesh.rememberMessage(message.id)) return;
+
+    switch (message.type) {
+      case "relay.status":
+        sendMessage(conn, relayStatus.relayStatusMessage(message.requestId));
+        return;
+      case "relay.client":
+        handleRelayClient(conn, message);
+        return;
+      case "relay.host":
+        handleRelayHost(conn, message);
+        return;
+      case "relay.peer-signal": {
+        if (typeof message.roomName !== "string") return;
+        if (typeof message.sourcePeerId === "string") mesh.rememberRemoteClientRoute(message.sourcePeerId, conn);
+        mesh.rememberClientRoute(conn, message.roomName, message.sourceClientId, message.sourcePeerId);
+        if (peerSignals.sendPeerSignalToClient(message, conn)) return;
+        mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+        return;
+      }
+      case "relay.matterhorn-operation":
+        if (typeof message.roomName !== "string") return;
+        void relayPluginRuntimes?.handleRelayOperation?.(message).catch((error) => {
+          sendMessage(conn, { type: "relay.error", code: "matterhorn-operation-failed", message: error?.message || "Relay Matterhorn operation failed" });
+        });
+        mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+        return;
+      case "relay.broadcast":
+        if (typeof message.roomName !== "string") return;
+        rememberPersonalStateFromHostMessage(message.roomName, message.message);
+        broadcastToRoom(message.roomName, message.message);
+        mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+        return;
+      case "relay.client.close": {
+        if (typeof message.peerId !== "string") return;
+        mesh.forgetRemoteClientRoute(message.peerId);
+        const client = clientConnections.get(message.peerId);
+        if (client) {
+          client.close?.();
+          return;
+        }
+        mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+        return;
+      }
+      case "relay.push": {
+        const userId = message.target?.userId;
+        if (!userId) return;
+        const grant = pushStorage?.selectGrant(userId);
+        if (grant) {
+          pushEgress?.sendRelayPush(message).then((result) => {
+            if (result?.delivered > 0) {
+              pushStorage?.deletePendingPush?.(message.pushId);
+              sendPushAck(conn, message, "delivered");
+              return;
+            }
+            if (persistPendingPush(message, result?.reason || "local-egress-deferred")) sendPushAck(conn, message);
+          }).catch((err) => {
+            if (process.env.MATTERHORN_DEBUG === "1") console.error(`Failed to send web push egress for user ${userId}:`, err);
+            if (persistPendingPush(message, "local-egress-error")) sendPushAck(conn, message);
+          });
+          return;
+        }
+        const events = eventStorage ? eventStorage.queryEvents([{ kinds: [9002] }]) : [];
+        let latestPayload = null;
+        for (const event of events) {
+          try {
+            const content = JSON.parse(event.content || "{}");
+            const payload = content.payload;
+            if (payload && payload.userId === userId) {
+              if (!latestPayload || payload.updatedAt > latestPayload.updatedAt) {
+                latestPayload = payload;
+              }
+            }
+          } catch {}
+        }
+        if (latestPayload && Array.isArray(latestPayload.relayIds)) {
+          const homeRelayIds = new Set(latestPayload.relayIds);
+          const connections = mesh.connections().filter((c) => {
+            const addr = c.MatterhornRelayAddress || c.MatterhornExpectedRelayAddress;
+            return addr && homeRelayIds.has(addr);
+          });
+          connections.sort((a, b) => {
+            const loadA = (a.MatterhornRelayLoad?.clients || 0) + (a.MatterhornRelayLoad?.roomHosts || 0);
+            const loadB = (b.MatterhornRelayLoad?.clients || 0) + (b.MatterhornRelayLoad?.roomHosts || 0);
+            return loadA - loadB;
+          });
+          const tryNext = async () => {
+            if (index >= connections.length) {
+              if (persistPendingPush(message, "forward-unconfirmed")) sendPushAck(conn, message);
+              mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+              return;
+            }
+            const targetConn = connections[index++];
+            if (targetConn.open === false) {
+              await tryNext();
+              return;
+            }
+            if (await sendPushWithAck(targetConn, message)) {
+              sendPushAck(conn, message);
+              return;
+            }
+            await tryNext();
+          };
+          let index = 0;
+          void tryNext();
+        } else {
+          if (persistPendingPush(message, "no-home-relay")) sendPushAck(conn, message);
+          mesh.sendEnvelope(message, conn, { alreadyRemembered: true });
+        }
+        return;
+      }
+      case "relay.push.ack":
+        pushStorage?.deletePendingPush?.(message.pushId);
+        return;
+      default:
+        return;
+    }
+  }
+
+  return {
+    handleRelayEnvelope
+  };
+}
+
+module.exports = {
+  createRelayMeshEnvelopeHandler
+};

package/runtime/host/relayPeerLifecycle.cjs

@@ -0,0 +1,96 @@
+const DEFAULT_PEER_RECONNECT_DEBOUNCE_MS = 1000;
+
+function isTransientPeerError(error) {
+  const type = error?.type;
+  const message = error?.message || "";
+  return type === "network"
+    || type === "peer-unavailable"
+    || type === "webrtc"
+    || message.includes("Lost connection to server")
+    || message.includes("Could not connect to peer");
+}
+
+function unavailablePeerIdFromError(error) {
+  const message = error?.message || "";
+  const match = message.match(/Could not connect to peer ([^\s.]+)/);
+  return match?.[1];
+}
+
+function isUnavailablePeerError(error) {
+  return error?.type === "peer-unavailable" || Boolean(unavailablePeerIdFromError(error));
+}
+
+function transientPeerErrorLabel(error) {
+  const message = error?.message || "";
+  if (error?.type === "network" || message.includes("Lost connection to server")) return "signaling network error";
+  if (message.includes("Could not connect to peer")) return "remote relay peer unavailable";
+  return "transient peer error";
+}
+
+function createRelayPeerLifecycle({
+  debug,
+  isClosing,
+  mesh,
+  peerReconnects,
+  relayPeer,
+  reconnectDebounceMs = DEFAULT_PEER_RECONNECT_DEBOUNCE_MS
+}) {
+  function iceUnavailableRelayPeer(error) {
+    const peerId = unavailablePeerIdFromError(error);
+    if (!peerId) return false;
+    const relayAddress = mesh.iceUnavailablePeer(peerId);
+    if (!relayAddress) return false;
+    debug(`relay peer unavailable; icing ${relayAddress}`);
+    return true;
+  }
+
+  function reconnectPeer(peer, label, reason = "disconnect") {
+    if (isClosing() || !peer || peer.destroyed || typeof peer.reconnect !== "function") return;
+    const peerId = peerReconnects.stablePeerId(peer);
+    if (peer.open && peer.disconnected !== true) {
+      debug(`${label} reconnect skipped after ${reason}; ${peerId} is already open`);
+      return;
+    }
+    const now = Date.now();
+    const lastReconnectAt = peer.MatterhornLastReconnectAt || 0;
+    if (now - lastReconnectAt < reconnectDebounceMs) {
+      debug(`${label} reconnect skipped after ${reason}; ${peerId} already attempted recently`);
+      return;
+    }
+    peer.MatterhornLastReconnectAt = now;
+    peerReconnects.warn(peer, label, reason);
+    try {
+      peer.reconnect();
+    } catch (error) {
+      const message = error?.message || String(error);
+      if (!message.includes("cannot reconnect because it is not disconnected")) {
+        debug(`${label} reconnect failed after ${reason}: ${message}`);
+      }
+    }
+  }
+
+  function handlePeerError(peer, label, error) {
+    if (!isTransientPeerError(error)) {
+      console.error(`${label} error:`, error);
+      return;
+    }
+    const errorLabel = transientPeerErrorLabel(error);
+    debug(`${label} ${errorLabel}: ${error?.message || String(error)}`);
+    if (peer === relayPeer() && isUnavailablePeerError(error)) iceUnavailableRelayPeer(error);
+    if (error?.type === "network") reconnectPeer(peer, label, errorLabel);
+  }
+
+  return {
+    handlePeerError,
+    reconnectPeer
+  };
+}
+
+module.exports = {
+  DEFAULT_PEER_RECONNECT_DEBOUNCE_MS,
+  createRelayPeerLifecycle,
+  isTransientPeerError,
+  isUnavailablePeerError,
+  transientPeerErrorLabel,
+  unavailablePeerIdFromError
+};