feat(proton): migrate notify.ts schemas + all 6 msg-push consumers

Mirrors all 27 notify.ts schemas as proton interface forms and switches
the entire msg-push decoder family over to the new compile-time API.

Migrated schemas (proton/notify.ts):
  OperatorField1, OperatorInfo, GroupChange, GroupAdminExtra,
  GroupAdminBody, GroupAdmin, InvitationInner, InvitationInfo,
  GroupInvitation, GroupInvite, GroupJoin, FriendRequestInfo,
  FriendRequest, FriendRecallTipInfo, FriendRecallInfo, FriendRecall,
  GroupMuteState, GroupMuteData, GroupMute, RecallMessage,
  GroupRecallTipInfo, GroupRecall, TemplParam, GeneralGrayTipInfo,
  EssenceMessage, NotifyMessageBody, GroupReactionDataInnerDataTarget,
  GroupReactionDataContent, GroupReactionDataInnerData,
  GroupReactionDataInner, GroupReactionData, GroupReactNotify

Consumer files switched to protobuf_decode<T>():
  - msg-push/helpers.ts (decodeOperatorUid)
  - msg-push/decoders/event-0x2dc.ts (5 call sites: GroupMute,
    GroupRecall, GroupGreyTip, GroupEssence, GroupMsgEmojiLike)
  - msg-push/decoders/event-0x210.ts (3 call sites: FriendRequest,
    FriendRecall, FriendPoke)
  - msg-push/decoders/group-admin.ts
  - msg-push/decoders/group-member-change.ts (join + leave)
  - msg-push/decoders/group-join-request.ts (join request + invitation
    + invite)

The notify.ts FriendRecall interface collides with events.ts's own
FriendRecall event type; the decoder imports it under the local alias
FriendRecallNotify to keep the existing event type intact.

Verification:
  - 6 new parity tests pinning notify wire equivalence
  - 591/591 core test suite passes (the existing decoder tests —
    group-msg-emoji-like, group-admin, etc. — implicitly validated
    wire format equivalence against real captured QQ payloads)
  - tsc --noEmit clean
