@zhin.js/adapter-onebot12 1.0.1 → 1.1.0

package/src/webhook.ts

@@ -0,0 +1,223 @@
+/**
+ * OneBot12 HTTP webhook endpoint — POST inbound + api_url outbound.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  ClientEndpoint,
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import {
+  buildSendMessageParams,
+  callOneBot12Action,
+  formatInboundContent,
+  formatOutboundSegments,
+  isBotMentioned,
+  isMessageEvent,
+  onebot12InboundConversation,
+  senderNickname,
+  senderUserId,
+  uploadOneBot12MediaSegments,
+  type OneBot12Event,
+  type OneBot12WebhookConfig,
+} from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
+import { verifyOneBotAccessToken } from './wss-auth.js';
+
+const logger = getLogger('onebot12');
+
+export interface OneBot12WebhookEndpointOptions {
+  readonly id: CapabilityId;
+  readonly http: HttpHost;
+  readonly config: OneBot12WebhookConfig;
+  readonly callAction?: typeof callOneBot12Action;
+}
+
+export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
+  readonly client: Onebot12Client;
+  readonly #options: OneBot12WebhookEndpointOptions;
+  readonly management: EndpointManagement;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content;
+  readonly #callAction: typeof callOneBot12Action;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #started = false;
+
+  constructor(options: OneBot12WebhookEndpointOptions) {
+    super();
+    this.#options = options;
+    this.#callAction = options.callAction ?? callOneBot12Action;
+    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callApi(action, params));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
+    this.management = createOneBot12EndpointManagement({ callApi });
+    this.content = createOneBot12ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot12ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot12Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    if (!this.#options.config.access_token) {
+      // webhook 模式未配 access_token 时任何 POST 都会被放行（verifyOneBotAccessToken 直接 return true）
+      logger.warn(formatCompact({
+        endpoint: this.#options.config.id,
+        mode: 'webhook',
+        ok: false,
+        error: 'missing access_token',
+      }));
+    }
+    this.#setupRoutes();
+    logger.info(formatCompact({
+      op: 'listen',
+      endpoint: this.#options.config.id,
+      mode: 'webhook',
+      path: this.#options.config.path,
+    }));
+  }
+
+  async stop(): Promise<void> {
+    this.close();
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
+  }
+
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const materialized = await uploadOneBot12MediaSegments(
+      payload,
+      (action, params) => callOnebot12Client(this.client, action, params),
+      (error) => {
+        logger.warn(formatCompact({
+          op: 'onebot12_upload_failed',
+          endpoint: this.#options.config.id,
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      },
+    );
+    const message = formatOutboundSegments(materialized);
+    const params = buildSendMessageParams(conversation, message);
+    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
+    const messageId = data?.message_id ?? '';
+    logger.debug(formatCompact({
+      op: 'onebot12_send',
+      endpoint: this.#options.config.id,
+      kind: conversation.kind,
+      conversationId: conversation.id,
+      messageId,
+    }));
+    return messageId;
+  }
+
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+  }
+
+  async #callApi(
+    action: string,
+    params: Record<string, unknown> = {},
+  ): Promise<import('@imhelper/onebot-v12').OneBotV12Response> {
+    const apiUrl = this.#options.config.api_url;
+    if (!apiUrl) {
+      throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
+    }
+    return this.#callAction(
+      { url: apiUrl, access_token: this.#options.config.access_token },
+      action,
+      params,
+    );
+  }
+
+  #admitRaw(ev: OneBot12Event): void {
+    if (!isMessageEvent(ev)) {
+      receiveOneBot12SideEvent(
+        (name, payload) => this.emit(name, payload),
+        this.#options.config.id,
+        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
+        ev,
+        logger,
+      );
+      return;
+    }
+    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+    const content = formatInboundContent(ev);
+    const nickname = senderNickname(ev);
+    const mentioned = isBotMentioned(ev);
+    void this.emit('message.receive', {
+      conversation,
+      message: { conversation, id: ev.message_id },
+      content,
+      sender: { id: senderUserId(ev), ...(nickname ? { name: nickname } : {}) },
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
+      metadata: Object.freeze({
+        detail_type: ev.detail_type,
+        user_id: ev.user_id,
+        group_id: ev.group_id,
+        channel_id: ev.channel_id,
+        guild_id: ev.guild_id,
+        time: ev.time,
+        ...(nickname ? { nickname } : {}),
+      }),
+    }).catch((err) => {
+      logger.warn(formatCompact({
+        op: 'onebot12_gateway_receive_failed',
+        kind: conversation.kind,
+        conversationId: conversation.id,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  #warnPlatformEvent(error: unknown): void {
+    logger.warn(formatCompact({
+      op: 'onebot12_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
+  #setupRoutes(): void {
+    const path = this.#options.config.path;
+    this.#routeReleases.push(
+      this.#options.http.route('POST', path, async (request, response) => {
+        await this.#handleWebhook(request, response);
+      }, { summary: 'OneBot12 webhook callback', tags: ['onebot12'] }),
+    );
+  }
+
+  async #handleWebhook(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    try {
+      if (!verifyOneBotAccessToken(this.#options.config.access_token, request)) {
+        response.writeHead(403, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ message: 'Unauthorized' }));
+        return;
+      }
+      if (!this.clientEventsOpen) {
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ status: 'ok' }));
+        return;
+      }
+      await this.client.acceptHttp(request, response);
+    } catch (error) {
+      logger.error('OneBot12 webhook error:', error);
+      if (!response.headersSent) {
+        response.writeHead(500, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ message: 'Internal Server Error' }));
+      }
+    }
+  }
+}

package/src/ws-endpoint.ts

@@ -0,0 +1,321 @@
+/**
+ * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
+ */
+import WebSocket from 'ws';
+import { clearTimeout } from 'node:timers';
+import {
+  ClientEndpoint,
+  createRecallEndpointControl,
+  createEndpointLifecycle,
+  type EndpointConnectHandle,
+  type EndpointControl,
+  type EndpointLifecycle,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import {
+  buildSendMessageParams,
+  buildWsConnectOptions,
+  formatInboundContent,
+  formatOutboundSegments,
+  isBotMentioned,
+  isMessageEvent,
+  onebot12InboundConversation,
+  senderNickname,
+  senderUserId,
+  uploadOneBot12MediaSegments,
+  type OneBot12ActionRequest,
+  type OneBot12ActionResponse,
+  type OneBot12Event,
+  type OneBot12WsConfig,
+} from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
+import {
+  type OneBot12WsCreateOptions,
+  type OneBot12WsSocket,
+  WS_OPEN,
+} from './ws-types.js';
+
+export interface OneBot12WsEndpointOptions {
+  readonly id: CapabilityId;
+  readonly config: OneBot12WsConfig;
+  readonly createWebSocket?: (
+    url: string,
+    options: OneBot12WsCreateOptions,
+  ) => OneBot12WsSocket;
+}
+
+export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
+  readonly client: Onebot12Client;
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: OneBot12WsEndpointOptions;
+  readonly management: EndpointManagement;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content;
+  readonly #lifecycle: EndpointLifecycle;
+  #ws?: OneBot12WsSocket;
+  #requestId = 0;
+  #pending = new Map<string, {
+    resolve: (value: OneBot12ActionResponse) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+  }>();
+
+  constructor(options: OneBot12WsEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('onebot12', options.config.id);
+    this.#options = options;
+    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callAction(action, params ?? {}));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
+    this.management = createOneBot12EndpointManagement({ callApi });
+    this.content = createOneBot12ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot12ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot12Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
+    const { config } = options;
+    this.#lifecycle = createEndpointLifecycle({
+      name: config.id,
+      reconnect: {
+        initialIntervalMs: config.reconnect_interval,
+        // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
+        multiplier: 1,
+        maxIntervalMs: config.reconnect_interval,
+        jitterMs: 0,
+      },
+      heartbeat: { intervalMs: config.heartbeat_interval },
+    });
+  }
+
+  async start(): Promise<void> {
+    if (this.#lifecycle.started) return;
+    try {
+      await this.#lifecycle.start((handle) => this.#connect(handle));
+    } catch (err) {
+      // start 失败必须清理现场（状态复位由基座保证）
+      if (this.#ws) {
+        try {
+          this.#ws.close();
+        } catch {
+          /* ignore */
+        }
+        this.#ws = undefined;
+      }
+      throw err;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.close();
+    // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+    await this.#lifecycle.stop();
+    for (const [, pending] of this.#pending) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error('连接已关闭'));
+    }
+    this.#pending.clear();
+    this.#ws = undefined;
+  }
+
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const materialized = await uploadOneBot12MediaSegments(
+      payload,
+      (action, params) => callOnebot12Client(this.client, action, params),
+      (error) => {
+        this.#logger.warn(formatCompact({
+          op: 'onebot12_upload_failed',
+          endpoint: this.#options.config.id,
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      },
+    );
+    const message = formatOutboundSegments(materialized);
+    const params = buildSendMessageParams(conversation, message);
+    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
+    const messageId = data?.message_id ?? '';
+    this.#logger.debug(formatCompact({
+      op: 'onebot12_send',
+      endpoint: this.#options.config.id,
+      kind: conversation.kind,
+      conversationId: conversation.id,
+      messageId,
+    }));
+    return messageId;
+  }
+
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+  }
+
+  #admitRaw(ev: OneBot12Event): void {
+    if (!isMessageEvent(ev)) {
+      receiveOneBot12SideEvent(
+        (name, payload) => this.emit(name, payload),
+        this.#options.config.id,
+        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
+        ev,
+        this.#logger,
+      );
+      return;
+    }
+    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+    const content = formatInboundContent(ev);
+    const nickname = senderNickname(ev);
+    const mentioned = isBotMentioned(ev);
+    void this.emit('message.receive', {
+      conversation,
+      message: { conversation, id: ev.message_id },
+      content,
+      sender: { id: senderUserId(ev), name: senderNickname(ev) },
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
+      metadata: Object.freeze({
+        detail_type: ev.detail_type,
+        user_id: ev.user_id,
+        group_id: ev.group_id,
+        channel_id: ev.channel_id,
+        guild_id: ev.guild_id,
+        time: ev.time,
+        ...(nickname ? { nickname } : {}),
+      }),
+    }).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'onebot12_gateway_receive_failed',
+        kind: conversation.kind,
+        conversationId: conversation.id,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'onebot12_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
+    const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
+    const create = this.#options.createWebSocket
+      ?? ((connectUrl: string, options: OneBot12WsCreateOptions) =>
+        new WebSocket(connectUrl, { headers: options.headers }) as unknown as OneBot12WsSocket);
+
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const ws = create(url, { headers });
+      this.#ws = ws;
+      handle.onForceClose(() => {
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+      });
+
+      ws.on('open', () => {
+        if (settled) return;
+        settled = true;
+        this.#logger.debug(formatCompact({
+          endpoint: this.#options.config.id,
+          mode: 'ws',
+          url: safeUrl,
+        }));
+        this.#lifecycle.startHeartbeat(() => {
+          this.#callAction('get_status', {}).catch(() => {});
+        });
+        resolve();
+      });
+
+      ws.on('message', (data) => {
+        this.#onMessage(data);
+      });
+
+      ws.on('close', (code, reason) => {
+        const reasonStr = typeof reason === 'string'
+          ? reason
+          : Buffer.isBuffer(reason)
+            ? reason.toString()
+            : String(reason ?? '');
+        const codeNum = typeof code === 'number' ? code : Number(code ?? 0);
+        if (!settled) {
+          settled = true;
+          reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
+        }
+        // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+        // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
+        handle.notifyClosed(`OneBot12 WS 关闭: ${codeNum} ${reasonStr || 'closed'}`);
+      });
+
+      ws.on('error', (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.#logger.warn(formatCompact({
+          op: 'ws_error',
+          endpoint: this.#options.config.id,
+          ok: false,
+          error: error.message,
+        }));
+        if (!settled) {
+          settled = true;
+          reject(error);
+        }
+      });
+    });
+  }
+
+  #onMessage(data: unknown): void {
+    try {
+      const raw = typeof data === 'string'
+        ? data
+        : Buffer.isBuffer(data)
+          ? data.toString()
+          : data instanceof ArrayBuffer
+            ? new TextDecoder().decode(data)
+            : String(data ?? '');
+      const msg = JSON.parse(raw) as OneBot12Event | OneBot12ActionResponse;
+      if ('echo' in msg && typeof (msg as OneBot12ActionResponse).echo === 'string') {
+        const resp = msg as OneBot12ActionResponse;
+        const pending = this.#pending.get(resp.echo!);
+        if (pending) {
+          this.#pending.delete(resp.echo!);
+          clearTimeout(pending.timeout);
+          pending.resolve(resp);
+        }
+        return;
+      }
+      this.client.ingest(msg as Parameters<Onebot12Client['ingest']>[0]);
+    } catch (error) {
+      this.#logger.warn(formatCompact({
+        op: 'onebot12_parse_failed',
+        endpoint: this.#options.config.id,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  }
+
+  #callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse> {
+    if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
+      return Promise.reject(new Error('WebSocket 未连接'));
+    }
+    const echo = `ob12_${++this.#requestId}`;
+    const req: OneBot12ActionRequest = { action, params, echo };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.#pending.delete(echo);
+        reject(new Error(`OneBot12 动作超时: ${action}`));
+      }, 30_000);
+      this.#pending.set(echo, { resolve, reject, timeout });
+      this.#ws!.send(JSON.stringify(req));
+    });
+  }
+}

package/src/ws-types.ts

@@ -0,0 +1,19 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface OneBot12WsSocket {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+
+export interface OneBot12WsCreateOptions {
+  readonly headers?: Record<string, string>;
+}
+
+export const WS_OPEN = 1;
+
+export interface OneBot12PendingAction {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  timeout: NodeJS.Timeout;
+}

package/src/wss-auth.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage } from 'node:http';
+
+export function verifyOneBotAccessToken(
+  accessToken: string | undefined,
+  request: IncomingMessage,
+): boolean {
+  if (!accessToken) return true;
+  const auth = request.headers.authorization ?? '';
+  if (auth === `Bearer ${accessToken}`) return true;
+  try {
+    const url = new URL(request.url ?? '/', 'http://localhost');
+    if (url.searchParams.get('access_token') === accessToken) return true;
+  } catch {
+    /* ignore */
+  }
+  return false;
+}