mslxdff 0.1.33 → 0.1.34

package/bin/mslxdff.js

@@ -280,14 +280,31 @@ if (groupCmd && groupCmd !== "create") {
       console.log(`${g.name}  (${entries.length} member${entries.length === 1 ? "" : "s"})`);
       // probe every member endpoint concurrently for reachability + latency;
       // display order = state order so the sequence numbers stay stable for -group remove
+      // broadband members (relay://) are not probed — they are reachable via leader
       const probes = await Promise.all(
-        entries.map(([id, m]) => probeHealth({ id, url: m?.url || id }))
+        entries.map(([id, m]) => probeHealth({ id, url: m?.url || id, kind: m?.kind, lastSeen: m?.lastSeen, publicIp: m?.publicIp }))
       );
       const leaderEntry = members.leader ? Object.entries(members).find(([id]) => id === "leader") : null;
       const leaderProbe = leaderEntry ? await probeHealth({ id: "leader", url: leaderEntry[1].url }) : null;
       const display = leaderProbe ? [...probes, leaderProbe] : probes;
       let seq = 0;
       for (const r of display) {
+        const m = entries.find(([eid]) => eid === r.id)?.[1] || (r.id === "leader" ? leaderEntry?.[1] : null);
+        const isBb = r.kind === "broadband" || String(r.url || "").startsWith("relay://") || m?.kind === "broadband";
+        if (isBb) {
+          const ago = r.lastSeen ? `${Math.round((Date.now() - r.lastSeen) / 1000)}s ago` : "no heartbeat yet";
+          const ip = r.publicIp || m?.publicIp || "?";
+          const via = r.stale ? "stale" : `via leader ${ago}`;
+          const stateBb = `${via} ip=${ip}`;
+          if (r.id === "leader") {
+            console.log(`  leader  ${r.url}  ${stateBb}`);
+            continue;
+          }
+          seq += 1;
+          const label = r.id && r.id !== r.url ? `  [${r.id}]` : "";
+          console.log(`  ${seq}. ${r.url}${label}  [broadband] ${stateBb}`);
+          continue;
+        }
         const state = r.fail ? `fail  ${r.fail}` : `ok    ${r.ms}ms`;
         if (r.id === "leader") {
           console.log(`  leader  ${r.url}  ${state}`);
@@ -334,12 +351,15 @@ if (groupCmd && groupCmd !== "create") {
   process.exit(0);
 }
 
-// -addtogroup <leader-host> <name>
+// -addtogroup <leader-host> <name> [--broadband]
 const addToGroupIdx = args.findIndex((x) => x === "-addtogroup" || x === "--addtogroup");
 if (addToGroupIdx >= 0) {
-  const [leaderHost, name] = args.slice(addToGroupIdx + 1);
-  if (!leaderHost || !name) {
-    console.error("usage: mslxdff -addtogroup <leader-host> <name>");
+  const rawArgs = args.slice(addToGroupIdx + 1);
+  const isBroadband = rawArgs.includes("--broadband");
+  const filtered = rawArgs.filter((a) => a !== "--broadband");
+  const [leaderHost, name] = filtered;
+  if (!leaderHost || !name || filtered.length > 2) {
+    console.error("usage: mslxdff -addtogroup <leader-host> <name> [--broadband]");
     process.exit(1);
   }
   const groups = createGroupsService({});
@@ -348,25 +368,34 @@ if (addToGroupIdx >= 0) {
   const leaderUrl = leaderHost.includes("://")
     ? leaderHost.replace(/\/+$/, "")
     : `http://${leaderHost}${leaderHost.includes(":") ? "" : ":8989"}`;
-  const myPort = effectivePort();
+  const kind = isBroadband ? "broadband" : "static";
+  let joinBody;
+  if (isBroadband) {
+    const relayId = `relay://${myToken.slice(0, 8)}`;
+    joinBody = { name, key: name, leaderUrl, url: relayId, token: myToken, kind: "broadband" };
+  } else {
+    const myPort = effectivePort();
+    joinBody = { name, key: name, leaderUrl, myPort, token: myToken, kind: "static" };
+  }
   try {
     const res = await fetch(`${leaderUrl}/v1/groups/join`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name, key: name, leaderUrl, myPort, token: myToken }),
+      body: JSON.stringify(joinBody),
     });
     if (!res.ok) {
       const text = await res.text().catch(() => "");
       throw new Error(`join failed (HTTP ${res.status}): ${text}`);
     }
     const data = await res.json();
-    const myUrl = data.you?.url || "";
-    markJoined({ name, leaderUrl, myUrl, memberName: myUrl });
+    const myUrl = data.you?.url || joinBody.url || "";
+    const memberName = isBroadband ? myUrl : myUrl;
+    markJoined({ name, leaderUrl, myUrl, memberName, kind });
     const synced = await syncAllJoinedGroups({ peers, groups });
     const s = synced.find((x) => x.name === name);
-    console.log(`joined group "${name}" at ${leaderUrl}`);
+    console.log(`joined group "${name}" at ${leaderUrl}${isBroadband ? " [broadband]" : ""}`);
     if (s?.error) console.log(`  local failover setup failed: ${s.error}`);
-    else console.log(`  ${s?.added ?? 0} failover target(s) configured`);
+    else console.log(`  ${s?.added ?? 0} failover target(s) configured${isBroadband ? " (broadband via leader, local 127.0.0.1)" : ""}`);
   } catch (err) {
     console.error(`join failed: ${err.message}`);
     process.exit(1);
@@ -386,6 +415,7 @@ if (resetBanArg !== null || args.includes("-resetban") || args.includes("--reset
 
 function markJoined(entry) {
   const { name } = entry;
+  if (!entry.kind) entry.kind = "static";
   const list = loadGroupsJoined().filter((g) => g.name !== name);
   saveGroupsJoined([...list, entry]);
 }
@@ -464,8 +494,15 @@ function errMsg(err) { return String(err?.message || err); }
 
 // Probe a member's health endpoint concurrently (v1/health preferred,
 // falling back to /health). Returns { id, url, ms, rank } or { id, url, fail }.
-async function probeHealth({ id, url } = {}) {
+// broadband relay:// members are not probed — they are reachable via leader relay.
+async function probeHealth({ id, url, kind, lastSeen, publicIp } = {}) {
   if (!url) return { id, url, fail: "no url", rank: 3 };
+  const isBb = kind === "broadband" || String(url).startsWith("relay://");
+  if (isBb) {
+    const staleMs = Number(process.env.MSLXDFF_BROADBAND_STALE_MS) > 0 ? Number(process.env.MSLXDFF_BROADBAND_STALE_MS) : 90_000;
+    const stale = typeof lastSeen === "number" ? Date.now() - lastSeen > staleMs : true;
+    return { id, url, kind: "broadband", lastSeen, publicIp, stale, rank: stale ? 2 : 0 };
+  }
   const base = String(url).replace(/\/+$/, "");
   const startedAt = Date.now();
   try {
@@ -500,6 +537,7 @@ async function syncAllJoinedGroups({ peers, groups }) {
           memberName: g.memberName,
           url: g.myUrl,
           token: myToken,
+          kind: g.kind,
         });
         results.push({
           name: g.name,
@@ -626,7 +664,8 @@ const bans = createBansService({ windowMs: banWindowMs(), threshold: banThreshol
 const isDebug = process.env.MSLXDFF_DEBUG === "1";
 const bus = createEventBus();
 const router = createRouter({ token, upstream, models, auto, logs, peers, maxHops: maxHopsValue(), groups, bans, bus });
-const srv = startServer({ router, signals: !isDebug });
+const listenHost = effectiveHost();
+const srv = startServer({ router, signals: !isDebug, host: listenHost });
 
 // -debug: push every event straight to this terminal.
 if (isDebug) {
@@ -687,6 +726,83 @@ const groupSyncTimer = setInterval(() => {
 }, groupSyncIntervalMs());
 groupSyncTimer.unref();
 
+// Broadband heartbeat + relay poll (only for broadband members)
+const broadbandGroups = () => loadGroupsJoined().filter((g) => g.kind === "broadband" && g.leaderUrl);
+if (broadbandGroups().length) {
+  const doHeartbeat = async () => {
+    for (const g of broadbandGroups()) {
+      try {
+        const res = await fetch(`${g.leaderUrl}/v1/groups/relay/heartbeat`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
+          body: JSON.stringify({ name: g.name, group: g.name }),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+          const txt = await res.text().catch(() => "");
+          console.log(`broadband heartbeat ${g.name}: ${res.status} ${txt.slice(0, 100)}`);
+        }
+      } catch (err) {
+        console.log(`broadband heartbeat ${g.name}: failed — ${errMsg(err)}`);
+      }
+    }
+  };
+  const doPoll = async () => {
+    for (const g of broadbandGroups()) {
+      try {
+        const pollRes = await fetch(`${g.leaderUrl}/v1/groups/relay/poll`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
+          body: JSON.stringify({ name: g.name, group: g.name }),
+          signal: AbortSignal.timeout(8000),
+        });
+        if (!pollRes.ok) continue;
+        const data = await pollRes.json().catch(() => ({}));
+        const items = data.data || [];
+        for (const item of items) {
+          const { reqId, body } = item;
+          let result;
+          try {
+            const upRes = await upstream.chat(body);
+            const ct = upRes.headers.get("content-type") || "";
+            const isStream = Boolean(body?.stream) || ct.includes("text/event-stream");
+            if (isStream && upRes.body) {
+              // collect stream chunks for relay (simplified: buffer then forward as SSE)
+              let collected = "";
+              for await (const chunk of upRes.body) {
+                collected += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+              }
+              result = { status: upRes.status, headers: { "Content-Type": "text/event-stream" }, body: collected };
+            } else {
+              const txt = await upRes.text();
+              let parsed;
+              try { parsed = JSON.parse(txt); } catch { parsed = txt; }
+              result = { status: upRes.status, headers: { "Content-Type": upRes.headers.get("content-type") || "application/json" }, body: typeof parsed === "string" ? parsed : JSON.stringify(parsed) };
+            }
+          } catch (err) {
+            result = { status: 502, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ error: errMsg(err) }) };
+          }
+          try {
+            await fetch(`${g.leaderUrl}/v1/groups/relay/result`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
+              body: JSON.stringify({ name: g.name, group: g.name, reqId, result }),
+              signal: AbortSignal.timeout(5000),
+            });
+          } catch {}
+        }
+      } catch {}
+    }
+  };
+  // initial heartbeat
+  doHeartbeat().catch(() => {});
+  const hbTimer = setInterval(doHeartbeat, 30_000);
+  hbTimer.unref();
+  const pollTimer = setInterval(doPoll, 1000);
+  pollTimer.unref();
+  console.log(`broadband relay: heartbeat 30s + poll 1s for ${broadbandGroups().length} group(s)`);
+}
+
 // Auto-update: periodically check npm for a newer mslxdff and restart.
 // Enable with MSLXDFF_AUTO_UPDATE=1 (hourly) or MSLXDFF_AUTO_UPDATE_MS=<ms>.
 // Uses the same npm view/install path as `mslxdff -update`, but runs inside
@@ -743,6 +859,16 @@ function effectivePort() {
   return resolvePort();
 }
 
+function effectiveHost() {
+  const envHost = process.env.MSLXDFF_HOST || process.env.MSLXDFF_BIND_HOST;
+  if (typeof envHost === "string" && envHost.trim()) return envHost.trim();
+  try {
+    const joined = loadGroupsJoined();
+    if (joined.some((g) => g.kind === "broadband")) return "127.0.0.1";
+  } catch {}
+  return "0.0.0.0";
+}
+
 function refreshIntervalMs() {
   const n = Number(process.env.MODELS_REFRESH_MS);
   return Number.isInteger(n) && n > 0 ? n : 2 * 60 * 60 * 1000;
@@ -828,7 +954,7 @@ Usage:
   mslxdff -showtoken               print the current auth token
   mslxdff -refresh-token           rotate the auth token (prints the new one)
   mslxdff -creategroup <name>      create a group on this node (the group name is the password)
-  mslxdff -addtogroup <leader-host> <name>  join a group via its leader host (default port 8989)
+  mslxdff -addtogroup <leader-host> <name> [--broadband]  join a group via its leader host (default port 8989) — broadband: 宽带动态IP成员（经Leader中继，无需公网入站，默认127.0.0.1）
   mslxdff -group sync              pull the freshest member list for all joined groups
   mslxdff -group leave <name>      leave a group (removes its members from this node)
   mslxdff -group list              list groups on this node (numbered members)
@@ -905,6 +1031,12 @@ async function printStatus() {
             const tags = [];
             if (id === "leader" && isLeader) tags.push("leader");
             if (m?.url && m.url === g.myUrl) tags.push("this node");
+            if (m?.kind === "broadband") tags.push("broadband");
+            if (m?.kind === "broadband" && m?.publicIp) tags.push(`ip=${m.publicIp}`);
+            if (m?.kind === "broadband" && m?.lastSeen) {
+              const ago = Math.round((Date.now() - m.lastSeen) / 1000);
+              tags.push(ago < 90 ? `via leader ${ago}s ago` : "stale");
+            }
             const tag = tags.length ? `  [${tags.join(", ")}]` : "";
             console.log(`      ${m?.url || id}${tag}`);
           }
@@ -1006,6 +1138,14 @@ function fmtEvent(e) {
       return `${head} forward ->    ${e.peer} model=${m(e.model)} hops=${e.hops}${e.retry ? " (retry)" : ""}`;
     case "peer-error":
       return `${head} peer err      ${e.peer} ${e.status ? `HTTP ${e.status}` : "network"}: ${m(e.message)}`;
+    case "relay-ip-change":
+      return `${head} relay ip      ${e.member || e.id || "?"} ${e.oldIp || "?"} -> ${e.newIp || e.publicIp || "?"} via leader`;
+    case "relay-forward":
+      return `${head} relay fwd     ${e.target || e.peer || "?"} via leader model=${m(e.model)} hops=${e.hops || 0}`;
+    case "relay-heartbeat":
+      return `${head} relay hb      ${e.member || "?"} ip=${e.ip || "?"} lastSeen=${e.lastSeen ? new Date(e.lastSeen).toISOString().slice(11,19) : "?"}`;
+    case "client-abort":
+      return `${head} client abort  ${m(e.model)} total=${fmtDur(e.totalMs)}`;
     case "result":
       return `${head} result        ${e.status} ${m(e.model)} via=${e.via} 响应耗时 ${fmtDur(e.durationMs)}`;
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/groups.js

@@ -30,37 +30,60 @@ export function createGroup(name, { file, key = name } = {}) {
 // Shared writer: register a member, de-duplicated by url (same ip:port
 // re-registering under a different name updates the existing entry instead of
 // creating a duplicate).
-function writeMember(group, memberName, url, token) {
+function writeMember(group, memberName, url, token, extra = {}) {
   const members = group.members || (group.members = {});
   const byUrl = Object.entries(members).find(([, m]) => m.url === url);
+  const entry = { url, token: token || "", ...extra };
+  // normalize kind default
+  if (!entry.kind) entry.kind = "static";
   if (byUrl) {
-    members[byUrl[0]] = { url, token: token || "" };
+    const prev = members[byUrl[0]] || {};
+    // merge: keep url/token from new, but preserve fields if not supplied
+    const merged = { ...prev, ...entry };
+    // ensure url/token from latest call win
+    merged.url = url;
+    merged.token = token || prev.token || "";
+    members[byUrl[0]] = merged;
     return;
   }
   const id = memberName || url;
-  members[id] = { url, token: token || "" };
+  // if id already exists with different url, update that entry too (fallback)
+  if (members[id] && members[id].url !== url) {
+    // treat as new url, keep old entry but also update
+  }
+  members[id] = { ...entry, url, token: token || "" };
 }
 
 // Leader side: add a member after verifying the join key.
-export function addGroupMember(name, { key, memberName, url, token, file } = {}) {
+export function addGroupMember(name, { key, memberName, url, token, kind, publicIp, lastSeen, status, file } = {}) {
   const groups = loadGroups(file ? { file } : {});
   const group = groups[name];
   if (!group) throw new Error(`group "${name}" not found on this node`);
   if (!verifyGroupKey(key, group.key)) throw new Error("invalid group key");
   if (!url) throw new Error("member url is required");
-  writeMember(group, memberName, url, token);
+  const extra = {};
+  if (kind) extra.kind = kind;
+  if (publicIp) extra.publicIp = publicIp;
+  if (lastSeen) extra.lastSeen = lastSeen;
+  if (status) extra.status = status;
+  writeMember(group, memberName, url, token, extra);
   saveGroups(groups, file ? { file } : {});
   return group.members;
 }
 
 // Leader side: upsert a member without key verification (used by the sync
 // path after the member's bearer token has already been validated).
-export function upsertMember(name, { memberName, url, token, file } = {}) {
+export function upsertMember(name, { memberName, url, token, kind, publicIp, lastSeen, status, file } = {}) {
   const groups = loadGroups(file ? { file } : {});
   const group = groups[name];
   if (!group) return null;
   if (!url) throw new Error("member url is required");
-  writeMember(group, memberName, url, token);
+  const extra = {};
+  if (kind) extra.kind = kind;
+  if (publicIp) extra.publicIp = publicIp;
+  if (lastSeen) extra.lastSeen = lastSeen;
+  if (status) extra.status = status;
+  writeMember(group, memberName, url, token, extra);
   saveGroups(groups, file ? { file } : {});
   return group.members;
 }
@@ -136,17 +159,19 @@ export function createGroupsService({ file } = {}) {
 
 // Re-register with the leader (join is idempotent) and return the fresh member list.
 // No key is needed once registered: the leader verifies our bearer token.
-export async function refreshGroupMembers(name, { leaderUrl, memberName, url, token, fetchImpl = fetch } = {}) {
+export async function refreshGroupMembers(name, { leaderUrl, memberName, url, token, kind, fetchImpl = fetch } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), SYNC_TIMEOUT_MS);
   try {
+    const body = { name, memberName, url, token };
+    if (kind) body.kind = kind;
     const res = await fetchImpl(`${leaderUrl}/v1/groups/join`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "Authorization": `Bearer ${token}`,
       },
-      body: JSON.stringify({ name, memberName, url, token }),
+      body: JSON.stringify(body),
       signal: controller.signal,
     });
     if (!res.ok) {
@@ -163,6 +188,8 @@ export async function refreshGroupMembers(name, { leaderUrl, memberName, url, to
 // Merge a member map into the local peer list, replacing the previous snapshot
 // of this group and skipping ourselves. Used by both leaders (local groups) and
 // members (leader-pulled members).
+// broadband members (relay://) are NOT added as direct peers — they are
+// reached via the leader relay, so we skip them here.
 export function syncPeersFromMembers({ peers, members, myUrl, group, skipIds = [] }) {
   const self = normalizePeerUrl(myUrl);
   const skip = new Set(skipIds);
@@ -170,6 +197,8 @@ export function syncPeersFromMembers({ peers, members, myUrl, group, skipIds = [
   let added = 0;
   for (const [id, m] of Object.entries(members || {})) {
     if (skip.has(id)) continue;
+    const kind = m?.kind || "static";
+    if (kind === "broadband" || String(m?.url || "").startsWith("relay://")) continue;
     const url = normalizePeerUrl(m?.url);
     if (!url || url === self) continue;
     if (peers.add({ name: id, url, token: m?.token || "", group })) added++;

package/src/peers.js

@@ -3,9 +3,23 @@ import { loadPeers, savePeers, loadPeerErrors, savePeerErrors, loadPeerStats, sa
 export const DEFAULT_PEER_COOLDOWN_MS = 30_000;
 export const DEFAULT_PEER_HEAT_MS = 5 * 60_000;
 export const DEFAULT_MAX_HOPS = 3;
+export const DEFAULT_BROADBAND_STALE_MS = 90_000;
 
 const EMA_ALPHA = 0.3;
 
+export function broadbandStaleMs() {
+  const n = Number(process.env.MSLXDFF_BROADBAND_STALE_MS);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_BROADBAND_STALE_MS;
+}
+
+export function isBroadbandStale(peer, nowMs = Date.now(), staleMs = broadbandStaleMs()) {
+  const kind = peer?.kind || (String(peer?.url || "").startsWith("relay://") ? "broadband" : "static");
+  if (kind !== "broadband") return false;
+  const lastSeen = peer?.lastSeen;
+  if (typeof lastSeen !== "number") return true; // no heartbeat yet => stale
+  return nowMs - lastSeen > staleMs;
+}
+
 export function normalizePeerUrl(url) {
   return String(url || "").trim().replace(/\/+$/, "");
 }
@@ -64,7 +78,16 @@ export function createPeersService({
   function isCooling(url) {
     if (!cooldownMs) return false;
     const err = lastErrorAt[url];
-    return typeof err === "number" && now() - err < cooldownMs;
+    if (typeof err === "number" && now() - err < cooldownMs) return true;
+    const peer = list.find((p) => p.url === url);
+    if (peer && isBroadbandStale(peer, now(), broadbandStaleMs())) return true;
+    return false;
+  }
+
+  function isBroadbandCooling(url) {
+    const peer = list.find((p) => p.url === url);
+    if (!peer) return false;
+    return isBroadbandStale(peer, now(), broadbandStaleMs());
   }
 
   function available() {
@@ -168,7 +191,10 @@ export function createPeersService({
   }
 
   return {
-    all, add, remove, removeByGroup, isCooling, isHot, stat, ordered, orderedByLastError, available, next,
+    all, add, remove, removeByGroup, isCooling, isBroadbandCooling, isBroadbandStale: (url) => {
+      const peer = list.find((p) => p.url === url);
+      return peer ? isBroadbandStale(peer, now(), broadbandStaleMs()) : false;
+    }, isHot, stat, ordered, orderedByLastError, available, next,
     recordError, recordResult, errors: () => ({ ...lastErrorAt }), stats: () => ({ ...stats }),
   };
 }

package/src/routes.js

@@ -3,9 +3,152 @@ import { performance } from "node:perf_hooks";
 import { injectReasoningContent, normalizeModel } from "./reasoning.js";
 import { isAutoModel } from "./auto.js";
 import { DEFAULT_MAX_HOPS } from "./peers.js";
+import { loadGroupsJoined } from "./state.js";
 
 export const errMsg = (err) => String(err?.message || err);
 
+// In-memory relay queues for broadband members (polling-based, no WS dependency)
+// pendingByTarget: Map<`${group}::${targetUrl}`, Array<{reqId, body, hops, resolve, reject, timer}>>
+const relayPending = new Map();
+const relayPendingByReqId = new Map();
+
+function enqueueRelay({ group, target, reqId, body, hops }) {
+  const key = `${group}::${target}`;
+  const list = relayPending.get(key) || [];
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const idx = list.findIndex((e) => e.reqId === reqId);
+      if (idx >= 0) list.splice(idx, 1);
+      relayPendingByReqId.delete(reqId);
+      reject(new Error("relay timeout"));
+    }, 30_000);
+    timer.unref?.();
+    const entry = { reqId, body, hops, resolve, reject, timer };
+    list.push(entry);
+    relayPending.set(key, list);
+    relayPendingByReqId.set(reqId, entry);
+  });
+}
+
+function dequeueRelayForPoll({ group, target, limit = 10 }) {
+  const key = `${group}::${target}`;
+  const list = relayPending.get(key) || [];
+  const batch = list.splice(0, limit);
+  for (const e of batch) {
+    // keep timer, but remove from pending list; result will resolve via relayResult
+    // we keep entry in relayPendingByReqId until result arrives
+  }
+  if (list.length) relayPending.set(key, list);
+  else relayPending.delete(key);
+  return batch.map((e) => ({ reqId: e.reqId, body: e.body, hops: e.hops }));
+}
+
+function resolveRelay(reqId, result) {
+  const entry = relayPendingByReqId.get(reqId);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  relayPendingByReqId.delete(reqId);
+  entry.resolve(result);
+  return true;
+}
+
+async function tryBroadbandRelay({ groups, token: myToken, model, body, hops, bus, logs, reqId, evt, res, mark, perf0, stages }) {
+  try {
+    const joined = loadGroupsJoined();
+    const broadbandGroups = joined.filter((g) => g.kind === "broadband" || g.myUrl?.startsWith("relay://"));
+    // Also consider leader-owned broadband members directly
+    const allCandidates = [];
+    // 1) If this node is leader, check its own groups for broadband members
+    if (groups) {
+      const localGroups = groups.list();
+      for (const [gName, g] of Object.entries(localGroups)) {
+        for (const [id, m] of Object.entries(g.members || {})) {
+          if (id === "leader") continue;
+          const isBb = m?.kind === "broadband" || String(m?.url || "").startsWith("relay://");
+          if (!isBb) continue;
+          const staleMs = Number(process.env.MSLXDFF_BROADBAND_STALE_MS) > 0 ? Number(process.env.MSLXDFF_BROADBAND_STALE_MS) : 90_000;
+          if (typeof m.lastSeen === "number" && Date.now() - m.lastSeen > staleMs) continue;
+          // local leader: enqueue directly
+          allCandidates.push({ group: gName, target: m.url, member: m, via: "local-leader", leaderUrl: null });
+        }
+      }
+    }
+    // 2) For member nodes, check leader's broadband members (need leaderUrl)
+    for (const g of joined) {
+      if (!g.leaderUrl) continue; // already handled as leader
+      try {
+        // fetch fresh members from leader (re-use refreshGroupMembers logic but direct fetch)
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 5000);
+        const r = await fetch(`${g.leaderUrl}/v1/groups/join`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "Authorization": `Bearer ${myToken}` },
+          body: JSON.stringify({ name: g.name, memberName: g.memberName, url: g.myUrl, token: myToken }),
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!r.ok) continue;
+        const data = await r.json().catch(() => ({}));
+        const members = data.members || {};
+        for (const [id, m] of Object.entries(members)) {
+          if (id === "leader") continue;
+          const isBb = m?.kind === "broadband" || String(m?.url || "").startsWith("relay://");
+          if (!isBb) continue;
+          if (m.url === g.myUrl) continue; // skip self
+          const staleMs = Number(process.env.MSLXDFF_BROADBAND_STALE_MS) > 0 ? Number(process.env.MSLXDFF_BROADBAND_STALE_MS) : 90_000;
+          if (typeof m.lastSeen === "number" && Date.now() - m.lastSeen > staleMs) continue;
+          allCandidates.push({ group: g.name, target: m.url, member: m, via: "via-leader", leaderUrl: g.leaderUrl });
+        }
+      } catch {}
+    }
+    if (!allCandidates.length) return null;
+    // Try each candidate via relay forward (sequential, first success wins)
+    for (const cand of allCandidates) {
+      try {
+        evt?.("relay-try", { reqId, model, via: cand.via, target: cand.target, group: cand.group });
+        if (!cand.leaderUrl) {
+          // local leader: enqueue and wait for broadband poll (same as forward handler's local path)
+          const fwdBody = { model, ...body, model };
+          const reqIdLocal = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+          const promise = enqueueRelay({ group: cand.group, target: cand.target, reqId: reqIdLocal, body: fwdBody, hops });
+          // also trigger a dummy poll wait: we can't directly wait for poll without D, so timeout quickly
+          // For local leader, the D will poll; we wait for result with timeout 30s
+          const result = await promise;
+          if (result && result.status) {
+            return { via: "broadband-local", result, target: cand.target, group: cand.group };
+          }
+        } else {
+          // forward via leader's relay/forward endpoint
+          const ctrl = new AbortController();
+          const t = setTimeout(() => ctrl.abort(), 35_000);
+          const r = await fetch(`${cand.leaderUrl}/v1/groups/relay/forward`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Authorization": `Bearer ${myToken}`, "x-mslxdff-hops": String(hops + 1) },
+            body: JSON.stringify({ group: cand.group, target: cand.target, body: { ...body, model }, hops: hops + 1, reqId }),
+            signal: ctrl.signal,
+          });
+          clearTimeout(t);
+          if (!r.ok) {
+            const txt = await r.text().catch(() => "");
+            evt?.("relay-fail", { reqId, model, via: cand.via, target: cand.target, status: r.status, message: txt.slice(0,200) });
+            continue;
+          }
+          // leader's forward returns the upstream response (maybe SSE)
+          // For simplicity, we treat it as direct response to relay back to client
+          // We can stream it back: but for now, we just return the Response
+          return { via: "broadband-via-leader", result: r, target: cand.target, group: cand.group };
+        }
+      } catch (err) {
+        evt?.("relay-fail", { reqId, model, via: cand.via, target: cand.target, message: String(err?.message || err).slice(0,200) });
+        continue;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 export function createRouter({ token, upstream, models, auto, logs, peers, maxHops = DEFAULT_MAX_HOPS, groups, bans, bus }) {
   return async function router(req, res) {
     const method = req.method || "GET";
@@ -419,7 +562,7 @@ const ROUTES = [
     method: "POST",
     path: "/v1/chat/completions",
     requiresAuth: true,
-    handler: async ({ req, res, upstream, auto, logs, peers, maxHops, bus }) => {
+    handler: async ({ req, res, upstream, auto, logs, peers, maxHops, groups, bus }) => {
       let body;
       try {
         body = await readBody(req);
@@ -596,6 +739,59 @@ const ROUTES = [
           evt("peer-race-lose", { reqId, model });
         }
 
+        // Broadband relay: try to forward via leader to a broadband member's quota
+        if (groups) {
+          const bb = await tryBroadbandRelay({ groups, token, model, body, hops, bus, logs, reqId, evt, res, mark, perf0, stages });
+          if (bb) {
+            const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
+            if (isResponse) {
+              // streaming response from leader's forward (which waited for broadband)
+              evt("relay-start", { reqId, model, via: "broadband", target: bb.target, group: bb.group });
+              const out = await relay(res, bb.result, body, {
+                onFirstChunk: (d) => mark(`ttf-bb-${model}`),
+                onDownstreamAbort: () => evt("client-abort", { reqId, model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
+              });
+              evt("relay-done", { reqId, model, via: "broadband", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
+              if (auto && out.status === 200) {
+                const latencyMs = out.totalMs ?? 0;
+                if (out.detail?.stallHits > 0 || (latencyMs && latencyMs > SLOW_TOTAL_MS)) {
+                  void auto.recordError(model, { status: 200, slow: true, note: `broadband slow ${latencyMs}ms` });
+                  void auto.recordLatency(model, latencyMs);
+                } else {
+                  await auto.recordOk(model, { latencyMs });
+                }
+              }
+              evt("result", { model, status: out.status, via: "broadband", timing: bb.result._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+              return;
+            } else if (bb.result && typeof bb.result.status === "number") {
+              // buffered result from local leader enqueue
+              const fakeRes = {
+                status: bb.result.status,
+                headers: { get: (k) => bb.result.headers?.[k] || bb.result.headers?.[k.toLowerCase()] || null },
+                text: async () => typeof bb.result.body === "string" ? bb.result.body : JSON.stringify(bb.result.body),
+                body: (() => {
+                  const b = bb.result.body || "";
+                  const str = typeof b === "string" ? b : JSON.stringify(b);
+                  const isSSE = bb.result.headers?.["Content-Type"]?.includes("text/event-stream");
+                  if (isSSE) {
+                    return (async function* () { yield Buffer.from(str); })();
+                  }
+                  return null;
+                })(),
+              };
+              evt("relay-start", { reqId, model, via: "broadband-local", target: bb.target, group: bb.group });
+              const out = await relay(res, fakeRes, body, {
+                onFirstChunk: (d) => mark(`ttf-bb-${model}`),
+                onDownstreamAbort: () => evt("client-abort", { reqId, model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
+              });
+              evt("relay-done", { reqId, model, via: "broadband-local", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
+              evt("result", { model, status: out.status, via: "broadband", timing: null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+              return;
+            }
+          }
+          evt("relay-miss", { reqId, model });
+        }
+
         if (canFallback) {
           evt("fallback", { reqId, from: model, to: order[idx + 1] ?? null, reason: lastErr?.message || `upstream ${lastErr?.status ?? 502}` });
           continue;
@@ -670,11 +866,31 @@ const ROUTES = [
         const hit = auth && groups.membersForToken(body.name, auth[1]);
         if (!hit) return fail("invalid member token");
         try {
+          const isBroadbandRe = String(body.url || hit.member?.url || "").startsWith("relay://") || body.kind === "broadband" || hit.member?.kind === "broadband";
+          const extra = {};
+          if (isBroadbandRe) {
+            extra.kind = "broadband";
+            extra.publicIp = ip;
+            extra.lastSeen = Date.now();
+            if (body.url) extra.url = String(body.url);
+          }
           const refreshed = groups.upsertMember(body.name, {
             memberName: body.memberName,
-            url: body.url,
-            token: body.token,
+            url: body.url || hit.member.url,
+            token: body.token || hit.member.token,
+            kind: extra.kind,
+            publicIp: extra.publicIp,
+            lastSeen: extra.lastSeen,
           });
+          // also ensure broadband's publicIp/lastSeen updated even if url same
+          if (isBroadbandRe && refreshed) {
+            const targetId = Object.keys(refreshed).find((k) => refreshed[k].url === (body.url || hit.member.url));
+            if (targetId) {
+              refreshed[targetId].publicIp = ip;
+              refreshed[targetId].lastSeen = Date.now();
+              refreshed[targetId].kind = "broadband";
+            }
+          }
           return json(res, 200, { object: "group", name: body.name, members: refreshed });
         } catch (err) {
           return json(res, 400, { error: errMsg(err) });
@@ -684,13 +900,21 @@ const ROUTES = [
       try {
         const youPort = Number(body.myPort);
         const youUrl = Number.isInteger(youPort) && youPort > 0 ? `http://${ip}:${youPort}` : "";
-        const memberUrl = String(body.url || youUrl);
+        let memberUrl = String(body.url || youUrl);
         if (!memberUrl) throw new Error("member url is required");
+        const isBroadband = String(memberUrl).startsWith("relay://") || body.kind === "broadband";
+        if (isBroadband) {
+          // broadband: keep relay:// url, record publicIp from source ip
+          memberUrl = String(body.url || memberUrl);
+        }
         const members = groups.addMember(body.name, {
           key: body.key,
           memberName: body.memberName,
           url: memberUrl,
           token: body.token,
+          kind: isBroadband ? "broadband" : "static",
+          publicIp: isBroadband ? ip : undefined,
+          lastSeen: isBroadband ? Date.now() : undefined,
         });
         // 5 wrong passwords bans the source IP (48h) — see createBansService.
         if (bans) bans.clear(ip);
@@ -743,6 +967,156 @@ const ROUTES = [
       }
     },
   },
+  {
+    method: "POST",
+    path: "/v1/groups/relay/heartbeat",
+    requiresAuth: false,
+    handler: async ({ req, res, groups, bus, logs }) => {
+      const auth = /^Bearer (.+)$/.exec(req.headers["authorization"] || "");
+      if (!auth) return json(res, 401, { error: "bearer token required" });
+      let body;
+      try { body = await readBody(req); } catch { return json(res, 400, { error: "Invalid JSON body" }); }
+      const groupName = body?.name || body?.group;
+      if (!groupName) return json(res, 400, { error: "group name is required" });
+      const hit = groups?.membersForToken(groupName, auth[1]);
+      if (!hit) return json(res, 403, { error: "invalid member token" });
+      const ip = clientIp(req);
+      try {
+        const memberUrl = hit.member?.url;
+        const members = groups.list()[groupName]?.members || {};
+        const targetId = Object.keys(members).find((k) => members[k].url === memberUrl) || hit.member?.url;
+        // update lastSeen/publicIp for broadband
+        if (hit.member?.kind === "broadband" || String(memberUrl).startsWith("relay://")) {
+          const m = members[targetId] || hit.member;
+          if (m) {
+            m.publicIp = ip;
+            m.lastSeen = Date.now();
+            // persist via groups service (upsert)
+            try { groups.upsertMember(groupName, { memberName: targetId, url: m.url, token: m.token, kind: "broadband", publicIp: ip, lastSeen: m.lastSeen }); } catch {}
+          }
+          const evtData = { ts: Date.now(), type: "relay-heartbeat", member: targetId, ip, lastSeen: m?.lastSeen, group: groupName };
+          if (bus) bus.emit(evtData);
+          logs?.appendEvent?.(evtData);
+        }
+        return json(res, 200, { object: "heartbeat", ok: true, ip, lastSeen: Date.now() });
+      } catch (err) {
+        return json(res, 400, { error: errMsg(err) });
+      }
+    },
+  },
+  {
+    method: "POST",
+    path: "/v1/groups/relay/poll",
+    requiresAuth: false,
+    handler: async ({ req, res, groups }) => {
+      const auth = /^Bearer (.+)$/.exec(req.headers["authorization"] || "");
+      if (!auth) return json(res, 401, { error: "bearer token required" });
+      let body;
+      try { body = await readBody(req); } catch { return json(res, 400, { error: "Invalid JSON body" }); }
+      const groupName = body?.name || body?.group;
+      if (!groupName) return json(res, 400, { error: "group name is required" });
+      const hit = groups?.membersForToken(groupName, auth[1]);
+      if (!hit) return json(res, 403, { error: "invalid member token" });
+      const targetUrl = hit.member?.url;
+      if (!targetUrl) return json(res, 400, { error: "member url not found" });
+      const batch = dequeueRelayForPoll({ group: groupName, target: targetUrl, limit: 10 });
+      return json(res, 200, { object: "poll", data: batch });
+    },
+  },
+  {
+    method: "POST",
+    path: "/v1/groups/relay/result",
+    requiresAuth: false,
+    handler: async ({ req, res, groups }) => {
+      const auth = /^Bearer (.+)$/.exec(req.headers["authorization"] || "");
+      if (!auth) return json(res, 401, { error: "bearer token required" });
+      let body;
+      try { body = await readBody(req); } catch { return json(res, 400, { error: "Invalid JSON body" }); }
+      const groupName = body?.name || body?.group;
+      const reqId = body?.reqId;
+      if (!groupName || !reqId) return json(res, 400, { error: "group and reqId required" });
+      const hit = groups?.membersForToken(groupName, auth[1]);
+      if (!hit) return json(res, 403, { error: "invalid member token" });
+      const ok = resolveRelay(reqId, body.result || body);
+      if (!ok) return json(res, 404, { error: "pending request not found or timed out" });
+      return json(res, 200, { object: "result", ok: true });
+    },
+  },
+  {
+    method: "POST",
+    path: "/v1/groups/relay/forward",
+    requiresAuth: true,
+    handler: async ({ req, res, groups, bus, logs }) => {
+      let body;
+      try { body = await readBody(req); } catch { return json(res, 400, { error: "Invalid JSON body" }); }
+      const groupName = body?.group || body?.name;
+      const target = body?.target || body?.url;
+      const hops = parseHops(req.headers["x-mslxdff-hops"] || body?.hops);
+      if (!groupName || !target) return json(res, 400, { error: "group and target required" });
+      if (hops >= DEFAULT_MAX_HOPS) return json(res, 429, { error: "max hops exceeded" });
+      const members = groups?.list()[groupName]?.members || {};
+      const targetMember = Object.values(members).find((m) => m.url === target) || Object.entries(members).find(([id]) => id === target)?.[1];
+      if (!targetMember) return json(res, 404, { error: `target ${target} not found in group ${groupName}` });
+      const isBb = targetMember.kind === "broadband" || String(targetMember.url).startsWith("relay://");
+      if (!isBb) {
+        // static: direct fetch (should have been handled by peer race, but support via relay as well)
+        try {
+          const fwdBody = body.body || body;
+          const r = await fetch(`${targetMember.url}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Authorization": `Bearer ${targetMember.token || ""}`, "x-mslxdff-hops": String(hops + 1), "x-mslxdff-model-lock": fwdBody.model || "", "Accept": "text/event-stream" },
+            body: JSON.stringify(fwdBody),
+          });
+          const evtData = { ts: Date.now(), type: "relay-forward", target, via: "direct", group: groupName, hops };
+          if (bus) bus.emit(evtData);
+          logs?.appendEvent?.(evtData);
+          res.statusCode = r.status;
+          if (r.headers.get("content-type")?.includes("text/event-stream")) {
+            res.setHeader("Content-Type", "text/event-stream");
+            if (r.body) for await (const c of r.body) res.write(c);
+            res.end();
+          } else {
+            const txt = await r.text();
+            res.setHeader("Content-Type", r.headers.get("content-type") || "application/json");
+            res.end(txt);
+          }
+          return;
+        } catch (err) {
+          return json(res, 502, { error: errMsg(err) });
+        }
+      }
+      // broadband: enqueue and wait for poll/result
+      const reqId = body.reqId || `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+      const fwdBody = body.body || { model: body.model, messages: body.messages, stream: body.stream };
+      const evtData = { ts: Date.now(), type: "relay-forward", target, via: "leader", group: groupName, hops, reqId, model: fwdBody.model };
+      if (bus) bus.emit(evtData);
+      logs?.appendEvent?.(evtData);
+      // check stale
+      const staleMs = Number(process.env.MSLXDFF_BROADBAND_STALE_MS) > 0 ? Number(process.env.MSLXDFF_BROADBAND_STALE_MS) : 90_000;
+      if (typeof targetMember.lastSeen === "number" && Date.now() - targetMember.lastSeen > staleMs) {
+        return json(res, 502, { error: "broadband member stale (no heartbeat)" });
+      }
+      try {
+        const resultPromise = enqueueRelay({ group: groupName, target: targetMember.url, reqId, body: fwdBody, hops });
+        // race with timeout already in enqueueRelay (30s)
+        const result = await resultPromise;
+        // result is expected to be { status, headers, body } from broadband
+        if (result && typeof result.status === "number") {
+          res.statusCode = result.status;
+          if (result.headers) for (const [k, v] of Object.entries(result.headers)) res.setHeader(k, v);
+          if (result.body) {
+            if (typeof result.body === "string") res.end(result.body);
+            else res.end(JSON.stringify(result.body));
+          } else res.end();
+          return;
+        }
+        // if result is raw upstream response body
+        return json(res, 200, result);
+      } catch (err) {
+        return json(res, 504, { error: errMsg(err) || "relay timeout" });
+      }
+    },
+  },
   {
     method: "GET",
     path: "/v1/models",

package/src/server.js

@@ -1,7 +1,8 @@
 import { createServer as httpCreateServer } from "node:http";
 import { DEFAULT_PORT, getPort } from "./state.js";
 
-export function startServer({ router, signals = true }, port = resolvePort()) {
+export function startServer({ router, signals = true, host }, port = resolvePort()) {
+  const listenHost = host ?? resolveHost();
   const server = httpCreateServer((req, res) => {
     router(req, res).catch((err) => {
       res.statusCode = 500;
@@ -13,7 +14,8 @@ export function startServer({ router, signals = true }, port = resolvePort()) {
   const ready = () =>
     new Promise((resolve, reject) => {
       server.on("error", reject);
-      server.listen(port, resolve);
+      if (listenHost) server.listen(port, listenHost, resolve);
+      else server.listen(port, resolve);
     });
 
   const close = () =>
@@ -32,6 +34,12 @@ export function startServer({ router, signals = true }, port = resolvePort()) {
   return { server, ready, close };
 }
 
+export function resolveHost() {
+  const envHost = process.env.MSLXDFF_HOST || process.env.MSLXDFF_BIND_HOST;
+  if (typeof envHost === "string" && envHost.trim()) return envHost.trim();
+  return "0.0.0.0";
+}
+
 export function resolvePort() {
   // 8989 is the hard default. Port only changes via an explicit, mslxdff-owned
   // override: the persisted `-port N` setting, or the MSLXDFF_PORT env var.