@juzi/wechaty-puppet-service 1.0.129 → 1.0.131

package/dist/esm/src/client/puppet-service.js

@@ -28,7 +28,8 @@ import { EventTypeRev, } from '../event-type-rev.js';
 import { packageJson } from '../package-json.js';
 import { GrpcManager } from './grpc-manager.js';
 import { PayloadStore } from './payload-store.js';
-import { OptionalBooleanUnwrapper, OptionalBooleanWrapper, callRecordPbToPayload, channelPayloadToPb, channelPbToPayload, chatHistoryPbToPayload, contactPbToPayload, postPayloadToPb, roomMemberPbToPayload, urlLinkPbToPayload, channelCardPayloadToPb, channelCardPbToPayload, miniProgramPayloadToPb, urlLinkPayloadToPb, locationPayloadToPb } from '../utils/pb-payload-helper.js';
+import { RoomCacheCoordinator, RoomCacheOperationError } from './room-cache-coordinator.js';
+import { OptionalBooleanUnwrapper, OptionalBooleanWrapper, callRecordPbToPayload, channelPayloadToPb, channelPbToPayload, chatHistoryPbToPayload, contactPbToPayload, postPayloadToPb, roomMemberPbToPayload, urlLinkPbToPayload, channelCardPayloadToPb, channelCardPbToPayload, miniProgramPayloadToPb, urlLinkPayloadToPb, locationPayloadToPb, roomPbToPayload, roomMemberLoadStatePbToPayload, roomMemberSnapshotPbToPayload, validateRoomMemberRevision, validateRoomMemberLoadState } from '../utils/pb-payload-helper.js';
 import { puppetCallMediaTypeToGrpc, grpcCallTypeToPuppetMedia } from '../utils/call-media-mapping.js';
 import { timeoutPromise } from 'gerror';
 import { BooleanIndicator } from 'state-switch';