This commit is contained in:
DrSmoothl
2026-05-19 08:19:14 +08:00
parent b7d8952163
commit 9f32dbd60c
8 changed files with 373 additions and 33 deletions
@@ -1,10 +1,12 @@
// Handles Event0x210 wrapper (528). Internal switch on subType dispatches
// to FriendRequest (35) / FriendRecall (138) / FriendPoke (290).
import { protoDecode } from '../../../protobuf/decode';
import {
FriendRequestSchema, FriendRecallSchema, GeneralGrayTipInfoSchema,
} from '../../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type {
FriendRequest as FriendRequestNotify,
FriendRecall as FriendRecallNotify,
GeneralGrayTipInfo,
} from '../../proto/proton/notify';
import type {
FriendRequestEvent, FriendRecall, FriendPokeEvent, QQEventVariant,
} from '../../events';
@@ -29,7 +31,7 @@ export const decodeEvent0x210: MsgPushDecoder = (ctx) => {
};
function decodeFriendRequest(ctx: MsgPushContext): QQEventVariant[] {
const request = protoDecode(ctx.content, FriendRequestSchema);
const request = protobuf_decode<FriendRequestNotify>(ctx.content);
if (!request?.info) return [];
const sourceUid = request.info.newSource || request.info.sourceUid || '';
const ev: FriendRequestEvent = {
@@ -45,7 +47,7 @@ function decodeFriendRequest(ctx: MsgPushContext): QQEventVariant[] {
}
function decodeFriendRecall(ctx: MsgPushContext): QQEventVariant[] {
const recall = protoDecode(ctx.content, FriendRecallSchema);
const recall = protobuf_decode<FriendRecallNotify>(ctx.content);
if (!recall?.info) return [];
const ev: FriendRecall = {
kind: 'friend_recall',
@@ -58,7 +60,7 @@ function decodeFriendRecall(ctx: MsgPushContext): QQEventVariant[] {
}
function decodeFriendPoke(ctx: MsgPushContext): QQEventVariant[] {
const grayTip = protoDecode(ctx.content, GeneralGrayTipInfoSchema);
const grayTip = protobuf_decode<GeneralGrayTipInfo>(ctx.content);
if (!grayTip || (grayTip.busiType ?? 0n) !== 12n) return [];
const templates = buildTemplateMap(grayTip.msgTemplParam ?? []);
const actor = findTemplateValue(templates, 'uin_str1');
@@ -2,10 +2,10 @@
// to GroupMute (12) / GroupMsgEmojiLike (16) / GroupRecall (17) /
// GroupGreyTip (20) / GroupEssence (21).
import { protoDecode } from '../../../protobuf/decode';
import {
GroupMuteSchema, NotifyMessageBodySchema, GroupReactNotifySchema,
} from '../../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type {
GroupMute, NotifyMessageBody, GroupReactNotify,
} from '../../proto/proton/notify';
import type {
GroupMuteEvent, GroupRecallEvent, GroupPokeEvent, GroupEssenceEvent,
GroupMsgEmojiLikeEvent,
@@ -35,7 +35,7 @@ export const decodeEvent0x2DC: MsgPushDecoder = (ctx) => {
};
function decodeGroupMute(ctx: MsgPushContext): QQEventVariant[] {
const mute = protoDecode(ctx.content, GroupMuteSchema);
const mute = protobuf_decode<GroupMute>(ctx.content);
if (!mute?.data?.state) return [];
const duration = mute.data.state.duration ?? 0;
const ev: GroupMuteEvent = {
@@ -53,7 +53,7 @@ function decodeGroupMute(ctx: MsgPushContext): QQEventVariant[] {
function decodeGroupRecall(ctx: MsgPushContext): QQEventVariant[] {
const payload = unwrapGroupNotifyPayload(ctx.content);
if (!payload) return [];
const notify = protoDecode(payload, NotifyMessageBodySchema);
const notify = protobuf_decode<NotifyMessageBody>(payload);
if (!notify?.recall?.recallMessages || notify.recall.recallMessages.length === 0) return [];
const recalled = notify.recall.recallMessages[0];
const ev: GroupRecallEvent = {
@@ -72,7 +72,7 @@ function decodeGroupRecall(ctx: MsgPushContext): QQEventVariant[] {
function decodeGroupGreyTip(ctx: MsgPushContext): QQEventVariant[] {
const payload = unwrapGroupNotifyPayload(ctx.content);
if (!payload) return [];
const notify = protoDecode(payload, NotifyMessageBodySchema);
const notify = protobuf_decode<NotifyMessageBody>(payload);
if (!notify?.generalGrayTip || (notify.generalGrayTip.busiType ?? 0n) !== 12n) return [];
const templates = buildTemplateMap(notify.generalGrayTip.msgTemplParam ?? []);
const actor = findTemplateValue(templates, 'uin_str1');
@@ -94,7 +94,7 @@ function decodeGroupGreyTip(ctx: MsgPushContext): QQEventVariant[] {
function decodeGroupEssence(ctx: MsgPushContext): QQEventVariant[] {
const payload = unwrapGroupNotifyPayload(ctx.content);
if (!payload) return [];
const notify = protoDecode(payload, NotifyMessageBodySchema);
const notify = protobuf_decode<NotifyMessageBody>(payload);
if (!notify?.essenceMessage) return [];
const essence = notify.essenceMessage;
const setFlag = essence.setFlag ?? essence.setFlag2 ?? 0;
@@ -124,7 +124,7 @@ const GROUP_REACT_DISCRIMINATOR = 35;
function decodeGroupMsgEmojiLike(ctx: MsgPushContext): QQEventVariant[] {
if (ctx.content.length <= GROUP_REACT_PREFIX_BYTES) return [];
const payload = ctx.content.subarray(GROUP_REACT_PREFIX_BYTES);
const notify = protoDecode(payload, GroupReactNotifySchema);
const notify = protobuf_decode<GroupReactNotify>(payload);
if (!notify) return [];
if ((notify.field13 ?? 0) !== GROUP_REACT_DISCRIMINATOR) {
unknownLog.debug('Event0x2DC subType=16 unhandled field13=%d (expected %d for emoji react)',
@@ -1,14 +1,14 @@
// Handles GroupAdminChangedNotice (44). extraEnable / extraDisable
// distinguishes set vs. unset.
import { protoDecode } from '../../../protobuf/decode';
import { GroupAdminSchema } from '../../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type { GroupAdmin } from '../../proto/proton/notify';
import type { GroupAdminEvent } from '../../events';
import type { MsgPushDecoder } from '../registry';
import { resolveUidToUin } from '../helpers';
export const decodeGroupAdmin: MsgPushDecoder = (ctx) => {
const admin = protoDecode(ctx.content, GroupAdminSchema);
const admin = protobuf_decode<GroupAdmin>(ctx.content);
if (!admin?.body) return [];
const extra = admin.body.extraEnable ?? admin.body.extraDisable;
if (!extra) return [];
@@ -2,16 +2,16 @@
// + GroupInviteNotice (87). All three produce GroupInviteEvent with
// different subType ('add' / 'invite') and flag prefixes.
import { protoDecode } from '../../../protobuf/decode';
import {
GroupJoinSchema, GroupInvitationSchema, GroupInviteSchema,
} from '../../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type {
GroupJoin, GroupInvitation, GroupInvite,
} from '../../proto/proton/notify';
import type { GroupInviteEvent } from '../../events';
import type { MsgPushDecoder } from '../registry';
import { resolveUidToUin } from '../helpers';
export const decodeGroupJoinRequest: MsgPushDecoder = (ctx) => {
const join = protoDecode(ctx.content, GroupJoinSchema);
const join = protobuf_decode<GroupJoin>(ctx.content);
if (!join) return [];
const ev: GroupInviteEvent = {
kind: 'group_invite',
@@ -28,7 +28,7 @@ export const decodeGroupJoinRequest: MsgPushDecoder = (ctx) => {
};
export const decodeGroupInvitation: MsgPushDecoder = (ctx) => {
const invitation = protoDecode(ctx.content, GroupInvitationSchema);
const invitation = protobuf_decode<GroupInvitation>(ctx.content);
if (!invitation?.info?.inner) return [];
const inner = invitation.info.inner;
const ev: GroupInviteEvent = {
@@ -46,7 +46,7 @@ export const decodeGroupInvitation: MsgPushDecoder = (ctx) => {
};
export const decodeGroupInvite: MsgPushDecoder = (ctx) => {
const invite = protoDecode(ctx.content, GroupInviteSchema);
const invite = protobuf_decode<GroupInvite>(ctx.content);
if (!invite) return [];
const ev: GroupInviteEvent = {
kind: 'group_invite',
@@ -2,14 +2,14 @@
// Both share GroupChangeSchema; the decreaseType field distinguishes kick vs
// voluntary leave (dt != 0 && dt != 130 means kicked).
import { protoDecode } from '../../../protobuf/decode';
import { GroupChangeSchema } from '../../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type { GroupChange } from '../../proto/proton/notify';
import type { GroupMemberJoin, GroupMemberLeave } from '../../events';
import type { MsgPushDecoder } from '../registry';
import { decodeOperatorUid, resolveUidToUin } from '../helpers';
export const decodeGroupMemberJoin: MsgPushDecoder = (ctx) => {
const change = protoDecode(ctx.content, GroupChangeSchema);
const change = protobuf_decode<GroupChange>(ctx.content);
if (!change) return [];
const groupId = change.groupUin ?? 0;
const userUid = change.memberUid ?? '';
@@ -28,7 +28,7 @@ export const decodeGroupMemberJoin: MsgPushDecoder = (ctx) => {
};
export const decodeGroupMemberLeave: MsgPushDecoder = (ctx) => {
const change = protoDecode(ctx.content, GroupChangeSchema);
const change = protobuf_decode<GroupChange>(ctx.content);
if (!change) return [];
const dt = change.decreaseType ?? 0;
const groupId = change.groupUin ?? 0;
+3 -3
View File
@@ -2,8 +2,8 @@
// and the rich-body decoder. No state, no I/O.
import { inflateSync } from 'zlib';
import { protoDecode } from '../../protobuf/decode';
import { OperatorInfoSchema } from '../proto/notify';
import { protobuf_decode } from '@snowluma/proton';
import type { OperatorInfo } from '../proto/proton/notify';
import type { IdentityService } from '../identity-service';
export function makeImageUrl(origUrl: string): string {
@@ -52,7 +52,7 @@ export function resolveUidToUin(identity: IdentityService, groupId: number, uid:
export function decodeOperatorUid(bytes: Uint8Array): string {
if (!bytes || bytes.length === 0) return '';
const info = protoDecode(bytes, OperatorInfoSchema);
const info = protobuf_decode<OperatorInfo>(bytes);
if (info?.operatorField?.uid) return info.operatorField.uid;
return Buffer.from(bytes).toString('utf8');
}
@@ -0,0 +1,239 @@
// Proton (compile-time) form of bridge/proto/notify.ts.
// One-to-one mirror; legacy `*Schema` constants stay alongside for back-compat.
import type { pb, pb_repeated, int_32, uint_32, uint_64, bool, bytes } from '@snowluma/proton';
export interface OperatorField1 {
uid?: pb<1, string>;
field2?: pb<2, uint_32>;
field3?: pb<3, bytes>;
field4?: pb<4, uint_32>;
field5?: pb<5, bytes>;
}
export interface OperatorInfo {
operatorField?: pb<1, OperatorField1>;
}
export interface GroupChange {
groupUin?: pb<1, uint_32>;
flag?: pb<2, uint_32>;
memberUid?: pb<3, string>;
decreaseType?: pb<4, uint_32>;
operatorBytes?: pb<5, bytes>;
increaseType?: pb<6, uint_32>;
field7?: pb<7, bytes>;
}
export interface GroupAdminExtra {
adminUid?: pb<1, string>;
isPromote?: pb<2, bool>;
}
export interface GroupAdminBody {
extraDisable?: pb<1, GroupAdminExtra>;
extraEnable?: pb<2, GroupAdminExtra>;
}
export interface GroupAdmin {
groupUin?: pb<1, uint_32>;
flag?: pb<2, uint_32>;
isPromote?: pb<3, bool>;
body?: pb<4, GroupAdminBody>;
}
export interface InvitationInner {
groupUin?: pb<1, uint_32>;
field2?: pb<2, uint_32>;
field3?: pb<3, uint_32>;
field4?: pb<4, uint_32>;
targetUid?: pb<5, string>;
invitorUid?: pb<6, string>;
field7?: pb<7, uint_32>;
field9?: pb<9, uint_32>;
field10?: pb<10, bytes>;
field11?: pb<11, uint_32>;
field12?: pb<12, string>;
}
export interface InvitationInfo {
inner?: pb<1, InvitationInner>;
}
export interface GroupInvitation {
cmd?: pb<1, int_32>;
info?: pb<2, InvitationInfo>;
}
export interface GroupInvite {
groupUin?: pb<1, uint_32>;
field2?: pb<2, uint_32>;
field3?: pb<3, uint_32>;
field4?: pb<4, uint_32>;
invitorUid?: pb<5, string>;
hashes?: pb<6, bytes>;
}
export interface GroupJoin {
groupUin?: pb<1, uint_32>;
field2?: pb<2, uint_32>;
targetUid?: pb<3, string>;
field4?: pb<4, uint_32>;
field6?: pb<6, uint_32>;
field7?: pb<7, string>;
field8?: pb<8, uint_32>;
field9?: pb<9, bytes>;
}
export interface FriendRequestInfo {
targetUid?: pb<1, string>;
sourceUid?: pb<2, string>;
newSource?: pb<5, string>;
message?: pb<10, string>;
source?: pb<11, string>;
}
export interface FriendRequest {
info?: pb<1, FriendRequestInfo>;
}
export interface FriendRecallTipInfo {
tip?: pb<2, string>;
}
export interface FriendRecallInfo {
fromUid?: pb<1, string>;
toUid?: pb<2, string>;
clientSequence?: pb<3, uint_32>;
newId?: pb<4, uint_64>;
time?: pb<5, uint_32>;
random?: pb<6, uint_32>;
pkgNum?: pb<7, uint_32>;
pkgIndex?: pb<8, uint_32>;
divSeq?: pb<9, uint_32>;
tipInfo?: pb<13, FriendRecallTipInfo>;
}
export interface FriendRecall {
info?: pb<1, FriendRecallInfo>;
instId?: pb<2, uint_32>;
appId?: pb<3, uint_32>;
longMessageFlag?: pb<4, uint_32>;
reserved?: pb<5, bytes>;
}
export interface GroupMuteState {
targetUid?: pb<1, string>;
duration?: pb<2, uint_32>;
}
export interface GroupMuteData {
timestamp?: pb<1, uint_32>;
type?: pb<2, uint_32>;
state?: pb<3, GroupMuteState>;
}
export interface GroupMute {
groupUin?: pb<1, uint_32>;
subType?: pb<2, uint_32>;
field3?: pb<3, uint_32>;
operatorUid?: pb<4, string>;
data?: pb<5, GroupMuteData>;
}
export interface RecallMessage {
sequence?: pb<1, uint_32>;
time?: pb<2, uint_32>;
random?: pb<3, uint_32>;
type?: pb<4, uint_32>;
flag?: pb<5, uint_32>;
authorUid?: pb<6, string>;
}
export interface GroupRecallTipInfo {
tip?: pb<2, string>;
}
export interface GroupRecall {
operatorUid?: pb<1, string>;
recallMessages?: pb_repeated<3, RecallMessage>;
userDef?: pb<5, bytes>;
groupType?: pb<6, int_32>;
opType?: pb<7, int_32>;
tipInfo?: pb<9, GroupRecallTipInfo>;
}
export interface TemplParam {
name?: pb<1, string>;
value?: pb<2, string>;
}
export interface GeneralGrayTipInfo {
busiType?: pb<1, uint_64>;
busiId?: pb<2, uint_64>;
ctrlFlag?: pb<3, uint_32>;
c2cType?: pb<4, uint_32>;
serviceType?: pb<5, uint_32>;
templId?: pb<6, uint_64>;
msgTemplParam?: pb_repeated<7, TemplParam>;
content?: pb<8, string>;
}
export interface EssenceMessage {
groupUin?: pb<1, uint_32>;
msgSequence?: pb<2, uint_32>;
random?: pb<3, uint_32>;
setFlag?: pb<4, uint_32>;
memberUin?: pb<5, uint_32>;
operatorUin?: pb<6, uint_32>;
timestamp?: pb<7, uint_32>;
msgSequence2?: pb<8, uint_32>;
operatorNickname?: pb<9, string>;
memberNickname?: pb<10, string>;
setFlag2?: pb<11, uint_32>;
}
export interface NotifyMessageBody {
type?: pb<1, uint_32>;
groupUin?: pb<4, uint_32>;
eventParam?: pb<5, bytes>;
recall?: pb<11, GroupRecall>;
field13?: pb<13, uint_32>;
operatorUid?: pb<21, string>;
generalGrayTip?: pb<26, GeneralGrayTipInfo>;
essenceMessage?: pb<33, EssenceMessage>;
msgSequence?: pb<37, uint_32>;
field39?: pb<39, uint_32>;
}
// ─── Event0x2DC subType=16: GroupMsgEmojiLike ────────────────────────
export interface GroupReactionDataInnerDataTarget {
seq?: pb<1, uint_64>;
}
export interface GroupReactionDataContent {
code?: pb<1, string>;
count?: pb<3, uint_32>;
operatorUid?: pb<4, string>;
type?: pb<5, uint_32>;
}
export interface GroupReactionDataInnerData {
groupReactionTarget?: pb<2, GroupReactionDataInnerDataTarget>;
groupReactionDataContent?: pb<3, GroupReactionDataContent>;
}
export interface GroupReactionDataInner {
data?: pb<1, GroupReactionDataInnerData>;
}
export interface GroupReactionData {
data?: pb<1, GroupReactionDataInner>;
}
export interface GroupReactNotify {
groupUin?: pb<4, uint_64>;
field13?: pb<13, uint_32>;
groupReactionData?: pb<44, GroupReactionData>;
}
+99
View File
@@ -28,6 +28,14 @@ import {
PushMsgBodySchema,
PushMsgSchema,
} from '../src/bridge/proto/message';
import {
GroupChangeSchema,
GroupAdminSchema,
NotifyMessageBodySchema,
GroupReactNotifySchema,
FriendRequestSchema,
GroupJoinSchema,
} from '../src/bridge/proto/notify';
import type {
SendLongMsgResp,
@@ -50,6 +58,14 @@ import type {
PushMsgBody,
PushMsg,
} from '../src/bridge/proto/proton/message';
import type {
GroupChange,
GroupAdmin,
NotifyMessageBody,
GroupReactNotify,
FriendRequest as FriendRequestNotify,
GroupJoin,
} from '../src/bridge/proto/proton/notify';
function hex(buf: Uint8Array): string {
return Buffer.from(buf).toString('hex');
@@ -286,6 +302,89 @@ describe('proton ↔ legacy parity (longmsg subset)', () => {
expect(hex(proton)).toBe(hex(legacy));
});
// ── notify.ts coverage ──────────────────────────────────────────────
it('encodes GroupChange identically', () => {
const data: GroupChange = {
groupUin: 555,
flag: 1,
memberUid: 'u_x',
decreaseType: 130,
operatorBytes: new Uint8Array([1, 2, 3]),
increaseType: 1,
};
const legacy = protoEncode(data as any, GroupChangeSchema);
const proton = protobuf_encode<GroupChange>(data);
expect(hex(proton)).toBe(hex(legacy));
});
it('encodes GroupAdmin (extraEnable variant) identically', () => {
const data: GroupAdmin = {
groupUin: 777, flag: 1, isPromote: true,
body: { extraEnable: { adminUid: 'u_admin', isPromote: true } },
};
const legacy = protoEncode(data as any, GroupAdminSchema);
const proton = protobuf_encode<GroupAdmin>(data);
expect(hex(proton)).toBe(hex(legacy));
});
it('encodes NotifyMessageBody (recall variant with repeated RecallMessage) identically', () => {
const data: NotifyMessageBody = {
type: 17,
groupUin: 555,
recall: {
operatorUid: 'u_op',
recallMessages: [
{ sequence: 1, time: 100, random: 42, type: 1, flag: 1, authorUid: 'u_a' },
{ sequence: 2, time: 200, random: 43, type: 1, flag: 1, authorUid: 'u_a' },
],
groupType: 1, opType: 2,
tipInfo: { tip: 'recalled' },
},
msgSequence: 99,
};
const legacy = protoEncode(data as any, NotifyMessageBodySchema);
const proton = protobuf_encode<NotifyMessageBody>(data);
expect(hex(proton)).toBe(hex(legacy));
});
it('encodes GroupReactNotify (deeply nested) identically', () => {
const data: GroupReactNotify = {
groupUin: 555n,
field13: 35,
groupReactionData: {
data: {
data: {
groupReactionTarget: { seq: 12345n },
groupReactionDataContent: { code: '128516', count: 1, operatorUid: 'u_op', type: 1 },
},
},
},
};
const legacy = protoEncode(data as any, GroupReactNotifySchema);
const proton = protobuf_encode<GroupReactNotify>(data);
expect(hex(proton)).toBe(hex(legacy));
});
it('encodes FriendRequest identically', () => {
const data: FriendRequestNotify = {
info: { targetUid: 'u_me', sourceUid: 'u_them', newSource: 'qrcode', message: 'hello!', source: 'web' },
};
const legacy = protoEncode(data as any, FriendRequestSchema);
const proton = protobuf_encode<FriendRequestNotify>(data);
expect(hex(proton)).toBe(hex(legacy));
});
it('encodes GroupJoin identically', () => {
const data: GroupJoin = {
groupUin: 555, field2: 1, targetUid: 'u_them', field4: 1,
field6: 1, field7: 'reason', field8: 1, field9: new Uint8Array([0xaa]),
};
const legacy = protoEncode(data as any, GroupJoinSchema);
const proton = protobuf_encode<GroupJoin>(data);
expect(hex(proton)).toBe(hex(legacy));
});
// ── Documented divergence: proto3 default-value omission ────────────
it('proton omits default-valued numeric fields (legacy emits them)', () => {