@dsbot-channel/onebot 0.0.0-stage → 0.7.0

package/dist/ws-forward.js

@@ -0,0 +1,318 @@
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
+/** Kept always on: a half-open socket is the failure that leaves no line in a log. */
+export const ONEBOT_PING_INTERVAL_MS = 30_000;
+export const ONEBOT_PONG_TIMEOUT_MS = 10_000;
+const REAL_CLOCK = {
+    setTimer: (callback, ms) => setTimeout(callback, ms),
+    clearTimer: (handle) => clearTimeout(handle),
+};
+/**
+ * The forward half of OneBot over WebSocket: this side dials out, sends actions with an
+ * `echo`, and reads events off the same socket or a second one.
+ */
+export class ForwardLink {
+    #options;
+    #pending = new Map();
+    #api;
+    #events;
+    #apiOpen = false;
+    #eventsOpen = false;
+    #closed = false;
+    #retry;
+    #eventRetry;
+    #beat;
+    #attempt = 0;
+    #reconnects = 0;
+    #state = 'offline';
+    #lastFailure = null;
+    #lastFailureAt = null;
+    #lastConnectedAt = null;
+    #lastFrameAt = 0;
+    #warnedSize = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    start() {
+        this.#closed = false;
+        this.#dial();
+        if (this.#options.heartbeat !== undefined && this.#options.heartbeat.intervalMs > 0) {
+            this.#startBeat();
+        }
+    }
+    close() {
+        this.#closed = true;
+        if (this.#retry !== undefined)
+            clearTimeout(this.#retry);
+        if (this.#eventRetry !== undefined)
+            clearTimeout(this.#eventRetry);
+        if (this.#beat !== undefined)
+            clearInterval(this.#beat);
+        this.#retry = undefined;
+        this.#eventRetry = undefined;
+        this.#beat = undefined;
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, code: 'unreachable', reason: 'the link closed while waiting for an answer' });
+        }
+        this.#pending.clear();
+        this.#api?.close();
+        this.#events?.close();
+        this.#api = undefined;
+        this.#events = undefined;
+        this.#apiOpen = false;
+        this.#eventsOpen = false;
+        this.#state = 'offline';
+    }
+    health() {
+        return {
+            kind: 'connection',
+            state: this.#state,
+            lastFailure: this.#lastFailure,
+            lastFailureAt: this.#lastFailureAt,
+            reconnectCount: this.#reconnects,
+            lastConnectedAt: this.#lastConnectedAt,
+            queueDepth: this.#pending.size,
+        };
+    }
+    /** Sends one action and waits for the frame that carries its echo. */
+    request(action, params, timeoutMs) {
+        const socket = this.#api;
+        if (socket === undefined || socket.readyState !== WebSocket.OPEN) {
+            return Promise.resolve({ ok: false, code: 'unreachable', reason: 'the forward socket is not open' });
+        }
+        const echo = randomUUID();
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(echo);
+                resolve({ ok: false, code: 'timeout', reason: 'the api did not answer in time' });
+            }, timeoutMs ?? this.#options.timeoutMs);
+            this.#pending.set(echo, { resolve, timer });
+            socket.send(JSON.stringify({ action, params, echo }), (error) => {
+                if (error === null || error === undefined)
+                    return;
+                const pending = this.#pending.get(echo);
+                if (pending === undefined)
+                    return;
+                clearTimeout(pending.timer);
+                this.#pending.delete(echo);
+                pending.resolve({ ok: false, code: 'unreachable', reason: `the frame could not be sent: ${String(error)}` });
+            });
+        });
+    }
+    #dial() {
+        const socket = new WebSocket(this.#options.apiUrl, {
+            ...(this.#options.token === undefined ? {} : { headers: { authorization: `Bearer ${this.#options.token}` } }),
+        });
+        this.#api = socket;
+        socket.on('open', () => {
+            this.#attempt = 0;
+            if (this.#lastConnectedAt !== null)
+                this.#reconnects += 1;
+            this.#lastConnectedAt = this.#now();
+            this.#lastFrameAt = this.#now();
+            this.#apiOpen = true;
+            if (this.#options.eventUrl !== undefined)
+                this.#openEvents();
+            this.#settle();
+        });
+        socket.on('message', (raw) => this.#onFrame(socket, raw));
+        this.#watch(socket);
+        socket.on('close', (code) => this.#dropped(`the forward socket closed with ${code}`));
+        socket.on('error', (error) => {
+            this.#lastFailure = error.message;
+            this.#lastFailureAt = this.#now();
+        });
+    }
+    /** Opens the event socket only while the api socket is up; it has no life of its own. */
+    #openEvents() {
+        const url = this.#options.eventUrl;
+        if (url === undefined || this.#events !== undefined || this.#eventRetry !== undefined)
+            return;
+        if (this.#api === undefined || this.#api.readyState !== WebSocket.OPEN)
+            return;
+        const socket = new WebSocket(url, {
+            ...(this.#options.token === undefined ? {} : { headers: { authorization: `Bearer ${this.#options.token}` } }),
+        });
+        this.#events = socket;
+        socket.on('open', () => {
+            this.#eventsOpen = true;
+            this.#settle();
+        });
+        this.#watch(socket);
+        socket.on('message', (raw) => this.#onFrame(socket, raw));
+        socket.on('close', () => {
+            this.#events = undefined;
+            this.#eventsOpen = false;
+            if (!this.#closed && this.#api !== undefined) {
+                this.#eventRetry = setTimeout(() => {
+                    this.#eventRetry = undefined;
+                    this.#openEvents();
+                }, 1000);
+            }
+            this.#settle();
+        });
+        socket.on('error', (error) => {
+            this.#lastFailure = error.message;
+            this.#lastFailureAt = this.#now();
+        });
+    }
+    #clock() {
+        return this.#options.clock ?? REAL_CLOCK;
+    }
+    /** Pings this socket on a fixed beat and closes it when a pong does not come back. */
+    #watch(socket) {
+        const liveness = this.#options.liveness ?? {
+            intervalMs: ONEBOT_PING_INTERVAL_MS,
+            timeoutMs: ONEBOT_PONG_TIMEOUT_MS,
+        };
+        const clock = this.#clock();
+        let waiting;
+        let tick;
+        const schedule = () => {
+            tick = clock.setTimer(() => {
+                tick = undefined;
+                if (socket.readyState !== WebSocket.OPEN)
+                    return;
+                if (waiting === undefined) {
+                    socket.ping();
+                    waiting = clock.setTimer(() => {
+                        waiting = undefined;
+                        this.#options.warn('dsbot-channel: closed the onebot socket: its ping went unanswered');
+                        socket.close(1001, 'ping timeout');
+                    }, liveness.timeoutMs);
+                }
+                schedule();
+            }, liveness.intervalMs);
+        };
+        schedule();
+        socket.on('pong', () => {
+            if (waiting !== undefined)
+                clock.clearTimer(waiting);
+            waiting = undefined;
+        });
+        socket.on('close', () => {
+            if (tick !== undefined)
+                clock.clearTimer(tick);
+            tick = undefined;
+            if (waiting !== undefined)
+                clock.clearTimer(waiting);
+            waiting = undefined;
+        });
+    }
+    /** Online means every socket this profile needs is open; anything else says why it is not. */
+    #settle() {
+        if (this.#closed) {
+            this.#state = 'offline';
+            return;
+        }
+        const needsEvents = this.#options.eventUrl !== undefined;
+        if (this.#apiOpen && (!needsEvents || this.#eventsOpen)) {
+            this.#state = 'online';
+            return;
+        }
+        this.#state = this.#retry !== undefined || this.#eventRetry !== undefined ? 'reconnecting' : 'offline';
+    }
+    #onFrame(socket, raw) {
+        // A replaced or closed socket can still deliver a straggler; it is not ours any more.
+        if (socket !== this.#api && socket !== this.#events)
+            return;
+        const bytes = Array.isArray(raw)
+            ? Buffer.concat(raw)
+            : Buffer.isBuffer(raw)
+                ? raw
+                : Buffer.from(new Uint8Array(raw));
+        if (bytes.length > this.#options.maxFrameBytes) {
+            socket.close(1009, 'frame too large');
+            if (!this.#warnedSize) {
+                this.#warnedSize = true;
+                this.#options.warn('dsbot-channel: closed the onebot socket: a frame exceeded the size limit');
+            }
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(bytes.toString());
+        }
+        catch {
+            this.#options.onMismatch();
+            return;
+        }
+        if (frame === null || typeof frame !== 'object' || Array.isArray(frame)) {
+            this.#options.onMismatch();
+            return;
+        }
+        const record = frame;
+        if (typeof record.echo === 'string') {
+            const pending = this.#pending.get(record.echo);
+            if (pending === undefined) {
+                this.#options.onMismatch();
+                return;
+            }
+            clearTimeout(pending.timer);
+            this.#pending.delete(record.echo);
+            pending.resolve(this.#answer(record));
+            return;
+        }
+        if (record.post_type !== undefined) {
+            this.#lastFrameAt = this.#now();
+            this.#options.onEvent(record);
+            return;
+        }
+        this.#options.onMismatch();
+    }
+    #answer(frame) {
+        if (frame.status !== 'ok') {
+            const message = typeof frame.message === 'string' && frame.message.length > 0 ? frame.message : 'the api answered with a failed status';
+            return { ok: false, code: 'rejected', reason: message };
+        }
+        return { ok: true, frame };
+    }
+    #dropped(reason) {
+        this.#lastFailure = reason;
+        this.#lastFailureAt = this.#now();
+        this.#apiOpen = false;
+        this.#eventsOpen = false;
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, code: 'unreachable', reason });
+        }
+        this.#pending.clear();
+        this.#api = undefined;
+        this.#events?.close();
+        this.#events = undefined;
+        if (this.#eventRetry !== undefined)
+            clearTimeout(this.#eventRetry);
+        this.#eventRetry = undefined;
+        const retry = this.#options.reconnect;
+        if (this.#closed || retry === false) {
+            this.#state = 'offline';
+            return;
+        }
+        const base = Math.min(retry.initialMs * retry.factor ** this.#attempt, retry.maxMs);
+        const jittered = Math.round(base * (0.8 + Math.random() * 0.4));
+        this.#attempt += 1;
+        this.#state = 'reconnecting';
+        this.#retry = setTimeout(() => {
+            this.#retry = undefined;
+            if (!this.#closed)
+                this.#dial();
+        }, jittered);
+    }
+    #startBeat() {
+        const beat = this.#options.heartbeat;
+        if (beat === undefined)
+            return;
+        this.#beat = setInterval(() => {
+            if (this.#state !== 'online')
+                return;
+            if (this.#now() - this.#lastFrameAt > beat.timeoutMs) {
+                this.#options.warn('dsbot-channel: closed the onebot socket: its heartbeat went silent');
+                this.#api?.close(1001, 'heartbeat timeout');
+            }
+        }, beat.intervalMs);
+    }
+    #now() {
+        return this.#options.now?.() ?? Date.now();
+    }
+}

