dsh_shenxian/src/net/relay/jitter.ts

/**
 * 覆盖网络 · **链路抖动（jitter）采样 · 直方图 · 选路主序**（序 ㉖ · 骨干稳定选路与加密）。
 *
 * ## 为什么需要它（用户口径 → 机器判据）
 *
 * 用户 2026-09-17 20:2x 的口径是「**按照连接稳定高效的方式 数据安全可加密传输**」。翻译成
 * 可验证的工程质量判据就是 **"选路看 jitter、⛔ 不看 RTT"**：
 *
 * - 改造前：`directory.ts` 的候选序 = **签名目录发布序**（同源优先插首位），`switcher.ts` 的换址
 *   = **排除当前 + 排除冷却中的 ⇒ 取链里下一个** ⇒ 两处**都没有**"哪条更稳"这个维度。
 * - 后果：一条 RTT 低但**抖得厉害**的路径会长期霸占首位 —— 而"稳定"恰恰是交互式会话的第一诉求
 *   （RTT 高只是慢，jitter 高是**卡顿/超时/断连**）。
 *
 * ## 三条口径（⛔ 改这三条等于改判据，必须同步改参数表）
 *
 * 1. **量 = `|ΔRTT|` 的 p95**（相邻两次心跳往返之差的绝对值），与 `scripts/overlay-jitter.cjs`
 *    序⑥ 实测所用的**同一个量**（`p95AbsDelta`）⇒ 历史读数（`p95 = 3 ms`）与本模块**同口径可比**。
 * 2. **序 = jitter 升序**，且 **只对"已测出样本"的候选生效**；**无样本者保原序排在其后**
 *    （⛔ 不惩罚"还没测过的备用中继"，也不凭空给它排位 —— 见 {@link orderByJitter}）。
 * 3. **零样本 ⇒ 逐字返回原数组**（⛔ 这是零回归的机器判据 `D9`：观测器没喂过数，
 *    行为必须与改造前**逐字一致**）。
 *
 * ## 为什么只有这一份算法
 *
 * relay 侧（`server.ts` 的每会话 RTT）与平台侧（`switcher.ts` 的选路）**共用**本模块的
 * `absDeltas` / `percentile` / `histogram` —— 本线的教训是「**另一份实现 = 另一处静默失效**」
 * （取址链踩过两次）。⛔ 不许在 `scripts/**` 或别的模块里再写一份 p95/直方图。
 *
 * ## 阈值来源（⛔ 全部来自参数表，模块内零魔数）
 *
 * `JITTER_ENABLE` / `JITTER_SAMPLE_MAX` / `JITTER_MIN_SAMPLES` / **`JITTER_LIMIT_MS`** /
 * `JITTER_HIST_MAX_MS` / `JITTER_HIST_BUCKETS` / `JITTER_SAMPLE_GAP_MS`
 * （口径见 `参数表_覆盖网络_20260917.md §3.7`）。
 *
 * 🔴 **劣化阈值复用 `JITTER_LIMIT_MS`（⛔ 不新造 `JITTER_SWITCH_MS`）**：该键在序⑥ 就已登记
 * （值 `20 ms`，语义 = `p95(|ΔRTT|)` 的**达标限值**）—— "超标"与"劣化到该换路"是**同一件事**
 * ⇒ 新造一个同值键只会变成"同一事实两处写"（本线的知识碎片化教训）。
 *
 * @module src/net/relay/jitter
 */

/** 本模块的阈值（**全部**来自参数表；见模块头）。 */
export interface JitterThresholds {
  /** 总开关（`JITTER_ENABLE`，默认 `1`）。置 `0` ⇒ 采样与排序**全部失效**回到改造前行为。 */
  enabled: boolean
  /** 每个 url 保留的 RTT 样本上限（环状，老的丢弃）。 */
  sampleMax: number
  /** 参与排序 / 劣化判定所需的**最小 |ΔRTT| 样本数**（不足 ⇒ 该 url 视为"未知"）。 */
  minSamples: number
  /**
   * **劣化阈值**：`p95(|ΔRTT|) ≥ 它` ⇒ 这条路径被判"不稳"，允许换到更稳的候选。
   *
   * ⚠️ 来源 = 参数表的 **`JITTER_LIMIT_MS`**（序⑥ 就有的"达标限值"；⛔ 不是新键）。
   */
  switchMs: number
  /** 直方图上界（`≥ 它` 的样本落进末桶）。 */
  histMaxMs: number
  /** 直方图桶数（**固定值**；探针拿它校验"口径一致"，⛔ 不是实现细节）。 */
  histBuckets: number
  /**
   * **同一份缓存读数的最小采样间隔（ms）**。
   *
   * 🔴 为什么必须有这个键：`RelayClient.status().rttMs` 是**上一次心跳的结果**，而心跳周期
   * （`HB_SEC = 15 s`）远大于巡检周期（`checkMs = 2 s`）⇒ 不做门限的话**同一个 RTT 值会被
   * 反复记录** ⇒ 差分恒为 0 ⇒ **jitter 被系统性低估到 0**（判据假绿）。
   * ⇒ 门限必须 **> 心跳周期**：同一份缓存值最多只贡献一个样本。
   *
   * ⚠️ relay 侧（`server.ts`）**不用**这个键 —— 它在 `PONG` 到达那一刻采样，本来就是新测量。
   */
  sampleGapMs: number
}

