Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

39.1 KB
Raw Blame
/**
 * The QQ bot open-platform (API v2) seam: the app-access-token exchange, the two message
 * sends, and the WebSocket gateway, behind an injectable transport so unit tests
 * substitute a fake and never open a socket to Tencent. QQ publishes no Node SDK this
 * product can take (the one Tencent ships for the scan flow is `UNLICENSED`), so the
 * production adapter is plain fetch plus undici's WebSocket — both of which resolve
 * undici's global dispatcher per call, which is how they inherit the admin proxy setting
 * (net/proxy.ts) without asking for it.
 *
 * Wire types below mirror the platform's JSON verbatim (snake_case): the transport does
 * not reshape payloads, so a test fake constructs exactly what the real API returns.
 *
 * Two properties of this platform shape the whole seam, and every caller downstream
 * inherits them:
 *
 *   1. AUTH IS A SHORT-LIVED TOKEN, NOT THE CREDENTIAL. Every OpenAPI call carries
 *      `Authorization: QQBot <access_token>`, and that token lasts at most 7200 seconds.
 *      The credential pair (App ID + App Secret) only ever buys a new one. So the client
 *      owns a token cache with early refresh rather than making callers think about it —
 *      and the platform documents that a request inside the last 60 seconds of validity
 *      returns a NEW token while the old one keeps working for those 60 seconds, so
 *      refreshing early can never strand a request that is already in flight.
 *   2. THE GATEWAY IS THE ONLY WAY IN FOR A LOCAL SERVER. QQ also offers an HTTP callback
 *      mode, but it needs a publicly reachable HTTPS URL on one of four ports (80, 443,
 *      8080, 8443) plus an Ed25519 challenge response — the same class of constraint that
 *      made Feishu a long connection and Telegram a long poll. So this seam opens a
 *      WebSocket, identifies with the group-and-C2C intent, heartbeats, and resumes.
 *
 * A THIRD property does not live here but is worth naming from the transport, because it
 * is the reason `QQSendArgs` has no "just send" shape: QQ has no free outbound. Every send
 * this product makes is a PASSIVE REPLY carrying the `msg_id` of an inbound message, and
 * that is a budget — see qq-connector.ts, which owns the accounting.
 */
import { WebSocket } from "undici";
import { MessagingChannelError, httpStatusRecovers } from "./connector.js";

/**
 * QQ bot OpenAPI host — both the token endpoint and the resource endpoints. Deliberately
 * not configurable: API v2 has no separate sandbox host (a sandbox in v2 is a whitelist of
 * groups and accounts configured in the console, served by this same host), so there is
 * nothing for a domain field to switch between, unlike Feishu's Feishu/Lark split.
 */
export const QQ_API_BASE = "https://api.bot.qq.com";

/**
 * The one intent this bot subscribes: `GROUP_AND_C2C_EVENT` (1 << 25). It carries the two
 * events this product reads — `C2C_MESSAGE_CREATE` (a single chat with the bot) and
 * `GROUP_AT_MESSAGE_CREATE` (a group message that @-mentions it) — along with eight
 * others (friend add/remove, the push-permission toggles, robot add/remove) that
 * normalizeDispatch drops.
 *
 * Nothing else is subscribed. Guild intents a bot has no permission for are refused at
 * identify with close code 4014, and this product has no use for them.
 */
export const QQ_INTENT_GROUP_AND_C2C = 1 << 25;

/** One credential set (a binding's stored values, or a test request's draft). */
export interface QQCredentials {
  /** The bot's App ID — also the channel-scoped account identity; never secret. */
  appId: string;
  /** The App Secret from the developer console (the platform's `clientSecret`). */
  appSecret: string;
}

/**
 * `POST /app/getAppAccessToken` result. `expires_in` is seconds and never exceeds 7200 —
 * typed as a union because the platform's own response example returns it quoted while its
 * field table calls it a number.
 */
export interface QQAppAccessToken {
  access_token: string;
  expires_in: number | string;
}

/** `GET /gateway` result: the WebSocket URL to connect to. */
export interface QQGatewayInfo {
  url: string;
}

/**
 * Which side of the platform a chat lives on. It selects the send endpoint AND the passive
 * reply budget, which is not the same on both (see qq-connector.ts).
 */
export type QQChatKind = "c2c" | "group";

/**
 * One inbound message event, reduced to what the connector consumes. `openid` is the
 * conversation's own id — the user's for a single chat, the group's for a group — which is
 * also the send endpoint's path segment, so it doubles as the chat id.
 */