@@ -47,6 +48,15 @@ class PuppetService extends PUPPET.Puppet {
     options;
     static VERSION = VERSION;
     _payloadStore;
+    roomCache = new RoomCacheCoordinator();
+    eventQueue = Promise.resolve();
+    eventEpoch = 0;
+    eventsBlocked = false;
+    failedEventSeq;
+    activeEventSeq;
+    pendingEventSeq;
+    checkpointQueue = Promise.resolve();
+    pendingCheckpointRollback;
     timeoutMilliseconds;
     _grpcManager;
     get grpcManager() {
@@ -100,6 +110,8 @@ class PuppetService extends PUPPET.Puppet {
         this.log.verbose('PuppetService', 'onStart()');
         this.waitingForLogin = false;
         this.waitingForReady = false;
+        this.suspendEventProcessing();
+        this.eventsBlocked = false;
         if (this._grpcManager) {
             this.log.warn('PuppetService', 'onStart() found this.grpc is already existed. dropped.');
             this._grpcManager = undefined;
@@ -116,7 +128,7 @@ class PuppetService extends PUPPET.Puppet {
         this.bridgeGrpcEventStream(grpcManager);
         this.log.info('PuppetService', 'start() setting up bridge grpc event stream ... done');
         this.log.info('PuppetService', 'start() starting grpc manager...');
-        const { lastEventSeq, accountId } = await this.getMiscellaneousStoreData();
+        const { lastEventSeq, accountId } = await this.eventResumePosition();
         await grpcManager.start(lastEventSeq, accountId);
         this.log.info('PuppetService', 'start() starting grpc manager... done');
         this.log.info('PuppetService', 'start healthCheck');
@@ -125,6 +137,8 @@ class PuppetService extends PUPPET.Puppet {
     }
     async onStop() {
         this.log.info('PuppetService', 'onStop()');
+        this.suspendEventProcessing();
+        await this.checkpointQueue;
         if (this._grpcManager) {
             this.log.info('PuppetService', 'onStop() stopping grpc manager ...');
             const grpcManager = this._grpcManager;
@@ -160,7 +174,41 @@ class PuppetService extends PUPPET.Puppet {
     bridgeGrpcEventStream(client) {
         this.log.verbose('PuppetService', 'bridgeGrpcEventStream(client)');
         client
-            .on('data', this.onGrpcStreamEvent.bind(this))
+            .on('data', (event) => {
+            if (client !== this._grpcManager || this.eventsBlocked) {
+                return;
+            }
+            const epoch = this.eventEpoch;
+            this.eventQueue = this.eventQueue.then(async () => {
+                if (!this.ownsEventWorker(client, epoch)) {
+                    return undefined;
+                }
+                this.activeEventSeq = event.getSeq();
+                try {
+                    if (this.failedEventSeq !== undefined && event.getSeq() > this.failedEventSeq) {
+                        throw new Error(`Replay skipped failed event ${this.failedEventSeq}; stream halted until reset`);
+                    }
+                    await this.onGrpcStreamEvent(event, epoch);
+                    if (!this.ownsEventWorker(client, epoch)) {
+                        return undefined;
+                    }
+                    if (event.getSeq() === this.failedEventSeq) {
+                        this.failedEventSeq = undefined;
+                    }
+                }
+                catch (error) {
+                    if (!this.ownsEventWorker(client, epoch)) {
+                        this.log.error('PuppetService', 'superseded event worker failed: %s', error);
+                        return undefined;
+                    }
+                    this.haltEventStream(client, event, error);
+                }
+                if (epoch === this.eventEpoch) {
+                    this.activeEventSeq = undefined;
+                }
+                return undefined;
+            }).catch((error) => { this.reportStreamError(error); });
+        })
             .on('end', () => {
             this.log.verbose('PuppetService', 'bridgeGrpcEventStream() eventStream.on(end)');
         })
@@ -185,7 +233,128 @@ class PuppetService extends PUPPET.Puppet {
             this.log.verbose('PuppetService', 'bridgeGrpcEventStream() eventStream.on(cancel), %s', JSON.stringify(args));
         });
     }
-    async onGrpcStreamEvent(event) {
+    suspendEventProcessing() {
+        if (this.activeEventSeq) {
+            this.pendingEventSeq ??= this.activeEventSeq;
+        }
+        this.eventEpoch++;
+        this.eventsBlocked = true;
+        this.activeEventSeq = undefined;
+        this.eventQueue = Promise.resolve();
+    }
+    ownsEventWorker(manager, epoch) {
+        return manager === this._grpcManager && this.isEventEpochCurrent(epoch);
+    }
+    isEventEpochCurrent(epoch) {
+        return epoch === this.eventEpoch && !this.eventsBlocked;
+    }
+    async eventResumePosition(epoch = this.eventEpoch) {
+        return this.withEventCheckpoint(async () => {
+            if (this.pendingCheckpointRollback) {
+                await this.restoreEventMetadata(this.pendingCheckpointRollback);
+                this.pendingCheckpointRollback = undefined;
+            }
+            const lastEventSeq = await this._payloadStore.miscellaneous?.get('lastEventSeq');
+            if (epoch !== this.eventEpoch) {
+                return { lastEventSeq };
+            }
+            if (this.pendingEventSeq !== undefined && this.pendingEventSeq > Number(lastEventSeq ?? 0)) {
+                this.failedEventSeq ??= this.pendingEventSeq;
+            }
+            this.pendingEventSeq = undefined;
+            return { lastEventSeq, accountId: await this._payloadStore.miscellaneous?.get('accountId') };
+        });
+    }
+    async withEventCheckpoint(operation) {
+        const result = this.checkpointQueue.then(operation);
+        this.checkpointQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async restoreEventMetadata(previous) {
+        for (const [key, value] of previous) {
+            if (value === undefined) {
+                await this._payloadStore.miscellaneous?.delete(key);
+            }
+            else {
+                await this._payloadStore.miscellaneous?.set(key, value);
+            }
+        }
+    }
+    async writeEventMetadata(changes, epoch) {
+        const isCurrent = () => epoch === undefined || this.isEventEpochCurrent(epoch);
+        if (!isCurrent()) {
+            return;
+        }
+        const previous = new Map();
+        for (const key of changes.keys()) {
+            previous.set(key, await this._payloadStore.miscellaneous?.get(key));
+        }
+        if (!isCurrent()) {
+            return;
+        }
+        try {
+            for (const [key, value] of changes) {
+                if (value === undefined) {
+                    await this._payloadStore.miscellaneous?.delete(key);
+                }
+                else {
+                    await this._payloadStore.miscellaneous?.set(key, value);
+                }
+                if (!isCurrent()) {
+                    await this.restoreEventMetadata(previous);
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            try {
+                await this.restoreEventMetadata(previous);
+            }
+            catch (rollbackError) {
+                this.pendingCheckpointRollback = previous;
+                this.log.error('PuppetService', 'checkpoint rollback failed: %s', rollbackError);
+            }
+            throw error;
+        }
+    }
+    async commitEventCheckpoint(seq, timestamp, epoch) {
+        await this.withEventCheckpoint(async () => {
+            if (!this.isEventEpochCurrent(epoch)) {
+                return;
+            }
+            const lastEventSeq = await this._payloadStore.miscellaneous?.get('lastEventSeq');
+            if (lastEventSeq && seq <= Number(lastEventSeq) && seq !== 1) {
+                return;
+            }
+            await this.writeEventMetadata(new Map([
+                ['lastEventTimestamp', timestamp], ['lastEventSeq', String(seq)],
+            ]), epoch);
+        });
+    }
+    reportStreamError(error) {
+        this.log.error('PuppetService', 'event processing failed: %s', error);
+        try {
+            this.emit('error', error);
+        }
+        catch (listenerError) {
+            this.log.error('PuppetService', 'error listener failed: %s', listenerError);
+        }
+    }
+    haltEventStream(manager, event, error) {
+        this.failedEventSeq ??= event.getSeq();
+        this.suspendEventProcessing();
+        try {
+            manager.stopStream();
+        }
+        catch (stopError) {
+            this.log.error('PuppetService', 'stopping failed event stream failed: %s', stopError);
+        }
+        this.reportStreamError(error);
+    }
+    async onGrpcStreamEvent(event, epoch = this.eventEpoch) {
+        if (!this.isEventEpochCurrent(epoch)) {
+            return;
+        }
         const type = event.getType();
         const payload = event.getPayload();
         const seq = event.getSeq();
@@ -199,15 +368,6 @@ class PuppetService extends PUPPET.Puppet {
                 data: `onGrpcStreamEvent(${EventTypeRev[type]})`,
             });
         }
-        if (seq && !envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
-            const { lastEventSeq } = await this.getMiscellaneousStoreData();
-            if (!lastEventSeq || (seq > Number(lastEventSeq) || seq === 1)) {
-                await this.setMiscellaneousStoreData({
-                    lastEventSeq: seq.toString(),
-                    lastEventTimestamp: timestamp,
-                });
-            }
-        }
         switch (type) {
             case grpcPuppet.EventType.EVENT_TYPE_DONG:
                 this.emit('dong', JSON.parse(payload));
@@ -230,11 +390,14 @@ class PuppetService extends PUPPET.Puppet {
                     const loginPayload = JSON.parse(payload);
                     if (!envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
                         const { accountId } = await this.getMiscellaneousStoreData();
+                        if (!this.isEventEpochCurrent(epoch)) {
+                            return;
+                        }
                         if (accountId !== loginPayload.contactId) {
-                            await this.resetMiscellaneousStoreData();
+                            await this.resetMiscellaneousStoreData(epoch);
                             await this.setMiscellaneousStoreData({
                                 accountId: loginPayload.contactId,
-                            });
+                            }, epoch);
                         }
                     }
                     (async () => this.login(loginPayload.contactId))().catch(e => this.log.error('PuppetService', 'onGrpcStreamEvent() this.login() rejection %s', e.message));
@@ -244,7 +407,7 @@ class PuppetService extends PUPPET.Puppet {
                 {
                     const logoutPayload = JSON.parse(payload);
                     if (!envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
-                        await this.resetMiscellaneousStoreData();
+                        await this.resetMiscellaneousStoreData(epoch);
                     }
                     ;
                     (async () => this.logout(logoutPayload.data))().catch(e => this.log.error('PuppetService', 'onGrpcStreamEvent() this.logout() rejection %s', e.message));
@@ -252,8 +415,25 @@ class PuppetService extends PUPPET.Puppet {
                 break;
             case grpcPuppet.EventType.EVENT_TYPE_DIRTY:
                 await this.fastDirty(JSON.parse(payload));
+                if (!this.isEventEpochCurrent(epoch)) {
+                    return;
+                }
                 this.emit('dirty', JSON.parse(payload));
                 break;
+            case grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD: {
+                const loadPayload = JSON.parse(payload);
+                validateRoomMemberLoadState(loadPayload);
+                this.roomCache.invalidate(loadPayload.roomId);
+                await this.roomCache.run(loadPayload.roomId, async () => {
+                    await this._payloadStore.room?.delete(loadPayload.roomId);
+                    await this._payloadStore.roomMember?.delete(loadPayload.roomId);
+                });
+                if (!this.isEventEpochCurrent(epoch)) {
+                    return;
+                }
+                this.emit('room-member-load', loadPayload);
+                break;
+            }
             case grpcPuppet.EventType.EVENT_TYPE_MESSAGE:
                 this.emit('message', JSON.parse(payload));
                 break;
@@ -316,10 +496,19 @@ class PuppetService extends PUPPET.Puppet {
             case grpcPuppet.EventType.EVENT_TYPE_CALL:
                 this.emit('call', JSON.parse(payload));
                 break;
+            case grpcPuppet.EventType.EVENT_TYPE_ORG_BROADCAST_CREATED:
+                this.emit('org-broadcast-created', JSON.parse(payload));
+                break;
+            case grpcPuppet.EventType.EVENT_TYPE_ORG_BROADCAST_SENT:
+                this.emit('org-broadcast-sent', JSON.parse(payload));
+                break;
             default:
                 // Huan(202003): in default, the `type` type should be `never`, please check.
                 this.log.error(`eventType ${type} unsupported! data: ${payload}`);
         }
+        if (seq && this.isEventEpochCurrent(epoch) && !envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
+            await this.commitEventCheckpoint(seq, timestamp, epoch);
+        }
     }
     async logout(reason) {
         this.log.verbose('PuppetService', 'logout(%s)', reason ? `"${reason}"` : '');
@@ -375,8 +564,14 @@ class PuppetService extends PUPPET.Puppet {
             [PUPPET.types.Dirty.Friendship]: async (_) => { },
             [PUPPET.types.Dirty.Message]: async (_) => { },
             [PUPPET.types.Dirty.Post]: async (_) => { },
-            [PUPPET.types.Dirty.Room]: async (id) => this._payloadStore.room?.delete(id),
-            [PUPPET.types.Dirty.RoomMember]: async (id) => this._payloadStore.roomMember?.delete(id),
+            [PUPPET.types.Dirty.Room]: async (id) => {
+                this.roomCache.invalidate(id);
+                return this.roomCache.run(id, async () => this._payloadStore.room?.delete(id));
+            },
+            [PUPPET.types.Dirty.RoomMember]: async (id) => {
+                this.roomCache.invalidate(id);
+                return this.roomCache.run(id, async () => this._payloadStore.roomMember?.delete(id));
+            },
             [PUPPET.types.Dirty.Tag]: async (id) => this._payloadStore.tag?.delete(id),
             [PUPPET.types.Dirty.TagGroup]: async (id) => this._payloadStore.tagGroup?.delete(id),
             [PUPPET.types.Dirty.Unspecified]: async (id) => { throw new Error('Unspecified type with id: ' + id); },
@@ -1545,8 +1740,9 @@ class PuppetService extends PUPPET.Puppet {
      */
     async roomRawPayload(id) {
         this.log.verbose('PuppetService', 'roomRawPayload(%s)', id);
-        const cachedPayload = await this._payloadStore.room?.get(id);
-        if (cachedPayload) {
+        const generation = this.roomCache.generation(id);
+        const cachedPayload = await this.roomCache.run(id, async () => this._payloadStore.room?.get(id));
+        if (cachedPayload && generation === this.roomCache.generation(id)) {
             this.log.silly('PuppetService', 'roomRawPayload(%s) cache HIT', id);
             return cachedPayload;
         }
@@ -1554,26 +1750,52 @@ class PuppetService extends PUPPET.Puppet {
         request.setId(id);
         const response = await util.promisify(this.grpcManager.client.roomPayload
             .bind(this.grpcManager.client))(request);
-        const payload = {
-            adminIdList: response.getAdminIdsList(),
-            avatar: response.getAvatar(),
-            handle: response.getHandle(),
-            id: response.getId(),
-            memberIdList: response.getMemberIdsList(),
-            ownerId: response.getOwnerId(),
-            topic: response.getTopic(),
-            additionalInfo: response.getAdditionalInfo(),
-            remark: response.getRoomRemark(),
-            external: response.getExternal(),
-        };
-        const createTime = response.getCreateTime();
-        if (createTime) {
-            payload.createTime = millisecondsFromTimestamp(createTime);
-        }
-        await this._payloadStore.room?.set(id, payload);
+        const payload = roomPbToPayload(response);
+        await this.roomCache.commit(id, generation, async () => this._payloadStore.room?.set(id, payload));
         this.log.silly('PuppetService', 'roomRawPayload(%s) cache SET', id);
         return payload;
     }
+    async roomMemberSync(roomId, options) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        const request = new grpcPuppet.RoomMemberSyncRequest();
+        request.setId(roomId);
+        if (options?.force !== undefined) {
+            request.setForce(options.force);
+        }
+        const response = await util.promisify(this.grpcManager.client.roomMemberSync.bind(this.grpcManager.client))(request);
+        return roomMemberLoadStatePbToPayload(response, roomId);
+    }
+    async roomMemberLoadState(roomId) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        const request = new grpcPuppet.RoomMemberLoadStateRequest();
+        request.setId(roomId);
+        const response = await util.promisify(this.grpcManager.client.roomMemberLoadState.bind(this.grpcManager.client))(request);
+        return roomMemberLoadStatePbToPayload(response, roomId);
+    }
+    async roomMemberSnapshot(roomId, revision, options) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        validateRoomMemberRevision(revision);
+        const request = new grpcPuppet.RoomMemberSnapshotRequest();
+        request.setId(roomId);
+        request.setRevision(revision);
+        if (options?.pageToken !== undefined) {
+            request.setPageToken(options.pageToken);
+        }
+        if (options?.pageSize !== undefined) {
+            if (!Number.isInteger(options.pageSize) || options.pageSize < 0 || options.pageSize > 500) {
+                throw new Error('pageSize must be an integer between 0 and 500');
+            }
+            request.setPageSize(options.pageSize);
+        }
+        const response = await util.promisify(this.grpcManager.client.roomMemberSnapshot.bind(this.grpcManager.client))(request);
+        return roomMemberSnapshotPbToPayload(response, roomId, revision);
+    }
     async roomRawPayloadParser(payload) {
         // this.log.silly('PuppetService', 'roomRawPayloadParser({id:%s})', payload.id)
         // passthrough
@@ -1583,10 +1805,11 @@ class PuppetService extends PUPPET.Puppet {
         this.log.verbose('PuppetService', 'batchRoomRawPayload(%s)', roomIdList);
         const result = new Map();
         const roomIdSet = new Set(roomIdList);
+        const generations = new Map(Array.from(roomIdSet, id => [id, this.roomCache.generation(id)]));
         const needGetSet = new Set();
         for (const roomId of roomIdSet) {
-            const cachedRoomPayload = await this._payloadStore.room?.get(roomId);
-            if (cachedRoomPayload) {
+            const cachedRoomPayload = await this.roomCache.run(roomId, async () => this._payloadStore.room?.get(roomId));
+            if (cachedRoomPayload && generations.get(roomId) === this.roomCache.generation(roomId)) {
                 result.set(roomId, cachedRoomPayload);
             }
             else {
@@ -1602,27 +1825,18 @@ class PuppetService extends PUPPET.Puppet {
                 const payloads = response.getRoomPayloadsList();
                 for (const payload of payloads) {
                     const roomId = payload.getId();
-                    const puppetPayload = {
-                        adminIdList: payload.getAdminIdsList(),
-                        avatar: payload.getAvatar(),
-                        handle: payload.getHandle(),
-                        id: payload.getId(),
-                        memberIdList: payload.getMemberIdsList(),
-                        ownerId: payload.getOwnerId(),
-                        topic: payload.getTopic(),
-                        additionalInfo: payload.getAdditionalInfo(),
-                        remark: payload.getRoomRemark(),
-                        external: payload.getExternal(),
-                    };
-                    const createTime = payload.getCreateTime();
-                    if (createTime) {
-                        puppetPayload.createTime = millisecondsFromTimestamp(createTime);
-                    }
+                    const puppetPayload = roomPbToPayload(payload);
                     result.set(roomId, puppetPayload);
-                    await this._payloadStore.room?.set(roomId, puppetPayload);
+                    const generation = generations.get(roomId);
+                    if (generation !== undefined) {
+                        await this.roomCache.commit(roomId, generation, async () => this._payloadStore.room?.set(roomId, puppetPayload));
+                    }
                 }
             }
             catch (e) {
+                if (e instanceof RoomCacheOperationError) {
+                    throw e;
+                }
                 this.log.error('PuppetService', 'batchRoomRawPayload(%s, %s) error: %s, use one by one method', roomIdList, needGetSet, e);
                 let fallbackSuccessCount = 0;
                 for (const roomId of needGetSet) {
@@ -1808,9 +2022,10 @@ class PuppetService extends PUPPET.Puppet {
     }
     async roomMemberRawPayload(roomId, contactId) {
         this.log.verbose('PuppetService', 'roomMemberRawPayload(%s, %s)', roomId, contactId);
-        const cachedPayload = await this._payloadStore.roomMember?.get(roomId);
+        const generation = this.roomCache.generation(roomId);
+        const cachedPayload = await this.roomCache.run(roomId, async () => this._payloadStore.roomMember?.get(roomId));
         const cachedRoomMemberPayload = cachedPayload && cachedPayload[contactId];
-        if (cachedRoomMemberPayload) {
+        if (cachedRoomMemberPayload && generation === this.roomCache.generation(roomId)) {
             this.log.silly('PuppetService', 'roomMemberRawPayload(%s, %s) cache HIT', roomId, contactId);
             return cachedRoomMemberPayload;
         }
@@ -1829,9 +2044,9 @@ class PuppetService extends PUPPET.Puppet {
             joinScene: response.getJoinScene(),
             joinTime: response.getJoinTime(),
         };
-        await this._payloadStore.roomMember?.set(roomId, {
-            ...cachedPayload,
-            [contactId]: payload,
+        await this.roomCache.commit(roomId, generation, async () => {
+            const current = await this._payloadStore.roomMember?.get(roomId);
+            await this._payloadStore.roomMember?.set(roomId, { ...current, [contactId]: payload });
         });
         this.log.silly('PuppetService', 'roomMemberRawPayload(%s, %s) cache SET', roomId, contactId);
         return payload;
@@ -1843,10 +2058,12 @@ class PuppetService extends PUPPET.Puppet {
     }
     async batchRoomMemberRawPayload(roomId, contactIdList) {
         this.log.verbose('PuppetService', 'batchRoomMemberRawPayload(%s, %s)', roomId, contactIdList);
+        const generation = this.roomCache.generation(roomId);
         const result = new Map();
         const contactIdSet = new Set(contactIdList);
         let needGetSet = new Set();
-        const cachedPayload = await this._payloadStore.roomMember?.get(roomId) || {};
+        const cached = await this.roomCache.run(roomId, async () => this._payloadStore.roomMember?.get(roomId));
+        const cachedPayload = generation === this.roomCache.generation(roomId) ? cached || {} : {};
         if (Object.keys(cachedPayload).length > 0) {
             for (const contactId of contactIdSet) {
                 const cachedRoomMemberPayload = cachedPayload[contactId];
@@ -1869,15 +2086,22 @@ class PuppetService extends PUPPET.Puppet {
                 const response = await util.promisify(this.grpcManager.client.batchRoomMemberPayload
                     .bind(this.grpcManager.client))(request);
                 const payloads = response.getMemberPayloadsList();
+                const fetched = {};
                 for (const payload of payloads) {
                     const contactId = payload.getId();
                     const puppetPayload = roomMemberPbToPayload(payload);
                     result.set(contactId, puppetPayload);
-                    cachedPayload[contactId] = puppetPayload;
+                    fetched[contactId] = puppetPayload;
                 }
-                await this._payloadStore.roomMember?.set(roomId, cachedPayload);
+                await this.roomCache.commit(roomId, generation, async () => {
+                    const current = await this._payloadStore.roomMember?.get(roomId);
+                    await this._payloadStore.roomMember?.set(roomId, { ...current, ...fetched });
+                });
             }
             catch (e) {
+                if (e instanceof RoomCacheOperationError) {
+                    throw e;
+                }
                 this.log.error('PuppetService', 'batchRoomMemberRawPayload(%s, %s) error: %s, use one by one method', roomId, needGetSet, e);
                 for (const contactId of needGetSet) {
                     const payload = await this.roomMemberRawPayload(roomId, contactId);
@@ -2568,6 +2792,42 @@ class PuppetService extends PUPPET.Puppet {
         }
         return result;
     }
+    async orgBroadcastPayload(orgBroadcastId) {
+        this.log.verbose('PuppetService', 'orgBroadcastPayload(%s)', orgBroadcastId);
+        const request = new grpcPuppet.OrgBroadcastPayloadRequest();
+        request.setId(orgBroadcastId);
+        const response = await util.promisify(this.grpcManager.client.orgBroadcastPayload.bind(this.grpcManager.client))(request);
+        return {
+            id: response.getId(),
+            sendType: response.getSendType(),
+            conversationType: response.getConversationType(),
+            creatorId: response.getCreatorId() || undefined,
+            execTime: response.getExecTime(),
+            status: response.getStatus(),
+            canCancel: response.getCanCancel(),
+            allowSelect: response.getAllowSelect(),
+            sent: response.getSent(),
+            totalCount: response.getTotalCount(),
+            sentCount: response.getSentCount(),
+            contentListJson: response.getContentListJson(),
+            targets: response.getTargetsList().map(targetPb => ({
+                contactId: targetPb.getContactId() || undefined,
+                roomId: targetPb.getRoomId() || undefined,
+                status: targetPb.getStatus(),
+            })),
+        };
+    }
+    async orgBroadcastExecute(orgBroadcastId, targetIds) {
+        this.log.verbose('PuppetService', 'orgBroadcastExecute(%s, %s)', orgBroadcastId, targetIds?.length);
+        // on the wire an empty target_ids means all targets, so an explicit empty list must not pass through
+        if (targetIds && targetIds.length === 0) {
+            throw new Error('targetIds is empty, omit it to send to all targets of the org broadcast');
+        }
+        const request = new grpcPuppet.OrgBroadcastExecuteRequest();
+        request.setId(orgBroadcastId);
+        request.setTargetIdsList(targetIds ?? []);
+        await util.promisify(this.grpcManager.client.orgBroadcastExecute.bind(this.grpcManager.client))(request);
+    }
     healthCheckInterval;
     startHealthCheck() {
         this.healthCheckInterval = setInterval(() => {
@@ -2583,23 +2843,40 @@ class PuppetService extends PUPPET.Puppet {
     waitingForReady = false;
     reconnectIndicator;
     async reset() {
-        if (!this._grpcManager) {
-            this.log.warn('PuppetService', 'grpc manager not constructed, perform regular reset');
-            return super.reset();
-        }
-        if (!this.isLoggedIn) {
-            this.log.warn('PuppetService', 'puppet not logged in, perform regular reset');
-            return super.reset();
-        }
         if (this.reconnectIndicator.value()) {
             this.log.warn('PuppetService', 'already trying to reconnect, pass this one');
             return;
         }
         this.reconnectIndicator.value(true);
-        this.grpcManager.stopStream();
-        const { lastEventSeq, accountId } = await this.getMiscellaneousStoreData();
+        this.suspendEventProcessing();
+        const epoch = this.eventEpoch;
+        const manager = this._grpcManager;
+        try {
+            await this.checkpointQueue;
+            if (epoch !== this.eventEpoch) {
+                return;
+            }
+            if (!manager || !this.isLoggedIn) {
+                this.log.warn('PuppetService', 'grpc manager unavailable or puppet logged out, perform regular reset');
+                return await super.reset();
+            }
+            await this.resetEventStream(manager, epoch);
+        }
+        finally {
+            this.reconnectIndicator.value(false);
+        }
+    }
+    async resetEventStream(manager, epoch) {
+        manager.stopStream();
+        const { lastEventSeq, accountId } = await this.eventResumePosition(epoch);
+        if (epoch !== this.eventEpoch || manager !== this._grpcManager) {
+            return;
+        }
         const onLoginResolve = (resolve) => {
             const onLogin = (event) => {
+                if (!this.ownsEventWorker(manager, epoch)) {
+                    return;
+                }
                 const type = event.getType();
                 const payload = event.getPayload();
                 if (this.waitingForLogin && type === grpcPuppet.EventType.EVENT_TYPE_LOGIN) {
@@ -2615,6 +2892,9 @@ class PuppetService extends PUPPET.Puppet {
         };
         const onReadyResolve = (resolve) => {
             const onReady = (event) => {
+                if (!this.ownsEventWorker(manager, epoch)) {
+                    return;
+                }
                 const type = event.getType();
                 if (this.waitingForReady && type === grpcPuppet.EventType.EVENT_TYPE_READY) {
                     this.waitingForReady = false;
@@ -2623,60 +2903,85 @@ class PuppetService extends PUPPET.Puppet {
             };
             return onReady;
         };
-        let onLogin;
-        let onReady;
+        const removeListeners = [];
         const loginFuture = new Promise(resolve => {
-            onLogin = onLoginResolve(resolve);
-            this.grpcManager.on('data', onLogin);
+            const onLogin = onLoginResolve(resolve);
+            manager.on('data', onLogin);
+            removeListeners.push(() => { manager.off('data', onLogin); });
         });
         const readyFuture = new Promise(resolve => {
-            onReady = onReadyResolve(resolve);
-            this.grpcManager.on('data', onReady);
+            const onReady = onReadyResolve(resolve);
+            manager.on('data', onReady);
+            removeListeners.push(() => { manager.off('data', onReady); });
         });
         const startTime = Date.now();
         const timeoutMilliseconds = this.timeoutMilliseconds / 10; // 2 min default, 4 min xiaoju-bot
-        while (true) {
+        this.waitingForLogin = true;
+        this.waitingForReady = true;
+        this.eventsBlocked = false;
+        try {
+            while (true) {
+                try {
+                    if (!this.ownsEventWorker(manager, epoch)) {
+                        return;
+                    }
+                    await timeoutPromise(manager.startStream(lastEventSeq, accountId), 30 * 1000);
+                    if (!this.ownsEventWorker(manager, epoch)) {
+                        return;
+                    }
+                    break;
+                }
+                catch (e) {
+                    if (!this.ownsEventWorker(manager, epoch)) {
+                        return;
+                    }
+                    if (Date.now() - startTime < timeoutMilliseconds) {
+                        this.log.warn('failed to start stream, will try again in 15 seconds');
+                        await new Promise(resolve => {
+                            setTimeout(resolve, 5000);
+                        });
+                    }
+                    else {
+                        this.log.warn('failed to start stream and reaches timeout, will perform regular reset');
+                        return super.reset();
+                    }
+                }
+            }
             try {
-                await timeoutPromise(this.grpcManager.startStream(lastEventSeq, accountId), 30 * 1000);
-                break;
+                await timeoutPromise(loginFuture, ResetLoginTimeout)
+                    .finally(() => {
+                    if (epoch === this.eventEpoch) {
+                        this.waitingForLogin = false;
+                    }
+                });
             }
             catch (e) {
-                if (Date.now() - startTime < timeoutMilliseconds) {
-                    this.log.warn('failed to start stream, will try again in 15 seconds');
-                    await new Promise(resolve => {
-                        setTimeout(resolve, 5000);
-                    });
-                }
-                else {
-                    this.log.warn('failed to start stream and reaches timeout, will perform regular reset');
-                    this.reconnectIndicator.value(false);
-                    return super.reset();
+                if (!this.ownsEventWorker(manager, epoch)) {
+                    return;
                 }
+                this.log.warn('PuppetService', 'waiting for event reset login error, will perform regular reset');
+                return super.reset();
+            }
+            try {
+                await timeoutPromise(readyFuture, ResetReadyTimeout)
+                    .finally(() => {
+                    if (epoch === this.eventEpoch) {
+                        this.waitingForReady = false;
+                    }
+                });
+            }
+            catch (e) {
+                this.log.warn('PuppetService', 'waiting for event reset ready error, will do nothing');
             }
         }
-        this.waitingForLogin = true;
-        this.waitingForReady = true;
-        try {
-            await timeoutPromise(loginFuture, ResetLoginTimeout)
-                .finally(() => {
+        finally {
+            for (const removeListener of removeListeners) {
+                removeListener();
+            }
+            if (epoch === this.eventEpoch) {
                 this.waitingForLogin = false;
-                this.reconnectIndicator.value(false);
-                this.grpcManager.off('data', onLogin);
-            });
-        }
-        catch (e) {
-            this.log.warn('PuppetService', 'waiting for event reset login error, will perform regular reset');
-            return super.reset();
-        }
-        try {
-            await timeoutPromise(readyFuture, ResetReadyTimeout)
-                .finally(() => {
                 this.waitingForReady = false;
-                this.grpcManager.off('data', onReady);
-            });
-        }
-        catch (e) {
-            this.log.warn('PuppetService', 'waiting for event reset ready error, will do nothing');
+            }
         }
     }
     async getMiscellaneousStoreData() {
@@ -2700,27 +3005,29 @@ class PuppetService extends PUPPET.Puppet {
             accountId,
         };
     }
-    async setMiscellaneousStoreData(data) {
+    async setMiscellaneousStoreData(data, epoch) {
         if (envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
             return;
         }
-        if (typeof data.lastEventSeq !== 'undefined') {
-            await this._payloadStore.miscellaneous?.set('lastEventSeq', data.lastEventSeq);
+        const changes = new Map();
+        if (data.lastEventTimestamp !== undefined) {
+            changes.set('lastEventTimestamp', data.lastEventTimestamp);
         }
-        if (typeof data.lastEventTimestamp !== 'undefined') {
-            await this._payloadStore.miscellaneous?.set('lastEventTimestamp', data.lastEventTimestamp);
+        if (data.accountId !== undefined) {
+            changes.set('accountId', data.accountId);
         }
-        if (typeof data.accountId !== 'undefined') {
-            await this._payloadStore.miscellaneous?.set('accountId', data.accountId);
+        if (data.lastEventSeq !== undefined) {
+            changes.set('lastEventSeq', data.lastEventSeq);
         }
+        await this.withEventCheckpoint(async () => this.writeEventMetadata(changes, epoch));
     }
-    async resetMiscellaneousStoreData() {
+    async resetMiscellaneousStoreData(epoch) {
         if (envVars.WECHATY_PUPPET_SERVICE_DISABLE_EVENT_CACHE()) {
             return;
         }
-        await this._payloadStore.miscellaneous?.delete('lastEventSeq');
-        await this._payloadStore.miscellaneous?.delete('lastEventTimestamp');
-        await this._payloadStore.miscellaneous?.delete('accountId');
+        await this.withEventCheckpoint(async () => this.writeEventMetadata(new Map([
+            ['lastEventSeq', undefined], ['lastEventTimestamp', undefined], ['accountId', undefined],
+        ]), epoch));
     }
 }
 export { PuppetService, };