@zhin.js/adapter-onebot11 1.1.18 → 1.1.20

package/src/ws-endpoint.ts

@@ -4,7 +4,8 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
  */
 import WebSocket from 'ws';
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec,
+  type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
@@ -12,6 +13,7 @@ import {
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
+  type PendingRpcRequest,
   type EndpointTransportState,
 } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -32,20 +34,16 @@ import {
 } from './protocol.js';
 import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
 import { createOneBot11ContentPort } from './content-port.js';
+import { createOneBot11Rpc, type OneBot11Rpc } from './ws-transport.js';
 import {
-  callOneBot11WsAction,
-  handleOneBot11WsMessage,
-  rejectAllPending,
-} from './ws-transport.js';
-import {
-  type OneBot11PendingAction,
   type OneBot11WsCreateOptions,
   type OneBot11WsSocket,
 } from './ws-types.js';
 import { probeOnebot11SelfId, resolveOnebot11SelfId } from './self-id.js';
-import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents, type Onebot11Client } from './client.js';
+import { callOnebot11Client, readOnebot11Response, onebot11ClientOptions, forwardOnebot11ClientEvents, Onebot11Client } from './client.js';
 
 export interface OneBot11WsEndpointOptions {
+  readonly signal?: AbortSignal;
   readonly id: CapabilityId;
   /** 连接后 best-effort 调用 get_login_info 上报账号（Adapter 工厂开启；默认关闭以免占用首个 echo）。 */
   readonly probeLoginInfo?: boolean;
@@ -56,35 +54,50 @@ export interface OneBot11WsEndpointOptions {
   ) => OneBot11WsSocket;
 }
 
-export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
-  readonly client: Onebot11Client;
+export class OneBot11WsEndpoint extends Onebot11Client implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: OneBot11WsEndpointOptions;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content;
+  readonly #management: EndpointManagement;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal?: AbortSignal) => this.#recallMessage(id, signal));
+  readonly #content;
+  readonly #releaseClientEvents: () => void;
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot11WsSocket;
   #stopped = false;
-  #requestId = { value: 0 };
-  #pending = new Map<string, OneBot11PendingAction>();
+  readonly #rpc: OneBot11Rpc;
 
   constructor(options: OneBot11WsEndpointOptions) {
-    super();
+    const rpc = createOneBot11Rpc({ endpointId: options.config.id, signal: options.signal,
+      socket: () => this.#lifecycle.state === 'open' ? this.#ws : undefined,
+    });
+    super(onebot11ClientOptions(options.config, (action, params) => rpc.call({ action, params })));
+    this.#rpc = rpc;
     this.#logger = getAdapterLogger('onebot11', options.config.id);
     this.#options = options;
-    this.client = createOnebot11EndpointClient(options.config, (action, params) => this.#callApi(action, params));
-    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot11Client(this.client, action, params);
-    this.management = createOneBot11EndpointManagement({ callApi });
-    this.content = createOneBot11ContentPort(callApi);
-    this.bindClientEvents(
-      (receive) => forwardOnebot11ClientEvents(this.client, receive),
-      (name, payload) => {
+    const callApi = (request: PendingRpcRequest) => this.#rpc.call(request).then(readOnebot11Response);
+    this.#management = createOneBot11EndpointManagement({ callApi });
+    this.#content = createOneBot11ContentPort(callApi);
+    const readTransportState = () => this.#lifecycle.state;
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#open = false; }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      get transportState() { return readTransportState(); },
+      management: this.#management, control: this.#control, content: this.#content,
+    });
+    this.#releaseClientEvents = forwardOnebot11ClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        // A native frame can arrive before start resolves. The spec owns candidate
+        // buffering and Root/child admission; transport start is not publication.
+        if (this.#stopped || (!this.#open && !this.#lifecycle.started)) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as OneBot11Event);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
       name: config.id,
@@ -99,11 +112,11 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     });
   }
 
-  get transportState(): EndpointTransportState {
+  get #transportState(): EndpointTransportState {
     return this.#lifecycle.state;
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#lifecycle.started) return;
     this.#stopped = false;
     try {
@@ -123,20 +136,23 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     }
   }
 