export interface QQInboundEvent {
  kind: QQChatKind;
  /** `author.user_openid` for a single chat, `group_openid` for a group. */
  openid: string;
  /** The platform's message id (`d.id`): the passive reply's `msg_id`, and the dedupe key. */
  messageId: string;
  /**
   * Message text, already trimmed. The platform strips the `@bot` prefix from a group
   * message's content itself but leaves the whitespace it sat in, so the trim is the
   * connector's half of that contract.
   */
  content: string;
  /** Sender openid (`author.user_openid` in a single chat, `author.member_openid` in a group). */
  senderOpenid?: string;
}

/**
 * One outbound send. Always a PASSIVE reply: `msgId` names the inbound message being
 * answered, and `msgSeq` orders the replies to it. There is no push shape here on purpose —
 * see the module doc.
 */
export interface QQSendArgs {
  kind: QQChatKind;
  openid: string;
  /**
   * The message body. Sent as `msg_type: 0` plain text, unless `markdown` is set — the
   * platform requires `content` to be EMPTY once a markdown object rides along, so the two
   * are alternatives rather than a body plus a rendering hint.
   */
  content: string;
  /**
   * QQ Markdown (see qq-markdown.ts), sent as `msg_type: 2` with `markdown.content`.
   * Free-form markdown is open to every bot in single and group chats; the deprecated
   * template fields are deliberately not used.
   */
  markdown?: string;
  /** The inbound message being answered — what makes this a passive reply rather than a push. */
  msgId: string;
  /**
   * Sequence among the replies to `msgId`, 1-based (the platform's own default is 1).
   * A repeated `msg_id` + `msg_seq` pair is REJECTED (40054005 消息被去重), not ignored, so
   * this must genuinely increment per reply.
   */
  msgSeq: number;
}

/** OpenAPI half of the seam, bound to one credential pair. Every method throws on failure with a readable reason. */
export interface QQBotClient {
  /**
   * Credential check: exchanges the App ID / App Secret for an access token. The platform
   * has no cheaper "who am I" call — and no call at all that identifies the bot by name —
   * so the exchange itself is the probe and there is no account label to surface.
   */
  checkCredentials(): Promise<void>;
  /** Sends one passive text reply into a single chat or a group. */
  sendMessage(args: QQSendArgs): Promise<void>;
}

export interface QQGatewayHandlers {
  onMessage(evt: QQInboundEvent): void | Promise<void>;
  /** The gateway completed a handshake (fires again after an automatic reconnect). */
  onReady?(): void;
  /** The gateway failed; reported once per outage, as the Telegram poll loop does. */
  onError?(err: unknown): void;
}

/** A live gateway session; `close` ends it and stops reconnecting (idempotent). */
export interface QQGatewayConnection {
  close(): void;
}

/** Factory the QQ connector is built over: the production adapter, or a test fake. */
export interface QQTransport {
  createClient(creds: QQCredentials): QQBotClient;
  /**
   * Opens the gateway for one bot. Resolves as soon as the session is constructed and
   * connecting — lifecycle arrives via the handlers (`onReady` / `onError`), because the
   * adapter reconnects on its own and a single promise cannot carry a lifecycle.
   */
  openGateway(creds: QQCredentials, handlers: QQGatewayHandlers): Promise<QQGatewayConnection>;
}

// ---------------------------------------------------------------------------
// Production adapter over fetch + undici's WebSocket
// ---------------------------------------------------------------------------

/** Overall per-request deadline for the OpenAPI calls (token exchange, gateway lookup, sends). */
const CALL_TIMEOUT_MS = 15_000;

/**
 * Refresh the access token this many seconds before it expires. The platform keeps the
 * previous token valid for exactly this long while it issues a replacement, so the margin
 * is the documented overlap rather than a guess.
 */
const TOKEN_REFRESH_MARGIN_SEC = 60;

/** Gateway opcodes (the subset this adapter speaks; the platform reuses Discord's numbering). */
const OP = {
  DISPATCH: 0,
  HEARTBEAT: 1,
  IDENTIFY: 2,
  RESUME: 6,
  RECONNECT: 7,
  INVALID_SESSION: 9,
  HELLO: 10,
  HEARTBEAT_ACK: 11,
} as const;

/**
 * Close codes that mean "this session handle is dead, identify fresh next time" (4006
 * invalid session id, 4007 sequence error, and the 4900-4913 internal band the platform's
 * own guidance says to re-identify after). 4009 — connection expired — is the one drop
 * that stays resumable, which is why it is absent here.
 */
function closeCodeInvalidatesSession(code: number): boolean {
  return code === 4006 || code === 4007 || (code >= 4900 && code <= 4913);
}

/**
 * Close codes there is no point retrying: the bot is delisted (4914, connectable only in
 * the console's sandbox whitelist) or banned (4915). Reconnecting on a one-minute ceiling
 * forever would just log the same refusal until someone looks.
 */
function closeCodeIsFatal(code: number): boolean {
  return code === 4914 || code === 4915;
}

