pi-tsgw 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,7 +10,6 @@ import { dirname, resolve } from "node:path";
10
10
 
11
11
  export const DEFAULT_GATEWAY_MODEL_TIMEOUT_MS = 5_000;
12
12
  export const DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
13
- export const STARTUP_GATEWAY_MODEL_CACHE_TTL_MS = 7 * DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS;
14
13
 
15
14
  export type GatewayModelFailureReason =
16
15
  | "http"
@@ -37,8 +36,6 @@ export interface GetGatewayModelIdsOptions extends FetchGatewayModelIdsOptions {
37
36
  force?: boolean;
38
37
  /** 各入口独立判断新鲜度,但共用原始获取时间与缓存。 */
39
38
  ttlMs?: number;
40
- /** 仅启动无有效作用域缓存时允许失败后重试一次。 */
41
- retryWithoutCache?: boolean;
42
39
  }
43
40
 
44
41
  export type FetchGatewayModelIdsResult =
@@ -66,6 +63,13 @@ export interface LoadedGatewayModelCache {
66
63
  fresh: boolean;
67
64
  }
68
65
 
66
+ export type CachedGatewayModelIds = ModelCacheEntry & { fresh: boolean };
67
+
68
+ export interface GetCachedGatewayModelIdsOptions {
69
+ cacheFilePath?: string;
70
+ ttlMs?: number;
71
+ }
72
+
69
73
  export type GetGatewayModelIdsResult =
70
74
  | {
71
75
  ok: true;
@@ -74,6 +78,7 @@ export type GetGatewayModelIdsResult =
74
78
  stale: boolean;
75
79
  storedAt: number;
76
80
  fallbackReason?: GatewayModelFailureReason;
81
+ fallbackStatus?: number;
77
82
  }
78
83
  | Extract<FetchGatewayModelIdsResult, { ok: false }>;
79
84
 
@@ -81,6 +86,12 @@ function errorDetail(error: unknown): string {
81
86
  return error instanceof Error ? error.message : String(error);
82
87
  }
83
88
 
89
+ function checkedTtl(ttlMs = DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS): number {
90
+ if (!Number.isFinite(ttlMs) || ttlMs < 0)
91
+ throw new RangeError("ttlMs 必须是非负有限数值");
92
+ return ttlMs;
93
+ }
94
+
84
95
  function modelsUrl(baseUrl: string): string {
85
96
  return `${baseUrl.replace(/\/+$/, "")}/v1/models`;
86
97
  }
@@ -165,8 +176,7 @@ export async function fetchGatewayModelIds(
165
176
  export function createModelCache(
166
177
  ttlMs = DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS,
167
178
  ): ModelCache {
168
- if (!Number.isFinite(ttlMs) || ttlMs < 0)
169
- throw new RangeError("ttlMs 必须是非负有限数值");
179
+ const ttl = checkedTtl(ttlMs);
170
180
  let entry: ModelCacheEntry | undefined;
171
181
 
172
182
  return {
@@ -180,7 +190,7 @@ export function createModelCache(
180
190
  },
181
191
  isFresh(now = Date.now()) {
182
192
  if (!entry) return false;
183
- return Math.max(0, now - entry.storedAt) < ttlMs;
193
+ return Math.max(0, now - entry.storedAt) < ttl;
184
194
  },
185
195
  };
186
196
  }
@@ -192,7 +202,7 @@ export function gatewayModelCacheScope(baseUrl: string, apiKey: string): string
192
202
  .digest("hex");
193
203
  }
194
204
 