/**
 * 从 env 读阈值（**值格必须纯数字**；非纯数字一律回退默认值）。
 *
 * ⚠️ 与 `relayFailoverThresholds` 同款纪律：参数表里写 `1` / `0`，⛔ **不许**写 `true` 或
 * 带夹注的 `1（默认）` —— 后者解析失败会**静默回退默认值**（本线已踩过一次）。
 */
export function jitterThresholds(env: Record<string, string | undefined> = process.env): JitterThresholds {
  const num = (key: string, dflt: number): number => {
    const raw = (env[key] ?? '').trim()
    if (raw === '') return dflt
    return /^\d+$/.test(raw) ? Number(raw) : dflt
  }
  return {
    enabled: num('JITTER_ENABLE', 1) !== 0,
    sampleMax: num('JITTER_SAMPLE_MAX', 32),
    minSamples: num('JITTER_MIN_SAMPLES', 3),
    switchMs: num('JITTER_LIMIT_MS', 20),
    histMaxMs: num('JITTER_HIST_MAX_MS', 200),
    histBuckets: num('JITTER_HIST_BUCKETS', 8),
    sampleGapMs: num('JITTER_SAMPLE_GAP_MS', 20_000),
  }
}

/**
 * 相邻样本的一阶差分绝对值 = **抖动量**（⛔ 不是标准差）。
 *
 * 🔴 为什么不用标准差：标准差会把"单调漂移"（排队时延缓慢变化）算成抖动，而交互式会话真正
 * 怕的是**相邻两拍之间的突变**（卡一下）。序⑥ 的实测口径同样是相邻差分 ⇒ 保持一致。
 */
export function absDeltas(samples: readonly number[]): number[] {
  const out: number[] = []
  for (let i = 1; i < samples.length; i++) {
    const d = Math.abs(samples[i]! - samples[i - 1]!)
    if (Number.isFinite(d)) out.push(d)
  }
  return out
}

/**
 * 百分位（**与 `scripts/overlay-jitter.cjs` 逐字同口径**：`sorted[min(len-1, floor(len·p))]`）。
 *
 * ⚠️ 口径必须与脚本一致，否则"实时选路看到的 p95"与"运维点测的 p95"会给出**两个数**。
 */
export function percentile(values: readonly number[], p: number): number {
  if (values.length === 0) return 0
  const s = [...values].sort((a, b) => a - b)
  return s[Math.min(s.length - 1, Math.floor(s.length * p))]!
}

/** 直方图（等宽桶；`≥ histMaxMs` 落末桶）。返回值长度**恒等于** `buckets`。 */
export function histogram(deltas: readonly number[], histMaxMs: number, buckets: number): number[] {
  const out = new Array<number>(Math.max(1, buckets)).fill(0)
  if (histMaxMs <= 0) return out
  const n = out.length
  for (const d of deltas) {
    const idx = Math.min(n - 1, Math.max(0, Math.floor((d / histMaxMs) * n)))
    out[idx] = (out[idx] ?? 0) + 1
  }
  return out
}

/** 一组样本的抖动画像。 */
export interface JitterStats {
  /** 已采到的 RTT 样本数。 */
  samples: number
  /** `|ΔRTT|` 样本数（= `samples - 1`，样本不足 2 时为 0）。 */
  deltas: number
  p95AbsDeltaMs: number
  meanAbsDeltaMs: number
  maxAbsDeltaMs: number
  /** 直方图（长度 = `histBuckets`）。 */
  hist: number[]
}

