@juzi/wechaty-puppet-service 1.0.130 → 1.0.131

package/src/client/room-member-load.spec.ts

@@ -0,0 +1,319 @@
+import util from 'util'
+import { sinon, test } from 'tstest'
+import { FileBox } from 'file-box'
+import * as PUPPET from '@juzi/wechaty-puppet'
+import { PuppetMock } from '@juzi/wechaty-puppet-mock'
+import { grpc, puppet as grpcPuppet } from '@juzi/wechaty-grpc'
+
+import { PuppetService } from './puppet-service.js'
+import { puppetImplementation } from '../server/puppet-implementation.js'
+import { EventStreamManager } from '../server/event-stream-manager.js'
+import { EventTypeRev } from '../event-type-rev.js'
+
+interface RpcFixture {
+  service: PuppetService
+  adapter: PUPPET.impls.PuppetInterface
+  client: grpcPuppet.PuppetClient
+  close: () => Promise<void>
+}
+
+async function createRpcFixture (legacyAdapter?: PUPPET.impls.PuppetInterface): Promise<RpcFixture> {
+  // The published mock resolves its own older Puppet dependency.
+  const adapter = legacyAdapter ?? Object.assign(new PuppetMock(), {
+    roomMemberSync: PUPPET.Puppet.prototype.roomMemberSync,
+    roomMemberLoadState: PUPPET.Puppet.prototype.roomMemberLoadState,
+    roomMemberSnapshot: PUPPET.Puppet.prototype.roomMemberSnapshot,
+  }) as unknown as PUPPET.impls.PuppetInterface
+  const server = new grpc.Server()
+  server.addService(grpcPuppet.PuppetService, puppetImplementation(adapter, FileBox))
+  const port = await util.promisify(server.bindAsync.bind(server))(
+    '127.0.0.1:0', grpc.ServerCredentials.createInsecure(),
+  )
+  const client = new grpcPuppet.PuppetClient(`127.0.0.1:${port}`, grpc.credentials.createInsecure())
+  const service = new PuppetService({ token: `load-test-${port}` })
+  Object.defineProperty(service, 'grpcManager', { value: { client } })
+  return {
+    adapter,
+    service,
+    client,
+    close: async (): Promise<void> => {
+      client.close()
+      await util.promisify(server.tryShutdown.bind(server))()
+    },
+  }
+}
+
+const state: PUPPET.payloads.RoomMemberLoadState = {
+  roomId: 'room', taskId: 'task', status: 3, revision: '9007199254740993', loadedAt: 123456789,
+}
+
+test('real gRPC sync, state, and snapshot roundtrip without dirty fallback', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const accepted: PUPPET.payloads.RoomMemberLoadState = {
+    roomId: 'room', taskId: 'task', status: PUPPET.types.RoomMemberLoadStatus.Pending, revision: '0',
+  }
+  const sync = sinon.stub(adapter, 'roomMemberSync').resolves(accepted)
+  const read = sinon.stub(adapter, 'roomMemberLoadState').resolves(state)
+  const snapshot = sinon.stub(adapter, 'roomMemberSnapshot').resolves({
+    roomId: 'room',
+    revision: state.revision,
+    loadedAt: state.loadedAt,
+    members: [ {
+      id: 'member',
+      name: 'name',
+      avatar: 'avatar',
+      roomAlias: 'alias',
+      inviterId: 'inviter',
+      additionalInfo: 'info',
+      joinTime: 12,
+      joinScene: 0,
+    } ],
+    nextPageToken: 'next',
+  })
+  const dirty = sinon.spy(adapter, 'dirtyPayload')
+  t.same(await service.roomMemberSync('room', { force: true }), accepted, 'returns accepted Pending state without waiting for Loaded')
+  t.same(sync.args[0], [ 'room', { force: true } ])
+  await service.roomMemberSync('room')
+  t.same(sync.args[1], [ 'room', undefined ], 'does not inject default force')
+  t.same(await service.roomMemberLoadState('room'), state)
+  t.equal(read.callCount, 1)
+  const page = await service.roomMemberSnapshot('room', state.revision, { pageToken: 'cursor', pageSize: 2 })
+  t.same(snapshot.args[0], [ 'room', state.revision, { pageToken: 'cursor', pageSize: 2 } ])
+  t.equal(page.nextPageToken, 'next')
+  t.equal(page.members[0]?.roomAlias, 'alias')
+  t.equal(page.loadedAt, state.loadedAt)
+  t.equal(dirty.callCount, 0)
+  await service.roomMemberSnapshot('room', state.revision)
+  t.same(snapshot.args[1], [ 'room', state.revision, { pageToken: '', pageSize: 0 } ])
+  await t.rejects(service.roomMemberSnapshot('room', '01'), /revision/)
+  await t.rejects(service.roomMemberSnapshot('room', '1', { pageSize: 501 }), /pageSize/)
+})
+
+test('snapshot conflicts and adapter unsupported errors keep standard gRPC status', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const snapshot = sinon.stub(adapter, 'roomMemberSnapshot').resolves({ roomId: 'room', revision: '2', members: [] })
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.FAILED_PRECONDITION })
+  snapshot.resolves({ roomId: 'other', revision: '1', members: [] })
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.FAILED_PRECONDITION })
+  snapshot.rejects(Object.assign(new Error('snapshot not loaded'), { code: grpc.status.FAILED_PRECONDITION }))
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.FAILED_PRECONDITION })
+  await t.rejects(service.roomMemberSync('room'), { code: grpc.status.UNIMPLEMENTED })
+  await t.rejects(service.roomMemberLoadState('room'), { code: grpc.status.UNIMPLEMENTED })
+  snapshot.restore()
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.UNIMPLEMENTED })
+})
+
+async function deliverEvent (service: PuppetService, event: grpcPuppet.EventResponse): Promise<void> {
+  const handler: unknown = Reflect.get(service, 'onGrpcStreamEvent')
+  if (typeof handler !== 'function') { throw new Error('Missing event handler') }
+  await handler.call(service, event)
+}
+
+test('independent event waits for both persistent stores then invalidates base caches', async t => {
+  const service = new PuppetService({ token: 'load-event-test' })
+  await service.cache.start()
+  t.teardown(() => service.cache.stop())
+  service.cache.room?.set('room', { id: 'room', topic: '', adminIdList: [], memberIdList: [] })
+  service.cache.roomMember?.set('room', { member: { id: 'member', name: '', avatar: '' } })
+  service.on('room-member-load', service.onRoomMemberLoad.bind(service))
+  let finishRoom: () => void = () => { throw new Error('Missing room resolver') }
+  let finishMembers: () => void = () => { throw new Error('Missing members resolver') }
+  const roomDeleted = new Promise<void>(resolve => { finishRoom = resolve })
+  const membersDeleted = new Promise<void>(resolve => { finishMembers = resolve })
+  const deleteRoom = sinon.stub().returns(roomDeleted)
+  const deleteMembers = sinon.stub().returns(membersDeleted)
+  Object.defineProperty(service, '_payloadStore', {
+    value: { room: { delete: deleteRoom }, roomMember: { delete: deleteMembers } },
+  })
+  const dirty = sinon.spy(service, 'dirtyPayload')
+  const dirtyEvent = sinon.spy()
+  const load = sinon.spy()
+  service.on('dirty', dirtyEvent)
+  service.on('room-member-load', load)
+  const event = new grpcPuppet.EventResponse()
+  event.setType(grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD)
+  event.setPayload(JSON.stringify(state))
+  const pending = deliverEvent(service, event)
+  t.equal(load.callCount, 0)
+  finishRoom()
+  await Promise.resolve()
+  t.equal(load.callCount, 0, 'second store still pending')
+  finishMembers()
+  await pending
+  t.same(deleteRoom.args[0], [ 'room' ])
+  t.same(deleteMembers.args[0], [ 'room' ])
+  t.same(load.args[0], [ state ])
+  t.equal(service.cache.room?.has('room'), false)
+  t.equal(service.cache.roomMember?.has('room'), false)
+  t.equal(dirty.callCount, 0)
+  t.equal(dirtyEvent.callCount, 0)
+  t.equal(EventTypeRev[39], 'EVENT_TYPE_ROOM_MEMBER_LOAD')
+})
+
+test('server forwards original room-member-load event and removes its listener', async t => {
+  const adapter = new PuppetMock() as unknown as PUPPET.impls.PuppetInterface
+  const manager = new EventStreamManager(adapter)
+  const emit = sinon.stub(manager, 'grpcEmit')
+  manager.connectPuppetEventToStreamingCall()
+  adapter.emit('room-member-load', state)
+  t.same(emit.args[0], [ grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD, state ])
+  manager.removePuppetListeners()
+  adapter.emit('room-member-load', state)
+  t.equal(emit.callCount, 1)
+})
+
+test('single and batch room payload RPCs retain every new field', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const payload: PUPPET.payloads.Room = {
+    id: 'room',
+    topic: 'topic',
+    avatar: 'avatar',
+    handle: 'handle',
+    ownerId: 'owner',
+    adminIdList: [ 'admin' ],
+    memberIdList: [],
+    additionalInfo: 'info',
+    remark: 'remark',
+    external: true,
+    createTime: 1234,
+    memberCount: 8,
+    memberLoadMode: 2,
+    memberLoadStatus: 3,
+    memberLoadRevision: state.revision,
+    memberLoadedAt: 0,
+  }
+  sinon.stub(adapter, 'roomPayload').resolves(payload)
+  sinon.stub(adapter, 'batchRoomPayload').resolves(new Map([ [ 'room', payload ] ]))
+  t.same(await service.roomRawPayload('room'), payload)
+  t.same((await service.batchRoomRawPayload([ 'room' ])).get('room'), payload)
+})
+
+test('malformed status and revision fail rather than falling back to dirty', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const read = sinon.stub(adapter, 'roomMemberLoadState').resolves({ ...state, status: 99 })
+  const dirty = sinon.spy(adapter, 'dirtyPayload')
+  await t.rejects(service.roomMemberLoadState('room'), /status/)
+  read.resolves({ ...state, revision: '01' })
+  await t.rejects(service.roomMemberLoadState('room'), /revision/)
+  read.resolves({ ...state, roomId: 'other' })
+  await t.rejects(service.roomMemberLoadState('room'), /roomId/)
+  t.equal(dirty.callCount, 0)
+})
+
+test('cache deletion failure rejects without announcing a successful load', async t => {
+  const service = new PuppetService({ token: 'load-event-failure' })
+  Object.defineProperty(service, '_payloadStore', {
+    value: {
+      room: { delete: async (): Promise<void> => { throw new Error('cache unavailable') } },
+      roomMember: { delete: async (): Promise<void> => {} },
+    },
+  })
+  const load = sinon.spy()
+  service.on('room-member-load', load)
+  const event = new grpcPuppet.EventResponse()
+  event.setType(grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD)
+  event.setPayload(JSON.stringify(state))
+  await t.rejects(deliverEvent(service, event), /cache unavailable/)
+  t.equal(load.callCount, 0)
+})
+
+test('server enforces snapshot request bounds before invoking the adapter', async t => {
+  const { adapter, client, close } = await createRpcFixture()
+  t.teardown(close)
+  const snapshot = sinon.stub(adapter, 'roomMemberSnapshot').resolves({ roomId: 'room', revision: '1', members: [] })
+  const request = new grpcPuppet.RoomMemberSnapshotRequest()
+  request.setId('room')
+  request.setRevision('1')
+  const invoke = util.promisify(client.roomMemberSnapshot.bind(client))
+  request.setPageSize(501)
+  await t.rejects(invoke(request), { code: grpc.status.INVALID_ARGUMENT })
+  request.setPageSize(0)
+  request.setRevision('01')
+  await t.rejects(invoke(request), { code: grpc.status.INVALID_ARGUMENT })
+  request.setRevision('1')
+  request.setId('')
+  await t.rejects(invoke(request), { code: grpc.status.INVALID_ARGUMENT })
+  t.equal(snapshot.callCount, 0)
+  request.setId('room')
+  await invoke(request)
+  t.same(snapshot.args[0], [ 'room', '1', { pageToken: '', pageSize: 0 } ])
+  request.setPageSize(500)
+  await invoke(request)
+  t.same(snapshot.args[1], [ 'room', '1', { pageToken: '', pageSize: 500 } ])
+})
+
+test('all three RPCs preserve adapter error codes', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const error = Object.assign(new Error('adapter capacity exhausted'), { code: grpc.status.RESOURCE_EXHAUSTED })
+  sinon.stub(adapter, 'roomMemberSync').rejects(error)
+  sinon.stub(adapter, 'roomMemberLoadState').rejects(error)
+  sinon.stub(adapter, 'roomMemberSnapshot').rejects(error)
+  await t.rejects(service.roomMemberSync('room'), { code: grpc.status.RESOURCE_EXHAUSTED })
+  await t.rejects(service.roomMemberLoadState('room'), { code: grpc.status.RESOURCE_EXHAUSTED })
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.RESOURCE_EXHAUSTED })
+})
+
+test('legacy adapter without member loading methods returns UNIMPLEMENTED', async t => {
+  const legacy = new PuppetMock() as unknown as PUPPET.impls.PuppetInterface
+  Object.defineProperties(legacy, {
+    roomMemberSync: { value: undefined },
+    roomMemberLoadState: { value: undefined },
+    roomMemberSnapshot: { value: undefined },
+  })
+  const { service, close } = await createRpcFixture(legacy)
+  t.teardown(close)
+  t.equal(typeof legacy.roomMemberSync, 'undefined')
+  t.equal(typeof legacy.roomMemberLoadState, 'undefined')
+  t.equal(typeof legacy.roomMemberSnapshot, 'undefined')
+  await t.rejects(service.roomMemberSync('room'), { code: grpc.status.UNIMPLEMENTED })
+  await t.rejects(service.roomMemberLoadState('room'), { code: grpc.status.UNIMPLEMENTED })
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.UNIMPLEMENTED })
+})
+
+test('plain adapter status objects retain their original details', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const logs = sinon.spy(PUPPET.log, 'error')
+  t.teardown(() => logs.restore())
+  sinon.stub(adapter, 'roomMemberSnapshot').rejects({ code: grpc.status.FAILED_PRECONDITION, details: 'revision retired' })
+  await t.rejects(service.roomMemberSnapshot('room', '1'), { code: grpc.status.FAILED_PRECONDITION, details: 'revision retired' })
+  t.equal(logs.args.some(args => args.includes('roomMemberSnapshot') && args.some(value => typeof value === 'string' && value.includes('revision retired'))), true)
+})
+
+test('server event validator rejects invalid state without forwarding a load event', async t => {
+  const adapter = new PuppetMock() as unknown as PUPPET.impls.PuppetInterface
+  const manager = new EventStreamManager(adapter)
+  const emit = sinon.stub(manager, 'grpcEmit')
+  const errors = sinon.spy()
+  adapter.on('error', errors)
+  manager.connectPuppetEventToStreamingCall()
+  adapter.emit('room-member-load', { ...state, status: 99 })
+  t.equal(errors.callCount, 1)
+  t.equal(emit.args.some(args => args[0] === grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD), false)
+  manager.removePuppetListeners()
+})
+
+test('persistent batch cache failure rejects without retrying raw RPCs', async t => {
+  const { adapter, service, close } = await createRpcFixture()
+  t.teardown(close)
+  const room: PUPPET.payloads.Room = { id: 'room', topic: '', adminIdList: [], memberIdList: [] }
+  const member: PUPPET.payloads.RoomMember = { id: 'member', name: '', avatar: '' }
+  sinon.stub(adapter, 'batchRoomPayload').resolves(new Map([ [ 'room', room ] ]))
+  sinon.stub(adapter, 'batchRoomMemberPayload').resolves(new Map([ [ 'member', member ] ]))
+  const roomFallback = sinon.spy(service, 'roomRawPayload')
+  const memberFallback = sinon.spy(service, 'roomMemberRawPayload')
+  const store = {
+    get: async (): Promise<undefined> => undefined,
+    set: async (): Promise<void> => { throw new Error('persistent cache unavailable') },
+  }
+  Object.defineProperty(service, '_payloadStore', { value: { room: store, roomMember: store } })
+  await t.rejects(service.batchRoomRawPayload([ 'room' ]), /persistent cache unavailable/)
+  await t.rejects(service.batchRoomMemberRawPayload('room', [ 'member' ]), /persistent cache unavailable/)
+  t.equal(roomFallback.callCount, 0)
+  t.equal(memberFallback.callCount, 0)
+})

