diff --git a/packages/core/src/bridge/apis/index.ts b/packages/core/src/bridge/apis/index.ts index 91aa3898..acd37f31 100644 --- a/packages/core/src/bridge/apis/index.ts +++ b/packages/core/src/bridge/apis/index.ts @@ -14,6 +14,7 @@ import { MiscApi } from './misc'; import { ProfileApi } from './profile'; import { QzoneApi } from './qzone'; import { WebApi } from './web'; +import { SystemFaceApi } from './system-face'; export interface ApiHub { /** Personal QQ collections: authenticated list retrieval and pagination. */ @@ -46,6 +47,8 @@ export interface ApiHub { readonly extras: ExtrasApi; /** Cookie-backed HTTP: essence / honor / notice / client-key / csrf-token. */ readonly web: WebApi; + /** QQ system-face directory: durable catalog, id lookup, and search. */ + readonly systemFace: SystemFaceApi; } /** @@ -73,6 +76,7 @@ export function buildApiHub(ctx: BridgeContext): ApiHub { misc: new MiscApi(ctx), extras: new ExtrasApi(ctx), web: new WebApi(ctx), + systemFace: new SystemFaceApi(ctx), }; } @@ -101,3 +105,4 @@ export { ProfileApi } from './profile'; export { QzoneApi } from './qzone'; export { FlashTransferApi, type FlashFileInfo } from './flash-transfer'; export { WebApi } from './web'; +export { SystemFaceApi } from './system-face'; diff --git a/packages/core/src/bridge/apis/system-face.ts b/packages/core/src/bridge/apis/system-face.ts new file mode 100644 index 00000000..6a1964be --- /dev/null +++ b/packages/core/src/bridge/apis/system-face.ts @@ -0,0 +1,35 @@ +import { + sysFaceStore, + type SysFaceEntry, + type SysFacePackEntry, +} from '@snowluma/protocol/sys-face-store'; +import { isSuperFaceEntry } from '@snowluma/protocol/oidb-services/sys-faces/fetch-sys-faces'; +import type { BridgeContext } from '../bridge-context'; + +/** QQ's account-independent system-face directory. The shared store owns + * persistence and refresh coalescing; this API binds it to one live sender. */ +export class SystemFaceApi { + constructor(private readonly ctx: BridgeContext) {} + + fetchCatalog(refresh = false): Promise { + return sysFaceStore.getCatalog(this.ctx, refresh); + } + + async fetchFace(faceId: number, refresh = false): Promise { + if (refresh) { + await sysFaceStore.refresh(this.ctx); + return sysFaceStore.lookup(faceId); + } + return sysFaceStore.resolve(this.ctx, faceId); + } + + async search(query: string): Promise { + await sysFaceStore.ensureReady(this.ctx); + return sysFaceStore.search(query); + } + + async isSuper(faceId: number, refresh = false): Promise { + const face = await this.fetchFace(faceId, refresh); + return face !== null && isSuperFaceEntry(face); + } +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 46484b55..fc6258dc 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -18,6 +18,7 @@ import { workerData } from 'node:worker_threads'; import { BridgeManager } from './bridge/manager'; import { createNotificationManager } from './notifications/manager'; import { createStateWiring } from './webui/state-wiring'; +import { bindSystemFaceCatalog } from './sys-face-catalog'; const log = createLogger('App'); @@ -57,6 +58,7 @@ async function main() { cleanupInvalidPerUinConfigs(); const bridgeManager = new BridgeManager(); + bindSystemFaceCatalog(bridgeManager); const oneBotManager = new OneBotManager(); const autoLoadOnDiscovery = resolveAutoLoad(runtimeConfig.hookAutoLoad); diff --git a/packages/core/src/sys-face-catalog.ts b/packages/core/src/sys-face-catalog.ts new file mode 100644 index 00000000..e04a9f6f --- /dev/null +++ b/packages/core/src/sys-face-catalog.ts @@ -0,0 +1,40 @@ +import path from 'node:path'; +import { createLogger } from '@snowluma/common/logger'; +import { + SysFaceStore, + sysFaceStore, + type SysFaceCatalogStorage, +} from '@snowluma/protocol/sys-face-store'; +import { JsonSysFaceCatalogStorage } from '@snowluma/protocol/sys-face-storage'; +import type { BridgeManager } from './bridge/manager'; + +const log = createLogger('SysFace'); + +export interface SystemFaceCatalogBindingOptions { + store?: SysFaceStore; + storage?: SysFaceCatalogStorage; + dataRoot?: string; +} + +/** Attach the shared system-face catalog to Bridge login edges. The first + * account restores + refreshes it; later accounts reuse the same result. */ +export function bindSystemFaceCatalog( + manager: BridgeManager, + options: SystemFaceCatalogBindingOptions = {}, +): void { + const store = options.store ?? sysFaceStore; + const storage = options.storage ?? new JsonSysFaceCatalogStorage( + path.join(options.dataRoot ?? 'data', 'sys-face-catalog.json'), + ); + store.configureStorage(storage); + + manager.addSessionStartedListener((uin, bridge) => { + void store.prewarm(bridge).catch((error) => { + log.error( + 'system face catalog login prewarm failed: uin=%s error=%s', + uin, + error instanceof Error ? (error.stack ?? error.message) : String(error), + ); + }); + }); +} diff --git a/packages/core/tests/sys-face-catalog.test.ts b/packages/core/tests/sys-face-catalog.test.ts new file mode 100644 index 00000000..ce0f68dc --- /dev/null +++ b/packages/core/tests/sys-face-catalog.test.ts @@ -0,0 +1,38 @@ +import { describe, expect, it, vi } from 'vitest'; +import { SysFaceStore, type SysFaceCatalogStorage } from '@snowluma/protocol/sys-face-store'; +import { BridgeManager } from '../src/bridge/manager'; +import { bindSystemFaceCatalog } from '../src/sys-face-catalog'; + +const storage: SysFaceCatalogStorage = { + load: async () => null, + save: async () => {}, +}; + +describe('bindSystemFaceCatalog', () => { + it('starts one shared catalog prewarm from the first logged-in account', async () => { + let fetches = 0; + const store = new SysFaceStore({ + fetchCatalog: async () => { + fetches += 1; + return [{ + packName: '经典', + emojis: [{ + qSid: '14', qDes: '/微笑', emCode: '14', qCid: null, + aniStickerType: null, aniStickerPackId: null, aniStickerId: null, + url: null, emojiNameAlias: [], + aniStickerWidth: null, aniStickerHeight: null, + }], + }]; + }, + }); + const manager = new BridgeManager(); + bindSystemFaceCatalog(manager, { store, storage }); + + const packetSender = { sendPacket: vi.fn() } as never; + manager.onHookLogin(101, '10001', packetSender); + manager.onHookLogin(202, '20002', packetSender); + + await vi.waitFor(() => expect(fetches).toBe(1)); + expect(store.lookup(14)?.qDes).toBe('/微笑'); + }); +}); diff --git a/packages/protocol/package.json b/packages/protocol/package.json index caac9bea..47034fdd 100644 --- a/packages/protocol/package.json +++ b/packages/protocol/package.json @@ -44,6 +44,14 @@ "types": "./src/self-uid.ts", "default": "./src/self-uid.ts" }, + "./sys-face-store": { + "types": "./src/sys-face-store.ts", + "default": "./src/sys-face-store.ts" + }, + "./sys-face-storage": { + "types": "./src/sys-face-storage.ts", + "default": "./src/sys-face-storage.ts" + }, "./bridge-oidb": { "types": "./src/bridge-oidb.ts", "default": "./src/bridge-oidb.ts" diff --git a/packages/protocol/src/element-builder.ts b/packages/protocol/src/element-builder.ts index 78fa3d95..32329364 100644 --- a/packages/protocol/src/element-builder.ts +++ b/packages/protocol/src/element-builder.ts @@ -55,12 +55,12 @@ function makeTextElem(text: string): ProtoElem { // super (animated, aniSticker not pack (1,1)) → CommonElem 37 + QFaceExtra // other id ≥ 260 → CommonElem 33 + QSmallFaceExtra // classic id < 260 → legacy FaceElem -function makeFaceElem(faceId: number, ctx?: SendContext): ProtoElem { - // Keep the catalog warm so subsequent super-face sends are classified even if - // this one raced ahead of the first fetch. - if (ctx) sysFaceStore.ensureWarm(ctx.bridge); - - const wire = sysFaceStore.classify(faceId); +async function makeFaceElem(faceId: number, ctx?: SendContext): Promise { + // With a live bridge, wait for the authoritative catalog. Login normally + // preloads it, while this await closes the reconnect / first-send race. + const wire = ctx + ? await sysFaceStore.resolveWire(ctx.bridge, faceId) + : sysFaceStore.classify(faceId); if (wire.kind === 'super') { return { commonElem: { @@ -495,7 +495,7 @@ export async function buildSendElems(elements: MessageElement[], ctx?: SendConte break; case 'face': - result.push(makeFaceElem(elem.faceId, ctx)); + result.push(await makeFaceElem(elem.faceId, ctx)); break; case 'poke': diff --git a/packages/protocol/src/sys-face-storage.ts b/packages/protocol/src/sys-face-storage.ts new file mode 100644 index 00000000..c550fc88 --- /dev/null +++ b/packages/protocol/src/sys-face-storage.ts @@ -0,0 +1,52 @@ +import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'; +import { dirname } from 'node:path'; +import type { SysFaceCatalogSnapshot, SysFaceCatalogStorage } from './sys-face-store'; + +function isErrno(error: unknown, code: string): boolean { + return typeof error === 'object' + && error !== null + && 'code' in error + && (error as { code?: unknown }).code === code; +} + +/** Atomic JSON persistence for the process-wide system-face catalog. */ +export class JsonSysFaceCatalogStorage implements SysFaceCatalogStorage { + constructor(readonly filePath: string) {} + + async load(): Promise { + let text: string; + try { + text = await readFile(this.filePath, 'utf8'); + } catch (error) { + if (isErrno(error, 'ENOENT')) return null; + throw new Error(`failed to read system face catalog ${this.filePath}`, { cause: error }); + } + + try { + return JSON.parse(text) as SysFaceCatalogSnapshot; + } catch (error) { + throw new Error(`failed to parse system face catalog ${this.filePath}`, { cause: error }); + } + } + + async save(snapshot: SysFaceCatalogSnapshot): Promise { + await mkdir(dirname(this.filePath), { recursive: true }); + const temporaryPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}`; + try { + await writeFile(temporaryPath, JSON.stringify(snapshot, null, 2), 'utf8'); + await rename(temporaryPath, this.filePath); + } catch (error) { + try { + await unlink(temporaryPath); + } catch (cleanupError) { + if (!isErrno(cleanupError, 'ENOENT')) { + throw new AggregateError( + [error, cleanupError], + `failed to persist system face catalog ${this.filePath} and remove its temporary file`, + ); + } + } + throw new Error(`failed to persist system face catalog ${this.filePath}`, { cause: error }); + } + } +} diff --git a/packages/protocol/src/sys-face-store.ts b/packages/protocol/src/sys-face-store.ts index 5e92853e..6d32e78b 100644 --- a/packages/protocol/src/sys-face-store.ts +++ b/packages/protocol/src/sys-face-store.ts @@ -1,11 +1,6 @@ -// Process-wide cache of QQ's system-face catalog (fetched once via 0x9154_1), -// used by the send path to pick a face id's wire encoding. The catalog is the -// same for every account, so a single shared store is fetched lazily and reused. -// -// `classify` is synchronous (the element builder is sync); a face sent before -// the catalog is warm falls back to an id-range guess. `ensureWarm` kicks off -// the one-shot fetch — call it proactively at login so the first super-face -// send is already classified. +// Process-wide catalog of QQ system faces. QQ publishes the mapping through +// 0x9154_1; this store makes that catalog durable, queryable, and safe to use +// from the asynchronous send path. import { createLogger } from '@snowluma/common/logger'; import { @@ -16,77 +11,337 @@ import { } from './oidb-services/sys-faces/fetch-sys-faces'; import type { OidbSender } from './oidb-service'; +export type { SysFaceEntry, SysFacePackEntry } from './oidb-services/sys-faces/fetch-sys-faces'; + const log = createLogger('SysFace'); -/** Wire encoding a face id maps to. `classic` → legacy FaceElem; `small` → - * CommonElem serviceType 33 (QSmallFaceExtra); `super` → CommonElem - * serviceType 37 (QFaceExtra) for animated/super faces. */ +/** Wire encoding a face id maps to. `classic` -> legacy FaceElem; `small` -> + * CommonElem serviceType 33; `super` -> CommonElem serviceType 37. */ export type FaceWire = | { kind: 'classic' } | { kind: 'small' } | { kind: 'super'; packId: string; stickerId: string; stickerType: number }; -/** Pure classification: a super face (per the catalog entry) → `super` with its - * pack/sticker ids; otherwise an id-range guess (`< 260` = classic, else - * small). Used both warm (entry from the catalog) and cold (entry undefined). */ +export interface SysFaceCatalogSnapshot { + schemaVersion: 1; + fetchedAt: number; + packs: SysFacePackEntry[]; +} + +export interface SysFaceCatalogStorage { + load(): Promise; + save(snapshot: SysFaceCatalogSnapshot): Promise; +} + +export interface SysFaceStoreOptions { + storage?: SysFaceCatalogStorage; + fetchCatalog?: (sender: OidbSender) => Promise; + now?: () => number; +} + +interface IndexedCatalog { + packs: SysFacePackEntry[]; + byId: Map; + packNameById: Map; +} + +/** Pure classification once an authoritative entry is known. */ export function faceWireFor(entry: SysFaceEntry | null | undefined, faceId: number): FaceWire { - if (entry && isSuperFaceEntry(entry)) { + if (!entry) { + throw new Error(`QQ system face id ${faceId} is absent from the current catalog`); + } + if (isSuperFaceEntry(entry)) { + if (entry.aniStickerPackId == null + || entry.aniStickerId == null + || entry.aniStickerType == null) { + throw new Error(`QQ system face id ${faceId} has incomplete super-face metadata`); + } return { kind: 'super', - packId: String(entry.aniStickerPackId ?? 1), - stickerId: String(entry.aniStickerId ?? 0), - stickerType: entry.aniStickerType ?? 0, + packId: String(entry.aniStickerPackId), + stickerId: String(entry.aniStickerId), + stickerType: entry.aniStickerType, }; } return faceId < 260 ? { kind: 'classic' } : { kind: 'small' }; } -const RETRY_COOLDOWN_MS = 30_000; +export class SysFaceStore { + private catalog: IndexedCatalog | null = null; + private storage: SysFaceCatalogStorage | null; + private readonly fetchCatalog: (sender: OidbSender) => Promise; + private readonly now: () => number; + private cacheLoadCompleted = false; + private cacheLoadInflight: Promise | null = null; + private refreshInflight: Promise | null = null; + private refreshedInProcess = false; + private prewarmInflight: Promise | null = null; + private prewarmed = false; -class SysFaceStore { - private byId: Map | null = null; - private inflight: Promise | null = null; - private lastFailedAt = 0; + constructor(options: SysFaceStoreOptions = {}) { + this.storage = options.storage ?? null; + this.fetchCatalog = options.fetchCatalog ?? ((sender) => FetchSysFaces.invoke(sender)); + this.now = options.now ?? Date.now; + } - /** Index a fetched catalog (also used by tests to seed without a network). */ + /** Configure persistence before the shared store has been used. */ + configureStorage(storage: SysFaceCatalogStorage): void { + if (this.cacheLoadCompleted || this.cacheLoadInflight || this.catalog || this.refreshInflight) { + throw new Error('system face catalog storage must be configured before first use'); + } + this.storage = storage; + } + + /** Index a trusted catalog. Kept public for protocol consumers that already + * obtained a full catalog and want to reuse the same query/send semantics. */ load(packs: SysFacePackEntry[]): void { - this.byId = buildIndex(packs); + this.catalog = indexCatalog(validateCatalog(packs)); } - /** Synchronous classification. Falls back to an id-range guess when the - * catalog isn't warm yet or the id is unknown. */ + lookup(faceId: number): SysFaceEntry | null { + return this.catalog?.byId.get(String(faceId)) ?? null; + } + + /** Case-insensitive query over id, description, aliases, and pack name. */ + search(query: string): SysFaceEntry[] { + const needle = query.trim().toLocaleLowerCase(); + if (!needle || !this.catalog) return []; + + const matches: SysFaceEntry[] = []; + for (const [id, face] of this.catalog.byId) { + const haystacks = [ + id, + face.qDes, + face.emCode, + this.catalog.packNameById.get(id) ?? '', + ...face.emojiNameAlias, + ]; + if (haystacks.some((value) => value.toLocaleLowerCase().includes(needle))) { + matches.push(face); + } + } + return matches; + } + + /** Synchronous classification for callers that already established catalog + * readiness. Unknown ids fail instead of guessing a QQ wire shape. */ classify(faceId: number): FaceWire { - return faceWireFor(this.byId?.get(String(faceId)), faceId); + return faceWireFor(this.lookup(faceId), faceId); } - /** Fire-and-forget one-shot warm. Coalesces concurrent callers; backs off - * briefly after a failure so a flaky fetch isn't hammered per message. */ - ensureWarm(sender: OidbSender): void { - if (this.byId || this.inflight) return; - if (Date.now() - this.lastFailedAt < RETRY_COOLDOWN_MS) return; - this.inflight = FetchSysFaces.invoke(sender) - .then((packs) => { - this.load(packs); - log.info('system face catalog loaded: %d faces', this.byId?.size ?? 0); + /** Load durable state, fetching only when no usable catalog exists. */ + async ensureReady(sender: OidbSender): Promise { + if (this.refreshInflight) { + await this.refreshInflight; + return; + } + if (this.catalog) return; + const loaded = await this.loadCache(); + if (!loaded) await this.refresh(sender); + } + + /** Login hook: restore the durable snapshot for immediate reads, then refresh + * from QQ exactly once per process. Multiple accounts share the same job. */ + prewarm(sender: OidbSender): Promise { + if (this.prewarmed) return Promise.resolve(); + if (this.prewarmInflight) return this.prewarmInflight; + + this.prewarmInflight = (async () => { + try { + await this.loadCache(); + } catch { + // loadCache already emitted the path and failure. A fresh server fetch + // is the authoritative repair for a corrupt rebuildable snapshot. + } + await this.refresh(sender); + this.prewarmed = true; + })().finally(() => { + this.prewarmInflight = null; + }); + return this.prewarmInflight; + } + + /** Fetch the current authoritative catalog. Concurrent callers share one + * request and one atomic persistence operation. */ + refresh(sender: OidbSender): Promise { + if (this.refreshInflight) return this.refreshInflight; + + const startedAt = this.now(); + this.refreshInflight = this.fetchCatalog(sender) + .then(async (packs) => { + const validated = validateCatalog(packs); + const snapshot: SysFaceCatalogSnapshot = { + schemaVersion: 1, + fetchedAt: this.now(), + packs: validated, + }; + this.catalog = indexCatalog(validated); + this.refreshedInProcess = true; + if (this.storage) await this.storage.save(snapshot); + log.info( + 'system face catalog refreshed: faces=%d packs=%d elapsedMs=%d', + this.catalog.byId.size, + validated.length, + this.now() - startedAt, + ); + return validated; }) - .catch((err) => { - this.lastFailedAt = Date.now(); - log.warn('failed to load system face catalog: %s', err instanceof Error ? err.message : String(err)); + .catch((error) => { + log.error( + 'system face catalog refresh failed: elapsedMs=%d error=%s', + this.now() - startedAt, + error instanceof Error ? error.message : String(error), + ); + throw error; }) .finally(() => { - this.inflight = null; + this.refreshInflight = null; }); + return this.refreshInflight; + } + + /** Resolve one id. A miss from a persisted snapshot causes exactly one + * authoritative refresh; a miss from that fresh catalog remains null. */ + async resolve(sender: OidbSender, faceId: number): Promise { + await this.ensureReady(sender); + const cached = this.lookup(faceId); + if (cached || this.refreshedInProcess) return cached; + + await this.refresh(sender); + return this.lookup(faceId); + } + + async resolveWire(sender: OidbSender, faceId: number): Promise { + const entry = await this.resolve(sender, faceId); + if (!entry) { + throw new Error(`QQ system face id ${faceId} is absent from the current catalog`); + } + return faceWireFor(entry, faceId); + } + + async getCatalog(sender: OidbSender, refresh = false): Promise { + if (refresh) await this.refresh(sender); + else await this.ensureReady(sender); + if (!this.catalog) { + throw new Error('system face catalog is unavailable after readiness completed'); + } + return this.catalog.packs; + } + + private loadCache(): Promise { + if (this.catalog) return Promise.resolve(true); + if (this.cacheLoadCompleted) return Promise.resolve(false); + if (this.cacheLoadInflight) return this.cacheLoadInflight; + + if (!this.storage) { + this.cacheLoadCompleted = true; + return Promise.resolve(false); + } + + const startedAt = this.now(); + this.cacheLoadInflight = this.storage.load() + .then((snapshot) => { + this.cacheLoadCompleted = true; + if (!snapshot) return false; + validateSnapshot(snapshot); + this.catalog = indexCatalog(snapshot.packs); + log.info( + 'system face catalog restored: faces=%d packs=%d fetchedAt=%d elapsedMs=%d', + this.catalog.byId.size, + snapshot.packs.length, + snapshot.fetchedAt, + this.now() - startedAt, + ); + return true; + }) + .catch((error) => { + this.cacheLoadCompleted = true; + log.error( + 'system face catalog restore failed: elapsedMs=%d error=%s', + this.now() - startedAt, + error instanceof Error ? error.message : String(error), + ); + throw error; + }) + .finally(() => { + this.cacheLoadInflight = null; + }); + return this.cacheLoadInflight; } } -function buildIndex(packs: SysFacePackEntry[]): Map { - const map = new Map(); - for (const pack of packs) { - for (const emoji of pack.emojis) { - if (emoji.qSid) map.set(emoji.qSid, emoji); +function validateSnapshot(snapshot: SysFaceCatalogSnapshot): void { + if (typeof snapshot !== 'object' || snapshot === null) { + throw new Error('invalid system face catalog snapshot root'); + } + if (snapshot.schemaVersion !== 1) { + throw new Error(`unsupported system face catalog schema version: ${String(snapshot.schemaVersion)}`); + } + if (!Number.isSafeInteger(snapshot.fetchedAt) || snapshot.fetchedAt < 0) { + throw new Error(`invalid system face catalog fetchedAt: ${String(snapshot.fetchedAt)}`); + } + validateCatalog(snapshot.packs); +} + +function validateCatalog(packs: SysFacePackEntry[]): SysFacePackEntry[] { + if (!Array.isArray(packs) || packs.length === 0) { + throw new Error('system face catalog is empty'); + } + + const seen = new Set(); + let faceCount = 0; + for (const [packIndex, pack] of packs.entries()) { + if (!pack || typeof pack.packName !== 'string' || !Array.isArray(pack.emojis)) { + throw new Error(`invalid system face pack at index ${packIndex}`); + } + for (const [faceIndex, face] of pack.emojis.entries()) { + if (!face || typeof face.qSid !== 'string' || !/^(?:0|[1-9]\d*)$/.test(face.qSid) + || !Number.isSafeInteger(Number(face.qSid)) || Number(face.qSid) < 0) { + throw new Error(`invalid system face id at pack ${packIndex}, face ${faceIndex}`); + } + if (seen.has(face.qSid)) { + throw new Error(`duplicate system face id ${face.qSid}`); + } + if (!Array.isArray(face.emojiNameAlias) + || face.emojiNameAlias.some((alias) => typeof alias !== 'string')) { + throw new Error(`invalid aliases for system face id ${face.qSid}`); + } + if (typeof face.qDes !== 'string' || typeof face.emCode !== 'string') { + throw new Error(`invalid text metadata for system face id ${face.qSid}`); + } + for (const [name, value] of [ + ['qCid', face.qCid], + ['aniStickerType', face.aniStickerType], + ['aniStickerPackId', face.aniStickerPackId], + ['aniStickerId', face.aniStickerId], + ['aniStickerWidth', face.aniStickerWidth], + ['aniStickerHeight', face.aniStickerHeight], + ] as const) { + if (value !== null && !Number.isSafeInteger(value)) { + throw new Error(`invalid ${name} for system face id ${face.qSid}`); + } + } + if (face.url !== null && typeof face.url !== 'string') { + throw new Error(`invalid url for system face id ${face.qSid}`); + } + seen.add(face.qSid); + faceCount += 1; } } - return map; + if (faceCount === 0) throw new Error('system face catalog contains no faces'); + return packs; +} + +function indexCatalog(packs: SysFacePackEntry[]): IndexedCatalog { + const byId = new Map(); + const packNameById = new Map(); + for (const pack of packs) { + for (const emoji of pack.emojis) { + byId.set(emoji.qSid, emoji); + packNameById.set(emoji.qSid, pack.packName); + } + } + return { packs, byId, packNameById }; } /** Shared, process-wide catalog (the face set is account-independent). */ diff --git a/packages/protocol/tests/sys-face-storage.test.ts b/packages/protocol/tests/sys-face-storage.test.ts new file mode 100644 index 00000000..f533432c --- /dev/null +++ b/packages/protocol/tests/sys-face-storage.test.ts @@ -0,0 +1,53 @@ +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { afterEach, describe, expect, it } from 'vitest'; +import { JsonSysFaceCatalogStorage } from '../src/sys-face-storage'; +import type { SysFaceCatalogSnapshot } from '../src/sys-face-store'; + +const roots: string[] = []; + +afterEach(async () => { + await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function fixturePath(): Promise { + const root = await mkdtemp(join(tmpdir(), 'snowluma-sys-face-')); + roots.push(root); + return join(root, 'nested', 'sys-faces.json'); +} + +const SNAPSHOT: SysFaceCatalogSnapshot = { + schemaVersion: 1, + fetchedAt: 123, + packs: [{ + packName: '经典', + emojis: [{ + qSid: '14', qDes: '/微笑', emCode: '14', qCid: null, + aniStickerType: null, aniStickerPackId: null, aniStickerId: null, + url: null, emojiNameAlias: ['smile'], + aniStickerWidth: null, aniStickerHeight: null, + }], + }], +}; + +describe('JsonSysFaceCatalogStorage', () => { + it('returns null for a missing cache and round-trips an atomic save', async () => { + const file = await fixturePath(); + const storage = new JsonSysFaceCatalogStorage(file); + + await expect(storage.load()).resolves.toBeNull(); + await storage.save(SNAPSHOT); + await expect(storage.load()).resolves.toEqual(SNAPSHOT); + expect(JSON.parse(await readFile(file, 'utf8'))).toEqual(SNAPSHOT); + }); + + it('surfaces malformed JSON with the cache path instead of ignoring it', async () => { + const file = await fixturePath(); + const storage = new JsonSysFaceCatalogStorage(file); + await storage.save(SNAPSHOT); + await writeFile(file, '{broken', 'utf8'); + + await expect(storage.load()).rejects.toThrow(file); + }); +}); diff --git a/packages/protocol/tests/sys-faces.test.ts b/packages/protocol/tests/sys-faces.test.ts index 6a92661a..52251420 100644 --- a/packages/protocol/tests/sys-faces.test.ts +++ b/packages/protocol/tests/sys-faces.test.ts @@ -1,6 +1,8 @@ import { describe, it, expect } from 'vitest'; -import { protobuf_decode } from '@snowluma/proton'; +import { protobuf_decode, protobuf_encode } from '@snowluma/proton'; import type { QFaceExtra, QSmallFaceExtra } from '@snowluma/proto-defs/element'; +import type { OidbBase } from '@snowluma/proto-defs/oidb'; +import type { OidbFetchSysFacesResp } from '@snowluma/proto-defs/oidb-actions/sys-faces'; import { FetchSysFaces, findFaceEntity, @@ -9,27 +11,54 @@ import { type SysFaceEntry, type SysFacePackEntry, } from '../src/oidb-services/sys-faces/fetch-sys-faces'; -import { faceWireFor, sysFaceStore } from '../src/sys-face-store'; +import { + faceWireFor, + SysFaceStore, + sysFaceStore, + type SysFaceCatalogSnapshot, + type SysFaceCatalogStorage, +} from '../src/sys-face-store'; import { buildSendElems } from '../src/element-builder'; -function entry(qSid: string, aniStickerType: number | null, aniStickerPackId: number | null, aniStickerId: number | null): SysFaceEntry { +function entry( + qSid: string, + aniStickerType: number | null, + aniStickerPackId: number | null, + aniStickerId: number | null, + qDes = '', + emojiNameAlias: string[] = [], +): SysFaceEntry { return { - qSid, qDes: '', emCode: '', qCid: null, + qSid, qDes, emCode: '', qCid: null, aniStickerType, aniStickerPackId, aniStickerId, - url: null, emojiNameAlias: [], aniStickerWidth: null, aniStickerHeight: null, + url: null, emojiNameAlias, aniStickerWidth: null, aniStickerHeight: null, }; } // 392 is a real non-(1,1) super face; 424 is a real (1,1) "new small" face. const CATALOG: SysFacePackEntry[] = [ - { packName: '经典', emojis: [entry('14', null, null, null)] }, + { packName: '经典', emojis: [entry('14', null, null, null, '/微笑', ['smile'])] }, { packName: '超级表情', emojis: [ - entry('392', 3, 2, 38), // super → CommonElem 37 + entry('392', 3, 2, 38, '/龙年快乐'), // super → CommonElem 37 entry('424', 1, 1, 52), // (1,1) → small → CommonElem 33 entry('358', 2, 1, 33), // super (packId 1 but type 2) → CommonElem 37 ] }, ]; +class MemoryCatalogStorage implements SysFaceCatalogStorage { + saved: SysFaceCatalogSnapshot[] = []; + + constructor(private readonly initial: SysFaceCatalogSnapshot | null = null) {} + + async load(): Promise { + return this.initial; + } + + async save(snapshot: SysFaceCatalogSnapshot): Promise { + this.saved.push(snapshot); + } +} + describe('isSuperFaceEntry / isSuperFaceId — the (1,1) rule', () => { it('treats only non-(1,1) aniSticker faces as super', () => { expect(isSuperFaceEntry(entry('x', 3, 2, 1))).toBe(true); @@ -58,13 +87,16 @@ describe('faceWireFor — classification', () => { kind: 'super', packId: '2', stickerId: '38', stickerType: 3, }); }); + it('rejects incomplete super-face metadata instead of filling guessed ids', () => { + expect(() => faceWireFor(entry('392', 3, 2, null), 392)) + .toThrow(/incomplete super-face metadata/); + }); it('(1,1) face → small/classic by id range, not super', () => { expect(faceWireFor(entry('424', 1, 1, 52), 424)).toEqual({ kind: 'small' }); }); - it('cold (no catalog entry) → id-range guess', () => { - expect(faceWireFor(undefined, 14)).toEqual({ kind: 'classic' }); // < 260 - expect(faceWireFor(undefined, 424)).toEqual({ kind: 'small' }); // ≥ 260 - expect(faceWireFor(null, 100)).toEqual({ kind: 'classic' }); + it('rejects an unknown id instead of guessing a wire shape', () => { + expect(() => faceWireFor(null, 14)).toThrow(/absent from the current catalog/); + expect(() => faceWireFor(undefined, 424)).toThrow(/absent from the current catalog/); }); }); @@ -80,9 +112,193 @@ describe('FetchSysFaces.deserialize', () => { }); }); +describe('SysFaceStore — persistent catalog and query seam', () => { + const sender = {} as never; + + it('accepts face id 0 from the authoritative catalog', async () => { + const zero = entry('0', null, null, null, '/惊讶'); + const store = new SysFaceStore({ + storage: new MemoryCatalogStorage({ + schemaVersion: 1, + fetchedAt: 123, + packs: [{ packName: '经典', emojis: [zero] }], + }), + fetchCatalog: async () => { throw new Error('network must not be used'); }, + }); + + await store.ensureReady(sender); + + expect(store.lookup(0)?.qDes).toBe('/惊讶'); + expect(store.classify(0)).toEqual({ kind: 'classic' }); + }); + + it('loads a persisted catalog and resolves ids, descriptions, aliases, and pack names', async () => { + const storage = new MemoryCatalogStorage({ + schemaVersion: 1, + fetchedAt: 123, + packs: CATALOG, + }); + const store = new SysFaceStore({ + storage, + fetchCatalog: async () => { throw new Error('network must not be used'); }, + }); + + await store.ensureReady(sender); + + expect(store.lookup(392)?.qDes).toBe('/龙年快乐'); + expect(store.search('龙年').map((face) => face.qSid)).toEqual(['392']); + expect(store.search('SMILE').map((face) => face.qSid)).toEqual(['14']); + expect(store.search('经典').map((face) => face.qSid)).toEqual(['14']); + }); + + it('coalesces concurrent refreshes and persists the authoritative result once', async () => { + const storage = new MemoryCatalogStorage(); + let fetches = 0; + let release!: (packs: SysFacePackEntry[]) => void; + const pending = new Promise((resolve) => { release = resolve; }); + const store = new SysFaceStore({ + storage, + now: () => 456, + fetchCatalog: async () => { + fetches += 1; + return pending; + }, + }); + + const first = store.refresh(sender); + const second = store.refresh(sender); + release(CATALOG); + await Promise.all([first, second]); + + expect(fetches).toBe(1); + expect(storage.saved).toEqual([{ + schemaVersion: 1, + fetchedAt: 456, + packs: CATALOG, + }]); + }); + + it('refreshes a cache miss once, then keeps an authoritative not-found result', async () => { + const storage = new MemoryCatalogStorage({ + schemaVersion: 1, + fetchedAt: 123, + packs: CATALOG.slice(0, 1), + }); + let fetches = 0; + const store = new SysFaceStore({ + storage, + fetchCatalog: async () => { + fetches += 1; + return CATALOG; + }, + }); + + expect((await store.resolve(sender, 392))?.qSid).toBe('392'); + expect(await store.resolve(sender, 99999)).toBeNull(); + expect(await store.resolve(sender, 99999)).toBeNull(); + expect(fetches).toBe(1); + }); + + it('prewarms from login only once per process while sharing the result across accounts', async () => { + let fetches = 0; + const store = new SysFaceStore({ + storage: new MemoryCatalogStorage(), + fetchCatalog: async () => { + fetches += 1; + return CATALOG; + }, + }); + + await Promise.all([ + store.prewarm({} as never), + store.prewarm({} as never), + store.prewarm({} as never), + ]); + await store.prewarm({} as never); + + expect(fetches).toBe(1); + }); + + it('waits for an in-flight login refresh before resolving a cached face', async () => { + const staleCatalog: SysFacePackEntry[] = [{ + packName: '旧目录', + emojis: [entry('392', 1, 1, 52)], + }]; + let release!: (packs: SysFacePackEntry[]) => void; + let markFetchStarted!: () => void; + const fetchStarted = new Promise((resolve) => { markFetchStarted = resolve; }); + const pending = new Promise((resolve) => { release = resolve; }); + const store = new SysFaceStore({ + storage: new MemoryCatalogStorage({ + schemaVersion: 1, + fetchedAt: 123, + packs: staleCatalog, + }), + fetchCatalog: async () => { + markFetchStarted(); + return pending; + }, + }); + + const prewarm = store.prewarm(sender); + await fetchStarted; + const resolved = store.resolveWire(sender, 392); + let settled = false; + void resolved.finally(() => { settled = true; }); + await Promise.resolve(); + expect(settled).toBe(false); + + release(CATALOG); + await expect(resolved).resolves.toMatchObject({ kind: 'super' }); + await prewarm; + }); +}); + describe('makeFaceElem (via buildSendElems) — three-way wire encoding', () => { const ctx = { bridge: {} as never }; + it('awaits an authoritative refresh when the first send misses the persisted catalog', async () => { + sysFaceStore.load(CATALOG.slice(0, 1)); + let requests = 0; + const responseData = protobuf_encode>({ + body: { + commonFace: { + emojiList: [{ + emojiPackName: '经典', + emojiDetail: [{ qSid: '14', qDes: '/微笑' }], + }], + }, + specialBigFace: { + emojiList: [{ + emojiPackName: '超级表情', + emojiDetail: [{ + qSid: '392', qDes: '/龙年快乐', + aniStickerType: 3, aniStickerPackId: 2, aniStickerId: 38, + }], + }], + }, + }, + }); + const liveCtx = { + bridge: { + sendRawPacket: async () => { + requests += 1; + return { + success: true, + gotResponse: true, + errorCode: 0, + responseData, + }; + }, + } as never, + }; + + const [elem] = await buildSendElems([{ type: 'face', faceId: 392 }], liveCtx); + + expect(requests).toBe(1); + expect(elem.commonElem?.serviceType).toBe(37); + }); + it('encodes each face id by its catalog classification', async () => { sysFaceStore.load(CATALOG); // warm → ensureWarm no-ops, classify uses the catalog @@ -101,4 +317,11 @@ describe('makeFaceElem (via buildSendElems) — three-way wire encoding', () => const [classicElem] = await buildSendElems([{ type: 'face', faceId: 14 }], ctx); expect(classicElem.face?.index).toBe(14); }); + + it('rejects an unknown id even when building without a live send context', async () => { + sysFaceStore.load(CATALOG); + + await expect(buildSendElems([{ type: 'face', faceId: 99999 }])) + .rejects.toThrow(/absent from the current catalog/); + }); });