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.mdindex 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.mdindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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><StatsGridmetrics={snapshot.metrics}direction="send"diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex 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.cssindex 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.tsindex 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.tsindex 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.tsindex 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 = zrole: 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 = zexport 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 = zdiff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex 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.tsindex 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.tsindex 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);