package/dist/ws-reverse.d.ts

@@ -0,0 +1,39 @@
+import type { Server } from 'node:http';
+import WebSocket from 'ws';
+import type { ActionAnswer, LinkClock, LivenessOptions } from './ws-forward.js';
+export interface ReverseOptions {
+    path: string;
+    token?: string | undefined;
+    selfId?: string | undefined;
+    maxFrameBytes: number;
+    /** Protocol-level ping/pong; always on in production, shortened in tests. */
+    liveness?: LivenessOptions | undefined;
+    /** Timer source for liveness; real timers unless a test hands in its own. */
+    clock?: LinkClock | undefined;
+    /** How long an action waits for its answer; the profile's `sendTimeoutMs`. */
+    timeoutMs: number;
+    heartbeat?: {
+        intervalMs: number;
+        timeoutMs: number;
+    } | undefined;
+    onEvent: (frame: Record<string, unknown>) => void;
+    onMismatch: () => void;
+    onAuthFailure: () => void;
+    onUnknownPath: () => void;
+    warn: (message: string) => void;
+    now?: (() => number) | undefined;
+}
+/**
+ * The reverse half of OneBot over WebSocket: an implementation dials us, we keep one
+ * connection per adapter, and actions travel back down it with an `echo`.
+ */
+export declare class ReverseLink {
+    #private;
+    constructor(options: ReverseOptions);
+    /** Takes over the server's upgrade events; anything not on our path is left to the caller. */
+    attach(server: Server): void;
+    close(): void;
+    connection(): WebSocket | undefined;
+    lastAuthenticatedAt(): number | null;
+    request(action: string, params: Record<string, unknown>, timeoutMs: number | undefined): Promise<ActionAnswer>;
+}