/**
 * Close codes the next handshake clears on its own, with nothing for anyone to change.
 *
 * 4009 is the platform expiring a long-lived connection — its documented handling is
 * "reconnect", and it is the one drop that stays RESUMABLE (see closeCodeInvalidatesSession),
 * so the next HELLO replays from `seq` and no inbound event is missed. 4900-4913 is the
 * platform's own internal-error band, whose documented handling is the fresh identify this
 * session already performs; nothing an operator holds could have prevented it or can speed it
 * up. The transport's own closes join them: 1006 is the socket dropping with no close frame at
 * all — the network, not the platform — and 1001 and 1011-1014 are a server or a proxy going
 * away, failing, restarting or losing its upstream. None of those ask anything of anyone.
 *
 * Deliberately narrower than "reconnects": nearly every close reconnects here, including the
 * ones that will never come up again. A rejected token (4004), an intent the bot was never
 * granted (4014) and a delisted or banned bot (4914 / 4915) all retry just as eagerly and
 * repeat the identical refusal until a human changes a credential or a console setting. 4006
 * and 4007 stay out too: they say the session state this client presented was refused, which
 * a fresh identify papers over — at the cost of whatever arrived during the gap — and which,
 * repeating, points at this client's own sequence bookkeeping.
 */
function closeCodeIsRoutine(code: number): boolean {
  return (
    code === 4009 ||
    (code >= 4900 && code <= 4913) ||
    code === 1001 ||
    code === 1006 ||
    (code >= 1011 && code <= 1014)
  );
}

/**
 * A connection the platform itself closed, carrying the code it closed with.
 *
 * The gateway's own kind of MessagingChannelError, so the error recorder can tell a socket the
 * gateway cycled from one that is down until someone acts, WITHOUT reading the message text: a
 * wording match would tie the dashboard's "needs a human" count to how a platform phrases
 * itself. error-kind.ts reads `recovers` and nothing else.
 *
 * `recovers` carries the answer rather than the raw code because the reconnect decision is
 * protocol state this file already owns and nothing above it holds (see GatewaySession). It
 * is true only where the next handshake restores the connection with nothing changed
 * (closeCodeIsRoutine), and false where retrying repeats the same refusal or the session has
 * stopped for good.
 *
 * It lives beside the gateway rather than in a shared module because the gateway is the only
 * connection in this product that learns WHY it was closed: the Feishu long connection is the
 * vendor SDK's own reconnect loop and surfaces a plain failure, and Telegram's transport is a
 * long poll with no connection to close.
 */
export class MessagingConnectionClosedError extends MessagingChannelError {
  constructor(
    message: string,
    /** The platform's own WebSocket close code. */
    readonly closeCode: number,
    /** Whether the next handshake brings the connection back with nothing changed. */
    recovers: boolean,
  ) {
    super(message, recovers);
    this.name = "MessagingConnectionClosedError";
  }
}

/**
 * How long a socket has to finish its handshake before it is dropped and retried.
 *
 * A socket that opened and then went quiet — a proxy that accepted the upgrade and
 * blackholed everything after it — never reaches HELLO, never starts a heartbeat, and never
 * fires `close`. Nothing else in this session would notice, so the binding would sit at
 * `connected` receiving nothing, forever. Generous next to a handshake that normally takes
 * one round trip.
 */
export const QQ_HANDSHAKE_TIMEOUT_MS = 30_000;

/**
 * The slice of the WebSocket API this session uses.
 *
 * Named as a type so a test can drive the handshake, the heartbeat and every close code
 * without opening a socket. It is not a module mock on purpose: the server suite shares one
 * module registry across files (see vitest.config.ts), so `vi.mock` is not available to it.
 */
export interface QQSocket {
  readonly readyState: number;
  addEventListener(type: "message", fn: (evt: { data: unknown }) => void): void;
  addEventListener(type: "error", fn: () => void): void;
  addEventListener(type: "close", fn: (evt: { code: number }) => void): void;
  send(data: string): void;
  close(): void;
}

/** Gateway reconnect backoff: 1s doubling to a 60s ceiling (a revoked secret retries once a minute). */
function defaultGatewayRetryMs(failures: number): number {
  return Math.min(1000 * 2 ** (failures - 1), 60_000);
}

/**
 * Readable failure text out of fetch's throw shapes. Nothing here may echo a request body:
 * the token exchange's carries the App Secret.
 */
function fetchErrorText(err: unknown): string {
  if (err instanceof Error) {
    if (err.name === "TimeoutError" || err.name === "AbortError") return "request timed out";
    const cause = (err as { cause?: unknown }).cause;
    if (cause instanceof Error && cause.message !== "") return cause.message;
    return err.message;
  }
  return String(err);
}