195
- function readGatewayModelCacheSnapshot(
205
+ function readStoredGatewayModelCache(
196
206
  filePath: string,
197
207
  ): (ModelCacheEntry & { scope: string }) | undefined {
198
208
  try {
@@ -226,20 +236,26 @@ function readGatewayModelCacheEntry(
226
236
  filePath: string,
227
237
  scope: string,
228
238
  ): ModelCacheEntry | undefined {
229
- const snapshot = readGatewayModelCacheSnapshot(filePath);
239
+ const snapshot = readStoredGatewayModelCache(filePath);
230
240
  if (!scope || snapshot?.scope !== scope) return undefined;
231
241
  return { storedAt: snapshot.storedAt, ids: snapshot.ids };
232
242
  }
233
243
 
234
- /** 刷新后的文件摘要;只确认可读性与获取时间,不用于恢复目录或认证作用域。 */
244
+ /** 刷新后的文件摘要;可同时核对当前配置及已应用的完整模型 ID 快照。 */
235
245
  export function readGatewayModelCacheSummary(
236
246
  cacheFilePath: string,
237
247
  minimumStoredAt: number,
248
+ expectedScope?: string,
249
+ expectedIds?: readonly string[],
238
250
  ): { cacheFilePath: string; count: number; storedAt: number } | undefined {
239
251
  if (!Number.isFinite(minimumStoredAt) || minimumStoredAt < 0) return undefined;
240
- const snapshot = readGatewayModelCacheSnapshot(cacheFilePath);
252
+ const snapshot = readStoredGatewayModelCache(cacheFilePath);
241
253
  if (!snapshot || !snapshot.ids.length || snapshot.storedAt < minimumStoredAt)
242
254
  return undefined;
255
+ if (expectedScope !== undefined && snapshot.scope !== expectedScope)
256
+ return undefined;
257
+ if (expectedIds && (snapshot.ids.length !== expectedIds.length ||
258
+ snapshot.ids.some((id, index) => id !== expectedIds[index]))) return undefined;
243
259
  return { cacheFilePath, count: snapshot.ids.length, storedAt: snapshot.storedAt };
244
260
  }
245
261
 
@@ -283,13 +299,12 @@ export function loadGatewayModelCache(
283
299
  now = Date.now(),
284
300
  ttlMs = DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS,
285
301
  ): LoadedGatewayModelCache | undefined {
286
- if (!Number.isFinite(ttlMs) || ttlMs < 0)
287
- throw new RangeError("ttlMs 必须是非负有限数值");
302
+ const ttl = checkedTtl(ttlMs);
288
303
  const entry = readGatewayModelCacheEntry(filePath, scope);
289
304
  if (!entry) return undefined;
290
305
  return {
291
306
  ids: [...entry.ids],
292
- fresh: isCacheEntryFresh(entry, now, ttlMs),
307
+ fresh: isCacheEntryFresh(entry, now, ttl),
293
308
  };
294
309
  }
295
310
 
@@ -305,6 +320,10 @@ const latestRequests = new Map<string, number>();
305
320
  const latestDiskRequests = new Map<string, number>();
306
321
  let revision = 0;
307
322
 
323
+ function memoryCacheKey(scope: string, filePath?: string): string {
324
+ return filePath ? `${scope}\0${resolve(filePath)}` : scope;
325
+ }
326
+
308
327
  function cacheFor(key: string): ModelCache {
309
328
  let cache = gatewayCaches.get(key);
310
329
  if (!cache) {
@@ -314,11 +333,59 @@ function cacheFor(key: string): ModelCache {
314
333
  return cache;
315
334
  }
316
335
 
336
+ function selectLatestGatewayModelCacheEntry(
337
+ key: string,
338
+ cacheFilePath: string | undefined,
339
+ ttlMs: number,
340
+ now: number,
341
+ ): { entry: ModelCacheEntry; fresh: boolean } | undefined {
342
+ const memory = gatewayCaches.get(memoryCacheKey(key, cacheFilePath))?.get();
343
+ const disk = cacheFilePath
344
+ ? readGatewayModelCacheEntry(cacheFilePath, key)
345
+ : undefined;
346
+ const entry =
347
+ memory && disk
348
+ ? memory.storedAt >= disk.storedAt
349
+ ? memory
350
+ : disk
351
+ : (memory ?? disk);
352
+ if (!entry) return undefined;
353
+ return { entry, fresh: isCacheEntryFresh(entry, now, ttlMs) };
354
+ }
355
+
356
+ /** 仅读取本地内存与磁盘,按当前 baseUrl/key 选择 storedAt 最新的快照。 */
357
+ export function getCachedGatewayModelIds(
358
+ baseUrl: string,
359
+ apiKey: string,
360
+ opts: GetCachedGatewayModelIdsOptions = {},
361
+ now = Date.now(),
362
+ ): CachedGatewayModelIds | undefined {
363
+ const key = gatewayModelCacheScope(baseUrl, apiKey);
364
+ const cacheKey = memoryCacheKey(key, opts.cacheFilePath);
365
+ const memory = gatewayCaches.get(cacheKey)?.get();
366
+ const selected = selectLatestGatewayModelCacheEntry(
367
+ key,
368
+ opts.cacheFilePath,
369
+ checkedTtl(opts.ttlMs),
370
+ now,
371
+ );
372
+ if (!selected) return undefined;
373
+ // 选中更新的磁盘快照时同步共享内存,避免磁盘随后损坏或删除时回退旧内存。
374
+ // 仅预热内存,不写磁盘,也不改变原始获取时间。
375
+ if (!memory || selected.entry.storedAt > memory.storedAt)
376
+ cacheFor(cacheKey).set(selected.entry.ids, selected.entry.storedAt);
377
+ return {
378
+ ids: [...selected.entry.ids],
379
+ storedAt: selected.entry.storedAt,
380
+ fresh: selected.fresh,
381
+ };
382
+ }
383
+
317
384
  /**
318
- * 加载网关模型 ID,默认有效期为 24 小时;启动入口可指定 7 天。
385
+ * 加载网关模型 ID,默认有效期为 24 小时。
319
386
  *
320
- * 缓存未过期时直接返回,不进行输入输出。刷新失败时,若有过期缓存则回退使用;
321
- * 否则返回获取失败的结果。
387
+ * 命中时选择内存与磁盘中 storedAt 较新的条目,避免新鲜内存遮蔽更新的磁盘。
388
+ * 刷新失败时回退到该条目并保留原始获取时间;否则返回获取失败的结果。
322
389
  */
323
390
  export async function getGatewayModelIds(
324
391
  baseUrl: string,
@@ -328,42 +395,24 @@ export async function getGatewayModelIds(
328
395
  ): Promise<GetGatewayModelIdsResult> {
329
396
  if (opts.signal?.aborted) return { ok: false, reason: "aborted" };
330
397
  const key = gatewayModelCacheScope(baseUrl, apiKey);
331
- const ttlMs = opts.ttlMs ?? DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS;
332
- if (!Number.isFinite(ttlMs) || ttlMs < 0) throw new RangeError("ttlMs 必须是非负有限数值");
333
- const cache = cacheFor(key);
334
- const memoryEntryBefore = cache.get();
335
- if (!opts.force && memoryEntryBefore && isCacheEntryFresh(memoryEntryBefore, now, ttlMs)) {
336
- const entry = memoryEntryBefore;
337
- if (entry)
338
- return {
339
- ok: true,
340
- ids: entry.ids,
341
- cached: true,
342
- stale: false,
343
- storedAt: entry.storedAt,
344
- };
345
- }
346
-
347
- const diskEntry = opts.cacheFilePath
348
- ? readGatewayModelCacheEntry(opts.cacheFilePath, key)
349
- : undefined;
350
- if (
351
- !opts.force &&
352
- diskEntry &&
353
- isCacheEntryFresh(diskEntry, now, ttlMs)
354
- ) {
355
- cache.set(diskEntry.ids, diskEntry.storedAt);
398
+ const ttlMs = checkedTtl(opts.ttlMs);
399
+ const cacheKey = memoryCacheKey(key, opts.cacheFilePath);
400
+ const cache = cacheFor(cacheKey);
401
+ const local = selectLatestGatewayModelCacheEntry(
402
+ key, opts.cacheFilePath, ttlMs, now,
403
+ );
404
+ if (!opts.force && local?.fresh) {
405
+ cache.set(local.entry.ids, local.entry.storedAt);
356
406
  return {
357
407
  ok: true,
358
- ids: [...diskEntry.ids],
359
- storedAt: diskEntry.storedAt,
408
+ ids: [...local.entry.ids],
360
409
  cached: true,
361
410
  stale: false,
411
+ storedAt: local.entry.storedAt,
362
412
  };
363
413
  }
364
414
 
365
- const retry = opts.retryWithoutCache === true && !memoryEntryBefore && !diskEntry;
366
- const requestKey = `${key}\0${opts.force ? "force" : "normal"}\0${retry}\0${opts.timeoutMs ?? DEFAULT_GATEWAY_MODEL_TIMEOUT_MS}`;
415
+ const requestKey = `${key}\0${opts.force ? "force" : "normal"}\0${opts.timeoutMs ?? DEFAULT_GATEWAY_MODEL_TIMEOUT_MS}`;
367
416
  // 共享请求无法安全地继承某个调用者的 AbortSignal:较新的调用者仍在等待时,
368
417
  // Pi 可能已替换该次刷新。只有不带信号的调用共享进行中的请求;
369
418
  // 可取消的调用独立发起获取请求。
@@ -371,19 +420,16 @@ export async function getGatewayModelIds(
371
420
  let request = shareRequest ? inFlightRequests.get(requestKey) : undefined;
372
421
  if (!request) {
373
422
  const requestRevision = ++revision;
374
- latestRequests.set(key, requestRevision);
375
423
  request = {
376
424
  revision: requestRevision,
377
425
  storedAt: now,
378
- promise: (async () => {
379
- const first = await fetchGatewayModelIds(baseUrl, apiKey, opts);
380
- if (first.ok || !retry || first.reason === "aborted" || opts.signal?.aborted) return first;
381
- return fetchGatewayModelIds(baseUrl, apiKey, opts);
382
- })(),
426
+ promise: fetchGatewayModelIds(baseUrl, apiKey, opts),
383
427
  };
384
428
  if (shareRequest) inFlightRequests.set(requestKey, request);
385
429
  }
386
430
 
431
+ // 请求可跨路径复用,但内存写入屏障按各自路径独立登记。
432
+ latestRequests.set(cacheKey, Math.max(latestRequests.get(cacheKey) ?? 0, request.revision));
387
433
  const diskPath = opts.cacheFilePath ? resolve(opts.cacheFilePath) : undefined;
388
434
  if (diskPath) {
389
435
  // 登记每个订阅者的路径,包括目标路径不同的共享请求。
@@ -406,7 +452,7 @@ export async function getGatewayModelIds(
406
452
  if (fetched.ok) {
407
453
  // 以后启动的请求为准,即使较新的请求失败或取消。
408
454
  // 被取代的成功请求仍向调用者返回结果,但不写入缓存。
409
- if (latestRequests.get(key) === request.revision) {
455
+ if (latestRequests.get(cacheKey) === request.revision) {
410
456
  cache.set(fetched.ids, request.storedAt);
411
457
  if (diskPath && latestDiskRequests.get(diskPath) === request.revision)
412
458
  saveGatewayModelCache(diskPath, key, fetched.ids, request.storedAt);
@@ -420,21 +466,21 @@ export async function getGatewayModelIds(
420
466
  };
421
467
  }
422
468
 
423
- const memoryEntry = cache.get();
424
- const stale =
425
- memoryEntry && diskEntry
426
- ? memoryEntry.storedAt >= diskEntry.storedAt
427
- ? memoryEntry
428
- : diskEntry
429
- : (memoryEntry ?? diskEntry);
430
- if (stale) {
469
+ // 失败回退选择当前内存与磁盘中较新的条目,且不刷新其 storedAt。
470
+ const fallback = selectLatestGatewayModelCacheEntry(
471
+ key, opts.cacheFilePath, ttlMs, now,
472
+ );
473
+ if (fallback) {
431
474
  return {
432
475
  ok: true,
433
- ids: stale.ids,
434
- storedAt: stale.storedAt,
476
+ ids: [...fallback.entry.ids],
477
+ storedAt: fallback.entry.storedAt,
435
478
  cached: true,
436
479
  stale: true,
437
480
  fallbackReason: fetched.reason,
481
+ ...(fetched.reason === "http" && fetched.status !== undefined
482
+ ? { fallbackStatus: fetched.status }
483
+ : {}),
438
484
  };
439
485
  }
440
486
  return fetched;