From efb32ed06966a46cfec2d1971f03fc825fb5f31c Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Sun, 4 Oct 2026 12:53:48 +0800 Subject: [PATCH] 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 --- .../proto-defs/src/oidb-actions/sys-faces.ts | 11 ++- .../oidb-services/sys-faces/fetch-sys-face.ts | 26 +++++++ .../sys-faces/fetch-sys-faces.ts | 4 +- packages/protocol/src/sys-face-store.ts | 49 +++++++++++--- packages/protocol/tests/sys-faces.test.ts | 67 ++++++++++++++++++- 5 files changed, 144 insertions(+), 13 deletions(-) create mode 100644 packages/protocol/src/oidb-services/sys-faces/fetch-sys-face.ts diff --git a/packages/proto-defs/src/oidb-actions/sys-faces.ts b/packages/proto-defs/src/oidb-actions/sys-faces.ts index 0b48e2d9..4029bcb3 100644 --- a/packages/proto-defs/src/oidb-actions/sys-faces.ts +++ b/packages/proto-defs/src/oidb-actions/sys-faces.ts @@ -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>; +} diff --git a/packages/protocol/src/oidb-services/sys-faces/fetch-sys-face.ts b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-face.ts new file mode 100644 index 00000000..9f2e71b4 --- /dev/null +++ b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-face.ts @@ -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): Uint8Array => + protobuf_encode>(env); + export const decode = (bytes: Uint8Array): OidbBase => + protobuf_decode>(bytes); + export const invoke = (deps: Deps, params: Params): Promise => + invokeOidb(deps, FetchSysFace, params); +} diff --git a/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts index 4d875b84..20fd18fa 100644 --- a/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts +++ b/packages/protocol/src/oidb-services/sys-faces/fetch-sys-faces.ts @@ -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); diff --git a/packages/protocol/src/sys-face-store.ts b/packages/protocol/src/sys-face-store.ts index bf3ec4af..808d204d 100644 --- a/packages/protocol/src/sys-face-store.ts +++ b/packages/protocol/src/sys-face-store.ts @@ -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; + fetchFace?: (sender: OidbSender, faceId: number) => Promise; now?: () => number; } @@ -69,6 +71,9 @@ export class SysFaceStore { private storage: SysFaceCatalogStorage | null; private readonly fetchCatalog: (sender: OidbSender) => Promise; private readonly now: () => number; + private readonly fetchFace: NonNullable; + private readonly singleFaces = new Map(); + private readonly singleInflight = new Map>(); private cacheLoadCompleted = false; private cacheLoadInflight: Promise | null = null; private refreshInflight: Promise | 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 { 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 { 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); } diff --git a/packages/protocol/tests/sys-faces.test.ts b/packages/protocol/tests/sys-faces.test.ts index f20ec968..86c5dd81 100644 --- a/packages/protocol/tests/sys-faces.test.ts +++ b/packages/protocol/tests/sys-faces.test.ts @@ -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>({ + 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>(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({ @@ -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(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(); + } + }); +});