/**
 * The failure envelope. The OpenAPI answers `{err_code, message, trace_id}` and the token
 * endpoint answers `{code, message}` — two different families, so both are read and
 * `err_code` wins where the platform sends both.
 */
interface QQErrorBody {
  code?: number;
  err_code?: number;
  message?: string;
}

/**
 * The send failures whose own wording names an internal rule instead of the thing the
 * operator has to change. Everything else passes through untouched.
 *
 * 40034128 is the one this product can genuinely provoke on its own — the platform folds
 * "the reply window closed" and "the reply count ran out" into a single code, so the text
 * has to name both. qq-connector.ts exists largely to keep it from ever being returned.
 */
/**
 * The send refusals that say nothing about the message BODY: the reply window closed, the
 * budget ran out, the user turned bots off. Re-sending the same message in another form
 * cannot help, and on this channel the attempt costs a slot out of four — so the
 * markdown-to-text fallback stops at these rather than spending one to learn nothing.
 */
export const QQ_BODY_INDEPENDENT_SEND_CODES: ReadonlySet<number> = new Set([
  40034128, 40034005, 304103, 40034024, 40034105, 40054013,
]);

export function qqSendErrorText(errCode: number | undefined, message: string): string {
  if (errCode === 40034128) {
    return `${message} — QQ allows only a few replies to one message, within minutes of it`;
  }
  if (errCode === 40034005 || errCode === 304103 || errCode === 40034024) {
    return `${message} — the QQ message being replied to has expired`;
  }
  if (errCode === 40034105 || errCode === 40054013) {
    return `${message} — this QQ user has turned off messages from bots`;
  }
  return message;
}

/**
 * A call the platform itself REFUSED, carrying the `err_code` it refused with.
 *
 * Its own class for the reason telegram-api's TelegramApiError is one: a refusal and a
 * request that never completed are the same outcome and opposite facts. The platform
 * answered, so nothing was delivered and the same message may safely be sent again in
 * another form — which is what the markdown-to-text fallback does. A timeout or a reset
 * carries no code, stays out of this class, and must never be retried: it may already have been
 * delivered, and on this channel a retry also spends another slot of a four-reply budget.
 *
 * `recovers` is read off the HTTP status the refusal came with (see httpStatusRecovers): the
 * platform's own codes name rules and budgets, not whether the next send meets the same no.
 */
export class QQApiError extends MessagingChannelError {
  constructor(
    message: string,
    readonly code: number | undefined,
    recovers = false,
  ) {
    super(message, recovers);
    this.name = "QQApiError";
  }
}

export interface QQTransportOpts {
  /** Test hook: gateway reconnect backoff (default: exponential, 1s → 60s). */
  gatewayRetryMs?: (failures: number) => number;
  /** Test hook: the socket the gateway session runs on (default: undici's WebSocket). */
  createSocket?: (url: string) => QQSocket;
  /** Test hook: the handshake deadline (default QQ_HANDSHAKE_TIMEOUT_MS). */
  handshakeTimeoutMs?: number;
}

/** One bot's access token with early refresh, shared by the OpenAPI client and the gateway identify. */
interface TokenCache {
  get(): Promise<string>;
  invalidate(): void;
}

function tokenCacheOf(creds: QQCredentials): TokenCache {
  let token = "";
  let expiresAtMs = 0;
  let inFlight: Promise<string> | null = null;

  const exchange = async (): Promise<string> => {
    let res: Response;
    try {
      res = await fetch(`${QQ_API_BASE}/app/getAppAccessToken`, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ appId: creds.appId, clientSecret: creds.appSecret }),
        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
      });
    } catch (err) {
      // The exchange never completed, so nothing was refused: the next one may well go through.
      throw new MessagingChannelError(`Token exchange failed: ${fetchErrorText(err)}`, true);
    }
    const body = (await res.json().catch(() => null)) as (QQAppAccessToken & QQErrorBody) | null;
    if (body === null || typeof body.access_token !== "string" || body.access_token === "") {
      const detail = body?.message ?? `HTTP ${res.status}`;
      const code = body?.code ?? body?.err_code;
      throw new MessagingChannelError(
        `Token exchange failed: ${detail}${code !== undefined ? ` (code ${code})` : ""}`,
        httpStatusRecovers(res.status),
      );
    }
    const ttl = Number(body.expires_in);
    // A missing or nonsensical TTL falls back to the platform's own ceiling rather than
    // caching forever on a malformed response.
    const seconds = Number.isFinite(ttl) && ttl > 0 ? Math.min(ttl, 7200) : 7200;
    token = body.access_token;
    expiresAtMs = Date.now() + Math.max(seconds - TOKEN_REFRESH_MARGIN_SEC, 1) * 1000;
    return token;
  };

  return {
    async get(): Promise<string> {
      if (token !== "" && Date.now() < expiresAtMs) return token;
      // Collapse concurrent refreshes: a burst of sends must not each buy a token, which
      // the endpoint rate-limits (100001 Too many requests).
      inFlight ??= exchange().finally(() => {
        inFlight = null;
      });
      return inFlight;
    },
    invalidate(): void {
      expiresAtMs = 0;
    },
  };
}

