@zhin.js/adapter-onebot12 3.0.2 → 3.0.3

package/lib/ws-endpoint.js

@@ -0,0 +1,240 @@
+/**
+ * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
+ */
+import WebSocket from 'ws';
+import { clearInterval, clearTimeout } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { WS_OPEN, } from './ws-types.js';
+const logger = getLogger('onebot12');
+export class OneBot12WsEndpoint {
+    #options;
+    #ws;
+    #reconnectTimer;
+    #heartbeatTimer;
+    #requestId = 0;
+    #pending = new Map();
+    #open = false;
+    #started = false;
+    #stopping = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#stopping = false;
+        await this.#connect();
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#stopping = true;
+        this.#started = false;
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('连接已关闭'));
+        }
+        this.#pending.clear();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const params = buildSendMessageParams(target, message);
+        const data = await this.#callAction('send_message', params);
+        const messageId = data?.message_id ?? '';
+        logger.debug(formatCompact({
+            op: 'onebot12_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a parsed event when the endpoint is open. */
+    admit(ev) {
+        if (!this.#open || !isMessageEvent(ev))
+            return;
+        const target = formatInboundTarget(ev);
+        const content = formatInboundContent(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isBotMentioned(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content,
+            sender: senderUserId(ev),
+            id: ev.message_id,
+            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,
+                endpoint: this.#options.config.name,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #connect() {
+        const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
+        const create = this.#options.createWebSocket
+            ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = create(url, { headers });
+            this.#ws = ws;
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                logger.debug(formatCompact({
+                    endpoint: this.#options.config.name,
+                    mode: 'ws',
+                    url: safeUrl,
+                }));
+                this.#startHeartbeat();
+                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);
+                logger.warn(formatCompact({
+                    op: 'disconnect',
+                    endpoint: this.#options.config.name,
+                    code: codeNum,
+                    error: reasonStr || 'closed',
+                    reconnect_ms: this.#options.config.reconnect_interval,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
+                }
+                this.#scheduleReconnect();
+            });
+            ws.on('error', (err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: this.#options.config.name,
+                    ok: false,
+                    error: error.message,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            });
+        });
+    }
+    #onMessage(data) {
+        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);
+            if ('echo' in msg && typeof msg.echo === 'string') {
+                const resp = msg;
+                const pending = this.#pending.get(resp.echo);
+                if (pending) {
+                    this.#pending.delete(resp.echo);
+                    clearTimeout(pending.timeout);
+                    if (resp.status === 'ok')
+                        pending.resolve(resp.data);
+                    else
+                        pending.reject(new Error(`OneBot12 retcode=${resp.retcode}: ${resp.message}`));
+                }
+                return;
+            }
+            this.admit(msg);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'onebot12_parse_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #callAction(action, params) {
+        if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
+            return Promise.reject(new Error('WebSocket 未连接'));
+        }
+        const echo = `ob12_${++this.#requestId}`;
+        const req = { 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));
+        });
+    }
+    #startHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+        }
+        this.#heartbeatTimer = setInterval(() => {
+            this.#callAction('get_status', {}).catch(() => { });
+        }, this.#options.config.heartbeat_interval);
+    }
+    #scheduleReconnect() {
+        if (this.#stopping || !this.#started || this.#reconnectTimer)
+            return;
+        const delay = this.#options.config.reconnect_interval;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            void this.#connect().catch((err) => {
+                logger.warn(formatCompact({
+                    op: 'reconnect',
+                    endpoint: this.#options.config.name,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }, delay);
+    }
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,16 @@
+/** 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 declare const WS_OPEN = 1;
+export interface OneBot12PendingAction {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export const WS_OPEN = 1;

package/lib/wss-auth.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function verifyOneBotAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;

package/lib/wss-auth.js

@@ -0,0 +1,16 @@
+export function verifyOneBotAccessToken(accessToken, request) {
+    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;
+}

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,24 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type OneBot12Event, type OneBot12WssConfig } from './protocol.js';
+export interface OneBot12WssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: OneBot12WssConfig;
+}
+export declare class OneBot12WssEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: OneBot12WssEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    admit(ev: OneBot12Event): void;
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,193 @@
+/**
+ * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { clearInterval } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { buildSendMessageParams, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { verifyOneBotAccessToken } from './wss-auth.js';
+import { WS_OPEN } from './ws-types.js';
+const logger = getLogger('onebot12');
+export class OneBot12WssEndpoint {
+    #options;
+    #ws;
+    #wsRelease;
+    #heartbeatTimer;
+    #requestId = 0;
+    #pending = new Map();
+    #open = false;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('连接已关闭'));
+        }
+        this.#pending.clear();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        this.#started = false;
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const params = buildSendMessageParams(target, message);
+        const data = await this.#callAction('send_message', params);
+        return data?.message_id ?? '';
+    }
+    admit(ev) {
+        if (!this.#open || !isMessageEvent(ev))
+            return;
+        const target = formatInboundTarget(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isBotMentioned(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(ev),
+            sender: senderUserId(ev),
+            id: ev.message_id,
+            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,
+                endpoint: this.#options.config.name,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #acceptConnection(connection) {
+        if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
+            connection.socket.close(4003, 'Unauthorized');
+            return;
+        }
+        const socket = connection.socket;
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.#ws = socket;
+        this.#startHeartbeat();
+        socket.on('message', (data) => {
+            this.#onMessage(data);
+        });
+        socket.on('close', () => {
+            if (this.#ws === socket) {
+                this.#ws = undefined;
+                if (this.#heartbeatTimer) {
+                    clearInterval(this.#heartbeatTimer);
+                    this.#heartbeatTimer = undefined;
+                }
+            }
+        });
+        logger.debug(formatCompact({
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+    #onMessage(data) {
+        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);
+            if ('echo' in msg && typeof msg.echo === 'string') {
+                const resp = msg;
+                const pending = this.#pending.get(resp.echo);
+                if (pending) {
+                    this.#pending.delete(resp.echo);
+                    clearTimeout(pending.timeout);
+                    if (resp.status === 'ok')
+                        pending.resolve(resp.data);
+                    else
+                        pending.reject(new Error(`OneBot12 retcode=${resp.retcode}: ${resp.message}`));
+                }
+                return;
+            }
+            this.admit(msg);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'onebot12_parse_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #callAction(action, params) {
+        if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
+            return Promise.reject(new Error('WebSocket 未连接'));
+        }
+        const echo = `ob12_${++this.#requestId}`;
+        const req = { 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));
+        });
+    }
+    #startHeartbeat() {
+        if (this.#heartbeatTimer)
+            clearInterval(this.#heartbeatTimer);
+        this.#heartbeatTimer = setInterval(() => {
+            this.#callAction('get_status', {}).catch(() => { });
+        }, this.#options.config.heartbeat_interval);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "3.0.2",
-  "description": "Zhin.js adapter for OneBot 12 protocol",
+  "version": "3.0.3",
+  "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,12 +13,14 @@
     }
   },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
     "agent",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "zhin",
@@ -36,23 +38,28 @@
     "directory": "plugins/adapters/onebot12"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.93",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2"
+    "vitest": "^4.1.10",
+    "@zhin.js/host-http": "1.0.1"
   },
   "peerDependencies": {
-    "zhin.js": "4.1.2",
-    "@zhin.js/host-router": "2.0.3"
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "zhin.js": {
       "optional": true
     }
   },
@@ -61,11 +68,30 @@
     "email": "admin@liucl.cn",
     "url": "https://github.com/lc-cn"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/onebot12/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+
+export default definePlugin({
+  name: 'onebot12',
+  metadata: {
+    displayName: 'OneBot 12 Adapter',
+  },
+});

package/schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": ["ws", "webhook", "wss"],
+      "default": "ws",
+      "description": "ws (default), webhook (httpHostToken POST), or wss (reverse WS via httpHostToken)"
+    },
+    "name": {
+      "type": "string",
+      "default": "onebot12-bot"
+    },
+    "url": {
+      "type": "string",
+      "description": "OneBot implementation WebSocket URL (required for connection: ws)"
+    },
+    "path": {
+      "type": "string",
+      "description": "HTTP/WS path for webhook or reverse-wss"
+    },
+    "api_url": {
+      "type": "string",
+      "description": "HTTP action endpoint for webhook outbound (required for connection: webhook send)"
+    },
+    "access_token": {
+      "type": "string"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    }
+  }
+}