fix(protocol): resolve animation metadata for unlisted faces

Query missing system faces individually and validate their metadata before sending. Share concurrent lookups and surface lookup failures.

Fixes #488
This commit is contained in:
DrSmoothl
2026-10-04 12:53:48 +08:00
parent cf2587a58b
commit efb32ed069
5 changed files with 144 additions and 13 deletions
@@ -1,6 +1,6 @@
// 0x9154_1 — QQ system face / emoji catalog protobuf shapes.
import type { pb, pb_repeated, int_32 } from '@snowluma/proton';
import type { pb, pb_repeated, int_32, bool } from '@snowluma/proton';
export interface OidbFaceResourceUrl {
baseUrl?: pb<1, string>;
@@ -49,3 +49,12 @@ export interface OidbFetchSysFacesResp {
specialBigFace?: pb<3, OidbFaceContent>;
specialMagicFace?: pb<4, OidbFaceContent>;
}
export interface OidbFetchSysFaceReq {
qSid?: pb<1, string>;
}
export interface OidbFetchSysFaceResp {
emoji?: pb<1, OidbFaceEmoji>;
field2?: pb<2, bool>;
}
@@ -0,0 +1,26 @@
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import type { OidbBase } from '@snowluma/proto-defs/oidb';
import type { OidbFetchSysFaceReq, OidbFetchSysFaceResp } from '@snowluma/proto-defs/oidb-actions/sys-faces';
import { invokeOidb, type OidbSender } from '../../oidb-service';
import { emojiToEntry, type SysFaceEntry } from './fetch-sys-faces';
/** Resolve metadata for a system face that is absent from the visible panels. */
export namespace FetchSysFace {
export const command = 0x9155;
export const subCommand = 1;
export interface Params { faceId: number }
export type Deps = OidbSender;
export const serialize = (_ctx: Deps, p: Params): OidbFetchSysFaceReq => ({ qSid: String(p.faceId) });
export const deserialize = (_ctx: Deps, body: OidbFetchSysFaceResp): SysFaceEntry | null => {
if (!body.emoji) return null;
const entry = emojiToEntry(body.emoji, { source: 'single', packIndex: 0, faceIndex: 0 });
if (!entry) throw new Error('system face lookup response is missing its id');
return entry;
};
export const encode = (env: OidbBase<OidbFetchSysFaceReq>): Uint8Array =>
protobuf_encode<OidbBase<OidbFetchSysFaceReq>>(env);
export const decode = (bytes: Uint8Array): OidbBase<OidbFetchSysFaceResp> =>
protobuf_decode<OidbBase<OidbFetchSysFaceResp>>(bytes);
export const invoke = (deps: Deps, params: Params): Promise<SysFaceEntry | null> =>
invokeOidb(deps, FetchSysFace, params);
}
@@ -44,12 +44,12 @@ export interface SysFacePackEntry {
}
interface FaceLocation {
source: 'common' | 'special-big' | 'magic';
source: 'common' | 'special-big' | 'magic' | 'single';
packIndex: number;
faceIndex: number;
}
function emojiToEntry(e: OidbFaceEmoji, location: FaceLocation): SysFaceEntry | null {
export function emojiToEntry(e: OidbFaceEmoji, location: FaceLocation): SysFaceEntry | null {
const qSid = e.qSid;
if (qSid == null || qSid === '') {
const metadata = protobuf_getUnknownFieldMetadata(e);
+40 -9
View File
@@ -9,6 +9,7 @@ import {
type SysFaceEntry,
type SysFacePackEntry,
} from './oidb-services/sys-faces/fetch-sys-faces';
import { FetchSysFace } from './oidb-services/sys-faces/fetch-sys-face';
import type { OidbSender } from './oidb-service';
export type { SysFaceEntry, SysFacePackEntry } from './oidb-services/sys-faces/fetch-sys-faces';
@@ -36,6 +37,7 @@ export interface SysFaceCatalogStorage {
export interface SysFaceStoreOptions {
storage?: SysFaceCatalogStorage;
fetchCatalog?: (sender: OidbSender) => Promise<SysFacePackEntry[]>;
fetchFace?: (sender: OidbSender, faceId: number) => Promise<SysFaceEntry | null>;
now?: () => number;
}
@@ -69,6 +71,9 @@ export class SysFaceStore {
private storage: SysFaceCatalogStorage | null;
private readonly fetchCatalog: (sender: OidbSender) => Promise<SysFacePackEntry[]>;
private readonly now: () => number;
private readonly fetchFace: NonNullable<SysFaceStoreOptions['fetchFace']>;
private readonly singleFaces = new Map<number, SysFaceEntry | null>();
private readonly singleInflight = new Map<number, Promise<SysFaceEntry | null>>();
private cacheLoadCompleted = false;
private cacheLoadInflight: Promise<boolean> | null = null;
private refreshInflight: Promise<SysFacePackEntry[]> | null = null;
@@ -80,6 +85,7 @@ export class SysFaceStore {
this.storage = options.storage ?? null;
this.fetchCatalog = options.fetchCatalog ?? ((sender) => FetchSysFaces.invoke(sender));
this.now = options.now ?? Date.now;
this.fetchFace = options.fetchFace ?? ((sender, faceId) => FetchSysFace.invoke(sender, { faceId }));
}
/** Configure persistence before the shared store has been used. */
@@ -94,10 +100,11 @@ export class SysFaceStore {
* obtained a full catalog and want to reuse the same query/send semantics. */
load(packs: SysFacePackEntry[]): void {
this.catalog = indexCatalog(validateCatalog(packs));
this.singleFaces.clear();
}
lookup(faceId: number): SysFaceEntry | null {
return this.catalog?.byId.get(String(faceId)) ?? null;
return this.catalog?.byId.get(String(faceId)) ?? this.singleFaces.get(faceId) ?? null;
}
/** Case-insensitive query over id, description, aliases, and pack name. */
@@ -183,6 +190,7 @@ export class SysFaceStore {
};
this.catalog = indexCatalog(validated);
this.refreshedInProcess = true;
this.singleFaces.clear();
if (this.storage) await this.storage.save(snapshot);
log.info(
'system face catalog refreshed: entries=%d uniqueFaces=%d overlaps=%d packs=%d elapsedMs=%d',
@@ -208,21 +216,44 @@ export class SysFaceStore {
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. */
/** Panel membership does not determine whether a face can be animated. */
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);
let cached = this.lookup(faceId);
if (cached) return cached;
if (!this.refreshedInProcess) {
await this.refresh(sender);
cached = this.lookup(faceId);
if (cached) return cached;
}
if (this.singleFaces.has(faceId)) return this.singleFaces.get(faceId)!;
const pending = this.singleInflight.get(faceId);
if (pending) return pending;
const request = this.fetchFace(sender, faceId).then((entry) => {
if (entry) {
if (entry.qSid !== String(faceId)) {
throw new Error(`system face lookup id mismatch: requested=${faceId} received=${entry.qSid}`);
}
validateCatalog([{ packName: '', emojis: [entry] }]);
faceWireFor(entry, faceId);
}
this.singleFaces.set(faceId, entry);
log.debug('system face lookup completed: id=%d found=%s animated=%s',
faceId, entry !== null, entry !== null && isSuperFaceEntry(entry));
return entry;
}).catch((error) => {
log.error('system face lookup failed: id=%d error=%s',
faceId, error instanceof Error ? error.message : String(error));
throw error;
}).finally(() => { this.singleInflight.delete(faceId); });
this.singleInflight.set(faceId, request);
return request;
}
async resolveWire(sender: OidbSender, faceId: number): Promise<FaceWire> {
const entry = await this.resolve(sender, faceId);
if (!entry) {
log.debug('system face id %d is not listed in the catalog; sending its small representation', faceId);
log.debug('system face id %d has no metadata after lookup; sending its small representation', faceId);
}
return faceWireFor(entry, faceId);
}
+66 -1
View File
@@ -1,10 +1,12 @@
import { describe, it, expect } from 'vitest';
import { describe, it, expect, vi } from 'vitest';
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 {
OidbFetchSysFacesReq,
OidbFetchSysFacesResp,
OidbFetchSysFaceReq,
OidbFetchSysFaceResp,
} from '@snowluma/proto-defs/oidb-actions/sys-faces';
import {
FetchSysFaces,
@@ -22,6 +24,7 @@ import {
type SysFaceCatalogStorage,
} from '../src/sys-face-store';
import { buildSendElems } from '../src/element-builder';
import { FetchSysFace } from '../src/oidb-services/sys-faces/fetch-sys-face';
function entry(
qSid: string,
@@ -127,6 +130,36 @@ describe('FetchSysFaces protocol contract', () => {
});
});
describe('FetchSysFace protocol contract', () => {
it('queries the requested id and preserves animation metadata from the response', async () => {
const sendRawPacket = vi.fn(async (_command: string, _body: Uint8Array) => ({
success: true, gotResponse: true, errorCode: 0, errorMessage: '',
responseData: protobuf_encode<OidbBase<OidbFetchSysFaceResp>>({
body: { emoji: {
qSid: '507', qDes: '/test', aniStickerType: 1,
aniStickerPackId: 4, aniStickerId: 107,
aniStickerWidth: 200, aniStickerHeight: 240,
} },
}),
}));
const store = new SysFaceStore({ fetchCatalog: async () => CATALOG });
await expect(store.resolveWire({ sendRawPacket }, 507)).resolves.toEqual({
kind: 'super', packId: '4', stickerId: '107', stickerType: 1,
});
expect(sendRawPacket).toHaveBeenCalledOnce();
const [command, bytes] = sendRawPacket.mock.calls[0]!;
expect(command).toBe('OidbSvcTrpcTcp.0x9155_1');
expect(protobuf_decode<OidbBase<OidbFetchSysFaceReq>>(bytes)).toMatchObject({
command: 0x9155, subCommand: 1, body: { qSid: '507' },
});
expect(store.lookup(507)).toMatchObject({ aniStickerWidth: 200, aniStickerHeight: 240 });
});
it('does not invent metadata for an empty lookup result', () => {
expect(FetchSysFace.deserialize({} as never, {})).toBeNull();
});
});
describe('FetchSysFaces.deserialize', () => {
it('decodes every group in the third panel, including unnamed and hidden faces (#482)', () => {
const wire = protobuf_encode<OidbFetchSysFacesResp>({
@@ -394,6 +427,7 @@ describe('SysFaceStore — persistent catalog and query seam', () => {
});
let fetches = 0;
const store = new SysFaceStore({
fetchFace: async () => null,
storage,
fetchCatalog: async () => {
fetches += 1;
@@ -576,3 +610,34 @@ describe('makeFaceElem (via buildSendElems) — three-way wire encoding', () =>
expect(protobuf_decode<QSmallFaceExtra>(element.commonElem!.pbElem!).faceId).toBe(504);
});
});
describe('system faces outside visible panels', () => {
it('resolves missing animation metadata once and shares concurrent lookups', async () => {
const fetchFace = vi.fn(async () => entry('507', 1, 4, 107));
const store = new SysFaceStore({ fetchCatalog: async () => CATALOG, fetchFace });
const [first, second] = await Promise.all([
store.resolveWire({} as never, 507), store.resolveWire({} as never, 507),
]);
expect(first).toEqual({ kind: 'super', packId: '4', stickerId: '107', stickerType: 1 });
expect(second).toEqual(first);
expect(store.lookup(507)?.qSid).toBe('507');
await store.resolveWire({} as never, 507);
expect(fetchFace).toHaveBeenCalledOnce();
});
it('does not silently send a small face after a lookup failure and permits retry', async () => {
const fetchFace = vi.fn().mockRejectedValueOnce(new Error('lookup failed'))
.mockResolvedValueOnce(entry('507', 1, 4, 107));
const store = new SysFaceStore({ fetchCatalog: async () => CATALOG, fetchFace });
await expect(store.resolveWire({} as never, 507)).rejects.toThrow('lookup failed');
await expect(store.resolveWire({} as never, 507)).resolves.toMatchObject({ kind: 'super' });
});
it('rejects mismatched or incomplete animation metadata', async () => {
for (const face of [entry('506', 1, 4, 107), entry('507', 1, 4, null)]) {
const store = new SysFaceStore({ fetchCatalog: async () => CATALOG, fetchFace: async () => face });
await expect(store.resolveWire({} as never, 507)).rejects.toThrow();
expect(store.lookup(507)).toBeNull();
}
});
});