/** The production client, plus the token cache the gateway session needs for its identify. */
interface ProductionClient extends QQBotClient {
  tokens: TokenCache;
}

function createProductionClient(creds: QQCredentials): ProductionClient {
  const tokens = tokenCacheOf(creds);

  const post = async (path: string, payload: Record<string, unknown>, retry = true) => {
    const token = await tokens.get();
    let res: Response;
    try {
      res = await fetch(`${QQ_API_BASE}${path}`, {
        method: "POST",
        headers: { "content-type": "application/json", authorization: `QQBot ${token}` },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
      });
    } catch (err) {
      throw new MessagingChannelError(`Message send failed: ${fetchErrorText(err)}`, true);
    }
    if (res.status >= 200 && res.status < 300) return;
    const body = (await res.json().catch(() => null)) as QQErrorBody | null;
    if (res.status === 401) {
      // The cached token died before its stated expiry — a secret rotated in the console,
      // or a clock further off than the refresh margin covers. Drop it and replay ONCE, so
      // a genuinely revoked credential still surfaces as an error instead of looping.
      tokens.invalidate();
      if (retry) return post(path, payload, false);
    }
    const errCode = body?.err_code ?? body?.code;
    const detail = qqSendErrorText(errCode, body?.message ?? `HTTP ${res.status}`);
    // The platform answered, whatever it said: a refused request delivered nothing, which is
    // what makes another form of the same message safe to send (see QQApiError).
    throw new QQApiError(
      `Message send failed: ${detail}${errCode !== undefined ? ` (code ${errCode})` : ""}`,
      errCode,
      httpStatusRecovers(res.status),
    );
  };

  return {
    tokens,
    async checkCredentials(): Promise<void> {
      await tokens.get();
    },
    sendMessage(args: QQSendArgs): Promise<void> {
      const path =
        args.kind === "group"
          ? `/v2/groups/${encodeURIComponent(args.openid)}/messages`
          : `/v2/users/${encodeURIComponent(args.openid)}/messages`;
      const markdown = args.markdown;
      return post(path, {
        // "传了 markdown 后此字段必须为空" — the platform rejects a payload carrying both.
        content: markdown === undefined ? args.content : "",
        // 0 = plain text, 2 = markdown. Rich media (7) needs a publicly reachable URL for the
        // bytes, which is why this channel refuses outbound files (see qq-connector).
        msg_type: markdown === undefined ? 0 : 2,
        ...(markdown !== undefined ? { markdown: { content: markdown } } : {}),
        msg_id: args.msgId,
        msg_seq: args.msgSeq,
      });
    },
  };
}

/** The production factory: plain HTTPS for the OpenAPI, undici's WebSocket for the gateway. */
export function createQQTransport(opts: QQTransportOpts = {}): QQTransport {
  const retryMs = opts.gatewayRetryMs ?? defaultGatewayRetryMs;
  const createSocket = opts.createSocket ?? ((url: string): QQSocket => new WebSocket(url));
  const handshakeMs = opts.handshakeTimeoutMs ?? QQ_HANDSHAKE_TIMEOUT_MS;
  return {
    createClient: (creds) => createProductionClient(creds),
    async openGateway(creds, handlers): Promise<QQGatewayConnection> {
      const session = new GatewaySession(createProductionClient(creds), handlers, {
        retryMs,
        createSocket,
        handshakeMs,
      });
      session.start();
      return { close: () => session.close() };
    },
  };
}