package/dist/ws-reverse.js

@@ -0,0 +1,265 @@
+import { randomUUID } from 'node:crypto';
+import WebSocket, { WebSocketServer } from 'ws';
+import { ONEBOT_PING_INTERVAL_MS, ONEBOT_PONG_TIMEOUT_MS } from './ws-forward.js';
+/**
+ * The reverse half of OneBot over WebSocket: an implementation dials us, we keep one
+ * connection per adapter, and actions travel back down it with an `echo`.
+ */
+export class ReverseLink {
+    #options;
+    #pending = new Map();
+    #server;
+    #socket;
+    #selfId;
+    #lastAuthenticatedAt = null;
+    #beat;
+    #lastFrameAt = 0;
+    #warnedSize = false;
+    #warnedNoId = false;
+    constructor(options) {
+        this.#options = options;
+        this.#server = new WebSocketServer({ noServer: true });
+    }
+    /** Takes over the server's upgrade events; anything not on our path is left to the caller. */
+    attach(server) {
+        server.on('upgrade', (request, socket, head) => {
+            void this.#upgrade(request, socket, head);
+        });
+        if (this.#options.heartbeat !== undefined && this.#options.heartbeat.intervalMs > 0) {
+            this.#startBeat();
+        }
+    }
+    close() {
+        if (this.#beat !== undefined)
+            clearInterval(this.#beat);
+        this.#beat = undefined;
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, code: 'unreachable', reason: 'the link closed while waiting for an answer' });
+        }
+        this.#pending.clear();
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.#server.close();
+    }
+    connection() {
+        return this.#socket;
+    }
+    lastAuthenticatedAt() {
+        return this.#lastAuthenticatedAt;
+    }
+    request(action, params, timeoutMs) {
+        const socket = this.#socket;
+        if (socket === undefined || socket.readyState !== WebSocket.OPEN) {
+            return Promise.resolve({ ok: false, code: 'unreachable', reason: 'no reverse socket is connected' });
+        }
+        const echo = randomUUID();
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(echo);
+                resolve({ ok: false, code: 'timeout', reason: 'the api did not answer in time' });
+            }, timeoutMs ?? this.#options.timeoutMs);
+            this.#pending.set(echo, { resolve, timer });
+            socket.send(JSON.stringify({ action, params, echo }), (error) => {
+                if (error === null || error === undefined)
+                    return;
+                const pending = this.#pending.get(echo);
+                if (pending === undefined)
+                    return;
+                clearTimeout(pending.timer);
+                this.#pending.delete(echo);
+                pending.resolve({ ok: false, code: 'unreachable', reason: `the frame could not be sent: ${String(error)}` });
+            });
+        });
+    }
+    async #upgrade(request, socket, head) {
+        const url = request.url ?? '/';
+        if (url !== this.#options.path) {
+            this.#options.onUnknownPath();
+            socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        if (!this.#authorized(request)) {
+            this.#options.onAuthFailure();
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        const claimed = headerOf(request, 'x-self-id');
+        if (this.#options.selfId !== undefined && claimed !== undefined && claimed !== this.#options.selfId) {
+            this.#options.onAuthFailure();
+            socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        if (this.#options.selfId === undefined && claimed === undefined && !this.#warnedNoId) {
+            this.#warnedNoId = true;
+            this.#options.warn('dsbot-channel: accepted an onebot reverse connection that names no X-Self-ID');
+        }
+        const previous = this.#socket;
+        if (previous !== undefined) {
+            const previousId = this.#selfId;
+            if (claimed !== undefined && previousId !== undefined && claimed !== previousId) {
+                this.#options.onAuthFailure();
+                socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            this.#options.warn('dsbot-channel: replaced the onebot reverse connection this adapter already held');
+            previous.close(1000, 'replaced by a new connection');
+        }
+        this.#server.handleUpgrade(request, socket, head, (upgraded) => {
+            this.#adopt(upgraded, claimed);
+        });
+    }
+    #adopt(socket, claimed) {
+        this.#socket = socket;
+        this.#lastAuthenticatedAt = this.#now();
+        this.#lastFrameAt = this.#now();
+        this.#selfId = claimed ?? this.#options.selfId;
+        this.#watch(socket);
+        socket.on('message', (raw) => this.#onFrame(socket, raw));
+        socket.on('close', () => {
+            if (this.#socket !== socket)
+                return;
+            this.#socket = undefined;
+            for (const [, pending] of this.#pending) {
+                clearTimeout(pending.timer);
+                pending.resolve({ ok: false, code: 'unreachable', reason: 'the reverse socket closed while waiting for an answer' });
+            }
+            this.#pending.clear();
+        });
+        socket.on('error', (error) => this.#options.warn(`dsbot-channel: onebot reverse socket: ${error.message}`));
+    }
+    #onFrame(socket, raw) {
+        // A replaced or closed socket can still deliver a straggler; it is not ours any more.
+        if (socket !== this.#socket)
+            return;
+        const bytes = Array.isArray(raw)
+            ? Buffer.concat(raw)
+            : Buffer.isBuffer(raw)
+                ? raw
+                : Buffer.from(new Uint8Array(raw));
+        if (bytes.length > this.#options.maxFrameBytes) {
+            this.#socket?.close(1009, 'frame too large');
+            if (!this.#warnedSize) {
+                this.#warnedSize = true;
+                this.#options.warn('dsbot-channel: closed the onebot socket: a frame exceeded the size limit');
+            }
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(bytes.toString());
+        }
+        catch {
+            this.#options.onMismatch();
+            return;
+        }
+        if (frame === null || typeof frame !== 'object' || Array.isArray(frame)) {
+            this.#options.onMismatch();
+            return;
+        }
+        const record = frame;
+        if (typeof record.echo === 'string') {
+            const pending = this.#pending.get(record.echo);
+            if (pending === undefined) {
+                this.#options.onMismatch();
+                return;
+            }
+            clearTimeout(pending.timer);
+            this.#pending.delete(record.echo);
+            pending.resolve(answerOf(record));
+            return;
+        }
+        if (record.post_type !== undefined) {
+            this.#lastFrameAt = this.#now();
+            this.#options.onEvent(record);
+            return;
+        }
+        this.#options.onMismatch();
+    }
+    #authorized(request) {
+        if (this.#options.token === undefined)
+            return true;
+        const header = request.headers.authorization;
+        if (typeof header !== 'string')
+            return false;
+        const match = /^(?:Bearer|Token)\s+(.+)$/i.exec(header.trim());
+        return match !== null && match[1] === this.#options.token;
+    }
+    #clock() {
+        return (this.#options.clock ?? {
+            setTimer: (callback, ms) => setTimeout(callback, ms),
+            clearTimer: (handle) => clearTimeout(handle),
+        });
+    }
+    /** Pings the reverse socket on the same fixed beat as the forward link. */
+    #watch(socket) {
+        const liveness = this.#options.liveness ?? {
+            intervalMs: ONEBOT_PING_INTERVAL_MS,
+            timeoutMs: ONEBOT_PONG_TIMEOUT_MS,
+        };
+        const clock = this.#clock();
+        let waiting;
+        let tick;
+        const schedule = () => {
+            tick = clock.setTimer(() => {
+                tick = undefined;
+                if (socket.readyState !== WebSocket.OPEN)
+                    return;
+                if (waiting === undefined) {
+                    socket.ping();
+                    waiting = clock.setTimer(() => {
+                        waiting = undefined;
+                        this.#options.warn('dsbot-channel: closed the onebot socket: its ping went unanswered');
+                        socket.close(1001, 'ping timeout');
+                    }, liveness.timeoutMs);
+                }
+                schedule();
+            }, liveness.intervalMs);
+        };
+        schedule();
+        socket.on('pong', () => {
+            if (waiting !== undefined)
+                clock.clearTimer(waiting);
+            waiting = undefined;
+        });
+        socket.on('close', () => {
+            if (tick !== undefined)
+                clock.clearTimer(tick);
+            tick = undefined;
+            if (waiting !== undefined)
+                clock.clearTimer(waiting);
+            waiting = undefined;
+        });
+    }
+    #startBeat() {
+        const beat = this.#options.heartbeat;
+        if (beat === undefined)
+            return;
+        this.#beat = setInterval(() => {
+            if (this.#socket === undefined)
+                return;
+            if (this.#now() - this.#lastFrameAt > beat.timeoutMs) {
+                this.#options.warn('dsbot-channel: closed the onebot socket: its heartbeat went silent');
+                this.#socket.close(1001, 'heartbeat timeout');
+            }
+        }, beat.intervalMs);
+    }
+    #now() {
+        return this.#options.now?.() ?? Date.now();
+    }
+}
+function headerOf(request, name) {
+    const value = request.headers[name];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function answerOf(frame) {
+    if (frame.status !== 'ok') {
+        const message = typeof frame.message === 'string' && frame.message.length > 0 ? frame.message : 'the api answered with a failed status';
+        return { ok: false, code: 'rejected', reason: message };
+    }
+    return { ok: true, frame };
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@dsbot-channel/onebot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "OneBot transport for dsbot-channel.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "cordis.patch.yml",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@dsbot-channel/core": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "~22.20.5",
+    "typescript": "~5.9.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "verify:dist": "node ../../scripts/verify-dist.mjs packages/onebot"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.