From 940b8235718df34b6ca8faba4bb97edeb9dd54ba Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Tue, 6 Oct 2026 00:11:44 +0800 Subject: [PATCH] fix(onebot): bring an account back when shutdown stalls If the previous OneBot session does not finish closing, the account now comes back online instead of staying disconnected until QQ is restarted. Fixes #509 --- packages/onebot/src/instance.ts | 14 ++++ packages/onebot/src/manager.ts | 64 ++++++++++++++++--- packages/onebot/src/network/adapter.ts | 5 ++ .../onebot/src/network/http-server-adapter.ts | 22 +++++++ .../onebot/src/network/network-manager.ts | 14 ++++ .../onebot/src/network/ws-client-adapter.ts | 15 +++++ .../onebot/src/network/ws-server-adapter.ts | 15 +++++ .../src/network/ws-server-connections.ts | 11 ++++ .../tests/http-server-force-close.test.ts | 55 ++++++++++++++++ .../onebot/tests/manager-lifecycle.test.ts | 49 ++++++++++++++ packages/websocket/src/server.ts | 17 +++++ 11 files changed, 273 insertions(+), 8 deletions(-) create mode 100644 packages/onebot/tests/http-server-force-close.test.ts diff --git a/packages/onebot/src/instance.ts b/packages/onebot/src/instance.ts index 7630c100..4871031d 100644 --- a/packages/onebot/src/instance.ts +++ b/packages/onebot/src/instance.ts @@ -273,6 +273,20 @@ export class OneBotInstance { this.ctx.musicSignUrl = globalSettings.musicSignUrl; } + /** Drop listeners and sockets without waiting for shutdown to finish. + * Used when dispose() does not settle and a replacement session must bind. */ + forceRelease(): void { + try { + this.quiesce(); + } catch (error) { + this.log.warn( + 'quiesce during forced release failed: %s', + error instanceof Error ? error.message : String(error), + ); + } + this.networkManager.forceRelease(); + } + /** Synchronously stop every ingress seam for this instance generation. * * This operation is sticky and idempotent. It is intentionally separate diff --git a/packages/onebot/src/manager.ts b/packages/onebot/src/manager.ts index 6cc82abe..70c50a5f 100644 --- a/packages/onebot/src/manager.ts +++ b/packages/onebot/src/manager.ts @@ -43,7 +43,13 @@ export interface DatabaseMigrationTask { cancel(): void; } +/** A peer that never finishes a close handshake must not keep the next + * account session offline. Ten seconds covers a normal drain. */ +const SESSION_RELEASE_DEADLINE_MS = 10_000; + export interface OneBotManagerOptions { + /** How long a retiring instance may block the replacement session. */ + sessionReleaseDeadlineMs?: number; createDatabaseMigrationTask?: (uin: string) => DatabaseMigrationTask; createInstance?: ( uin: string, @@ -91,8 +97,12 @@ export class OneBotManager { private readonly createInstance: NonNullable; private disposePromise: Promise | null = null; private disposed = false; + private readonly sessionReleaseDeadlineMs: number; constructor(options: OneBotManagerOptions = {}) { + this.sessionReleaseDeadlineMs = options.sessionReleaseDeadlineMs && options.sessionReleaseDeadlineMs > 0 + ? options.sessionReleaseDeadlineMs + : SESSION_RELEASE_DEADLINE_MS; this.createDatabaseMigrationTask = options.createDatabaseMigrationTask ?? createMessageStoreMigrationTask; this.createInstance = options.createInstance @@ -447,20 +457,58 @@ export class OneBotManager { return result; } + private async releaseRetiringInstance( + uin: string, + pending: { bridge: BridgeInterface; cancelled: boolean }, + instance: OneBotInstance, + ): Promise { + let timer: NodeJS.Timeout | undefined; + const timeout = new Promise<'timeout'>((resolve) => { + timer = setTimeout(() => resolve('timeout'), this.sessionReleaseDeadlineMs); + timer.unref?.(); + }); + // Map rejection here so a dispose() that fails after the deadline still + // has a handler. The race may already have moved on. + const releasing = instance.dispose().then( + () => 'released' as const, + (error: unknown) => ({ failed: error }), + ); + try { + const outcome = await Promise.race([releasing, timeout]); + if (outcome === 'timeout') { + log.error( + 'session release timed out; forcing adapters closed and starting the replacement: UIN=%s', + uin, + ); + try { + instance.forceRelease?.(); + } catch (error) { + log.error( + 'forced session release failed: UIN=%s: %s', + uin, + error instanceof Error ? error.message : String(error), + ); + } + return; + } + if (typeof outcome === 'object') { + // Do not leave this UIN permanently guarded by a failed handoff. A + // later session-start observation may retry the still-visible retire. + if (this.pendingStarts.get(uin) === pending) this.pendingStarts.delete(uin); + throw new InstanceLifecycleError(instance, outcome.failed); + } + } finally { + if (timer) clearTimeout(timer); + } + } + private async finishRetiringBeforeStart( uin: string, pending: { bridge: BridgeInterface; cancelled: boolean }, retiring: OneBotInstance[], ): Promise { for (const instance of retiring) { - try { - await instance.dispose(); - } catch (error) { - // Do not leave this UIN permanently guarded by a failed handoff. A - // later session-start observation may retry the still-visible retire. - if (this.pendingStarts.get(uin) === pending) this.pendingStarts.delete(uin); - throw new InstanceLifecycleError(instance, error); - } + await this.releaseRetiringInstance(uin, pending, instance); this.retirementSucceeded(instance); } if (this.pendingStarts.get(uin) !== pending) return; diff --git a/packages/onebot/src/network/adapter.ts b/packages/onebot/src/network/adapter.ts index db316403..2e9763d9 100644 --- a/packages/onebot/src/network/adapter.ts +++ b/packages/onebot/src/network/adapter.ts @@ -61,6 +61,11 @@ export abstract class IOneBotNetworkAdapter { abstract open(): void | Promise; abstract close(): void | Promise; + /** Drop sockets and listeners without waiting for a peer handshake. + * Graceful `close()` can sit forever on a half-open connection; shutdown + * uses this so the next account session can bind the same ports. */ + forceClose(): void { /* adapters that own a listener override this */ } + abstract onEvent(event: JsonObject, payload: DispatchPayload): void | Promise; /** Report live connection health for the WebUI dashboard. */ diff --git a/packages/onebot/src/network/http-server-adapter.ts b/packages/onebot/src/network/http-server-adapter.ts index 4e8daef0..5d9539cb 100644 --- a/packages/onebot/src/network/http-server-adapter.ts +++ b/packages/onebot/src/network/http-server-adapter.ts @@ -25,6 +25,7 @@ export class HttpServerAdapter extends IOneBotNetworkAdapter private server: Server | null = null; private webSocketServer: WebSocketServer | null = null; private listening = false; + private releaseForced = false; private closePromise: Promise | null = null; private acceptingActions = false; private readonly inFlightActions = new Set>(); @@ -113,6 +114,7 @@ export class HttpServerAdapter extends IOneBotNetworkAdapter try { await attempt; } catch (error) { + if (this.releaseForced) return; if (!httpReleased && server?.listening === true) { // A failed HTTP close callback cannot prove the listener was released. // The upgrade handler is still attached, so the old ingress can accept @@ -128,6 +130,26 @@ export class HttpServerAdapter extends IOneBotNetworkAdapter } } + override forceClose(): void { + this.releaseForced = true; + this.acceptingActions = false; + this.webSocketConnections.stopAccepting(); + this.isEnabled = false; + this.listening = false; + this.webSocketConnections.terminateAll(); + const webSocketServer = this.webSocketServer; + this.webSocketServer = null; + const server = this.server; + this.server = null; + if (webSocketServer) { + try { webSocketServer.destroy(); } catch { /* already dropping */ } + } + if (server) { + try { server.closeAllConnections(); } catch { /* already closed */ } + try { server.close(() => undefined); } catch { /* already closed */ } + } + } + override describeStatus(): AdapterStatus { if (!this.isEnabled) return { name: this.name, kind: 'httpServer', status: 'disabled', detail: '未启用' }; if (!this.listening) return { name: this.name, kind: 'httpServer', status: 'down', detail: '未监听(端口被占用?)' }; diff --git a/packages/onebot/src/network/network-manager.ts b/packages/onebot/src/network/network-manager.ts index 38f48f8f..0c4616b6 100644 --- a/packages/onebot/src/network/network-manager.ts +++ b/packages/onebot/src/network/network-manager.ts @@ -228,6 +228,20 @@ export class OneBotNetworkManager { return this.shutdown(); } + /** Best-effort immediate release. Does not wait for the operation queue, + * in-flight dispatches, or peer close handshakes. */ + forceRelease(): void { + this.acceptingReconciles = false; + this.acceptingEvents = false; + for (const { adapter } of this.adapters.values()) { + try { + adapter.forceClose(); + } catch (error) { + log.error('forced adapter release failed: %s', errMessage(error)); + } + } + } + emitEvent(event: JsonObject): Promise { if (!this.acceptingEvents) { return Promise.reject(new Error('network manager is shutting down; event dispatch rejected')); diff --git a/packages/onebot/src/network/ws-client-adapter.ts b/packages/onebot/src/network/ws-client-adapter.ts index 7bad4279..f5e67ffe 100644 --- a/packages/onebot/src/network/ws-client-adapter.ts +++ b/packages/onebot/src/network/ws-client-adapter.ts @@ -60,6 +60,21 @@ export class WsClientAdapter extends IOneBotNetworkAdapter { } } + override forceClose(): void { + this.explicitlyClosed = true; + this.acceptingActions = false; + this.isEnabled = false; + this.connected = false; + this.cancelReconnect(); + this.heartbeatStop?.(); + this.heartbeatStop = null; + const socket = this.socket; + this.socket = null; + if (socket) { + try { socket.terminate(); } catch { /* already gone */ } + } + } + async close(): Promise { this.explicitlyClosed = true; this.acceptingActions = false; diff --git a/packages/onebot/src/network/ws-server-adapter.ts b/packages/onebot/src/network/ws-server-adapter.ts index 2ce9b834..806d36e3 100644 --- a/packages/onebot/src/network/ws-server-adapter.ts +++ b/packages/onebot/src/network/ws-server-adapter.ts @@ -15,6 +15,7 @@ const moduleLog = createLogger('OneBot.WS-Server'); export class WsServerAdapter extends IOneBotNetworkAdapter { private wss: WebSocketServer | null = null; private listening = false; + private releaseForced = false; private closePromise: Promise | null = null; private readonly connections: WsServerConnections; @@ -66,6 +67,7 @@ export class WsServerAdapter extends IOneBotNetworkAdapter { await attempt; if (wss && this.wss === wss) this.wss = null; } catch (error) { + if (this.releaseForced) return; // A failed close callback leaves release ambiguous. Retain the server // reference and active binding state so a later shutdown can retry. this.isEnabled = wasEnabled; @@ -77,6 +79,19 @@ export class WsServerAdapter extends IOneBotNetworkAdapter { } } + override forceClose(): void { + this.releaseForced = true; + this.isEnabled = false; + this.listening = false; + this.connections.stopAccepting(); + this.connections.terminateAll(); + const wss = this.wss; + this.wss = null; + if (wss) { + try { wss.destroy(); } catch { /* already dropping */ } + } + } + override describeStatus(): AdapterStatus { if (!this.isEnabled) return { name: this.name, kind: 'wsServer', status: 'disabled', detail: '未启用' }; if (!this.listening) return { name: this.name, kind: 'wsServer', status: 'down', detail: '未监听(端口被占用?)' }; diff --git a/packages/onebot/src/network/ws-server-connections.ts b/packages/onebot/src/network/ws-server-connections.ts index a0721429..4c6857c2 100644 --- a/packages/onebot/src/network/ws-server-connections.ts +++ b/packages/onebot/src/network/ws-server-connections.ts @@ -212,6 +212,17 @@ export class WsServerConnections { this.connections.clear(); } + /** Destroy sockets immediately. A graceful close frame can leave the + * listener waiting on a peer that will never answer. */ + terminateAll(): void { + this.stopAccepting(); + for (const connection of this.connections.values()) { + connection.stopHeartbeat(); + try { connection.socket.terminate(); } catch { /* already gone */ } + } + this.connections.clear(); + } + private async handleApiMessage(socket: WebSocket, role: WsRole, raw: Buffer | string): Promise { const text = rawDataToString(raw); if (!text) { diff --git a/packages/onebot/tests/http-server-force-close.test.ts b/packages/onebot/tests/http-server-force-close.test.ts new file mode 100644 index 00000000..d0b04e9e --- /dev/null +++ b/packages/onebot/tests/http-server-force-close.test.ts @@ -0,0 +1,55 @@ +import { once } from 'node:events'; +import http from 'node:http'; +import net from 'node:net'; +import type { AddressInfo } from 'node:net'; +import { describe, expect, it } from 'vitest'; +import type { NetworkAdapterContext } from '../src/network/adapter'; +import { HttpServerAdapter } from '../src/network/http-server-adapter'; +import type { HttpServerNetwork } from '../src/types'; + +describe('HttpServerAdapter forced release', () => { + it('drops a held connection so the port can be bound again', async () => { + const ctx = { + uin: '10001', + api: { handle: async () => ({ status: 'ok', retcode: 0, data: null }), isStreamAction: () => false }, + buildLifecycleEvent: () => ({}), + buildHeartbeatEvent: () => ({}), + } as unknown as NetworkAdapterContext; + const config: HttpServerNetwork = { + name: 'http-force-close', + host: '127.0.0.1', + port: 0, + path: '/', + messageFormat: 'array', + reportSelfMessage: false, + }; + const adapter = new HttpServerAdapter(config.name, config, ctx); + let socket: net.Socket | null = null; + try { + await adapter.open(); + const server = (adapter as unknown as { server: http.Server | null }).server; + expect(server).not.toBeNull(); + const port = (server!.address() as AddressInfo).port; + socket = net.connect({ host: '127.0.0.1', port }); + await once(socket, 'connect'); + + adapter.forceClose(); + + expect(server!.listening).toBe(false); + await expect(listenOn(port)).resolves.toBeUndefined(); + } finally { + socket?.destroy(); + await adapter.close(); + } + }); +}); + +function listenOn(port: number): Promise { + const server = net.createServer(); + return new Promise((resolve, reject) => { + server.once('error', reject); + server.listen(port, '127.0.0.1', () => { + server.close(() => resolve()); + }); + }); +} diff --git a/packages/onebot/tests/manager-lifecycle.test.ts b/packages/onebot/tests/manager-lifecycle.test.ts index fbd68ec7..7f62c054 100644 --- a/packages/onebot/tests/manager-lifecycle.test.ts +++ b/packages/onebot/tests/manager-lifecycle.test.ts @@ -569,6 +569,55 @@ describe('OneBotManager lifecycle failure accounting', () => { expect((manager as unknown as { pendingStarts: Map }).pendingStarts.has('10001')).toBe(false); }); + it('starts the replacement account when release never finishes', async () => { + const originalCwd = process.cwd(); + const root = mkdtempSync(path.join(tmpdir(), 'snowluma-manager-release-')); + process.chdir(root); + const forceRelease = vi.fn(); + const old = { + ...fakeInstance('10001', () => new Promise(() => undefined)), + forceRelease, + } as unknown as OneBotInstance; + const replacement = { + ...fakeInstance('10001', async () => undefined), + waitUntilNetworkReady: vi.fn(async () => ({ applied: true, statuses: [], errors: [] })), + startLoginHistorySync: vi.fn(), + startGroupRequestPolling: vi.fn(), + } as unknown as OneBotInstance; + let created = false; + const manager = new OneBotManager({ + sessionReleaseDeadlineMs: 30, + createDatabaseMigrationTask: () => ({ + beginMigration: vi.fn(), + cancel: vi.fn(), + start: (next) => { next.onReady(); }, + }), + createInstance: () => { + created = true; + return replacement; + }, + }); + const internals = manager as unknown as { + retiringInstances: Set; + onSessionStarted(uin: string, bridge: never): void; + pendingStarts: Map; + }; + try { + internals.retiringInstances.add(old); + internals.onSessionStarted('10001', fakeBridge() as never); + await vi.waitFor(() => { + expect(created).toBe(true); + }); + expect(forceRelease).toHaveBeenCalledOnce(); + expect(manager.getInstance('10001')).toBe(replacement); + expect(internals.pendingStarts.has('10001')).toBe(false); + expect(internals.retiringInstances.has(old)).toBe(false); + } finally { + process.chdir(originalCwd); + rmSync(root, { recursive: true, force: true }); + } + }); + it('allows a later same-UIN start observation to retry a failed handoff', async () => { const manager = new OneBotManager(); let attempts = 0; diff --git a/packages/websocket/src/server.ts b/packages/websocket/src/server.ts index a6a0defa..7c4a211b 100644 --- a/packages/websocket/src/server.ts +++ b/packages/websocket/src/server.ts @@ -282,4 +282,21 @@ export class WebSocketServer extends EventEmitter { setImmediate(cb); } } + + /** Destroy clients and, when this server owns the HTTP listener, that + * listener too. An external HTTP server is left to its owner. */ + destroy(): void { + for (const ws of this.clients) { + try { ws.terminate(); } catch { /* noop */ } + } + if (this._externalServer && this._upgradeHandler) { + this._externalServer.removeListener('upgrade', this._upgradeHandler); + this._upgradeHandler = null; + } + if (this._server) { + try { this._server.closeAllConnections(); } catch { /* noop */ } + try { this._server.close(() => undefined); } catch { /* noop */ } + this._server = null; + } + } }