@gakr-gakr/discord 0.1.0

package/src/monitor/gateway-metadata.ts

@@ -0,0 +1,298 @@
+import type { APIGatewayBotInfo } from "discord-api-types/v10";
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import { captureHttpExchange } from "autobot/plugin-sdk/proxy-capture";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+import { fetchWithSsrFGuard } from "autobot/plugin-sdk/ssrf-runtime";
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+import { isDiscordRateLimitResponseBody, summarizeDiscordResponseBody } from "../error-body.js";
+import { withAbortTimeout } from "./timeouts.js";
+
+const DISCORD_GATEWAY_BOT_URL = "https://discord.com/api/v10/gateway/bot";
+const DISCORD_API_HOST = "discord.com";
+const DEFAULT_DISCORD_GATEWAY_URL = "wss://gateway.discord.gg/";
+const DEFAULT_DISCORD_GATEWAY_INFO_TIMEOUT_MS = 30_000;
+const MAX_DISCORD_GATEWAY_INFO_TIMEOUT_MS = 120_000;
+const DISCORD_GATEWAY_INFO_TIMEOUT_ENV = "AUTOBOT_DISCORD_GATEWAY_INFO_TIMEOUT_MS";
+const DISCORD_GATEWAY_METADATA_FALLBACK_LOG_INTERVAL_MS = 60_000;
+
+type DiscordGatewayMetadataResponse = Pick<Response, "ok" | "status" | "text">;
+export type DiscordGatewayFetchInit = Record<string, unknown> & {
+  headers?: Record<string, string>;
+};
+export type DiscordGatewayFetch = (
+  input: string,
+  init?: DiscordGatewayFetchInit,
+) => Promise<DiscordGatewayMetadataResponse>;
+
+type DiscordGatewayMetadataError = Error & { transient?: boolean };
+
+const discordGatewayBotInfoSchema = Type.Object({
+  url: Type.String({ minLength: 1 }),
+  shards: Type.Integer({ minimum: 1 }),
+  session_start_limit: Type.Object({
+    total: Type.Integer({ minimum: 0 }),
+    remaining: Type.Integer({ minimum: 0 }),
+    reset_after: Type.Number({ minimum: 0 }),
+    max_concurrency: Type.Integer({ minimum: 1 }),
+  }),
+});
+
+const gatewayMetadataFallbackLogLastAt = new WeakMap<RuntimeEnv, number>();
+
+function resolveFetchInputUrl(input: RequestInfo | URL): string {
+  if (typeof input === "string") {
+    return input;
+  }
+  if (input instanceof URL) {
+    return input.toString();
+  }
+  return input.url;
+}
+
+async function materializeGuardedResponse(response: Response): Promise<Response> {
+  const body = await response.arrayBuffer();
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+function normalizeGatewayInfoTimeoutMs(value: unknown): number | undefined {
+  const numeric =
+    typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return undefined;
+  }
+  return Math.min(Math.floor(numeric), MAX_DISCORD_GATEWAY_INFO_TIMEOUT_MS);
+}
+
+export function resolveDiscordGatewayInfoTimeoutMs(params?: {
+  configuredTimeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): number {
+  return (
+    normalizeGatewayInfoTimeoutMs(params?.configuredTimeoutMs) ??
+    normalizeGatewayInfoTimeoutMs(params?.env?.[DISCORD_GATEWAY_INFO_TIMEOUT_ENV]) ??
+    DEFAULT_DISCORD_GATEWAY_INFO_TIMEOUT_MS
+  );
+}
+
+function summarizeGatewayResponseBody(body: string): string {
+  return summarizeDiscordResponseBody(body, { emptyText: "<empty>" }) ?? "<empty>";
+}
+
+function isDiscordGatewayRateLimitResponse(status: number, body: string): boolean {
+  return status === 429 && isDiscordRateLimitResponseBody(body);
+}
+
+function isTransientDiscordGatewayResponse(status: number, body: string): boolean {
+  if (status >= 500) {
+    return true;
+  }
+  if (isDiscordGatewayRateLimitResponse(status, body)) {
+    return true;
+  }
+  const normalized = body.toLowerCase();
+  return (
+    normalized.includes("upstream connect error") ||
+    normalized.includes("disconnect/reset before headers") ||
+    normalized.includes("reset reason:")
+  );
+}
+
+function createGatewayMetadataError(params: {
+  detail: string;
+  transient: boolean;
+  cause?: unknown;
+}): Error {
+  const error = new Error(
+    params.transient
+      ? "Failed to get gateway information from Discord: fetch failed"
+      : `Failed to get gateway information from Discord: ${params.detail}`,
+    {
+      cause: params.cause ?? (params.transient ? new Error(params.detail) : undefined),
+    },
+  ) as DiscordGatewayMetadataError;
+  Object.defineProperty(error, "transient", {
+    value: params.transient,
+    enumerable: false,
+  });
+  return error;
+}
+
+function isTransientGatewayMetadataError(error: unknown): boolean {
+  return Boolean((error as DiscordGatewayMetadataError | undefined)?.transient);
+}
+
+function createDefaultGatewayInfo(): APIGatewayBotInfo {
+  return {
+    url: DEFAULT_DISCORD_GATEWAY_URL,
+    shards: 1,
+    session_start_limit: {
+      total: 1,
+      remaining: 1,
+      reset_after: 0,
+      max_concurrency: 1,
+    },
+  };
+}
+
+function summarizeGatewaySchemaErrors(value: unknown): string {
+  const errors = Errors(discordGatewayBotInfoSchema, value);
+  if (errors.length === 0) {
+    return "unknown schema mismatch";
+  }
+  return errors
+    .slice(0, 3)
+    .map((error) => `${error.instancePath || "/"} ${error.message}`)
+    .join("; ");
+}
+
+export function parseDiscordGatewayInfoBody(body: string): APIGatewayBotInfo {
+  const parsed = JSON.parse(body) as unknown;
+  if (!Check(discordGatewayBotInfoSchema, parsed)) {
+    throw new Error(summarizeGatewaySchemaErrors(parsed));
+  }
+  return parsed;
+}
+
+export async function fetchDiscordGatewayInfo(params: {
+  token: string;
+  fetchImpl: DiscordGatewayFetch;
+  fetchInit?: DiscordGatewayFetchInit;
+}): Promise<APIGatewayBotInfo> {
+  let response: DiscordGatewayMetadataResponse;
+  try {
+    response = await params.fetchImpl(DISCORD_GATEWAY_BOT_URL, {
+      ...params.fetchInit,
+      headers: {
+        ...params.fetchInit?.headers,
+        Authorization: `Bot ${params.token}`,
+      },
+    });
+  } catch (error) {
+    throw createGatewayMetadataError({
+      detail: formatErrorMessage(error),
+      transient: true,
+      cause: error,
+    });
+  }
+
+  let body: string;
+  try {
+    body = await response.text();
+  } catch (error) {
+    throw createGatewayMetadataError({
+      detail: formatErrorMessage(error),
+      transient: true,
+      cause: error,
+    });
+  }
+  const summary = summarizeGatewayResponseBody(body);
+  const transient = isTransientDiscordGatewayResponse(response.status, body);
+
+  if (!response.ok) {
+    throw createGatewayMetadataError({
+      detail: `Discord API /gateway/bot failed (${response.status}): ${summary}`,
+      transient,
+    });
+  }
+
+  try {
+    return parseDiscordGatewayInfoBody(body);
+  } catch (error) {
+    throw createGatewayMetadataError({
+      detail: `Discord API /gateway/bot returned invalid metadata: ${formatErrorMessage(error)} (${summary})`,
+      transient,
+      cause: error,
+    });
+  }
+}
+
+export async function fetchDiscordGatewayInfoWithTimeout(params: {
+  token: string;
+  fetchImpl: DiscordGatewayFetch;
+  fetchInit?: DiscordGatewayFetchInit;
+  timeoutMs?: number;
+}): Promise<APIGatewayBotInfo> {
+  const timeoutMs = Math.max(1, params.timeoutMs ?? DEFAULT_DISCORD_GATEWAY_INFO_TIMEOUT_MS);
+  return await withAbortTimeout({
+    timeoutMs,
+    createTimeoutError: () =>
+      createGatewayMetadataError({
+        detail: `Discord API /gateway/bot timed out after ${timeoutMs}ms`,
+        transient: true,
+        cause: new Error("gateway metadata timeout"),
+      }),
+    run: async (signal) =>
+      await fetchDiscordGatewayInfo({
+        token: params.token,
+        fetchImpl: params.fetchImpl,
+        fetchInit: {
+          ...params.fetchInit,
+          signal,
+        },
+      }),
+  });
+}
+
+export function resolveGatewayInfoWithFallback(params: { runtime?: RuntimeEnv; error: unknown }): {
+  info: APIGatewayBotInfo;
+  usedFallback: boolean;
+} {
+  if (!isTransientGatewayMetadataError(params.error)) {
+    throw params.error;
+  }
+  const message = formatErrorMessage(params.error);
+  const now = Date.now();
+  if (params.runtime) {
+    const previous = gatewayMetadataFallbackLogLastAt.get(params.runtime);
+    if (
+      previous === undefined ||
+      now - previous >= DISCORD_GATEWAY_METADATA_FALLBACK_LOG_INTERVAL_MS
+    ) {
+      params.runtime.log?.(
+        `discord: gateway metadata lookup failed transiently; using default gateway url (${message})`,
+      );
+      gatewayMetadataFallbackLogLastAt.set(params.runtime, now);
+    }
+  }
+  return {
+    info: createDefaultGatewayInfo(),
+    usedFallback: true,
+  };
+}
+
+export async function fetchDiscordGatewayMetadataDirect(
+  input: string,
+  init?: DiscordGatewayFetchInit,
+  capture?: false | { flowId: string; meta: Record<string, unknown> },
+): Promise<Response> {
+  const guarded = await fetchWithSsrFGuard({
+    url: resolveFetchInputUrl(input),
+    init: init as RequestInit,
+    policy: { allowedHostnames: [DISCORD_API_HOST] },
+    capture: false,
+    auditContext: "discord.gateway.metadata",
+  });
+  let response: Response;
+  try {
+    response = await materializeGuardedResponse(guarded.response);
+  } finally {
+    await guarded.release();
+  }
+  if (capture) {
+    captureHttpExchange({
+      url: input,
+      method: (init?.method as string | undefined) ?? "GET",
+      requestHeaders: init?.headers as Headers | Record<string, string> | undefined,
+      requestBody: (init as RequestInit & { body?: BodyInit | null })?.body ?? null,
+      response,
+      flowId: capture.flowId,
+      meta: capture.meta,
+    });
+  }
+  return response;
+}

package/src/monitor/gateway-plugin.ts

@@ -0,0 +1,302 @@
+import { randomUUID } from "node:crypto";
+import { Agent as HttpsAgent } from "node:https";
+import * as httpsProxyAgent from "https-proxy-agent";
+import type { DiscordAccountConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  captureWsEvent,
+  resolveEffectiveDebugProxyUrl,
+  resolveDebugProxySettings,
+} from "autobot/plugin-sdk/proxy-capture";
+import { danger } from "autobot/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+import * as ws from "ws";
+import * as discordGateway from "../internal/gateway.js";
+import { createDiscordDnsLookup } from "../network-config.js";
+import { validateDiscordProxyUrl } from "../proxy-fetch.js";
+import { resolveDiscordVoiceEnabled } from "../voice/config.js";
+import { DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT } from "./gateway-handle.js";
+import {
+  fetchDiscordGatewayInfoWithTimeout,
+  fetchDiscordGatewayMetadataDirect,
+  resolveDiscordGatewayInfoTimeoutMs,
+  resolveGatewayInfoWithFallback,
+  type DiscordGatewayFetch,
+  type DiscordGatewayFetchInit,
+} from "./gateway-metadata.js";
+
+export {
+  parseDiscordGatewayInfoBody,
+  resolveDiscordGatewayInfoTimeoutMs,
+} from "./gateway-metadata.js";
+
+const DISCORD_GATEWAY_HANDSHAKE_TIMEOUT_MS = 30_000;
+const discordDnsLookup = createDiscordDnsLookup();
+
+type DiscordGatewayWebSocketCtor = new (
+  url: string,
+  options?: { agent?: unknown; handshakeTimeout?: number },
+) => ws.WebSocket;
+type DiscordGatewayWebSocketAgent =
+  | InstanceType<typeof HttpsAgent>
+  | InstanceType<typeof httpsProxyAgent.HttpsProxyAgent<string>>;
+const registrationPromises = new WeakMap<discordGateway.GatewayPlugin, Promise<void>>();
+type DiscordGatewayClient = Parameters<discordGateway.GatewayPlugin["registerClient"]>[0];
+type GatewayPluginTestingOptions = {
+  registerClient?: (
+    plugin: discordGateway.GatewayPlugin,
+    client: DiscordGatewayClient,
+  ) => Promise<void>;
+  webSocketCtor?: DiscordGatewayWebSocketCtor;
+};
+type CreateDiscordGatewayPluginTestingOptions = GatewayPluginTestingOptions & {
+  HttpsProxyAgentCtor?: typeof httpsProxyAgent.HttpsProxyAgent;
+};
+type DiscordGatewayRegistrationState = {
+  client?: DiscordGatewayClient;
+  ws?: unknown;
+  isConnecting?: boolean;
+};
+
+function assignGatewayClient(
+  plugin: discordGateway.GatewayPlugin,
+  client: DiscordGatewayClient,
+): void {
+  (plugin as unknown as DiscordGatewayRegistrationState).client = client;
+}
+
+function hasGatewaySocketStarted(plugin: discordGateway.GatewayPlugin): boolean {
+  const state = plugin as unknown as DiscordGatewayRegistrationState;
+  return state.ws != null || state.isConnecting === true;
+}
+
+type ResolveDiscordGatewayIntentsParams = {
+  intentsConfig?: import("autobot/plugin-sdk/config-contracts").DiscordIntentsConfig;
+  voiceEnabled?: boolean;
+};
+
+export function resolveDiscordGatewayIntents(params?: ResolveDiscordGatewayIntentsParams): number {
+  const intentsConfig = params?.intentsConfig;
+  const voiceEnabled = params?.voiceEnabled;
+  const voiceStatesEnabled = intentsConfig?.voiceStates ?? voiceEnabled ?? false;
+  let intents =
+    discordGateway.GatewayIntents.Guilds |
+    discordGateway.GatewayIntents.GuildMessages |
+    discordGateway.GatewayIntents.MessageContent |
+    discordGateway.GatewayIntents.DirectMessages |
+    discordGateway.GatewayIntents.GuildMessageReactions |
+    discordGateway.GatewayIntents.DirectMessageReactions;
+  if (voiceStatesEnabled) {
+    intents |= discordGateway.GatewayIntents.GuildVoiceStates;
+  }
+  if (intentsConfig?.presence) {
+    intents |= discordGateway.GatewayIntents.GuildPresences;
+  }
+  if (intentsConfig?.guildMembers) {
+    intents |= discordGateway.GatewayIntents.GuildMembers;
+  }
+  return intents;
+}
+
+function createGatewayPlugin(params: {
+  options: {
+    reconnect: { maxAttempts: number };
+    intents: number;
+    autoInteractions: boolean;
+  };
+  gatewayInfoTimeoutMs: number;
+  fetchImpl: DiscordGatewayFetch;
+  fetchInit?: DiscordGatewayFetchInit;
+  wsAgent?: DiscordGatewayWebSocketAgent;
+  runtime?: RuntimeEnv;
+  testing?: GatewayPluginTestingOptions;
+}): discordGateway.GatewayPlugin {
+  class AutoBotGatewayPlugin extends discordGateway.GatewayPlugin {
+    private gatewayInfoUsedFallback = false;
+
+    constructor() {
+      super(params.options);
+    }
+
+    override registerClient(client: DiscordGatewayClient) {
+      const registration = this.registerClientInternal(client);
+      // Client construction starts plugin hooks without awaiting them. Mark the
+      // promise handled immediately, then let startup await the original promise.
+      registration.catch(() => {});
+      registrationPromises.set(this, registration);
+      return registration;
+    }
+
+    private async registerClientInternal(client: DiscordGatewayClient) {
+      // Publish the client reference before the metadata fetch can yield, so an external
+      // connect()->identify() cannot silently drop IDENTIFY (#52372).
+      assignGatewayClient(this, client);
+
+      if (!this.gatewayInfo || this.gatewayInfoUsedFallback) {
+        const resolved = await fetchDiscordGatewayInfoWithTimeout({
+          token: client.options.token,
+          fetchImpl: params.fetchImpl,
+          fetchInit: params.fetchInit,
+          timeoutMs: params.gatewayInfoTimeoutMs,
+        })
+          .then((info) => ({
+            info,
+            usedFallback: false,
+          }))
+          .catch((error) => resolveGatewayInfoWithFallback({ runtime: params.runtime, error }));
+        this.gatewayInfo = resolved.info;
+        this.gatewayInfoUsedFallback = resolved.usedFallback;
+      }
+      if (params.testing?.registerClient) {
+        await params.testing.registerClient(this, client);
+        return;
+      }
+      // If the lifecycle timeout already started a socket while metadata was
+      // loading, do not register again; it would close that socket and open another one.
+      if (hasGatewaySocketStarted(this)) {
+        return;
+      }
+      return super.registerClient(client);
+    }
+
+    override createWebSocket(url: string) {
+      if (!url) {
+        throw new Error("Gateway URL is required");
+      }
+      const wsFlowId = randomUUID();
+      // Avoid Node's undici-backed global WebSocket here. We have seen late
+      // close-path crashes during Discord gateway teardown; the ws transport is
+      // already our proxy path and behaves predictably for lifecycle cleanup.
+      const WebSocketCtor = params.testing?.webSocketCtor ?? ws.default;
+      const socket = new WebSocketCtor(url, {
+        handshakeTimeout: DISCORD_GATEWAY_HANDSHAKE_TIMEOUT_MS,
+        ...(params.wsAgent ? { agent: params.wsAgent } : {}),
+      });
+      const emitTransportActivity = () => {
+        if ((this as unknown as { ws?: unknown }).ws !== socket) {
+          return;
+        }
+        this.emitter.emit(DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT, { at: Date.now() });
+      };
+      captureWsEvent({
+        url,
+        direction: "local",
+        kind: "ws-open",
+        flowId: wsFlowId,
+        meta: { subsystem: "discord-gateway" },
+      });
+      socket.on?.("message", (data: unknown) => {
+        emitTransportActivity();
+        captureWsEvent({
+          url,
+          direction: "inbound",
+          kind: "ws-frame",
+          flowId: wsFlowId,
+          payload: Buffer.isBuffer(data) ? data : Buffer.from(String(data)),
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      socket.on?.("close", (code: number, reason: Buffer) => {
+        captureWsEvent({
+          url,
+          direction: "local",
+          kind: "ws-close",
+          flowId: wsFlowId,
+          closeCode: code,
+          payload: reason,
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      socket.on?.("error", (error: Error) => {
+        captureWsEvent({
+          url,
+          direction: "local",
+          kind: "error",
+          flowId: wsFlowId,
+          errorText: error.message,
+          meta: { subsystem: "discord-gateway" },
+        });
+      });
+      if ("binaryType" in socket) {
+        try {
+          socket.binaryType = "arraybuffer";
+        } catch {
+          // Ignore runtimes that expose a readonly binaryType.
+        }
+      }
+      return socket;
+    }
+  }
+
+  return new AutoBotGatewayPlugin();
+}
+
+function createDiscordGatewayMetadataFetch(debugCaptureEnabled: boolean): DiscordGatewayFetch {
+  return (input, init) =>
+    fetchDiscordGatewayMetadataDirect(
+      input,
+      init,
+      debugCaptureEnabled
+        ? false
+        : {
+            flowId: randomUUID(),
+            meta: { subsystem: "discord-gateway-metadata" },
+          },
+    );
+}
+
+export function waitForDiscordGatewayPluginRegistration(
+  plugin: unknown,
+): Promise<void> | undefined {
+  if (typeof plugin !== "object" || plugin === null) {
+    return undefined;
+  }
+  return registrationPromises.get(plugin as discordGateway.GatewayPlugin);
+}
+
+export function createDiscordGatewayPlugin(params: {
+  discordConfig: DiscordAccountConfig;
+  runtime: RuntimeEnv;
+  testing?: CreateDiscordGatewayPluginTestingOptions;
+}): discordGateway.GatewayPlugin {
+  const intents = resolveDiscordGatewayIntents({
+    intentsConfig: params.discordConfig?.intents,
+    voiceEnabled: resolveDiscordVoiceEnabled(params.discordConfig?.voice),
+  });
+  const proxy = resolveEffectiveDebugProxyUrl(params.discordConfig?.proxy);
+  const debugProxySettings = resolveDebugProxySettings();
+  const gatewayInfoTimeoutMs = resolveDiscordGatewayInfoTimeoutMs({
+    configuredTimeoutMs: params.discordConfig?.gatewayInfoTimeoutMs,
+    env: process.env,
+  });
+  let fetchImpl = createDiscordGatewayMetadataFetch(debugProxySettings.enabled);
+  let wsAgent: DiscordGatewayWebSocketAgent = new HttpsAgent({
+    lookup: discordDnsLookup,
+  });
+
+  if (proxy) {
+    try {
+      validateDiscordProxyUrl(proxy);
+      const HttpsProxyAgentCtor =
+        params.testing?.HttpsProxyAgentCtor ?? httpsProxyAgent.HttpsProxyAgent;
+      wsAgent = new HttpsProxyAgentCtor<string>(proxy);
+      params.runtime.log?.("discord: gateway proxy enabled");
+    } catch (err) {
+      params.runtime.error?.(danger(`discord: invalid gateway proxy: ${String(err)}`));
+      fetchImpl = (input, init) => fetchDiscordGatewayMetadataDirect(input, init, false);
+    }
+  }
+
+  return createGatewayPlugin({
+    options: {
+      reconnect: { maxAttempts: 50 },
+      intents,
+      // AutoBot registers its own async interaction listener.
+      autoInteractions: false,
+    },
+    gatewayInfoTimeoutMs,
+    fetchImpl,
+    runtime: params.runtime,
+    testing: params.testing,
+    ...(wsAgent ? { wsAgent } : {}),
+  });
+}

package/src/monitor/gateway-registry.ts

@@ -0,0 +1,37 @@
+import type { GatewayPlugin } from "../internal/gateway.js";
+
+/**
+ * Module-level registry of active Discord GatewayPlugin instances.
+ * Bridges the gap between agent tool handlers (which only have REST access)
+ * and the gateway WebSocket (needed for operations like updatePresence).
+ * Follows the same pattern as presence-cache.ts.
+ */
+const gatewayRegistry = new Map<string, GatewayPlugin>();
+
+// Sentinel key for the default (unnamed) account. Uses a prefix that cannot
+// collide with user-configured account IDs.
+const DEFAULT_ACCOUNT_KEY = "\0__default__";
+
+function resolveAccountKey(accountId?: string): string {
+  return accountId ?? DEFAULT_ACCOUNT_KEY;
+}
+
+/** Register a GatewayPlugin instance for an account. */
+export function registerGateway(accountId: string | undefined, gateway: GatewayPlugin): void {
+  gatewayRegistry.set(resolveAccountKey(accountId), gateway);
+}
+
+/** Unregister a GatewayPlugin instance for an account. */
+export function unregisterGateway(accountId?: string): void {
+  gatewayRegistry.delete(resolveAccountKey(accountId));
+}
+
+/** Get the GatewayPlugin for an account. Returns undefined if not registered. */
+export function getGateway(accountId?: string): GatewayPlugin | undefined {
+  return gatewayRegistry.get(resolveAccountKey(accountId));
+}
+
+/** Clear all registered gateways (for testing). */
+export function clearGateways(): void {
+  gatewayRegistry.clear();
+}