web-font/backend/shared.ts
崮生(子虚) 7a2e8dc209 feat(双端): P95/P99 延迟可观测 + woff2 编码移出闸门 + stats 防抖 dirty 化 (1.15.6)
- 双端: 子集请求耗时环形缓冲(1024) + /api/stats 输出 latencySamples/P50/P95/P99
- rust: woff2 编码移出内存闸门,闸门只管读盘+解析+裁剪
- TS: markStatsDirty 改传快照函数,落盘时才拷贝(对齐 rust dirty 模式)
- rust: 修复环形未满时零值掺入分位的 bug
2026-11-04 21:23:15 +08:00

222 lines
7.8 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import { fontDirs, subsetCacheMaxSize } from "./config";
import { LruCache } from "./lru_cache";
import type { SubsetTtfObject } from "./font_util/glyph_bitmap";
import { path_join, readFile, stat, readdir } from "./interface";
import { loadPersistedStats, scheduleStatsFlush, type PersistedStats } from "./stats_store";
/** 解析请求 URL(req.url 只有路径,需要补全协议和主机才能用 URL API) */
export function parseUrl(req: Request): URL {
return new URL(req.url, "http://localhost");
}
/** JSON 响应工具 */
export function jsonResponse(data: unknown, status = 200) {
return new Response(JSON.stringify(data), {
status,
headers: { "Content-Type": "application/json" },
});
}
/** 运行时统计(累计计数跨重启持久化,startTime 为本次进程启动时刻) */
export const stats = {
/** 服务启动时间戳(进程级,不持久化) */
startTime: Date.now(),
/** 总请求数(持久化累计) */
totalRequests: 0,
/** 字体裁剪请求次数(含缓存命中;持久化累计) */
subsetRequests: 0,
/** 字体裁剪缓存命中次数(持久化累计) */
subsetCacheHits: 0,
/** 累计裁剪文字字符数(持久化累计) */
totalChars: 0,
/** 临时文件上传次数(持久化累计) */
tempUploads: 0,
/** 离线裁剪完成次数(纯浏览器端裁剪的匿名上报;持久化累计) */
offlineSubsets: 0,
/** 离线裁剪字体下载次数(匿名上报;持久化累计) */
offlineDownloads: 0,
};
/**
* 从持久化文件恢复累计计数
*
* 在 main() 最早期 await 一次:让计数器从历史值起步,实现跨重启持久化。
* startTime 始终重置为当前时刻——uptime 度量的是本次进程。
*/
export async function initStats(): Promise<void> {
const persisted = await loadPersistedStats();
stats.startTime = persisted.startTime;
stats.totalRequests = persisted.totalRequests;
stats.subsetRequests = persisted.subsetRequests;
stats.subsetCacheHits = persisted.subsetCacheHits;
stats.totalChars = persisted.totalChars;
stats.tempUploads = persisted.tempUploads;
stats.offlineSubsets = persisted.offlineSubsets;
stats.offlineDownloads = persisted.offlineDownloads;
}
/** 取出需要持久化的累计计数字段 */
export function snapshotStats(): PersistedStats {
return {
totalRequests: stats.totalRequests,
subsetRequests: stats.subsetRequests,
subsetCacheHits: stats.subsetCacheHits,
totalChars: stats.totalChars,
tempUploads: stats.tempUploads,
offlineSubsets: stats.offlineSubsets,
offlineDownloads: stats.offlineDownloads,
};
}
/** 子集请求总耗时直方图:固定容量环形缓冲,只保留最近 1024 个样本(进程级,不持久化) */
const LATENCY_RING = 1024;
const latencyRing = new Array<number>(LATENCY_RING).fill(0);
let latencyNext = 0;
let latencyCount = 0;
/** 记录一次子集请求总耗时(毫秒,含缓存命中路径) */
export function recordSubsetLatency(totalMs: number): void {
latencyRing[latencyNext] = totalMs;
latencyNext = (latencyNext + 1) % LATENCY_RING;
if (latencyCount < LATENCY_RING) latencyCount++;
}
/** 最近样本的分位数(percentile 0~100);无样本返回 null */
function latencyPercentile(p: number): number | null {
if (latencyCount === 0) return null;
const sorted = latencyRing.slice(0, latencyCount).sort((a, b) => a - b);
const idx = Math.min(sorted.length - 1, Math.round(((sorted.length - 1) * p) / 100));
return sorted[idx];
}
/** 延迟分位快照(/api/stats 输出用) */
export function latencySnapshot(): {
latencySamples: number;
latencyP50: number | null;
latencyP95: number | null;
latencyP99: number | null;
} {
return {
latencySamples: latencyCount,
latencyP50: latencyPercentile(50),
latencyP95: latencyPercentile(95),
latencyP99: latencyPercentile(99),
};
}
/**
* 标记统计已变更,触发防抖落盘
*
* 请求热路径调用:仅置脏标志 + 幂等的定时器检查,快照延迟到落盘时才取
* (消除每请求一次对象拷贝)。真正的磁盘 IO 由 stats_store 按间隔批量执行。
*/
export function markStatsDirty(): void {
scheduleStatsFlush(snapshotStats);
}
/** 字体文件 LRU 缓存,最多保留 3 个最近使用的字体 buffer(按条目数淘汰) */
export const fontBufferCache = new LruCache<ArrayBuffer>({ maxSize: 3 });
/**
* 字体裁剪产物缓存条目:bytes 供 HTTP 下载/前端预览;
* ttf 为内存子集对象(cmap 已重建,可直接光栅化评分),OTF 输入时为 null。
* 不为序列化已产出的对象单独留副本,两处消费方共享同一份产物。
*/
export interface SubsetCacheEntry {
/** 序列化裁剪字体(供 HTTP 下载/前端预览) */
bytes: Uint8Array;
/** 评分用内存子集对象(cmap 已重建,可直接光栅化),OTF 输入时为 null */
ttf: SubsetTtfObject | null;
}
/**
* 字体裁剪结果共享 LRU 缓存(按内存容量淘汰)。
* key 由消费方自定(版本指纹:字体路径:outType:文本);
* 容量计费 = 序列化 bytes + ttf 对象估算开销(16 倍),避免缓存对象本身把容器排薄。
*/
export const subsetCache = new LruCache<SubsetCacheEntry>({
maxBytes: subsetCacheMaxSize,
sizeFn: (v) => v.bytes.byteLength * (v.ttf ? 17 : 1),
});
/** 字体目录清单条目:模糊匹配键 + 列表输出共享 */
interface FontDirEntry {
/** 去扩展名小写 stem(前缀/包含匹配键) */
stem: string;
/** 原始文件名(/api/fonts 输出) */
name: string;
/** 所在目录 */
dir: string;
}
/** 目录清单缓存(5s TTL):消除每请求 readdir + 逐项判定的成本(随字体数线性增长)。
* 上传/删除后主动失效(invalidateFontDirCache);精确匹配不走此缓存,新上传字体立即可见 */
const FONT_DIR_CACHE_TTL = 5_000;
let fontDirCache: { at: number; entries: FontDirEntry[] } | null = null;
/** 上传/删除字体后主动失效(下一次任何查找立即重建清单) */
export function invalidateFontDirCache(): void {
fontDirCache = null;
}
/** 取字体目录清单(TTL 内复用),findFontPath 模糊匹配与 /api/fonts 共享 */
export async function fontDirListing(): Promise<FontDirEntry[]> {
if (fontDirCache && Date.now() - fontDirCache.at < FONT_DIR_CACHE_TTL) {
return fontDirCache.entries;
}
const entries: FontDirEntry[] = [];
for (const dir of fontDirs) {
try {
const list = await readdir(dir);
for (const entry of list) {
if (entry.isFile() && /\.(ttf|otf|woff|woff2)$/i.test(entry.name)) {
entries.push({
stem: entry.name.replace(/\.[^.]+$/, "").toLowerCase(),
name: entry.name,
dir,
});
}
}
} catch {}
}
fontDirCache = { at: Date.now(), entries };
return entries;
}
/**
* 在所有字体目录中查找字体文件
* 匹配优先级:精确匹配 > 前缀匹配 > 包含匹配
*/
export async function findFontPath(filename: string): Promise<string | null> {
for (const dir of fontDirs) {
const filePath = path_join(dir, filename);
try {
const s = await stat(filePath);
if (s.isFile()) return filePath;
} catch {}
}
const allFonts = await fontDirListing();
const query = filename.replace(/\.[^.]+$/, "").toLowerCase();
for (const f of allFonts) {
if (f.stem.startsWith(query)) return path_join(f.dir, f.name);
}
for (const f of allFonts) {
if (f.stem.includes(query)) return path_join(f.dir, f.name);
}
return null;
}
/** 从缓存或磁盘读取字体 buffer */
export async function readFontBuffer(fontPath: string): Promise<ArrayBuffer> {
const cached = fontBufferCache.get(fontPath);
if (cached) return cached;
const buffer = new Uint8Array(await readFile(fontPath)).buffer;
fontBufferCache.set(fontPath, buffer);
return buffer;
}