/**
 * One gateway session with its own reconnect loop.
 *
 * Every step of the handshake is the platform's, and each earns its line: HELLO carries the
 * heartbeat interval in milliseconds (a socket that stops sending them is closed), IDENTIFY
 * authenticates with the same `QQBot <token>` string the OpenAPI takes (a still-published
 * doc page describes a `Bot <appid>.<token>` form — that is the retired v1 scheme and it is
 * rejected), READY hands back a `session_id` that RESUME replays a dropped connection from,
 * and every DISPATCH's `s` is the sequence RESUME rewinds to — so `seq` is tracked from the
 * first frame, not from the first message.
 *
 * The reconnect decision is protocol state nobody above this file holds, which is why it
 * lives here: a close is resumable unless its code says the session handle is dead (4006 /
 * 4007 / the internal band), an INVALID_SESSION says the resume was refused, and a
 * RECONNECT is the platform asking for the same round trip while keeping the session
 * resumable. Two codes end the session for good — a delisted or banned bot will not connect
 * however long it is retried.
 *
 * The gateway URL is fetched once and reused across reconnects: `GET /gateway` is rate
 * limited to 2 requests a minute, which a reconnect storm would spend on nothing.
 *
 * Two watchdogs bound a session that is neither speaking nor closing, because a socket that
 * stops carrying traffic without a FIN — a NAT or proxy drop, and this path deliberately
 * inherits the admin proxy dispatcher — keeps `readyState` OPEN and fires no `close` at
 * all: one deadline on the handshake (QQ_HANDSHAKE_TIMEOUT_MS), and one on the heartbeat,
 * which the platform acknowledges with HEARTBEAT_ACK and which is therefore a round trip
 * rather than a write. Either drops the socket into the same fail-and-back-off path a real
 * close takes — and drives it directly rather than waiting on a `close` event a half-open
 * socket may never produce.
 *
 * What surfaces upward is only the outcome: `onReady` per successful handshake, `onError`
 * once per outage — the same contract the Feishu long connection and the Telegram poll loop
 * report, so the bridge's status means the same thing on all three channels.
 */
class GatewaySession {
  private ws: QQSocket | null = null;
  private closed = false;
  private failures = 0;
  /** The resume handle from READY; null until the first successful identify. */
  private sessionId: string | null = null;
  /** Latest dispatch sequence (the heartbeat's `d`, and the resume's). */
  private seq: number | null = null;
  /** Cached `GET /gateway` URL (see the class doc: 2 QPM). */
  private gatewayUrl: string | null = null;
  private heartbeat: ReturnType<typeof setInterval> | null = null;
  private retryTimer: ReturnType<typeof setTimeout> | null = null;
  /** Armed with the socket, disarmed by the handshake: see QQ_HANDSHAKE_TIMEOUT_MS. */
  private handshakeTimer: ReturnType<typeof setTimeout> | null = null;
  /** When the last HEARTBEAT_ACK arrived, against which the heartbeat tick measures silence. */
  private lastAckAt = 0;
  /**
   * What this outage has already reported; the retries stay quiet until a handshake succeeds.
   *
   * One report per outage is what keeps a backoff loop from filling the error table. A routine
   * failure — one whose MessagingChannelError says it recovers — is filed `expected`, though, so
   * letting it claim the slot outright would silence the outage behind it: a socket the platform
   * expires at 4009 followed by an auth refusal on every retry would leave the dashboard reading
   * zero defects for a binding that is down until a person acts. So a routine report is spent
   * once more — by the first failure that is not routine — and only then does the outage go
   * quiet.
   */
  private reported: "none" | "routine" | "defect" = "none";

  constructor(
    private readonly client: ProductionClient,
    private readonly handlers: QQGatewayHandlers,
    private readonly opts: {
      retryMs: (failures: number) => number;
      createSocket: (url: string) => QQSocket;
      handshakeMs: number;
    },
  ) {}

  start(): void {
    void this.connect();
  }

  close(): void {
    this.closed = true;
    this.stopHeartbeat();
    this.disarmHandshake();
    if (this.retryTimer !== null) clearTimeout(this.retryTimer);
    this.retryTimer = null;
    const ws = this.ws;
    this.ws = null;
    try {
      ws?.close();
    } catch {
      // A socket already closing throws on some paths; the session is going away regardless.
    }
  }

  private async connect(): Promise<void> {
    if (this.closed) return;
    try {
      const token = await this.client.tokens.get();
      if (this.closed) return;
      this.gatewayUrl ??= await this.fetchGatewayUrl(token);
      if (this.closed) return;
      this.openSocket(this.gatewayUrl, token);
    } catch (err) {
      this.fail(err);
    }
  }

  private async fetchGatewayUrl(token: string): Promise<string> {
    let res: Response;
    try {
      res = await fetch(`${QQ_API_BASE}/gateway`, {
        headers: { authorization: `QQBot ${token}` },
        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
      });
    } catch (err) {
      throw new MessagingChannelError(`Gateway lookup failed: ${fetchErrorText(err)}`, true);
    }
    const body = (await res.json().catch(() => null)) as (QQGatewayInfo & QQErrorBody) | null;
    if (body === null || typeof body.url !== "string" || body.url === "") {
      throw new MessagingChannelError(
        `Gateway lookup failed: ${body?.message ?? `HTTP ${res.status}`}`,
        httpStatusRecovers(res.status),
      );
    }
    return body.url;
  }

