feat(protocol): complete system face catalog lifecycle
Persist and validate the shared system face catalog, refresh it once when the first account connects, and coalesce concurrent loads. Resolve outgoing face metadata from the catalog so startup races, unknown IDs, and incomplete entries fail before sending.
This commit is contained in:
@@ -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';
|
||||
|
||||
@@ -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<SysFacePackEntry[]> {
|
||||
return sysFaceStore.getCatalog(this.ctx, refresh);
|
||||
}
|
||||
|
||||
async fetchFace(faceId: number, refresh = false): Promise<SysFaceEntry | null> {
|
||||
if (refresh) {
|
||||
await sysFaceStore.refresh(this.ctx);
|
||||
return sysFaceStore.lookup(faceId);
|
||||
}
|
||||
return sysFaceStore.resolve(this.ctx, faceId);
|
||||
}
|
||||
|
||||
async search(query: string): Promise<SysFaceEntry[]> {
|
||||
await sysFaceStore.ensureReady(this.ctx);
|
||||
return sysFaceStore.search(query);
|
||||
}
|
||||
|
||||
async isSuper(faceId: number, refresh = false): Promise<boolean> {
|
||||
const face = await this.fetchFace(faceId, refresh);
|
||||
return face !== null && isSuperFaceEntry(face);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
|
||||
|
||||
@@ -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),
|
||||
);
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -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('/微笑');
|
||||
});
|
||||
});
|
||||
@@ -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"
|
||||
|
||||
@@ -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<ProtoElem> {
|
||||
// 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':
|
||||
|
||||
@@ -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<SysFaceCatalogSnapshot | null> {
|
||||
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<void> {
|
||||
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 });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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<SysFaceCatalogSnapshot | null>;
|
||||
save(snapshot: SysFaceCatalogSnapshot): Promise<void>;
|
||||
}
|
||||
|
||||
export interface SysFaceStoreOptions {
|
||||
storage?: SysFaceCatalogStorage;
|
||||
fetchCatalog?: (sender: OidbSender) => Promise<SysFacePackEntry[]>;
|
||||
now?: () => number;
|
||||
}
|
||||
|
||||
interface IndexedCatalog {
|
||||
packs: SysFacePackEntry[];
|
||||
byId: Map<string, SysFaceEntry>;
|
||||
packNameById: Map<string, string>;
|
||||
}
|
||||
|
||||
/** 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<SysFacePackEntry[]>;
|
||||
private readonly now: () => number;
|
||||
private cacheLoadCompleted = false;
|
||||
private cacheLoadInflight: Promise<boolean> | null = null;
|
||||
private refreshInflight: Promise<SysFacePackEntry[]> | null = null;
|
||||
private refreshedInProcess = false;
|
||||
private prewarmInflight: Promise<void> | null = null;
|
||||
private prewarmed = false;
|
||||
|
||||
class SysFaceStore {
|
||||
private byId: Map<string, SysFaceEntry> | null = null;
|
||||
private inflight: Promise<void> | 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<void> {
|
||||
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<void> {
|
||||
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<SysFacePackEntry[]> {
|
||||
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<SysFaceEntry | null> {
|
||||
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<FaceWire> {
|
||||
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<SysFacePackEntry[]> {
|
||||
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<boolean> {
|
||||
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<string, SysFaceEntry> {
|
||||
const map = new Map<string, SysFaceEntry>();
|
||||
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<string>();
|
||||
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<string, SysFaceEntry>();
|
||||
const packNameById = new Map<string, string>();
|
||||
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). */
|
||||
|
||||
@@ -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<string> {
|
||||
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);
|
||||
});
|
||||
});
|
||||
@@ -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<SysFaceCatalogSnapshot | null> {
|
||||
return this.initial;
|
||||
}
|
||||
|
||||
async save(snapshot: SysFaceCatalogSnapshot): Promise<void> {
|
||||
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<SysFacePackEntry[]>((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<void>((resolve) => { markFetchStarted = resolve; });
|
||||
const pending = new Promise<SysFacePackEntry[]>((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<OidbBase<OidbFetchSysFacesResp>>({
|
||||
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/);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user