@genee/omp-opsx-addon 0.1.0

package/lib/usage-redis-probe.ts

@@ -0,0 +1,389 @@
+/**
+ * Redis probe 状态机 + write-through 镜像 + prefetch/reconcile。
+ *
+ * 全局聚合语义（跨 session 累加在写入侧完成，展示侧只读不聚合）：
+ * 1. probe 状态机：`unknown` 立即 / `healthy` 每 `probeIntervalMs` 心跳 / `unhealthy`
+ *    每 `unhealthyRetryMs` 退避重试，全部绝对时间门控（由 poller 1s tick 驱动，无新 timer）
+ * 2. write-through 镜像（全 fire-and-forget：同步返回、绝不 throw、绝不重试，失败只置
+ *    `mirrorFailed`，由 `observeMirrorFailure` 观察后翻 `unhealthy`）：
+ *    - `onDelta`：秒级事件级 `HINCRBY opsx:usage:sec:<abssec> <provider> <delta>` +
+ *      `EXPIRE`（跨 session 在写入时天然累加）
+ *    - `onTotalsDelta`：累计级 `HINCRBY opsx:usage:totals <provider>:total|input|output`
+ *      （无 TTL——totals 是永久累计）
+ * 3. prefetch：healthy 时每 tick pipeline 读秒窗口（nowSec-60 .. nowSec-2，2s 滞后）的
+ *    全部 sec key + `opsx:usage:totals`，解析成 `RedisSnapshot`；totals 在 Redis 缺失时
+ *    用文件值兜底（Redis 重启的 ≤30s 空窗）；失败翻 unhealthy 并 rethrow（poller 回退文件）
+ * 4. reconcile：healthy 时逐 key 覆盖——`HSET opsx:usage:totals`（文件全量）+ 冻结秒
+ *    `HSET opsx:usage:sec:<sec> <provider> <值>` + `EXPIRE`，跳过当前进行中秒；禁止增量
+ *    合并；无 DEL+整体重建、无 owner 选举、无锁
+ *
+ * 语义硬约束：
+ * - key 结构 `opsx:usage:sec:<abssec>`（field `<provider>`）与 `opsx:usage:totals`
+ *   （field `<provider>:total|input|output`）
+ * - `ttlSec = round(ttlMs / 1000)` 只作用于 sec key；totals 永久
+ * - client 懒建：命令前若 `client == null` 则经 `clientFactory` 新建（失败后旧 client
+ *   失效置 null，下次命令重建）
+ * - await 路径失败 → close + 置 null + 翻 unhealthy；fire-and-forget 失败 → 只置 mirrorFailed
+ * - provider 含 `:` → 写入侧防御跳过该次镜像并置 mirrorFailed；解析侧防御跳过（防 id
+ *   引入 `:` 导致 field 错位）
+ * - 不新增 timer/interval（所有节奏门控由 poller 的现有 1s tick 驱动）
+ */
+
+import { RedisClient, type RedisReply, type RedisTransport } from './usage-redis-client.js';
+
+// ── 类型 ────────────────────────────────────────────────────────────────
+
+/** probe 状态机：内存态，不持久化（重启回 `unknown`，下个 tick 立即探测）。 */
+export type RedisState = 'unknown' | 'healthy' | 'unhealthy';
+
+/** `RedisRelay` 构造参数。 */
+export interface RedisRelayOptions {
+    host: string;
+    port: number;
+    /** 连接超时 ms（透传 `RedisClient`）。 */
+    connectTimeoutMs: number;
+    /** 单命令往返超时 ms（透传 `RedisClient`）。 */
+    commandTimeoutMs: number;
+    /** healthy 心跳 PING 周期 ms（默认 30000）。 */
+    probeIntervalMs: number;
+    /** unhealthy 退避重试 PING 周期 ms（默认 5000）。 */
+    unhealthyRetryMs: number;
+    /** reconcile 周期 ms（默认 30000）。 */
+    reconcileIntervalMs: number;
+    /** sec key 的 TTL ms（默认 180000）。 */
+    ttlMs: number;
+    /** 连接工厂透传（测试 seam）。 */
+    transport?: RedisTransport;
+    /** 测试 seam：绝对时间源（默认 `Date.now`）。 */
+    now?: () => number;
+}
+
+/**
+ * 结构化 realtime 权威数据：GLOBAL cross-session aggregates（poller 的
+ * `RealtimeFile` 自动兼容）。
+ */
+export interface RealtimeLike {
+    /** provider → 累计三元组。 */
+    totals?: Record<string, { total: number; input: number; output: number }>;
+    /** unix second → provider → tokens（全局和）。 */
+    seconds?: Record<string, Record<string, number>>;
+}
+
+/** prefetch 返回的 Redis 快照（全局聚合，可直接渲染）。 */
+export interface RedisSnapshot {
+    /** provider → bucket。 */
+    totals: Record<string, { total: number; input: number; output: number }>;
+    /** provider → {secStr: tokens}。 */
+    perSecond: Record<string, Record<string, number>>;
+}
+
+// ── field 解析（对 `:` 前置假设防御）────────────────────────────────────
+
+/** 解析 totals field `<provider>:total|input|output`；非三者或段空则跳过。 */
+function parseTotalsField(
+    field: string,
+    value: string,
+): { provider: string; metric: 'total' | 'input' | 'output'; num: number } | null {
+    const parts = field.split(':');
+    if (parts.length !== 2) return null;
+    const [provider, metric] = parts;
+    if (!provider || !metric) return null;
+    if (metric !== 'total' && metric !== 'input' && metric !== 'output') return null;
+    const num = Number(value);
+    if (!Number.isFinite(num)) return null;
+    return { provider, metric, num };
+}
+
+// ── RedisRelay ──────────────────────────────────────────────────────────
+
+/**
+ * Redis probe 状态机 + write-through 镜像 + prefetch/reconcile（见文件头）。
+ *
+ * 不新增 timer：所有 tick 步骤由 poller 的现有 1s `renderTimer` firing 内绝对时间门控调用。
+ */
+export class RedisRelay {
+    private readonly host: string;
+    private readonly port: number;
+    private readonly connectTimeoutMs: number;
+    private readonly commandTimeoutMs: number;
+    private readonly probeIntervalMs: number;
+    private readonly unhealthyRetryMs: number;
+    private readonly reconcileIntervalMs: number;
+    private readonly ttlSec: number;
+    private readonly transport: RedisTransport | undefined;
+    private readonly now: () => number;
+    private readonly clientFactory: () => RedisClient;
+
+    /** 懒建 client：命令前若为 null 则经 `clientFactory` 新建；失败后 close + 置 null。 */
+    private client: RedisClient | null = null;
+    private _state: RedisState = 'unknown';
+
+    /** 任一镜像写（fire-and-forget）失败/超时置 true；`observeMirrorFailure` 消费后翻 unhealthy。 */
+    mirrorFailed = false;
+    /** 最近一次探测尝试的绝对时间戳（含失败尝试）。 */
+    lastProbeAt = 0;
+    /** 最近一次成功 reconcile 的绝对时间戳；0 = 从未 reconcile（首 tick 立即 reconcile）。 */
+    lastReconcileAt = 0;
+
+    constructor(opts: RedisRelayOptions) {
+        this.host = opts.host;
+        this.port = opts.port;
+        this.connectTimeoutMs = opts.connectTimeoutMs;
+        this.commandTimeoutMs = opts.commandTimeoutMs;
+        this.probeIntervalMs = opts.probeIntervalMs;
+        this.unhealthyRetryMs = opts.unhealthyRetryMs;
+        this.reconcileIntervalMs = opts.reconcileIntervalMs;
+        this.ttlSec = Math.round(opts.ttlMs / 1000);
+        this.transport = opts.transport;
+        this.now = opts.now ?? Date.now;
+        this.clientFactory = () =>
+            new RedisClient({
+                host: this.host,
+                port: this.port,
+                connectTimeoutMs: this.connectTimeoutMs,
+                commandTimeoutMs: this.commandTimeoutMs,
+                transport: this.transport,
+            });
+    }
+
+    /** 只读暴露。 */
+    get state(): RedisState {
+        return this._state;
+    }
+
+    // ── 写镜像（全部 fire-and-forget：同步返回、绝不 throw、绝不重试）────
+
+    /**
+     * 秒级事件级镜像：`HINCRBY opsx:usage:sec:<secNow> <provider> <delta>` +
+     * `EXPIRE`（TTL 续期）。healthy 才发；非 healthy 静默 no-op。跨 session 的
+     * 累加发生在写入侧——同秒所有 session 的 delta 汇入同一 field。
+     */
+    onDelta(sessionId: string, provider: string, secNow: string, deltaTotal: number): void {
+        if (this._state !== 'healthy') return;
+        void sessionId; // sink 契约兼容：field 无需 session 维度（全局聚合）
+        if (provider.includes(':')) {
+            this.mirrorFailed = true; // 前置假设被破坏：跳过该次镜像
+            return;
+        }
+        const key = `opsx:usage:sec:${secNow}`;
+        this.fireAndForget(
+            this.getClient().pipeline([
+                ['HINCRBY', key, provider, String(deltaTotal)],
+                ['EXPIRE', key, String(this.ttlSec)],
+            ]),
+        );
+    }
+
+    /**
+     * 累计级镜像：`HINCRBY opsx:usage:totals <provider>:total|input|output`（无 TTL，
+     * totals 永久累计）。delta 由 poller 按「当前累计 - 上次已写入」算出，失败不
+     * 重试（超时重试会双计），丢失由 reconcile 的文件权威覆盖修复。
+     */
+    onTotalsDelta(provider: string, dTotal: number, dInput: number, dOutput: number): void {
+        if (this._state !== 'healthy') return;
+        if (provider.includes(':')) {
+            this.mirrorFailed = true;
+            return;
+        }
+        this.fireAndForget(
+            this.getClient().pipeline([
+                ['HINCRBY', 'opsx:usage:totals', `${provider}:total`, String(dTotal)],
+                ['HINCRBY', 'opsx:usage:totals', `${provider}:input`, String(dInput)],
+                ['HINCRBY', 'opsx:usage:totals', `${provider}:output`, String(dOutput)],
+            ]),
+        );
+    }
+
+    // ── tick 步骤（poller 每 1s 调用；绝对时间门控；自吞异常翻 unhealthy）──
+
+    /** 镜像写失败观察：`mirrorFailed` → 翻 `unhealthy` 并清标志（翻转延迟 ≤1s）。 */
+    observeMirrorFailure(_now: number): void {
+        if (this.mirrorFailed) {
+            this.mirrorFailed = false;
+            this._state = 'unhealthy';
+        }
+    }
+
+    /**
+     * 探测：`unknown` 立即 / `healthy` 每 `probeIntervalMs` / `unhealthy` 每
+     * `unhealthyRetryMs`（绝对时间门控，与 tick 次数无关）。每次尝试都更新
+     * `lastProbeAt`。PING 成功 → `healthy`（此前非 healthy 则 `lastReconcileAt=0`
+     * 触发下一次 tick 立即 reconcile）；失败 → close 失效 client + `unhealthy`。
+     * 绝不向外抛。
+     */
+    async maybeProbe(now: number): Promise<void> {
+        let due: boolean;
+        if (this._state === 'unknown') {
+            due = true;
+        } else if (this._state === 'healthy') {
+            due = now - this.lastProbeAt >= this.probeIntervalMs;
+        } else {
+            due = now - this.lastProbeAt >= this.unhealthyRetryMs;
+        }
+        if (!due) return;
+        this.lastProbeAt = now;
+        const wasHealthy = this._state === 'healthy';
+        try {
+            await this.getClient().ping();
+            if (!wasHealthy) this.lastReconcileAt = 0; // 恢复：立即 reconcile 补齐降级期增量
+            this._state = 'healthy';
+        } catch {
+            this.closeClient();
+            this._state = 'unhealthy';
+        }
+    }
+
+    /**
+     * 预取读：healthy 时 pipeline 一次 HGETALL 秒窗口（nowSec-60 .. nowSec-2，
+     * 2s 滞后）+ `opsx:usage:totals`；解析为可直接渲染的 `RedisSnapshot`。
+     * totals 在 Redis 缺失/为空时用文件权威值兜底（Redis 重启的 ≤30s 空窗）。
+     * 失败 → close + 翻 unhealthy 并 rethrow（poller catch 后回退文件）。
+     * 非 healthy 直接返回空快照。
+     */
+    async prefetch(realtime: RealtimeLike, now: number): Promise<RedisSnapshot> {
+        const snapshot: RedisSnapshot = { totals: {}, perSecond: {} };
+        if (this._state !== 'healthy') return snapshot;
+        try {
+            const commands: Array<{ cmd: string[]; abssec?: string }> = [];
+            const nowSec = Math.floor(now / 1000);
+            for (let sec = nowSec - 60; sec <= nowSec - 2; sec++) {
+                commands.push({ cmd: ['HGETALL', `opsx:usage:sec:${sec}`], abssec: String(sec) });
+            }
+            commands.push({ cmd: ['HGETALL', 'opsx:usage:totals'] });
+            if (commands.length === 0) return snapshot;
+            const replies = await this.getClient().pipeline(commands.map((c) => c.cmd));
+            for (let i = 0; i < replies.length; i++) {
+                this.applyPrefetchReply(snapshot, commands[i], replies[i]);
+            }
+            this.fallbackTotalsFromFile(snapshot, realtime);
+            return snapshot;
+        } catch (err) {
+            this.closeClient();
+            this._state = 'unhealthy';
+            throw err;
+        }
+    }
+
+    /**
+     * reconcile 逐 key 覆盖：`HSET opsx:usage:totals`（文件全量字段）+ 冻结秒
+     * `HSET opsx:usage:sec:<sec> <provider> <值>` + `EXPIRE`；只覆盖已冻结秒
+     * （`sec < floor(now/1000)`），跳过当前进行中秒（事件级 HINCRBY 已领先文件，
+     * 覆盖会回退）。HSET 覆盖幂等、非增量合并。成功后更新 `lastReconcileAt`；
+     * 命令失败 → close + 翻 unhealthy 并 rethrow（poller 侧 catch）。非 healthy
+     * 静默 no-op。
+     */
+    async reconcile(realtime: RealtimeLike, now: number): Promise<void> {
+        if (this._state !== 'healthy') return;
+        try {
+            const commands: string[][] = [];
+            const nowSec = Math.floor(now / 1000);
+            const totalsArgs: string[] = ['HSET', 'opsx:usage:totals'];
+            for (const [provider, bucket] of Object.entries(realtime.totals ?? {})) {
+                if (provider.includes(':')) continue;
+                totalsArgs.push(
+                    `${provider}:total`,
+                    String(bucket.total),
+                    `${provider}:input`,
+                    String(bucket.input),
+                    `${provider}:output`,
+                    String(bucket.output),
+                );
+            }
+            if (totalsArgs.length > 2) commands.push(totalsArgs);
+            for (const [secStr, secMap] of Object.entries(realtime.seconds ?? {})) {
+                const sec = Number(secStr);
+                if (!Number.isInteger(sec) || sec >= nowSec) continue; // 只覆盖已冻结秒
+                const key = `opsx:usage:sec:${sec}`;
+                const args: string[] = ['HSET', key];
+                for (const [provider, amount] of Object.entries(secMap)) {
+                    if (provider.includes(':')) continue;
+                    args.push(provider, String(amount));
+                }
+                if (args.length > 2) {
+                    commands.push(args);
+                    commands.push(['EXPIRE', key, String(this.ttlSec)]);
+                }
+            }
+            if (commands.length > 0) {
+                await this.getClient().pipeline(commands);
+            }
+            this.lastReconcileAt = now;
+        } catch (err) {
+            this.closeClient();
+            this._state = 'unhealthy';
+            throw err;
+        }
+    }
+
+    /** 释放连接；之后 fire-and-forget/await 路径经懒建重建。 */
+    close(): void {
+        this.closeClient();
+    }
+
+    // ── 内部 ─────────────────────────────────────────────────────────────
+
+    private fireAndForget(p: Promise<unknown>): void {
+        void p.catch(() => {
+            this.mirrorFailed = true;
+        });
+    }
+
+    private getClient(): RedisClient {
+        if (this.client === null) {
+            this.client = this.clientFactory();
+        }
+        return this.client;
+    }
+
+    private closeClient(): void {
+        if (this.client !== null) {
+            try {
+                this.client.close();
+            } catch {
+                /* ignore */
+            }
+            this.client = null;
+        }
+    }
+
+    /** 把一条 pipeline 回复（sec hash 或 totals hash）并入快照；异常 field 防御跳过。 */
+    private applyPrefetchReply(
+        snapshot: RedisSnapshot,
+        entry: { cmd: string[]; abssec?: string },
+        reply: RedisReply,
+    ): void {
+        if (reply === null || !Array.isArray(reply)) return;
+        const fields = reply as string[];
+        for (let i = 0; i + 1 < fields.length; i += 2) {
+            const field = fields[i];
+            const value = fields[i + 1];
+            if (typeof field !== 'string' || typeof value !== 'string') continue;
+            if (entry.abssec !== undefined) {
+                // sec hash: field = provider, value = global tokens
+                if (!field || field.includes(':')) continue;
+                const amount = Number(value);
+                if (!Number.isFinite(amount)) continue;
+                const bySec = (snapshot.perSecond[field] ??= {});
+                bySec[entry.abssec] = (bySec[entry.abssec] ?? 0) + amount;
+            } else {
+                // totals hash: field = <provider>:metric
+                const parsed = parseTotalsField(field, value);
+                if (!parsed) continue;
+                const totals = (snapshot.totals[parsed.provider] ??= { total: 0, input: 0, output: 0 });
+                totals[parsed.metric] += parsed.num;
+            }
+        }
+    }
+
+    /** Redis totals 缺失/为空（如重启后）→ 用文件权威值兜底，展示零缺口。 */
+    private fallbackTotalsFromFile(snapshot: RedisSnapshot, realtime: RealtimeLike): void {
+        for (const [provider, bucket] of Object.entries(realtime.totals ?? {})) {
+            if (snapshot.totals[provider]) continue; // Redis 侧有（活数据）→ 以 Redis 为准
+            snapshot.totals[provider] = {
+                total: bucket.total,
+                input: bucket.input,
+                output: bucket.output,
+            };
+        }
+    }
+}