  private openSocket(url: string, token: string): void {
    const ws = this.opts.createSocket(url);
    this.ws = ws;
    // The socket is open; nothing says the far end is listening. This is the deadline for
    // it to prove it, and it covers both silences: no HELLO, and an IDENTIFY nobody answers.
    this.handshakeTimer = setTimeout(() => {
      this.handshakeTimer = null;
      this.dropSocket(ws, new MessagingChannelError("gateway handshake did not complete", true));
    }, this.opts.handshakeMs);
    this.handshakeTimer.unref?.();
    ws.addEventListener("message", (evt) => {
      if (this.ws !== ws) return;
      this.onFrame(String(evt.data), token);
    });
    // A WebSocket `error` event carries no usable detail and is always followed by `close`,
    // which is where the outage is reported; this listener exists so it is not unhandled.
    ws.addEventListener("error", () => {});
    ws.addEventListener("close", (evt) => {
      if (this.ws !== ws) return;
      this.stopHeartbeat();
      this.disarmHandshake();
      this.ws = null;
      if (closeCodeInvalidatesSession(evt.code)) {
        this.sessionId = null;
        this.seq = null;
      }
      if (closeCodeIsFatal(evt.code)) {
        this.closed = true;
        this.handlers.onError?.(
          new MessagingConnectionClosedError(
            `gateway refused this bot (close code ${evt.code}) — it is delisted or banned on the QQ open platform`,
            evt.code,
            false,
          ),
        );
        return;
      }
      this.fail(
        new MessagingConnectionClosedError(
          `gateway connection closed (code ${evt.code})`,
          evt.code,
          closeCodeIsRoutine(evt.code),
        ),
      );
    });
  }

  private onFrame(raw: string, token: string): void {
    let frame: QQGatewayFrame;
    try {
      frame = JSON.parse(raw) as QQGatewayFrame;
    } catch {
      return;
    }
    if (typeof frame.s === "number") this.seq = frame.s;
    switch (frame.op) {
      case OP.HELLO: {
        const interval = (frame.d as { heartbeat_interval?: number } | undefined)
          ?.heartbeat_interval;
        this.startHeartbeat(typeof interval === "number" && interval > 0 ? interval : 45_000);
        // A session handle from a previous connection makes this a resume; otherwise identify.
        this.send(
          this.sessionId !== null
            ? {
                op: OP.RESUME,
                d: { token: `QQBot ${token}`, session_id: this.sessionId, seq: this.seq ?? 0 },
              }
            : {
                op: OP.IDENTIFY,
                d: {
                  token: `QQBot ${token}`,
                  intents: QQ_INTENT_GROUP_AND_C2C,
                  // Unsharded: this product runs one connection per bot.
                  shard: [0, 1],
                  // Documented as having no effect today; sent empty rather than inventing values.
                  properties: {},
                },
              },
        );
        return;
      }
      case OP.DISPATCH:
        this.onDispatch(frame);
        return;
      case OP.INVALID_SESSION:
        // The resume was refused: forget the handle so the next handshake identifies fresh.
        this.sessionId = null;
        this.seq = null;
        this.ws?.close();
        return;
      case OP.RECONNECT: {
        // Politely asked to reconnect; the session stays resumable. The drop is driven from
        // here, with its reason, because the `close` the request leads to carries no code
        // that says it was asked for — the refused resume above closes the same way.
        const ws = this.ws;
        if (ws !== null) {
          this.dropSocket(ws, new MessagingChannelError("gateway asked to reconnect", true));
        }
        return;
      }
      case OP.HEARTBEAT_ACK:
        // The one frame that proves the socket is still a round trip rather than a write
        // into a dead pipe. startHeartbeat measures its silence.
        this.lastAckAt = Date.now();
        return;
      default:
        // The webhook-only opcodes need no action.
        return;
    }
  }

  private onDispatch(frame: QQGatewayFrame): void {
    if (frame.t === "READY") {
      const d = frame.d as { session_id?: string } | undefined;
      if (typeof d?.session_id === "string") this.sessionId = d.session_id;
      this.onHandshake();
      return;
    }
    if (frame.t === "RESUMED") {
      this.onHandshake();
      return;
    }
    const evt = normalizeDispatch(frame);
    if (evt !== null) void this.handlers.onMessage(evt);
  }

  /** A handshake completed: the outage (if any) is over and the backoff resets. */
  private onHandshake(): void {
    this.disarmHandshake();
    this.failures = 0;
    this.reported = "none";
    this.handlers.onReady?.();
  }

  private disarmHandshake(): void {
    if (this.handshakeTimer !== null) clearTimeout(this.handshakeTimer);
    this.handshakeTimer = null;
  }

