Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

feat(web): expose authoritative viewer topology

AAA671f7ef73123
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 9bbf5c88..4bb6a75f 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -32,7 +32,7 @@ Last updated: 2026-08-21
- Flagship media is UDP; HTTPS/WSS stays TLS/TCP; the old release remains rollback-only.
- Treat settings as ceilings and degradation as unclassified. Use correlated Host A+B/Viewer C and one-variable evidence; never force AV1, infer by UA, or create a composite score.
- Web requests window audio and offers system audio for full displays; both are browser hints. Returned tracks use the `music` hint. Native Win11 process audio stays source-only; one Viewer got 495 Opus packets.
-- Viewer-local names and the opt-in Web participant roster remain control-plane-only. Web Host names are deployed in the current release and stay socket/localStorage-only; Native remains outside the capability boundary.
+- Presence is control-plane-only and exposes the exact active upstream for Host diagnostics; it does not create media. Web Host names stay socket/localStorage-only; Native remains outside the capability boundary.
- Do not add scene detection, dynamic-FPS control, or forced AV1 without negotiation, encode, game, CPU/GPU, and sender evidence.
- ADR-0002 grant/public access, the v3 room-password migration, and Web Host display names are deployed. Names/presence remain session-only without account or roster tables.
diff --git a/docs/status.md b/docs/status.md
index 24c8a4b5..b5e145e7 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -17,7 +17,7 @@ Flagship; parallel; min run/smoke/rollback; benchmark later. Active UI/config/lo
- Capture precedes room creation; source/quality changes and AV pause preserve peers. Recommended profiles and advanced defaults use `balanced`; clarity/fluid remain explicit. The browser chooses degradation; readback/stats report actual behavior.
- Production access is `screener-v2`: a valid private fragment grant enters directly; every code-only Viewer must first hold site access, after which public-watch accepts the code and private rooms still require their room password. `SITE_ACCESS_PASSWORD`, `/api/site-access`, and the site-access cookie are deployed atomically; raw credentials are never stored.
-- Web Hosts can set their local/session display name, and the current release advertises it through the existing presence wire. The name is not an account identity.
+- Web Host names are session-local. Presence now exposes exact active upstream for P2P/SFU details and an on-demand Host topology; production still has the prior roster UI.
- Native v2 is source-only (memory rooms, 300s reclaim); it follows authenticated direct-child assignments up to two and fails unsupported SFU/selected ingress boundedly.
- PR #44's STUN-only/SFU-UDP router and token-free fallback prewarm are process-enabled for all normal rooms: roots <=2, browser relay <=1, bounded failure. Room `1` is historical smoke; mobile/iPad viewers are leaves, healthy edges sticky, and HTTPS/WSS stays TLS/TCP.
- After an answer, a generation-bound 15s initial-connect deadline enters ICE restart; success/replacement/disposal cancels it. It is deployed but not mobile-verified.
diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
index db030e17..e2d8169f 100644
--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
@@ -98,9 +98,9 @@ rotate、revoke 或从 public-watch 切回 private-link 都是当前 Viewer 的
显示名是独立的本地偏好:同源 `localStorage` 只保存浏览器输入,存储不可用时静默退回内存 fallback;服务端只把参与者的规范化名称挂在当前 authenticated socket state,断线即丢弃,不进入 RoomStore、SQLite 或日志。shared schema 先做 NFC、合并 Unicode space separators、去除边缘空格,再限制为 1 至 24 个 Unicode code points,并拒绝控制字符、行/段分隔符、BOM、双向控制符和孤立 surrogate;未设置时 Viewer 使用通用“访客”,Web Host 可由 room-scoped stable client ID 生成本地 fallback。普通多语言文本、组合字符和 emoji 仍可用。
-Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,Viewer 也可显式订阅同一 participant snapshot;Native sender 不发送,因此继续只收到原有 exact server wire。两端可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的 Web participant 发送完整 `viewer-presence` snapshot,列表严格来自当前带 sessionId 的在线参与者,不含五秒媒体恢复 grace 成员;条目用 `role` discriminator 区分 Host/Viewer。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”Viewer 总数取 Viewer 条目数,“Host 直连”取其中 active media topology 为 `host-direct` 的条目,最多两条的媒体 peer snapshot 只补充本机连接指标。
+Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,Viewer 也可显式订阅同一 participant snapshot;Native sender 不发送,因此继续只收到原有 exact server wire。两端可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的 Web participant 发送完整 `viewer-presence` snapshot,列表严格来自当前带 sessionId 的在线参与者,不含五秒媒体恢复 grace 成员;条目用 `role` discriminator 区分 Host/Viewer。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”Viewer 总数只取 Viewer 条目数;最多两条本机媒体快照只补充当前以 Host 为 active upstream 的连接指标。
-每个 presence 条目包含 `role`、`peerId`、`displayName` 和当前 active media topology;Host 使用 `host`,Viewer 使用 `host-direct`、`peer-relay`、`sfu` 或 `pending`。UI 始终展示名称加 peerId 尾部至少六字符短后缀;碰撞时逐字符有界延长至完整 peerId。peerId 不因此成为授权身份或路由输入。媒体拓扑标签使用“Host 直连 / Peer 中转 / SFU / 连接中”;ICE candidate path 单独使用“ICE 直连 / TURN 传输 / ICE 未知”,不能把 TURN transport 伪装成媒体拓扑。Host 与 Viewer 的本地改名和订阅仍不上传或持久化 IP,也不改变 Host/Viewer 的授权、媒体或路由状态机。
+每个 presence 条目包含 `role`、`peerId`、`displayName` 和服务端 active assignment 的精确 `upstream`:Host 为 `none`,Viewer 为 `none | peer(peerId) | sfu`。UI 始终展示名称加 peerId 尾部至少六字符短后缀;碰撞时逐字符有界延长至完整 peerId。卡片状态只依据本机连接或当前 Viewer 接收证据显示“已连接”,否则区分“线路已分配”和“连接中”;连接详情只显示 `P2P` 或 `SFU`,且仅在本机真实 selected relay 时附加 `TURN`。独立拓扑按钮从同一 snapshot 展示 Host、实际存在的 SFU 节点及精确上下游,不从客户端媒体快照推断。peerId 不因此成为授权身份或路由输入;名称、presence 与拓扑视图不改变授权、媒体或路由状态机。
## 信令协议
@@ -113,7 +113,7 @@ WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-
| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话,并可显式订阅 Web-only viewer presence/password settings;Viewer 以 public room code、private Viewer grant 或当前房间密码尝试建立仅观看会话并可附带规范化本地显示名 |
| server -> client | `authenticated` | 返回角色、peerId、可为空的房间期限、容量、host 状态、该 viewer 的历史 connectionId、host 的权威 viewer 列表和 ICE 配置 |
| viewer -> server | `set-display-name` | 只更新该 Viewer 当前 authenticated socket state 的规范化名称,不写房间或数据库状态 |
-| server -> subscribed Web host | `viewer-presence` | 返回全部当前在线 Viewer 的权威 snapshot 与只读 active media topology;不触发媒体连接 |
+| server -> subscribed Web host | `viewer-presence` | 返回全部当前在线 Viewer 的权威 snapshot 与精确 active upstream;不触发媒体连接 |
| host -> server -> host | `set-viewer-access` / `viewer-access-updated` | Host 切换 public/private、rotate 或 revoke;raw grant 只在新建、rotate 或 public-to-private 成功响应中出现一次 |
| opted-in Web host -> server -> host | `set-viewer-password` / `viewer-password-updated` | 设置、替换或移除逐房间 Viewer 密码;服务端只返回 enabled snapshot,不回显密码;未声明 capability 的 v2 Host 不接收该新 type |
| server -> host | `peer-joined` / `peer-left` | 建立或关闭该观看者的独立连接 |
@@ -244,7 +244,7 @@ Native v2 与 authenticated snapshot 继续 STUN-only。凭据不进入 URL、
storage、room row 或 SQLite。
该临时 edge 不改写 active SFU assignment 或另建 route owner;attempt 存续期间
-presence 仍报告 `sfu`,本地 ICE path 才报告 TURN transport。签发前按当前 assignment
+presence 的 active upstream 仍为 `sfu`,本地 ICE path 才报告 TURN transport。签发前按当前 assignment
重新计算 parent 下游预算,Host 的 SFU publication 也占一边;Host 两边或 ViewerRelay
一边已满且 target 不是现有 child 时 fail closed,不替换无关 child。
diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
index ec3b44a2..98c680d6 100644
--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
@@ -32,7 +32,7 @@
- [ ] 路径级质量状态:应用的 `HIGH`/`FALLBACK` 非对称窗口只决定拓扑资格和诊断,不命令正常的媒体层切换,也不计算综合分数。SFU BWE downshift 先进入 `suspect`;多个连续窗口的 sender/viewer 关联证据确认 `FALLBACK` 后,应用不得稳定保留该 parent,并把 downstream capacity 降为 0。计划或显式质量 fallback 仅是内建路径失败后的候选:已有 children 时先在 connection/assignment generation guard 下全部迁走,失败或代次过期则保持原 assignment/quality。Autonomous downshift 无法 packet-level 预先迁移,default-on 前必须验收 descendants 的短暂影响。只有更长的稳定恢复窗口和 cooldown 后才能重新声明 relay capacity。Viewer 请求必须鉴权、限频、去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、协商 codec/profile/parameters 与 viewer 解码、丢帧、冻结证据交叉验证;不能仅凭自报生效,也不得上传 raw SDP、candidate 地址或原始设备/网络标识。
- [ ] 断线恢复:临时网络变化时按不同层级做一次性恢复,而不是把同一动作机械重复三次。`failed` 边先做一次 ICE restart,再重建一次同 parent 的 `RTCPeerConnection`,随后尝试一个不同的合格 peer parent;只有 peer 路径耗尽才进入 SFU。`connecting`/`checking` 先显示不改变拓扑的慢连接状态,硬超时必须由真实移动网络证据确定,不能为了更快使用服务器而过早放弃最终可成功的 P2P。任一步恢复即停止后续动作;所有异步结果受 session、route revision、assignment/connection generation 约束。active SFU 只允许一次 fresh-token 重试,再失败即有界回到 peer baseline 或明确失败,并向 Host 显示不含 URL、地址、token 或原始错误的失败阶段。
- [ ] 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选与错误的 wire、日志和导出只使用[低服务器成本媒体路由](./research/low-server-media-routes.md)的脱敏字段和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText` 或网络标识。只有创建该 `RTCPeerConnection` 的本机可在折叠详情中显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。
-- [ ] 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;候选路径、RTT、视频/音频 RTP 区间丢包率、实际编解码器、音频区间码率/jitter 和视频编码耗时等技术详情由一个明确的“显示连接详情”开关展开。音频 codec MIME、RTP clock、channels 与 fmtp 只能来自当前 RTP 对象引用的 `RTCCodecStats`,缺失即未知;`opus/48000/2` 不得写成 48 kHz 音源或实际立体声。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。
+- [ ] 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 的 Viewer 卡片只把本机连接或当前接收证据称为“已连接”,其余 active assignment 显示“线路已分配”,未分配显示“连接中”。展开连接详情只把媒体方式归为 `P2P` 或 `SFU`,实际 selected relay 时才另标 `TURN`;Host/Peer 上下游只在独立的权威拓扑视图中展示。候选路径、RTT、视频/音频 RTP 区间丢包率、实际编解码器、音频区间码率/jitter 和视频编码耗时等技术详情由一个明确的“显示连接详情”开关展开。音频 codec MIME、RTP clock、channels 与 fmtp 只能来自当前 RTP 对象引用的 `RTCCodecStats`,缺失即未知;`opus/48000/2` 不得写成 48 kHz 音源或实际立体声。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。
- [ ] 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}`、`/join` 和 public-watch 必须先持有效站点 cookie,之后才检查房间 public/private policy 和房间密码。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。
- [ ] 房间级观看授权:新房间默认生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。私密房间缺失 grant 时必须先通过站点访问,再提供正确房间观看密码;任一缺失都 fail closed。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可 rotate 或 revoke;revoke 只锁定 grant 路径,已配置的房间密码仍是独立的后续进入方式。新 grant 摘要成功提交后必须清除 Viewer grace/路由、终止旧授权代次的信令和媒体并断开全部旧 Viewer,数据库写失败则不得改变连接。public-watch 是显式、可逆的 room policy,只放宽房间级观看,不绕过站点访问。
- [ ] 最小持久化:`ROOM_DATABASE_PATH` 可选且必须与 `SITE_ACCESS_PASSWORD` 同时配置。两者都存在时,SQLite 只持久保存从 `1` 开始自增的房间 ID、Host token 摘要、nullable Viewer grant 摘要,以及 nullable 48-byte Viewer-password material(16-byte salt + 32-byte scrypt verifier);数据库 `CHECK` 约束非空 BLOB 长度,不新增用户、成员或 session 表。明文房间密码只短暂存在于当前页面和鉴权/派生调用内存,不进入 URL、cookie、浏览器持久存储、日志或 SQLite。持久房间停止后仍显示等待状态;私密邀请按期限或 Host rotate 更新。旧 schema 行在原子迁移时必须 fail-closed 为没有可用明文 grant 的锁定私密状态,Host rotate 后才能生成新邀请。
diff --git a/src/client/components/StatusBadge.tsx b/src/client/components/StatusBadge.tsx
index 9d1f09a7..3a1f7328 100644
--- a/src/client/components/StatusBadge.tsx
+++ b/src/client/components/StatusBadge.tsx
@@ -1,5 +1,4 @@
import { CircleAlert, Radio, Wifi, WifiOff } from "lucide-react";
-import type { ViewerMediaTopology } from "../../shared/protocol";
import type {
MediaPath,
SignalConnectionState,
@@ -37,14 +36,15 @@ export function SignalStatusBadge({
export function PeerStatusBadge({
state,
}: {
- state: RTCPeerConnectionState | "reconnecting" | "waiting";
+ state: RTCPeerConnectionState | "reconnecting" | "waiting" | "assigned";
}) {
const labels: Record<
- RTCPeerConnectionState | "reconnecting" | "waiting",
+ RTCPeerConnectionState | "reconnecting" | "waiting" | "assigned",
BadgeProps
> = {
waiting: { tone: "neutral", label: "等待开始分享" },
reconnecting: { tone: "warning", label: "正在恢复" },
+ assigned: { tone: "neutral", label: "线路已分配" },
new: { tone: "neutral", label: "准备中" },
connecting: { tone: "neutral", label: "正在连接" },
connected: { tone: "good", label: "已连接" },
@@ -89,21 +89,6 @@ export function MediaRouteBadge({ route }: { route: "p2p" | "sfu" }) {
/>
);
}
-
-export function TopologyBadge({
- topology,
-}: {
- topology: ViewerMediaTopology;
-}) {
- const values: Record<ViewerMediaTopology, BadgeProps> = {
- "host-direct": { tone: "good", label: "Host 直连" },
- "peer-relay": { tone: "warning", label: "Peer 中转" },
- sfu: { tone: "warning", label: "SFU fallback" },
- pending: { tone: "neutral", label: "连接中" },
- };
- return <Badge {...values[topology]} />;
-}
-
export function WarningBanner({ children }: { children: React.ReactNode }) {
return (
<div className="notice notice-warning" role="status">
diff --git a/src/client/components/TopologyView.tsx b/src/client/components/TopologyView.tsx
new file mode 100644
index 00000000..49a241b4
--- /dev/null
+++ b/src/client/components/TopologyView.tsx
@@ -0,0 +1,58 @@
+import type { LabeledViewerPresence } from "../lib/viewer-presence";
+import { deriveParticipantTopology, type TopologyBranch } from "../lib/participant-topology";
+function ViewerBranch({ branch, edge }: { branch: TopologyBranch; edge: "P2P" | "SFU" }) {
+ return (
+ <li>
+ <div className="topology-node">
+ <span className="topology-edge">{edge}</span><strong>{branch.viewer.label}</strong>
+ </div>
+ {branch.children.length > 0 && (
+ <ul>
+ {branch.children.map((child) => (
+ <ViewerBranch key={child.viewer.peerId} branch={child} edge="P2P" />
+ ))}
+ </ul>
+ )}
+ </li>
+ );
+}
+
+export function TopologyView({ hostPeerId, hostLabel, viewers }: { hostPeerId: string | null; hostLabel: string; viewers: readonly LabeledViewerPresence[] }) {
+ const topology = deriveParticipantTopology(hostPeerId, viewers);
+ return (
+ <div className="topology-view" id="room-topology">
+ <ul className="topology-tree" aria-label="当前连接拓扑">
+ <li>
+ <div className="topology-node">
+ <span className="topology-role">Host</span><strong>{hostLabel}</strong>
+ </div>
+ <ul>
+ {topology.peerRoots.map((root) => (
+ <ViewerBranch key={root.viewer.peerId} branch={root} edge="P2P" />
+ ))}
+ {topology.sfuRoots.length > 0 && (
+ <li>
+ <div className="topology-node">
+ <span className="topology-role">SFU</span><strong>媒体服务器</strong>
+ </div>
+ <ul>
+ {topology.sfuRoots.map((root) => (
+ <ViewerBranch key={root.viewer.peerId} branch={root} edge="SFU" />
+ ))}
+ </ul>
+ </li>
+ )}
+ </ul>
+ </li>
+ </ul>
+ {topology.pending.length > 0 && (
+ <div className="topology-pending">
+ <span>连接中</span>
+ {topology.pending.map((viewer) => (
+ <strong key={viewer.peerId}>{viewer.label}</strong>
+ ))}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/src/client/lib/participant-topology.ts b/src/client/lib/participant-topology.ts
new file mode 100644
index 00000000..dc262aef
--- /dev/null
+++ b/src/client/lib/participant-topology.ts
@@ -0,0 +1,36 @@
+import type { LabeledViewerPresence } from "./viewer-presence";
+export type TopologyBranch = { viewer: LabeledViewerPresence; children: TopologyBranch[] };
+export function deriveParticipantTopology(hostPeerId: string | null, viewers: readonly LabeledViewerPresence[]) {
+ const peerChildren = new Map<string, LabeledViewerPresence[]>();
+ const sfuViewers: LabeledViewerPresence[] = [];
+ for (const viewer of viewers) {
+ if (viewer.upstream.kind === "peer") {
+ const children = peerChildren.get(viewer.upstream.peerId) ?? [];
+ children.push(viewer);
+ peerChildren.set(viewer.upstream.peerId, children);
+ } else if (viewer.upstream.kind === "sfu") {
+ sfuViewers.push(viewer);
+ }
+ }
+ const included = new Set<string>();
+ const branch = (viewer: LabeledViewerPresence, path: Set<string>): TopologyBranch => {
+ included.add(viewer.peerId);
+ const nextPath = new Set(path).add(viewer.peerId);
+ return {
+ viewer,
+ children: (peerChildren.get(viewer.peerId) ?? [])
+ .filter((child) => !nextPath.has(child.peerId))
+ .map((child) => branch(child, nextPath)),
+ };
+ };
+ const peerRoots = hostPeerId
+ ? (peerChildren.get(hostPeerId) ?? []).map((viewer) =>
+ branch(viewer, new Set([hostPeerId])),
+ )
+ : [];
+ return {
+ peerRoots,
+ sfuRoots: sfuViewers.map((viewer) => branch(viewer, new Set())),
+ pending: viewers.filter((viewer) => !included.has(viewer.peerId)),
+ };
+}
diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsx
index 5825f191..80482332 100644
--- a/src/client/pages/HostPage.tsx
+++ b/src/client/pages/HostPage.tsx
@@ -7,6 +7,7 @@ import {
LockKeyhole,
Maximize2,
MonitorUp,
+ Network,
Pause,
Pencil,
Play,
@@ -35,13 +36,14 @@ import { ConnectionDetailsToggle } from "../components/ConnectionDetailsToggle";
import { RoomCode } from "../components/RoomCode";
import { qualityLimitationSummary } from "../components/connection-details";
import {
+ MediaRouteBadge,
PathBadge,
PeerStatusBadge,
SignalStatusBadge,
- TopologyBadge,
WarningBanner,
} from "../components/StatusBadge";
import { StatsGrid } from "../components/StatsGrid";
+import { TopologyView } from "../components/TopologyView";
import { ApiError, createRoom } from "../lib/api";
import { createOpaqueId } from "../lib/opaque-id";
import {
@@ -225,6 +227,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
const [changingQuality, setChangingQuality] = useState(false);
const [sharingPaused, setSharingPaused] = useState(false);
const [showConnectionDetails, setShowConnectionDetails] = useState(false);
+ const [showTopology, setShowTopology] = useState(false);
const videoRef = useRef<HTMLVideoElement | null>(null);
const streamRef = useRef<MediaStream | null>(null);
@@ -283,15 +286,6 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
) ?? null,
[participantPresence],
);
- const hostDirectViewerCount = useMemo(
- () =>
- participantPresence.filter(
- (participant) =>
- participant.role === "viewer" &&
- participant.mediaTopology === "host-direct",
- ).length,
- [participantPresence],
- );
const selectedQualityProfileId = useMemo(
() => matchingQualityProfileId(qualitySettings),
[qualitySettings],
@@ -1523,7 +1517,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
</div>
<p className="section-meta">
{phase === "live"
- ? `${viewers.length}/${maxViewers ?? "-"} 人在线 · ${hostDirectViewerCount} 条 Host 直连`
+ ? `${viewers.length}/${maxViewers ?? "-"} 人在线`
: phase === "starting"
? "正在连接"
: phase === "ended" && room
@@ -2040,35 +2034,65 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
<div className="viewer-panel-heading">
<div>
<h2 id="viewer-heading">观看者</h2>
- <span>
- 在线 {viewers.length}/{maxViewers ?? "-"} · Host 直连{" "}
- {hostDirectViewerCount}
- </span>
+ <span>在线 {viewers.length}/{maxViewers ?? "-"}</span>
</div>
- <Users size={18} aria-hidden="true" />
+ <button
+ className="icon-button"
+ type="button"
+ title={showTopology ? "隐藏连接拓扑" : "显示连接拓扑"}
+ aria-label={showTopology ? "隐藏连接拓扑" : "显示连接拓扑"}
+ aria-controls="room-topology"
+ aria-expanded={showTopology}
+ onClick={() => setShowTopology((current) => !current)}
+ >
+ <Network size={17} aria-hidden="true" />
+ </button>
</div>
+ {showTopology && (
+ <TopologyView
+ hostPeerId={hostPresence?.peerId ?? hostPeerIdRef.current}
+ hostLabel={hostPresence?.displayName ?? displayName}
+ viewers={viewers}
+ />
+ )}
+
<div className="viewer-list">
{viewers.map((viewer) => {
- const snapshot = peerSnapshots.get(viewer.peerId);
+ const snapshot =
+ viewer.upstream.kind === "peer" &&
+ viewer.upstream.peerId ===
+ (hostPresence?.peerId ?? hostPeerIdRef.current)
+ ? peerSnapshots.get(viewer.peerId)
+ : undefined;
const qualityEvidence = viewerQualityEvidence.get(viewer.peerId);
+ const viewerState =
+ snapshot?.connectionState === "connected" || qualityEvidence
+ ? "connected"
+ : snapshot?.connectionState ??
+ (viewer.upstream.kind === "none"
+ ? "connecting"
+ : "assigned");
return (
<article className="viewer-item" key={viewer.peerId}>
<div className="viewer-item-heading">
<div>
<h3 title={viewer.label}>{viewer.label}</h3>
- {snapshot && (
- <PeerStatusBadge state={snapshot.connectionState} />
- )}
+ <PeerStatusBadge state={viewerState} />
</div>
- <TopologyBadge topology={viewer.mediaTopology} />
</div>
+ {showConnectionDetails && viewer.upstream.kind !== "none" && (
+ <div className="viewer-transport-heading">
+ <MediaRouteBadge
+ route={viewer.upstream.kind === "peer" ? "p2p" : "sfu"}
+ />
+ {snapshot?.metrics.path === "relay" && (
+ <PathBadge path="relay" />
+ )}
+ </div>
+ )}
{showConnectionDetails && snapshot && (
<>
- <div className="viewer-transport-heading">
- <span>Host 本机传输</span>
- <PathBadge path={snapshot.metrics.path} />
- </div>
<StatsGrid
metrics={snapshot.metrics}
direction="send"
diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsx
index 73b8fb92..befd37cc 100644
--- a/src/client/pages/ViewerPage.tsx
+++ b/src/client/pages/ViewerPage.tsx
@@ -1105,13 +1105,12 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {
: (peerSnapshot?.connectionState ?? "waiting")
}
/>
- {sfuUpstream ? (
- <MediaRouteBadge route="sfu" />
- ) : showConnectionDetails &&
- peerSnapshot &&
- peerSnapshot.metrics.path !== "unknown" ? (
- <PathBadge path={peerSnapshot.metrics.path} />
- ) : null}
+ {showConnectionDetails && (sfuUpstream || peerSnapshot) && (
+ <>
+ <MediaRouteBadge route={sfuUpstream ? "sfu" : "p2p"} />
+ {(sfuUpstream?.metrics ?? peerSnapshot?.metrics)?.path === "relay" && <PathBadge path="relay" />}
+ </>
+ )}
</div>
</div>
@@ -1293,9 +1292,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {
<h2 id="stats-heading">连接数据</h2>
<div className="viewer-transport-heading">
<MediaRouteBadge route="p2p" />
- {peerSnapshot.metrics.path !== "unknown" && (
- <PathBadge path={peerSnapshot.metrics.path} />
- )}
+ {peerSnapshot.metrics.path === "relay" && <PathBadge path="relay" />}
</div>
<StatsGrid metrics={peerSnapshot.metrics} direction="receive" />
</section>
@@ -1305,10 +1302,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {
<h2 id="sfu-stats-heading">连接数据</h2>
<div className="viewer-transport-heading">
<MediaRouteBadge route="sfu" />
- {sfuUpstream.metrics &&
- sfuUpstream.metrics.path !== "unknown" && (
- <PathBadge path={sfuUpstream.metrics.path} />
- )}
+ {sfuUpstream.metrics?.path === "relay" && <PathBadge path="relay" />}
</div>
{sfuUpstream.metrics && (
<StatsGrid metrics={sfuUpstream.metrics} direction="receive" />
diff --git a/src/client/styles.css b/src/client/styles.css
index fd875f42..86319e78 100644
--- a/src/client/styles.css
+++ b/src/client/styles.css
@@ -803,6 +803,54 @@ h3 {
font-size: 12px;
}
+.topology-view {
+ margin-bottom: 14px;
+ border-block: 1px solid var(--border);
+}
+.topology-tree,
+.topology-tree ul {
+ margin: 0;
+ padding: 0;
+ list-style: none;
+}
+.topology-tree ul {
+ margin-left: 9px;
+ padding-left: 17px;
+ border-left: 1px solid var(--border-strong);
+}
+.topology-tree li {
+ padding: 4px 0;
+}
+.topology-node {
+ display: flex;
+ min-width: 0;
+ align-items: center;
+ gap: 7px;
+ color: var(--text);
+ font-size: 12px;
+}
+.topology-node strong {
+ min-width: 0;
+ overflow-wrap: anywhere;
+}
+.topology-edge,
+.topology-role {
+ flex: 0 0 32px;
+ color: var(--faint);
+ font-size: 10px;
+ font-weight: 700;
+}
+.topology-pending {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 5px 9px;
+ margin-top: 7px;
+ padding-top: 8px;
+ border-top: 1px solid var(--border);
+ color: var(--faint);
+ font-size: 11px;
+}
+
.viewer-list {
display: grid;
gap: 10px;
diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.ts
index 32191336..16f4ed76 100644
--- a/src/server/hybrid-media-router.ts
+++ b/src/server/hybrid-media-router.ts
@@ -4,12 +4,12 @@ import {
MAX_MEDIA_ROUTE_REVISION,
type ClientMessage,
type MediaAssignment,
+ type MediaRouteUpstream,
type ParentEdgeQualityProof,
type ParticipantRouteAssignment,
type RelayDownstreamEdges,
type Role,
type ServerMessage,
- type ViewerMediaTopology,
} from "../shared/protocol.js";
import type { SfuTokenIssuer } from "./livekit-token.js";
import type { SelectedEdgeTurnConfig } from "./config.js";
@@ -417,24 +417,21 @@ export class HybridMediaRouter {
};
}
- getViewerMediaTopology(
+ getViewerRouteUpstream(
roomId: string,
viewerPeerId: string,
- ): ViewerMediaTopology {
+ ): MediaRouteUpstream {
const assignment = this.mediaRouteControllers
.get(roomId)
?.getActiveRoute()
.assignments.get(viewerPeerId);
if (!assignment || assignment.upstream.kind === "none") {
- return "pending";
+ return { kind: "none" };
}
- if (assignment.upstream.kind === "sfu") {
- return "sfu";
+ if (assignment.upstream.kind === "peer") {
+ return { kind: "peer", peerId: assignment.upstream.peerId };
}
- return assignment.upstream.peerId ===
- this.peerRelayTopology.getHostPeerId(roomId)
- ? "host-direct"
- : "peer-relay";
+ return { kind: "sfu" };
}
handleViewerQualityEvidence(input: ForwardedViewerQualityEvidence): void {
diff --git a/src/server/signaling.ts b/src/server/signaling.ts
index 9c1ecf56..40a4d30b 100644
--- a/src/server/signaling.ts
+++ b/src/server/signaling.ts
@@ -1480,7 +1480,7 @@ export class SignalingServer {
role: "host",
peerId: host.peerId,
displayName: hostState.displayName,
- mediaTopology: "host",
+ upstream: { kind: "none" },
});
}
@@ -1501,12 +1501,14 @@ export class SignalingServer {
role: "viewer",
peerId: viewer.peerId,
displayName: viewerState.displayName,
- mediaTopology: this.isHybridMediaEnabled()
- ? this.hybridMediaRouter!.getViewerMediaTopology(
+ upstream: this.isHybridMediaEnabled()
+ ? this.hybridMediaRouter!.getViewerRouteUpstream(
roomId,
viewer.peerId,
)
- : "host-direct",
+ : host
+ ? { kind: "peer", peerId: host.peerId }
+ : { kind: "none" },
});
}
diff --git a/src/shared/protocol.ts b/src/shared/protocol.ts
index 69302851..68524e49 100644
--- a/src/shared/protocol.ts
+++ b/src/shared/protocol.ts
@@ -51,27 +51,31 @@ export const displayNameSchema = z
});
export type DisplayName = z.infer<typeof displayNameSchema>;
-export const viewerMediaTopologySchema = z.enum([
- "host-direct",
- "peer-relay",
- "sfu",
- "pending",
-]);
-export type ViewerMediaTopology = z.infer<typeof viewerMediaTopologySchema>;
-
const opaqueIdSchema = z
.string()
.min(8)
.max(128)
.regex(/^[A-Za-z0-9_-]+$/);
+export const mediaRouteUpstreamSchema = z.discriminatedUnion("kind", [
+ z.object({ kind: z.literal("none") }).strict(),
+ z
+ .object({
+ kind: z.literal("peer"),
+ peerId: opaqueIdSchema,
+ })
+ .strict(),
+ z.object({ kind: z.literal("sfu") }).strict(),
+]);
+export type MediaRouteUpstream = z.infer<typeof mediaRouteUpstreamSchema>;
+
export const participantPresenceEntrySchema = z.discriminatedUnion("role", [
z
.object({
role: z.literal("host"),
peerId: opaqueIdSchema,
displayName: displayNameSchema,
- mediaTopology: z.literal("host"),
+ upstream: z.object({ kind: z.literal("none") }).strict(),
})
.strict(),
z
@@ -79,7 +83,7 @@ export const participantPresenceEntrySchema = z.discriminatedUnion("role", [
role: z.literal("viewer"),
peerId: opaqueIdSchema,
displayName: displayNameSchema,
- mediaTopology: viewerMediaTopologySchema,
+ upstream: mediaRouteUpstreamSchema,
})
.strict(),
]);
@@ -92,7 +96,7 @@ export const viewerPresenceEntrySchema = z
role: z.literal("viewer"),
peerId: opaqueIdSchema,
displayName: displayNameSchema,
- mediaTopology: viewerMediaTopologySchema,
+ upstream: mediaRouteUpstreamSchema,
})
.strict();
export type ViewerPresenceEntry = z.infer<typeof viewerPresenceEntrySchema>;
@@ -332,18 +336,6 @@ export const mediaRouteRevisionSchema = z
export const mediaRoutePhaseSchema = z.enum(["prepare", "active"]);
export type MediaRoutePhase = z.infer<typeof mediaRoutePhaseSchema>;
-export const mediaRouteUpstreamSchema = z.discriminatedUnion("kind", [
- z.object({ kind: z.literal("none") }).strict(),
- z
- .object({
- kind: z.literal("peer"),
- peerId: opaqueIdSchema,
- })
- .strict(),
- z.object({ kind: z.literal("sfu") }).strict(),
-]);
-export type MediaRouteUpstream = z.infer<typeof mediaRouteUpstreamSchema>;
-
export const sfuPublicationGenerationSchema = opaqueIdSchema;
export const participantRouteAssignmentSchema = z
diff --git a/tests/client-state.test.ts b/tests/client-state.test.ts
index 882a00ab..af61f8a1 100644
--- a/tests/client-state.test.ts
+++ b/tests/client-state.test.ts
@@ -25,6 +25,7 @@ import {
shouldReconnectSignaling,
SignalingClient,
} from "../src/client/lib/signaling.ts";
+import { deriveParticipantTopology } from "../src/client/lib/participant-topology.ts";
import { labelViewerPresence } from "../src/client/lib/viewer-presence.ts";
import { qualityEvidenceWindowFromMetrics } from "../src/client/media/viewer-quality-evidence.ts";
import { createStatsAccumulator, collectConnectionMetrics } from "../src/client/webrtc/stats.ts";
@@ -59,19 +60,19 @@ describe("browser-local display name", () => {
role: "viewer",
peerId: "viewer_AAAAAAsuffix",
displayName: "同名",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: "host_12345678" },
},
{
role: "viewer",
peerId: "viewer_BBBBBBsuffix",
displayName: "同名",
- mediaTopology: "peer-relay",
+ upstream: { kind: "peer", peerId: "viewer_AAAAAAsuffix" },
},
{
role: "viewer",
peerId: "viewer_independent",
displayName: "朋友",
- mediaTopology: "sfu",
+ upstream: { kind: "sfu" },
},
]);
@@ -81,6 +82,42 @@ describe("browser-local display name", () => {
expect(labeled[2].peerIdSuffix).toHaveLength(6);
expect(labeled[0].label).toContain("同名 (");
});
+
+ it("derives exact peer and SFU branches without guessing orphaned routes", () => {
+ const viewer = (
+ peerId: string,
+ upstream:
+ | { kind: "none" }
+ | { kind: "sfu" }
+ | { kind: "peer"; peerId: string },
+ ) => ({ role: "viewer" as const, peerId, displayName: peerId, upstream });
+ const topology = deriveParticipantTopology(
+ "host_12345678",
+ labelViewerPresence([
+ viewer("viewer_root_1", { kind: "peer", peerId: "host_12345678" }),
+ viewer("viewer_child_1", { kind: "peer", peerId: "viewer_root_1" }),
+ viewer("viewer_sfu_1", { kind: "sfu" }),
+ viewer("viewer_sfu_child", {
+ kind: "peer",
+ peerId: "viewer_sfu_1",
+ }),
+ viewer("viewer_pending", { kind: "none" }),
+ viewer("viewer_orphan", { kind: "peer", peerId: "viewer_offline" }),
+ ]),
+ );
+
+ expect(topology.peerRoots[0].viewer.peerId).toBe("viewer_root_1");
+ expect(topology.peerRoots[0].children[0].viewer.peerId).toBe(
+ "viewer_child_1",
+ );
+ expect(topology.sfuRoots[0].children[0].viewer.peerId).toBe(
+ "viewer_sfu_child",
+ );
+ expect(topology.pending.map((entry) => entry.peerId)).toEqual([
+ "viewer_pending",
+ "viewer_orphan",
+ ]);
+ });
});
describe("client session identity", () => {
diff --git a/tests/protocol.test.ts b/tests/protocol.test.ts
index bfc94698..e4e205c4 100644
--- a/tests/protocol.test.ts
+++ b/tests/protocol.test.ts
@@ -726,7 +726,7 @@ describe("server signaling protocol", () => {
role: "viewer",
peerId: "viewer_12345678",
displayName: "小明",
- mediaTopology: "peer-relay",
+ upstream: { kind: "peer", peerId: "viewer_parent_12345678" },
} as const;
expect(
serverMessageSchema.safeParse({
@@ -740,6 +740,12 @@ describe("server signaling protocol", () => {
viewers: [viewer, viewer],
}).success,
).toBe(false);
+ expect(
+ serverMessageSchema.safeParse({
+ type: "viewer-presence",
+ viewers: [{ ...viewer, mediaTopology: "peer-relay" }],
+ }).success,
+ ).toBe(false);
expect(
serverMessageSchema.safeParse({
type: "viewer-presence",
@@ -755,7 +761,7 @@ describe("server signaling protocol", () => {
role: "host",
peerId: "host_12345678",
displayName: "分享者",
- mediaTopology: "host",
+ upstream: { kind: "none" },
},
],
}).success,
diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.ts
index 53e9724c..c88850ba 100644
--- a/tests/server-signal.test.ts
+++ b/tests/server-signal.test.ts
@@ -1077,7 +1077,7 @@ describe("WebSocket signaling", () => {
it("reports every online Viewer without expanding the Host media fanout", async () => {
const harness = await startHarness({ peerAssistedMedia: true });
const host = await openClient(harness.webSocketUrl);
- await authenticate(
+ const hostAuth = await authenticate(
host,
harness.room,
"host",
@@ -1111,7 +1111,9 @@ describe("WebSocket signaling", () => {
(message) =>
viewerPresenceEntries(message).length === 3 &&
viewerPresenceEntries(message).some(
- (viewer) => viewer.mediaTopology === "peer-relay",
+ (viewer) =>
+ viewer.upstream.kind === "peer" &&
+ viewer.upstream.peerId !== hostAuth.peerId,
),
);
expect(viewerPresenceEntries(full).map((viewer) => viewer.displayName)).toEqual([
@@ -1121,9 +1123,23 @@ describe("WebSocket signaling", () => {
]);
expect(
viewerPresenceEntries(full).filter(
- (viewer) => viewer.mediaTopology === "host-direct",
+ (viewer) =>
+ viewer.upstream.kind === "peer" &&
+ viewer.upstream.peerId === hostAuth.peerId,
),
).toHaveLength(2);
+ const relay = viewerPresenceEntries(full).find(
+ (viewer) =>
+ viewer.upstream.kind === "peer" &&
+ viewer.upstream.peerId !== hostAuth.peerId,
+ )!;
+ const relayParentPeerId =
+ relay.upstream.kind === "peer" ? relay.upstream.peerId : null;
+ expect(
+ viewerPresenceEntries(full).some(
+ (viewer) => viewer.peerId === relayParentPeerId,
+ ),
+ ).toBe(true);
viewers[2].socket.send(
JSON.stringify({ type: "set-display-name", displayName: "后来改名" }),
@@ -1165,7 +1181,7 @@ describe("WebSocket signaling", () => {
role: "host",
peerId: hostAuth.peerId,
displayName: "原始分享者",
- mediaTopology: "host",
+ upstream: { kind: "none" },
});
const viewer = await openClient(harness.webSocketUrl);
@@ -1227,7 +1243,7 @@ describe("WebSocket signaling", () => {
await firstHost.inbox.next("viewer-presence");
const viewer = await openClient(harness.webSocketUrl);
- await authenticate(
+ const viewerAuth = await authenticate(
viewer,
harness.room,
"viewer",
@@ -1248,6 +1264,9 @@ describe("WebSocket signaling", () => {
(message) => hostPresenceEntry(message) === undefined,
);
expect(offline.viewers.some((entry) => entry.role === "host")).toBe(false);
+ expect(viewerPresenceEntries(offline)).toMatchObject([
+ { peerId: viewerAuth.peerId, upstream: { kind: "none" } },
+ ]);
const replacement = await openClient(harness.webSocketUrl);
const replacementAuth = await authenticate(
@@ -1272,7 +1291,7 @@ describe("WebSocket signaling", () => {
it("publishes one empty Viewer roster after ordinary rotate and revoke", async () => {
const harness = await startHarness();
const host = await openClient(harness.webSocketUrl);
- await authenticate(
+ const hostAuth = await authenticate(
host,
harness.room,
"host",
@@ -1303,7 +1322,7 @@ describe("WebSocket signaling", () => {
role: "viewer",
peerId: firstViewerAuth.peerId,
displayName: "第一位",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: hostAuth.peerId },
},
]);
@@ -5804,7 +5823,7 @@ describe("WebSocket signaling", () => {
it("replaces the same client presence once without leave churn", async () => {
const harness = await startHarness({ viewerDisconnectGraceMs: 40 });
const host = await openClient(harness.webSocketUrl);
- await authenticate(
+ const hostAuth = await authenticate(
host,
harness.room,
"host",
@@ -5832,7 +5851,7 @@ describe("WebSocket signaling", () => {
role: "viewer",
peerId: originalAuth.peerId,
displayName: "旧会话",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: hostAuth.peerId },
},
]);
@@ -5858,7 +5877,7 @@ describe("WebSocket signaling", () => {
role: "viewer",
peerId: originalAuth.peerId,
displayName: "新会话",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: hostAuth.peerId },
},
]);
await host.inbox.expectNone(70);
@@ -6030,7 +6049,7 @@ describe("WebSocket signaling", () => {
it("keeps media identity through grace while presence returns once", async () => {
const harness = await startHarness({ viewerDisconnectGraceMs: 500 });
const firstHost = await openClient(harness.webSocketUrl);
- await authenticate(
+ const firstHostAuth = await authenticate(
firstHost,
harness.room,
"host",
@@ -6060,7 +6079,7 @@ describe("WebSocket signaling", () => {
role: "viewer",
peerId: firstViewerAuth.peerId,
displayName: "短线重连",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: firstHostAuth.peerId },
},
]);
firstHost.socket.send(
@@ -6120,7 +6139,7 @@ describe("WebSocket signaling", () => {
role: "viewer",
peerId: firstViewerAuth.peerId,
displayName: "短线重连",
- mediaTopology: "host-direct",
+ upstream: { kind: "peer", peerId: secondHostAuth.peerId },
},
]);
await secondHost.inbox.expectNone(30);