SuperAPI AI 工具集

realtime-transport-contracts

前端与建站

查看项目

更新于 10-16 06:44

技能介绍

用途:在 WebSocket 或 SSE 客户端跨断连恢复时,把重连、续传、去重、乱序、保活、背压和重新鉴权等环节定义为显式契约,而非依赖框架默认行为。前提是把连接视为不可靠、每个增量都可能重复、乱序或缺失。

主要能力与要求:1)重连退避:使用带上限的指数退避加抖动,如 sleep = random(0, min(cap, base * 2**attempt));仅在连接稳定超过一个稳定窗口后重置尝试计数;仅对可重试关闭码(1006 异常、1011 服务错误、1012 重启、1013 稍后重试)重试,不对鉴权/策略码(1008、应用层 4xxx)或协议错误(1002/1003)循环重试。EventSource 自动重连,需主动调用 .close() 停止,204 响应会让浏览器停止重试。2)续传:重连后须重新订阅并从位置恢复。SSE 会自动发送 Last-Event-ID,条件是服务端发过 id: 行且未被重置、服务端确实按该头重放。WebSocket 需自行发送最后已应用的游标/序号,否则出现缺口或重复快照。3)增量折叠:以单调递增的服务端序号/版本为键,丢弃 seq <= lastApplied,将 seq > 期望值的放入小型重排缓冲,无法补齐的空缺应重新拉快照而非插值;避免忽略序号的 last-writer-wins 合并。4)快照与流在同一游标上对账,只应用比快照版本更新的增量并回填缺口。5)心跳与存活探测:readyState 为 OPEN 的 socket 仍可能是僵尸;浏览器 JS 无法发送协议级 ping/pong,需应用层 ping 加超时,未收到 pong 则关闭重连,并结合 navigator.onLine 与 Page Visibility 控制重连。6)背压:轮询 bufferedAmount 并在超过阈值时限流或合并发送,同时限制入站队列;发送缓冲满时浏览器会强制关闭连接。7)长连接鉴权刷新:在令牌过期前通过带内推送新令牌或带新令牌重连,并定义明确的 reauth-required 信号。

使用方式:可按提示中的 ripgrep 命令定位 new WebSocket、new EventSource、reconnect、backoff、Last-Event-ID、bufferedAmount、heartbeat、token 等代码路径,再按契约逐项核对。

适用场景与限制:适用于自研实时客户端;若使用 Socket.IO、Phoenix Channels、Ably、Pusher、@microsoft/signalr、TanStack Query streaming 等已内置退避抖动、续传和心跳的库,应先检查其配置,避免误报。短生命周期的请求级 socket 不适用。本技能不处理令牌如何轮换(见 frontend-auth-flow-contracts)、令牌放 URL 与头部的安全取舍(见 frontend-security-baseline)、SSR 首屏水合不一致(见 ssr-hydration-mismatch)及 WebView 桥接(见 webview-bridge-pages)。

输出形态:按契约、证据(文件/行与连接/应用路径、关闭码或症状)、风险、最小修复、验证用失败序列测试的紧凑结构给出。