  /**
   * Abandons a socket the session has given up on and starts the backoff itself.
   *
   * The `close` handler is not enough on its own here: the failure both watchdogs cover is
   * a socket that never fires `close`, and asking a half-open one to close is a request the
   * far end may never answer. Detaching first makes the `close` that may eventually arrive
   * a no-op (every listener is gated on `this.ws === ws`). A RECONNECT takes the same path,
   * so the failure it reports is the reason it was asked for rather than a bare close code.
   */
  private dropSocket(ws: QQSocket, err: Error): void {
    if (this.ws !== ws) return;
    this.stopHeartbeat();
    this.disarmHandshake();
    this.ws = null;
    try {
      ws.close();
    } catch {
      // Same as close(): a socket already going away throws on some paths and it changes
      // nothing here.
    }
    this.fail(err);
  }

  private startHeartbeat(intervalMs: number): void {
    this.stopHeartbeat();
    const ws = this.ws;
    if (ws === null) return;
    // HELLO is the last thing heard from this socket so far, which is what the first
    // interval is measured against.
    this.lastAckAt = Date.now();
    this.heartbeat = setInterval(() => {
      // Two intervals of silence: the platform acknowledges every heartbeat, so a socket
      // still writable but no longer answering is a dead pipe rather than a slow one. One
      // interval would be a lost ack; two is an outage.
      if (Date.now() - this.lastAckAt > intervalMs * 2) {
        this.dropSocket(
          ws,
          new MessagingChannelError("gateway stopped acknowledging heartbeats", true),
        );
        return;
      }
      this.send({ op: OP.HEARTBEAT, d: this.seq });
    }, intervalMs);
    // A heartbeat must never be the reason the process cannot exit.
    this.heartbeat.unref?.();
  }

  private stopHeartbeat(): void {
    if (this.heartbeat !== null) clearInterval(this.heartbeat);
    this.heartbeat = null;
  }

  private send(frame: QQGatewayFrame): void {
    try {
      if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));
    } catch {
      // A send into a socket that died between the check and the write is the same outage
      // the `close` handler is about to report; there is nothing extra to say here.
    }
  }

  /**
   * One report per outage, then retry with backoff — the Telegram poll loop's contract, with
   * the one exception `reported` documents: a routine failure does not get to be the whole
   * story of an outage that turns out to need a person.
   */
  private fail(err: unknown): void {
    if (this.closed) return;
    this.failures += 1;
    const routine = err instanceof MessagingChannelError && err.recovers;
    if (this.reported === "none" || (this.reported === "routine" && !routine)) {
      this.reported = routine ? "routine" : "defect";
      this.handlers.onError?.(err);
    }
    this.retryTimer = setTimeout(() => {
      this.retryTimer = null;
      void this.connect();
    }, this.opts.retryMs(this.failures));
    this.retryTimer.unref?.();
  }
}

/** One gateway frame. `s` and `t` ride dispatches only. */
export interface QQGatewayFrame {
  op: number;
  d?: unknown;
  s?: number;
  t?: string;
  /** The dispatch's own event id (an alternative passive-reply anchor this product does not use). */
  id?: string;
}

/**
 * One dispatch frame reduced to the connector's inbound shape; null for anything that is
 * not one of the two message events this product answers.
 *
 * A single-chat message and a group @-message differ in exactly two places — where the
 * conversation's openid lives, and which author field carries the sender — so they
 * normalize to one record with a `kind` discriminator rather than two shapes. The group
 * event's sender is `author.member_openid`, NOT `user_openid`: that field exists on the
 * group event too and is empty there, so reading it would quietly yield blanks.
 *
 * `GROUP_MESSAGE_CREATE` — every group message rather than only the @-mentions — rides the
 * same intent when a console switch is on, and is deliberately dropped: a bot that answered
 * everything said in a group is not what binding a conversation to it asks for.
 */
export function normalizeDispatch(frame: QQGatewayFrame): QQInboundEvent | null {
  const d = frame.d as
    | {
        id?: string;
        content?: string;
        group_openid?: string;
        author?: { user_openid?: string; member_openid?: string };
      }
    | undefined;
  if (d === undefined || typeof d.id !== "string" || d.id === "") return null;
  // The platform strips the "@bot" prefix but not the space it sat in.
  const content = typeof d.content === "string" ? d.content.trim() : "";
  if (frame.t === "C2C_MESSAGE_CREATE") {
    const openid = d.author?.user_openid;
    if (typeof openid !== "string" || openid === "") return null;
    return { kind: "c2c", openid, messageId: d.id, content, senderOpenid: openid };
  }
  if (frame.t === "GROUP_AT_MESSAGE_CREATE") {
    const openid = d.group_openid;
    if (typeof openid !== "string" || openid === "") return null;
    const sender = d.author?.member_openid;
    return {
      kind: "group",
      openid,
      messageId: d.id,
      content,
      ...(typeof sender === "string" && sender !== "" ? { senderOpenid: sender } : {}),
    };
  }
  return null;
}