/** 由**已在别处算好的差分序列**构造画像（relay 侧多会话合并时用；⛔ 不重复实现统计）。 */
export function statsFromDeltas(deltas: readonly number[], th: JitterThresholds): JitterStats {
  const sum = deltas.reduce((a, b) => a + b, 0)
  return {
    samples: deltas.length + 1,
    deltas: deltas.length,
    p95AbsDeltaMs: round2(percentile(deltas, 0.95)),
    meanAbsDeltaMs: deltas.length === 0 ? 0 : round2(sum / deltas.length),
    maxAbsDeltaMs: deltas.length === 0 ? 0 : round2(Math.max(...deltas)),
    hist: histogram(deltas, th.histMaxMs, th.histBuckets),
  }
}

function round2(v: number): number {
  return Math.round(v * 100) / 100
}

/**
 * **每个 url 一份的 RTT 样本环 + 抖动画像**（进程内单例，见 {@link sharedJitterTracker}）。
 *
 * ⛔ 它**不做 I/O**、不定时、不联网 —— 采样由调用方喂（relay 侧 = PONG 回来的那一刻；
 * 平台侧 = 当前通道的 `status().rttMs`）。这样本模块可以在单测里被**逐项断言**。
 */
export class JitterTracker {
  private readonly th: JitterThresholds
  private readonly rings = new Map<string, number[]>()

  constructor(th: Partial<JitterThresholds> = {}) {
    this.th = { ...jitterThresholds(), ...th }
  }

  /** 阈值快照（调用方据此做判定，⛔ 不许各自再读一遍 env）。 */
  thresholds(): JitterThresholds {
    return this.th
  }

  /** 是否开启（`JITTER_ENABLE=0` ⇒ 采样与排序全部失效）。 */
  get enabled(): boolean {
    return this.th.enabled
  }

  /**
   * 记一次 RTT 样本。
   *
   * 非法输入（非有限数 / 负数）**静默丢弃并返回 `false`** —— 这里故意不抛：
   * 采样点在生产路径上（每 15 s 一次心跳），抛异常会把**选路**带崩，
   * 而"少一个样本"只影响排序精度。⛔ 但**不静默吞掉"整条通道读不到 RTT"**：那是
   * `switcher.ts` 的 `jitterAlerts` / 探针 `OBS-19` 负责点名的分工。
   */
  record(url: string, rttMs: number): boolean {
    if (!this.th.enabled) return false
    if (url === '' || !Number.isFinite(rttMs) || rttMs < 0) return false
    const ring = this.rings.get(url) ?? []
    ring.push(rttMs)
    const max = Math.max(2, this.th.sampleMax)
    if (ring.length > max) ring.splice(0, ring.length - max)
    this.rings.set(url, ring)
    return true
  }

  /** 该 url 的画像；**样本不足 `minSamples` 个差分 ⇒ `undefined`（= 未知，⛔ 不当 0 用）**。 */
  stats(url: string): JitterStats | undefined {
    const ring = this.rings.get(url)
    if (ring === undefined || ring.length < 2) return undefined
    const st = statsFromDeltas(absDeltas(ring), this.th)
    if (st.deltas < this.th.minSamples) return undefined
    return st
  }

  /** 该 url 的 jitter（`undefined` = 未知）。 */
  jitterMs(url: string): number | undefined {
    return this.stats(url)?.p95AbsDeltaMs
  }

  /** 已采过样的 url（信息输出 / 观测用）。 */
  urls(): string[] {
    return [...this.rings.keys()].sort()
  }

  /** 全量快照（**只读**副本；给 `/status` 与探针用）。 */
  snapshot(): { url: string; samples: number; jitterMs?: number }[] {
    return this.urls().map((url) => {
      const st = this.stats(url)
      return {
        url,
        samples: this.rings.get(url)?.length ?? 0,
        ...(st === undefined ? {} : { jitterMs: st.p95AbsDeltaMs }),
      }
    })
  }

  /** 清空（测试与"配置热更"用；⛔ 生产路径不调它）。 */
  reset(): void {
    this.rings.clear()
  }
}

/**
 * **候选排序：jitter 为主序**（`E1` 的实现本体）。
 *
 * 语义（⛔ 三条都要照做，改一条就等于改判据）：
 * 1. **已测出样本**（差分 ≥ `minSamples`）的候选按 `jitter` **升序**在前 —— 并列时**保原相对序**；
 * 2. **未测出样本**的候选按**原相对序**排在其后 —— ⛔ 不把"没测过"当成"很差"（那会让**备用中继
 *    永远排最后 ⇒ 永远不被使用 ⇒ 永远测不出来**，形成死角），也⛔ 不把它当成"很好"（那会让
 *    推荐序失去意义）；
 * 3. **一个都没测出来 ⇒ 返回原数组本身**（`D9`：零回归的机器判据）。
 *
 * ⚠️ 排序必须 **stable**（同 key 保原序）—— 否则同源优先、目录发布序这些**已有语义**会被
 * 一次抖动采样随机洗牌 ⇒ 那是净退化（R11）。
 */