-  async stop(): Promise<void> {
+  async #stop(): Promise<void> {
     this.#stopped = true;
-    this.close();
+    this.#open = false;
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
-    await this.#lifecycle.stop();
-    rejectAllPending(this.#pending);
-    this.#ws = undefined;
-    this.reportSelfUserId(undefined);
+    try { await this.#lifecycle.stop(); }
+    finally {
+      this.#rpc.dispose();
+      this.#releaseClientEvents();
+      this.#ws = undefined;
+      this[endpointSpec].reportSelfUserId(undefined);
+    }
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await callOnebot11Client<{ message_id?: number | string }>(this.client, action, params);
+    const data = readOnebot11Response<{ message_id?: number | string }>(await this.#rpc.call({ action, params, signal }));
     const rawId = data?.message_id;
     if ((typeof rawId !== 'number' && typeof rawId !== 'string') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
       throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: platform returned no message_id', 'unknown');
@@ -151,35 +167,30 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     return messageId;
   }
 
-  async recallMessage(messageId: string): Promise<void> {
+  async #recallMessage(messageId: string, signal?: AbortSignal): Promise<void> {
     if (!messageId) return;
-    await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
+    await this.#rpc.call({ action: 'delete_msg', params: { message_id: Number(messageId) }, signal }).then(readOnebot11Response);
   }
 
-  #callApi(
-    action: string,
-    params: Record<string, unknown> = {},
-  ): ReturnType<typeof callOneBot11WsAction> {
-    return callOneBot11WsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
-  }
 
   #admitRaw(ev: OneBot11Event): void {
     const selfId = resolveOnebot11SelfId(ev.self_id);
-    if (!this.#stopped && selfId && selfId !== this.selfUserId) this.reportSelfUserId(selfId);
+    if (!this.#stopped && selfId) this[endpointSpec].reportSelfUserId(selfId);
     if (!isMessageEvent(ev)) {
-      receiveOneBot11SideEvent(
-        (name, payload) => this.emit(name, payload),
-        this.#options.config.id,
-        { callApi: (action, params) => callOnebot11Client(this.client, action, params) },
-        ev,
-        this.#logger,
-      );
+      receiveOneBot11SideEvent(ev, {
+        emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+        endpointKey: this.#options.config.id,
+        caller: { callApi: (action, params) => callOnebot11Client({ client: this, action, params }) },
+        logger: this.#logger,
+      });
       return;
     }
-    const conversation = onebot11InboundConversation(String(this.#options.id), ev);
+    const conversation = { ...onebot11InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
     const content = formatInboundContent(ev);
     const inbound = formatInboundMetadata(ev, this.#options.config.id);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event: ev,
+      ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
       conversation,
       message: { conversation, id: String(ev.message_id) },
       content,
@@ -203,14 +214,14 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
 
   /** Best-effort 登录账号探测；失败仅 debug，不影响连接。 */
   async #probeSelfUserId(): Promise<void> {
-    const selfId = await probeOnebot11SelfId(this.client, (error) => {
+    const selfId = await probeOnebot11SelfId(this, (error) => {
       this.#logger.debug(formatCompact({
         op: 'onebot11_get_login_info_failed',
         error: error instanceof Error ? error.message : String(error),
       }));
     });
-    if (this.#stopped || this.transportState !== 'open') return;
-    if (selfId && selfId !== this.selfUserId) this.reportSelfUserId(selfId);
+    if (this.#stopped || this.#transportState !== 'open') return;
+    if (selfId) this[endpointSpec].reportSelfUserId(selfId);
   }
 
   #warnPlatformEvent(error: unknown): void {
@@ -232,7 +243,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       this.#ws = ws;
       handle.onForceClose(() => {
         if (this.#ws === ws) {
-          rejectAllPending(this.#pending);
+          this.#rpc.disconnect();
         }
         try {
           ws.close();
@@ -266,17 +277,13 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       ws.on('message', (data) => {
         if (this.#ws !== ws || ws.readyState !== 1 || !this.#lifecycle.started) return;
         this.#lifecycle.notifyHeartbeatAck();
-        handleOneBot11WsMessage(data, {
-          endpointId: this.#options.config.id,
-          pending: this.#pending,
-          ingest: (ev) => this.client.ingest(ev as Parameters<Onebot11Client['ingest']>[0]),
-        });
+        this.#rpc.receive(data, (ev) => this.ingest(ev as Parameters<Onebot11Client['ingest']>[0]));
       });
 
       ws.on('close', (code, reason) => {
         if (this.#ws !== ws) return;
         this.#ws = undefined;
-        rejectAllPending(this.#pending);
+        this.#rpc.disconnect();
         const reasonStr = typeof reason === 'string'
           ? reason
           : Buffer.isBuffer(reason)

package/src/ws-transport.ts

@@ -1,92 +1,51 @@
-import { EndpointDeliveryError } from '@zhin.js/im-contract';
-import { clearTimeout, setTimeout } from 'node:timers';
+import { createPendingRpc, type PendingRpc, type PendingRpcRequest } from 'zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import {
-  type OneBot11ActionRequest,
-  type OneBot11ActionResponse,
-  type OneBot11Event,
-} from './protocol.js';
-import {
-  WS_OPEN,
-  type OneBot11PendingAction,
-  type OneBot11WsSocket,
-} from './ws-types.js';
+import type { OneBot11ActionResponse, OneBot11Event } from './protocol.js';
+import { WS_OPEN, type OneBot11WsSocket } from './ws-types.js';
 
 const logger = getLogger('onebot11');
-
-export function decodeWsPayload(data: unknown): string {
-  if (typeof data === 'string') return data;
-  if (Buffer.isBuffer(data)) return data.toString();
-  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
-  return String(data ?? '');
+export interface OneBot11RpcOptions {
+  readonly endpointId: string;
+  readonly signal?: AbortSignal;
+  /** Reads the lifecycle's selected socket; RPC never opens or reconnects it. */
+  readonly socket: () => OneBot11WsSocket | undefined;
 }
-
-export function handleOneBot11WsMessage(
-  data: unknown,
-  options: {
-    readonly endpointId: string;
-    readonly pending: Map<string, OneBot11PendingAction>;
-    readonly ingest: (ev: OneBot11Event) => void;
-  },
-): void {
-  try {
-    const raw = decodeWsPayload(data);
-    const msg = JSON.parse(raw) as OneBot11Event | OneBot11ActionResponse;
-    if ('echo' in msg && typeof (msg as OneBot11ActionResponse).echo === 'string') {
-      const resp = msg as OneBot11ActionResponse;
-      const pending = options.pending.get(resp.echo!);
-      if (pending) {
-        options.pending.delete(resp.echo!);
-        clearTimeout(pending.timeout);
-        pending.resolve(resp);
-      }
-      return;
-    }
-    options.ingest(msg as OneBot11Event);
-  } catch (error) {
-    logger.warn(formatCompact({
-      op: 'onebot11_parse_failed',
-      endpoint: options.endpointId,
-      error: error instanceof Error ? error.message : String(error),
-    }));
-  }
+export interface OneBot11Rpc {
+  call(request: PendingRpcRequest): Promise<OneBot11ActionResponse>;
+  receive(data: unknown, ingest: (event: OneBot11Event) => void): void;
+  disconnect: PendingRpc<OneBot11ActionResponse>['disconnect'];
+  dispose(): void;
+  readonly pendingCount: number;
 }
 
-export function callOneBot11WsAction(
-  ws: OneBot11WsSocket | undefined,
-  pending: Map<string, OneBot11PendingAction>,
-  requestId: { value: number },
-  action: string,
-  params: Record<string, unknown>,
-): Promise<OneBot11ActionResponse> {
-  if (!ws || ws.readyState !== WS_OPEN) {
-    return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket 未连接', 'not_sent'));
-  }
-  const echo = `ob11_${++requestId.value}`;
-  const req: OneBot11ActionRequest = { action, params, echo };
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      pending.delete(echo);
-      reject(new EndpointDeliveryError('endpoint_timeout', `OneBot11 动作超时: ${action}`, 'unknown'));
-    }, 30_000);
-    pending.set(echo, { resolve, reject, timeout });
-    try {
-      ws.send(JSON.stringify(req));
-    } catch (error) {
-      pending.delete(echo);
-      clearTimeout(timeout);
-      reject(error instanceof Error ? error : new Error(String(error)));
-    }
+/** A Client's one request owner serves native SDK actions and framework operations. */
+export function createOneBot11Rpc(options: OneBot11RpcOptions): OneBot11Rpc {
+  const pending = createPendingRpc<OneBot11ActionResponse>({
+    signal: options.signal, requestPrefix: 'ob11_', timeoutMs: 30_000,
+    transport: () => { const socket = options.socket(); return socket?.readyState === WS_OPEN ? socket : undefined; },
+    serialize: request => JSON.stringify({ action: request.action, params: request.params ?? {}, echo: request.id }),
+  });
+  return Object.freeze({
+    call: pending.call, disconnect: pending.disconnect, dispose: pending.dispose,
+    get pendingCount() { return pending.pendingCount; },
+    receive(data: unknown, ingest: (event: OneBot11Event) => void) {
+      try {
+        const message = JSON.parse(decodeWsPayload(data)) as OneBot11Event | OneBot11ActionResponse;
+        if ('echo' in message && typeof message.echo === 'string') {
+          pending.accept({ id: message.echo, value: message as OneBot11ActionResponse }); return;
+        }
+        ingest(message as OneBot11Event);
+      } catch (error) {
+        logger.warn(formatCompact({ op: 'onebot11_parse_failed', endpoint: options.endpointId,
+          error: error instanceof Error ? error.message : String(error) }));
+      }
+    },
   });
 }
 
-export function rejectAllPending(
-  pending: Map<string, OneBot11PendingAction>,
-  message = '连接已关闭',
-): void {
-  for (const [, entry] of pending) {
-    clearTimeout(entry.timeout);
-    entry.reject(new EndpointDeliveryError('endpoint_disconnected', message, 'unknown'));
-  }
-  pending.clear();
+export function decodeWsPayload(data: unknown): string {
+  if (typeof data === 'string') return data;
+  if (Buffer.isBuffer(data)) return data.toString();
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  return String(data ?? '');
 }

package/src/ws-types.ts

@@ -12,10 +12,3 @@ export interface OneBot11WsCreateOptions {
 }
 
 export const WS_OPEN = 1;
-
-export interface OneBot11PendingAction {
-  resolve: (value: OneBot11ActionResponse) => void;
-  reject: (err: Error) => void;
-  timeout: NodeJS.Timeout;
-}
-import type { OneBot11ActionResponse } from './protocol.js';