package/src/package-json.ts

@@ -4,7 +4,7 @@
 import type { PackageJson } from 'type-fest'
 export const packageJson: PackageJson = {
   "name": "@juzi/wechaty-puppet-service",
-  "version": "1.0.130",
+  "version": "1.0.131",
   "description": "Puppet Service for Wechaty",
   "type": "module",
   "exports": {
@@ -55,7 +55,7 @@ export const packageJson: PackageJson = {
     "@chatie/eslint-config": "^1.0.4",
     "@chatie/semver": "^0.4.7",
     "@chatie/tsconfig": "^4.6.3",
-    "@juzi/wechaty-puppet": "^1.0.157",
+    "@juzi/wechaty-puppet": "^1.0.158",
     "@juzi/wechaty-puppet-mock": "^1.0.1",
     "@swc/core": "1.3.39",
     "@types/google-protobuf": "^3.15.5",
@@ -75,10 +75,10 @@ export const packageJson: PackageJson = {
     "why-is-node-running": "^2.2.1"
   },
   "peerDependencies": {
-    "@juzi/wechaty-puppet": "^1.0.157"
+    "@juzi/wechaty-puppet": "^1.0.158"
   },
   "dependencies": {
-    "@juzi/wechaty-grpc": "^1.0.109",
+    "@juzi/wechaty-grpc": "^1.0.110",
     "clone-class": "^1.1.1",
     "ducks": "^1.0.2",
     "file-box": "^1.5.5",

package/src/server/event-stream-manager.ts

@@ -23,6 +23,7 @@ import {
 }                                   from '@juzi/wechaty-grpc'
 
 import * as PUPPET from '@juzi/wechaty-puppet'
+import { validateRoomMemberLoadState } from '../utils/pb-payload-helper.js'
 
 import { log, NO_LOG_EVENTS } from '../config.js'
 import {
@@ -245,6 +246,20 @@ class EventStreamManager {
           this.offCallbackList.push(off)
           break
         }
+        case 'room-member-load': {
+          const listener = (payload: PUPPET.payloads.EventRoomMemberLoad): void => {
+            try {
+              validateRoomMemberLoadState(payload)
+              this.grpcEmit(grpcPuppet.EventType.EVENT_TYPE_ROOM_MEMBER_LOAD, payload)
+            } catch (error) {
+              log.error('EventStreamManager', 'room-member-load rejected: %s', error)
+              this.puppet.emit('error', error)
+            }
+          }
+          this.puppet.on('room-member-load', listener)
+          this.offCallbackList.push(() => this.puppet.off('room-member-load', listener))
+          break
+        }
         case 'room-join': {
           const listener = (payload: PUPPET.payloads.EventRoomJoin) => this.grpcEmit(grpcPuppet.EventType.EVENT_TYPE_ROOM_JOIN, payload)
           this.puppet.on('room-join', listener)

package/src/server/puppet-implementation.ts

@@ -20,6 +20,7 @@
 /* eslint-disable sort-keys */
 /* eslint-disable @typescript-eslint/no-misused-promises */
 import type { Writable }    from 'stream'
+import { inspect } from 'util'
 import {
   chunkDecoder,
   chunkEncoder,
@@ -43,12 +44,33 @@ import {
 import { log } from '../config.js'
 import { grpcError }          from './grpc-error.js'
 import { EventStreamManager } from './event-stream-manager.js'
-import { OptionalBooleanUnwrapper, OptionalBooleanWrapper, callRecordPayloadToPb, channelPayloadToPb, channelPbToPayload, chatHistoryPayloadToPb, postPbToPayload, urlLinkPayloadToPb, channelCardPayloadToPb } from '../utils/pb-payload-helper.js'
+import { OptionalBooleanUnwrapper, OptionalBooleanWrapper, callRecordPayloadToPb, channelPayloadToPb, channelPbToPayload, chatHistoryPayloadToPb, postPbToPayload, urlLinkPayloadToPb, channelCardPayloadToPb, roomPayloadToPb, roomMemberLoadStateToPb, roomMemberSnapshotToPb, validateRoomMemberLoadState, validateRoomMemberSnapshot, validateRoomMemberRevision } from '../utils/pb-payload-helper.js'
 import { grpcCallTypeToPuppetMedia, puppetCallMediaTypeToGrpc } from '../utils/call-media-mapping.js'
 import { TextContentType } from '@juzi/wechaty-puppet/types'
 
 type MessageBatchSendResponse = Awaited<ReturnType<PUPPET.impls.PuppetInterface['messageBatchSendText']>>
 
+function roomMemberRpcError<Response> (
+  method: string, error: unknown, callback: grpc.sendUnaryData<Response>,
+): void {
+  log.error('PuppetServiceImpl', 'roomMemberRpcError() %s() rejection: %s', method, inspect(error))
+  if (typeof error === 'object' && error !== null && 'code' in error) {
+    const status = error as Record<string, unknown>
+    const code = status['code']
+    if (typeof code === 'number' && Number.isInteger(code) && code > 0 && code <= 16) {
+      const details = typeof status['details'] === 'string' ? status['details']
+        : error instanceof Error ? error.message : 'Room member RPC failed'
+      callback({ code, details }, null)
+      return
+    }
+  }
+  if (error instanceof Error && /unsupported/i.test(error.message)) {
+    callback({ code: grpc.status.UNIMPLEMENTED, details: error.message }, null)
+    return
+  }
+  grpcError(method, error, callback)
+}
+
 type GrpcBatchResult = {
   setConversationId(value: string): void,
   setError(value: string): void,
@@ -1996,6 +2018,75 @@ function puppetImplementation (
       }
     },
 
+    roomMemberSync: async (
+      call: grpc.ServerUnaryCall<grpcPuppet.RoomMemberSyncRequest, grpcPuppet.RoomMemberLoadStateResponse>,
+      callback: grpc.sendUnaryData<grpcPuppet.RoomMemberLoadStateResponse>,
+    ): Promise<void> => {
+      try {
+        const roomId = call.request.getId()
+        if (!roomId) {
+          return callback({ code: grpc.status.INVALID_ARGUMENT, details: 'roomId is required' }, null)
+        }
+        const options = call.request.getForce() ? { force: true } : undefined
+        if (typeof puppet.roomMemberSync !== 'function') { throw new Error('roomMemberSync unsupported by adapter') }
+        const state = await puppet.roomMemberSync(roomId, options)
+        validateRoomMemberLoadState(state, roomId)
+        return callback(null, roomMemberLoadStateToPb(state))
+      } catch (error) {
+        return roomMemberRpcError('roomMemberSync', error, callback)
+      }
+    },
+
+    roomMemberLoadState: async (
+      call: grpc.ServerUnaryCall<grpcPuppet.RoomMemberLoadStateRequest, grpcPuppet.RoomMemberLoadStateResponse>,
+      callback: grpc.sendUnaryData<grpcPuppet.RoomMemberLoadStateResponse>,
+    ): Promise<void> => {
+      try {
+        const roomId = call.request.getId()
+        if (!roomId) {
+          return callback({ code: grpc.status.INVALID_ARGUMENT, details: 'roomId is required' }, null)
+        }
+        if (typeof puppet.roomMemberLoadState !== 'function') { throw new Error('roomMemberLoadState unsupported by adapter') }
+        const state = await puppet.roomMemberLoadState(roomId)
+        validateRoomMemberLoadState(state, roomId)
+        return callback(null, roomMemberLoadStateToPb(state))
+      } catch (error) {
+        return roomMemberRpcError('roomMemberLoadState', error, callback)
+      }
+    },
+
+    roomMemberSnapshot: async (
+      call: grpc.ServerUnaryCall<grpcPuppet.RoomMemberSnapshotRequest, grpcPuppet.RoomMemberSnapshotResponse>,
+      callback: grpc.sendUnaryData<grpcPuppet.RoomMemberSnapshotResponse>,
+    ): Promise<void> => {
+      try {
+        const roomId = call.request.getId()
+        const revision = call.request.getRevision()
+        const pageSize = call.request.getPageSize()
+        try {
+          if (!roomId) { throw new Error('roomId is required') }
+          validateRoomMemberRevision(revision)
+          if (!Number.isInteger(pageSize) || pageSize < 0 || pageSize > 500) {
+            throw new Error('pageSize must be an integer between 0 and 500')
+          }
+        } catch (error) {
+          return callback({ code: grpc.status.INVALID_ARGUMENT, details: (error as Error).message }, null)
+        }
+        if (typeof puppet.roomMemberSnapshot !== 'function') { throw new Error('roomMemberSnapshot unsupported by adapter') }
+        const snapshot = await puppet.roomMemberSnapshot(roomId, revision, {
+          pageToken: call.request.getPageToken(), pageSize,
+        })
+        try {
+          validateRoomMemberSnapshot(snapshot, roomId, revision)
+        } catch (error) {
+          return callback({ code: grpc.status.FAILED_PRECONDITION, details: (error as Error).message }, null)
+        }
+        return callback(null, roomMemberSnapshotToPb(snapshot))
+      } catch (error) {
+        return roomMemberRpcError('roomMemberSnapshot', error, callback)
+      }
+    },
+
     roomMemberList: async (call, callback) => {
       log.verbose('PuppetServiceImpl', 'roomMemberList()')
 
@@ -2085,20 +2176,7 @@ function puppetImplementation (
 
         const payload = await puppet.roomPayload(roomId)
 
-        const response = new grpcPuppet.RoomPayloadResponse()
-        response.setAdminIdsList(payload.adminIdList)
-        response.setAvatar(payload.avatar || '')
-        response.setHandle(payload.handle || '')
-        response.setId(payload.id)
-        response.setMemberIdsList(payload.memberIdList)
-        response.setOwnerId(payload.ownerId || '')
-        response.setTopic(payload.topic)
-        response.setAdditionalInfo(payload.additionalInfo || '')
-        response.setRoomRemark(payload.remark || '')
-        response.setExternal(!!payload.external)
-        if (payload.createTime) {
-          response.setCreateTime(timestampFromMilliseconds(payload.createTime))
-        }
+        const response = roomPayloadToPb(payload)
 
         return callback(null, response)
 
@@ -2119,20 +2197,7 @@ function puppetImplementation (
 
         const payloads: grpcPuppet.RoomPayloadResponse[] = []
         for (const [ _, payload ] of payloadMap.entries()) {
-          const pb = new grpcPuppet.RoomPayloadResponse()
-          pb.setAdminIdsList(payload.adminIdList)
-          pb.setAvatar(payload.avatar || '')
-          pb.setHandle(payload.handle || '')
-          pb.setId(payload.id)
-          pb.setMemberIdsList(payload.memberIdList)
-          pb.setOwnerId(payload.ownerId || '')
-          pb.setTopic(payload.topic)
-          pb.setAdditionalInfo(payload.additionalInfo || '')
-          pb.setRoomRemark(payload.remark || '')
-          pb.setExternal(!!payload.external)
-          if (payload.createTime) {
-            pb.setCreateTime(timestampFromMilliseconds(payload.createTime))
-          }
+          const pb = roomPayloadToPb(payload)
           payloads.push(pb)
         }