export function orderByJitter(
  urls: readonly string[],
  tracker: JitterTracker | undefined,
  minSamples?: number,
): readonly string[] {
  if (tracker === undefined || !tracker.enabled || urls.length < 2) return urls
  const th = tracker.thresholds()
  const need = minSamples ?? th.minSamples
  const known: { url: string; jitterMs: number; idx: number }[] = []
  for (let i = 0; i < urls.length; i++) {
    const url = urls[i]!
    const st = tracker.stats(url)
    if (st === undefined || st.deltas < need) continue
    known.push({ url, jitterMs: st.p95AbsDeltaMs, idx: i })
  }
  /** ③ 零已知 ⇒ 原数组（⛔ 连新数组都不建：`D9` 要的是"逐字一致"）。 */
  if (known.length === 0) return urls
  known.sort((a, b) => (a.jitterMs === b.jitterMs ? a.idx - b.idx : a.jitterMs - b.jitterMs))
  const pinned = new Set(known.map((k) => k.url))
  return [...known.map((k) => k.url), ...urls.filter((u) => !pinned.has(u))]
}

/**
 * **"jitter 劣化即切"的挑人单点判据**（`E2` 的实现本体）。
 *
 * 规则（⛔ 只有这一处实现；`switcher.ts` 只负责调用 + 记数 + 告警）：
 * - 当前通道 jitter `< switchMs` ⇒ `undefined`（**没劣化，一步都不许动**）；
 * - 否则在候选里找 **① 不是当前 ② 不在 `blocked` 里**（`blocked` = 当前 + 冷却中的，
 *   ⛔ **jitter 换址没有打破冷却的权力** —— 豁免权只属于"当前这条已经挂了"这条语义，见 `switcher.ts`）
 *   且 **jitter 已知且严格更小** 的最小者；
 * - 找不到 ⇒ `undefined`（**原地不动**，⛔ 不切空、⛔ 不静默回退默认机）。
 */
export function pickJitterTarget(opts: {
  urls: readonly string[]
  tracker: JitterTracker | undefined
  curUrl: string
  curJitterMs: number
  switchMs: number
  minSamples?: number
  blocked?: ReadonlySet<string>
}): { url: string; jitterMs: number } | undefined {
  const { urls, tracker, curUrl, curJitterMs, switchMs, blocked } = opts
  if (tracker === undefined || !tracker.enabled) return undefined
  if (!Number.isFinite(curJitterMs) || curJitterMs < switchMs) return undefined
  const need = opts.minSamples ?? tracker.thresholds().minSamples
  let best: { url: string; jitterMs: number } | undefined
  for (const url of urls) {
    if (url === curUrl) continue
    if (blocked !== undefined && blocked.has(url)) continue
    const st = tracker.stats(url)
    if (st === undefined || st.deltas < need) continue
    const j = st.p95AbsDeltaMs
    if (j >= curJitterMs) continue
    if (best === undefined || j < best.jitterMs) best = { url, jitterMs: j }
  }
  return best
}

/**
 * **进程级共享 tracker**（`switcher.ts` 采样 / `directory.ts` 排序 / relay `/status` 观测
 * 都用它 ⇒ 装配点**零改动**）。
 *
 * 🔴 为什么必须是单例：装配点（`src/web/server.ts` / `src/worker/relay-tunnel.ts` /
 * `src/net/relay/main.ts`）**不在序㉖ 的在册文件集**内 ⇒ 若把 tracker 做成"构造时注入"，
 * 生产上**永远不会被注入** ⇒ 本序所有判据都变成**静默失效**（装了但一次都没生效）。
 * 单例把"接线"这件事**从装配点挪进模块内部**，代价是"测试要能换掉它" ⇒ 见
 * {@link setSharedJitterTracker}。
 */
let shared: JitterTracker | undefined

export function sharedJitterTracker(): JitterTracker {
  if (shared === undefined) shared = new JitterTracker()
  return shared
}

/** 注入/清空共享 tracker（**只有单测用**）。 */
export function setSharedJitterTracker(t: JitterTracker | undefined): void {
  shared = t
}