@genee/omp-opsx-addon 0.1.0

package/lib/reachability-cache.ts

@@ -0,0 +1,288 @@
+/**
+ * 可达性探测缓存模块。
+ *
+ * 缓存文件：`~/.omp/cache/omp-opsx-addon-reachability.json`
+ * 复用 usage-poller 的持久化模式（CacheFile 契约、test seam）。
+ *
+ * 职责：
+ * 1. 探测结果的读写与 TTL 判定
+ * 2. blockedModels（403 记忆）的加载与落盘
+ * 3. 文件缺失/损坏 → 优雅降级，不抛异常
+ *
+ * 设计要点（遵循 design.md D4-D5）：
+ * - D4: 单文件承载探测结果与 403 记忆
+ * - D5: per-provider 10 分钟 TTL，按 checkedAt 独立判定
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── 缓存契约 ─────────────────────────────────────────────────────────────
+
+/** 缓存文件的 JSON 结构。 */
+export interface ReachabilityCacheFile {
+  /** 缓存格式版本 */
+  version: 1;
+  /** 全局时间戳（本次写入时刻） */
+  fetchedAt: number;
+  /** per-provider 探测记录 */
+  providers: Record<string, ReachabilityProviderEntry>;
+  /** 403 屏蔽模型列表（`provider/modelId` 格式） */
+  blockedModels: string[];
+  /** blockedModels 最后更新时间戳 */
+  blockedUpdatedAt: number;
+}
+
+/** 单个 provider 的探测记录。 */
+export interface ReachabilityProviderEntry {
+  reachable: boolean;
+  /** 探测时间戳（epoch ms），驱动 per-provider TTL 判定 */
+  checkedAt: number;
+  /** 探测方法：'tls'、'http' 或 'discovery' */
+  method: 'tls' | 'http' | 'discovery';
+  /** 主探测主机名 */
+  host: string;
+  /** 失败原因（仅不可达时记录） */
+  reason?: string;
+  /** 模型级探测得到的真实可用模型 id 列表（undefined = 未探测/无接口） */
+  availableModelIds?: string[];
+}
+
+/** 探测结果的简化视图（来自 reachability-probe.ts 的 ProbeResult） */
+export interface CacheProbeResult {
+  reachable: boolean;
+  method: 'tls' | 'http' | 'discovery';
+  host: string;
+  reason?: string;
+  /** 模型级探测的真实可用模型 id 列表 */
+  availableModelIds?: string[];
+}
+
+// ── 路径 ─────────────────────────────────────────────────────────────────
+
+const CACHE_DIR = join(homedir(), '.omp', 'cache');
+const CACHE_FILE = join(CACHE_DIR, 'omp-opsx-addon-reachability.json');
+
+/** 版本号：仅匹配 version 1 */
+const CACHE_VERSION = 1;
+
+// ── test seam ─────────────────────────────────────────────────────────────
+
+let cacheFileOverride: string | null = null;
+
+/** 解析缓存文件路径（生产路径或测试临时路径）。 */
+const resolveCacheFile = (): string => cacheFileOverride ?? CACHE_FILE;
+
+// ── 内部工具 ──────────────────────────────────────────────────────────────
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ── 缓存读写 ──────────────────────────────────────────────────────────────
+
+/**
+ * 同步读取缓存文件。
+ * 缺失/损坏/版本不匹配返回 null，不抛异常。
+ */
+export function loadReachabilityCache(): ReachabilityCacheFile | null {
+  try {
+    const path = resolveCacheFile();
+    if (!existsSync(path)) return null;
+
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+
+    // 版本检查
+    if (parsed == null || typeof parsed !== 'object' || parsed.version !== CACHE_VERSION) {
+      return null;
+    }
+
+    // 校验基本结构的合法性
+    if (
+      typeof parsed.fetchedAt !== 'number' ||
+      parsed.providers == null ||
+      typeof parsed.providers !== 'object'
+    ) {
+      return null;
+    }
+
+    // blockedModels 兼容旧缓存无此字段
+    if (!Array.isArray(parsed.blockedModels)) {
+      parsed.blockedModels = [];
+    }
+    if (typeof parsed.blockedUpdatedAt !== 'number') {
+      parsed.blockedUpdatedAt = 0;
+    }
+
+    return parsed as ReachabilityCacheFile;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 将缓存对象写盘。
+ * 确保目录存在，写失败吞没异常并 warn。
+ */
+export function writeReachabilityCache(cache: ReachabilityCacheFile): void {
+  try {
+    const path = resolveCacheFile();
+    ensureDir(dirname(path));
+    writeFileSync(path, JSON.stringify(cache, null, 2), 'utf-8');
+  } catch (e) {
+    console.warn(`[omp-opsx-addon] failed to write reachability cache: ${e}`);
+  }
+}
+
+// ── 不可达 provider 查询（TTL）───────────────────────────────────────────
+
+/**
+ * 返回缓存中 TTL 内且不可达的 provider 集合。
+ * 过期记录忽略（过期后重新探测可能变为可达）。
+ */
+export function getUnreachableProviders(ttlMs: number): Set<string> {
+  const cache = loadReachabilityCache();
+  if (!cache) return new Set();
+
+  const now = Date.now();
+  const result = new Set<string>();
+
+  for (const [provider, entry] of Object.entries(cache.providers)) {
+    if (entry.reachable) continue;
+    if (now - entry.checkedAt > ttlMs) continue; // 过期忽略
+    result.add(provider);
+  }
+
+  return result;
+}
+
+/**
+ * 返回缓存中 TTL 内 provider 的真实可用模型 id 列表。
+ * 无记录/过期/未探测时返回 null（表示未知，不应用过滤）。
+ */
+export function getAvailableModelIds(provider: string, ttlMs: number): string[] | null {
+  const cache = loadReachabilityCache();
+  if (!cache) return null;
+  const entry = cache.providers[provider];
+  if (!entry || !Array.isArray(entry.availableModelIds)) return null;
+  if (Date.now() - entry.checkedAt > ttlMs) return null; // 过期忽略
+  return entry.availableModelIds;
+}
+
+// ── 新鲜 provider 查询（TTL，不分正负）───────────────────────────────────
+
+/**
+ * 返回缓存中 TTL 内已探测的 provider 集合（无论可达与否）。
+ * 用于 refresh 时跳过仍在 TTL 内的 provider，避免重复探测。
+ * 对应 design.md D5：可达与不可达结果共用同一 TTL。
+ */
+export function getFreshlyProbedProviders(ttlMs: number): Set<string> {
+  const cache = loadReachabilityCache();
+  if (!cache) return new Set();
+
+  const now = Date.now();
+  const result = new Set<string>();
+
+  for (const [provider, entry] of Object.entries(cache.providers)) {
+    if (now - entry.checkedAt <= ttlMs) {
+      result.add(provider);
+    }
+  }
+
+  return result;
+}
+
+// ── 合并探测结果写入缓存 ─────────────────────────────────────────────────
+
+/**
+ * 将新探测结果按 provider 合并进缓存并整体覆盖写盘。
+ * 仅更新被探测的 provider，其他 provider 的旧记录保留。
+ */
+export function mergeProbeResults(providerResults: Map<string, CacheProbeResult>): void {
+  const existing = loadReachabilityCache();
+  const now = Date.now();
+
+  const providers: Record<string, ReachabilityProviderEntry> = existing?.providers
+    ? { ...existing.providers }
+    : {};
+
+  for (const [provider, result] of providerResults) {
+    providers[provider] = {
+      reachable: result.reachable,
+      checkedAt: now,
+      method: result.method,
+      host: result.host,
+      reason: result.reason,
+      // discovery 结果携带可用模型列表；其他方法不覆盖已有列表
+      availableModelIds: result.method === 'discovery'
+        ? (result.availableModelIds ?? [])
+        : (providers[provider]?.availableModelIds ?? result.availableModelIds),
+    };
+  }
+
+  const cache: ReachabilityCacheFile = {
+    version: CACHE_VERSION,
+    fetchedAt: now,
+    providers,
+    blockedModels: existing?.blockedModels ?? [],
+    blockedUpdatedAt: existing?.blockedUpdatedAt ?? 0,
+  };
+
+  writeReachabilityCache(cache);
+}
+
+// ── blockedModels（403 记忆）持久化 ──────────────────────────────────────
+
+/**
+ * 从缓存文件同步加载 blockedModels 列表。
+ * 缺失/损坏返回空数组。
+ */
+export function loadBlockedModels(): string[] {
+  const cache = loadReachabilityCache();
+  if (!cache || !Array.isArray(cache.blockedModels)) return [];
+  return cache.blockedModels;
+}
+
+/**
+ * 将 blockedModels set 落盘（追加到已有缓存文件的 blockedModels 字段）。
+ * 写失败吞没异常，不抛出。
+ */
+export function persistBlockedModels(blockedSet: Set<string>): void {
+  const existing = loadReachabilityCache();
+  const now = Date.now();
+
+  const providers: Record<string, ReachabilityProviderEntry> = existing?.providers
+    ? { ...existing.providers }
+    : {};
+
+  const cache: ReachabilityCacheFile = {
+    version: CACHE_VERSION,
+    fetchedAt: existing?.fetchedAt ?? now,
+    providers,
+    blockedModels: [...blockedSet],
+    blockedUpdatedAt: now,
+  };
+
+  writeReachabilityCache(cache);
+}
+
+// ── test seams ────────────────────────────────────────────────────────────
+// Redirect disk I/O to a temp path and reset module state between tests.
+// Production code never calls these (the underscore prefix signals test-only intent).
+
+/**
+ * 设置测试用缓存文件路径。
+ * 传入 `null` 恢复默认路径。
+ */
+export function _setCacheFileForTest(path: string | null): void {
+  cacheFileOverride = path;
+}
+
+/**
+ * 重置模块测试状态。
+ */
+export function _resetForTest(): void {
+  cacheFileOverride = null;
+}