@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/gateway-metadata.ts

@@ -0,0 +1,298 @@
+import type { APIGatewayBotInfo } from "discord-api-types/v10";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { captureHttpExchange } from "klaw/plugin-sdk/proxy-capture";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { fetchWithSsrFGuard } from "klaw/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 = "KLAW_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.test.ts

@@ -0,0 +1,320 @@
+import { EventEmitter } from "node:events";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT } from "./gateway-handle.js";
+
+const { GatewayIntents, GatewayPlugin } = vi.hoisted(() => {
+  const GatewayIntents = {
+    Guilds: 1 << 0,
+    GuildMessages: 1 << 1,
+    MessageContent: 1 << 2,
+    DirectMessages: 1 << 3,
+    GuildMessageReactions: 1 << 4,
+    DirectMessageReactions: 1 << 5,
+    GuildPresences: 1 << 6,
+    GuildMembers: 1 << 7,
+    GuildVoiceStates: 1 << 8,
+  } as const;
+
+  class TestEmitter {
+    private readonly listenersByEvent = new Map<string, Array<(value: unknown) => void>>();
+
+    on(event: string, listener: (value: unknown) => void) {
+      const listeners = this.listenersByEvent.get(event) ?? [];
+      listeners.push(listener);
+      this.listenersByEvent.set(event, listeners);
+    }
+
+    emit(event: string, value: unknown) {
+      for (const listener of this.listenersByEvent.get(event) ?? []) {
+        listener(value);
+      }
+    }
+  }
+
+  class GatewayPlugin {
+    options: unknown;
+    gatewayInfo: unknown;
+    emitter = new TestEmitter();
+    isConnecting: boolean = false;
+    heartbeatInterval?: NodeJS.Timeout;
+    firstHeartbeatTimeout?: NodeJS.Timeout;
+    ws?: unknown;
+
+    constructor(options?: unknown) {
+      this.options = options;
+    }
+
+    async registerClient(clientForTest: unknown): Promise<void> {}
+
+    connect(_resume = false): void {
+      if (this.isConnecting) {
+        return;
+      }
+    }
+  }
+
+  return { GatewayIntents, GatewayPlugin };
+});
+
+vi.mock("../internal/gateway.js", () => ({
+  GatewayIntents,
+  GatewayPlugin,
+}));
+
+vi.mock("klaw/plugin-sdk/proxy-capture", () => ({
+  captureHttpExchange: vi.fn(),
+  captureWsEvent: vi.fn(),
+  resolveEffectiveDebugProxyUrl: () => undefined,
+  resolveDebugProxySettings: () => ({ enabled: false }),
+}));
+
+vi.mock("klaw/plugin-sdk/runtime-env", () => ({
+  danger: (value: string) => value,
+}));
+
+describe("createDiscordGatewayPlugin", () => {
+  let createDiscordGatewayPlugin: typeof import("./gateway-plugin.js").createDiscordGatewayPlugin;
+  let parseDiscordGatewayInfoBody: typeof import("./gateway-plugin.js").parseDiscordGatewayInfoBody;
+  let resolveDiscordGatewayIntents: typeof import("./gateway-plugin.js").resolveDiscordGatewayIntents;
+  let resolveDiscordGatewayInfoTimeoutMs: typeof import("./gateway-plugin.js").resolveDiscordGatewayInfoTimeoutMs;
+
+  beforeAll(async () => {
+    ({
+      createDiscordGatewayPlugin,
+      parseDiscordGatewayInfoBody,
+      resolveDiscordGatewayIntents,
+      resolveDiscordGatewayInfoTimeoutMs,
+    } = await import("./gateway-plugin.js"));
+  });
+
+  function createPlugin(
+    testing?: NonNullable<Parameters<typeof createDiscordGatewayPlugin>[0]["testing"]>,
+    discordConfig: Parameters<typeof createDiscordGatewayPlugin>[0]["discordConfig"] = {},
+  ) {
+    return createDiscordGatewayPlugin({
+      discordConfig,
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: vi.fn(),
+      },
+      ...(testing ? { testing: testing } : {}),
+    });
+  }
+
+  it("omits GuildVoiceStates by default for text-only Discord configs", () => {
+    expect(resolveDiscordGatewayIntents() & GatewayIntents.GuildVoiceStates).toBe(0);
+  });
+
+  it("includes GuildVoiceStates when voice is enabled", () => {
+    const intents = resolveDiscordGatewayIntents({ voiceEnabled: true });
+
+    expect(intents & GatewayIntents.GuildVoiceStates).toBe(GatewayIntents.GuildVoiceStates);
+  });
+
+  it("omits GuildVoiceStates when voice is disabled", () => {
+    const intents = resolveDiscordGatewayIntents({ voiceEnabled: false });
+
+    expect(intents & GatewayIntents.GuildVoiceStates).toBe(0);
+  });
+
+  it("lets intents.voiceStates override voice enablement", () => {
+    const enabled = resolveDiscordGatewayIntents({
+      intentsConfig: { voiceStates: true },
+      voiceEnabled: false,
+    });
+    const disabled = resolveDiscordGatewayIntents({
+      intentsConfig: { voiceStates: false },
+      voiceEnabled: true,
+    });
+
+    expect(enabled & GatewayIntents.GuildVoiceStates).toBe(GatewayIntents.GuildVoiceStates);
+    expect(disabled & GatewayIntents.GuildVoiceStates).toBe(0);
+  });
+
+  it("includes optional configured privileged intents", () => {
+    const intents = resolveDiscordGatewayIntents({
+      intentsConfig: { presence: true, guildMembers: true },
+    });
+
+    expect(intents & GatewayIntents.GuildPresences).toBe(GatewayIntents.GuildPresences);
+    expect(intents & GatewayIntents.GuildMembers).toBe(GatewayIntents.GuildMembers);
+  });
+
+  it("resolves gateway metadata timeout from config, env, then default", () => {
+    expect(resolveDiscordGatewayInfoTimeoutMs({ configuredTimeoutMs: 45_000 })).toBe(45_000);
+    expect(
+      resolveDiscordGatewayInfoTimeoutMs({
+        env: { KLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS: "25000" },
+      }),
+    ).toBe(25_000);
+    expect(resolveDiscordGatewayInfoTimeoutMs({ env: {} })).toBe(30_000);
+  });
+
+  it("parses valid Discord gateway metadata", () => {
+    expect(
+      parseDiscordGatewayInfoBody(
+        JSON.stringify({
+          url: "wss://gateway.discord.gg",
+          shards: 1,
+          session_start_limit: {
+            total: 1000,
+            remaining: 999,
+            reset_after: 0,
+            max_concurrency: 1,
+          },
+        }),
+      ),
+    ).toEqual({
+      url: "wss://gateway.discord.gg",
+      shards: 1,
+      session_start_limit: {
+        total: 1000,
+        remaining: 999,
+        reset_after: 0,
+        max_concurrency: 1,
+      },
+    });
+  });
+
+  it("rejects malformed Discord gateway metadata", () => {
+    expect(() =>
+      parseDiscordGatewayInfoBody(
+        JSON.stringify({
+          url: "",
+          shards: 0,
+          session_start_limit: {
+            total: 1000,
+            remaining: 999,
+            reset_after: 0,
+            max_concurrency: 1,
+          },
+        }),
+      ),
+    ).toThrow(/url|shards/);
+  });
+
+  it("omits voice states when Discord voice is disabled in account config", () => {
+    const plugin = createPlugin(undefined, { voice: { enabled: false } });
+    const options = (plugin as unknown as { options?: { intents?: number } }).options;
+
+    expect((options?.intents ?? 0) & GatewayIntents.GuildVoiceStates).toBe(0);
+  });
+
+  it("omits voice states when Discord voice config is absent", () => {
+    const plugin = createPlugin(undefined, {});
+    const options = (plugin as unknown as { options?: { intents?: number } }).options;
+
+    expect((options?.intents ?? 0) & GatewayIntents.GuildVoiceStates).toBe(0);
+  });
+
+  it("keeps voice states for existing Discord voice config blocks", () => {
+    const plugin = createPlugin(undefined, { voice: {} });
+    const options = (plugin as unknown as { options?: { intents?: number } }).options;
+
+    expect((options?.intents ?? 0) & GatewayIntents.GuildVoiceStates).toBe(
+      GatewayIntents.GuildVoiceStates,
+    );
+  });
+
+  it("leaves autoInteractions disabled so Klaw owns interaction handoff", () => {
+    const plugin = createPlugin();
+
+    expect(
+      (
+        plugin as unknown as {
+          options?: {
+            autoInteractions: boolean;
+            intents: number;
+            reconnect: { maxAttempts: number };
+          };
+        }
+      ).options,
+    ).toEqual({
+      autoInteractions: false,
+      intents:
+        GatewayIntents.Guilds |
+        GatewayIntents.GuildMessages |
+        GatewayIntents.MessageContent |
+        GatewayIntents.DirectMessages |
+        GatewayIntents.GuildMessageReactions |
+        GatewayIntents.DirectMessageReactions,
+      reconnect: { maxAttempts: 50 },
+    });
+  });
+
+  it("keeps Klaw metadata timeout out of gateway options", () => {
+    const plugin = createDiscordGatewayPlugin({
+      discordConfig: { gatewayInfoTimeoutMs: 5_000 },
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: vi.fn(),
+      },
+    });
+
+    expect(
+      (plugin as unknown as { options?: { gatewayInfoTimeoutMs?: number } }).options
+        ?.gatewayInfoTimeoutMs,
+    ).toBeUndefined();
+  });
+
+  it("emits transport activity for current gateway socket messages", () => {
+    const socket = new EventEmitter() as EventEmitter & { binaryType?: string };
+    const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    const plugin = createPlugin({
+      webSocketCtor: function WebSocketCtor() {
+        return socket;
+      } as unknown as NonNullable<
+        Parameters<typeof createDiscordGatewayPlugin>[0]["testing"]
+      >["webSocketCtor"],
+    });
+    const activitySpy = vi.fn();
+    (
+      plugin as unknown as {
+        emitter: { on: (event: string, listener: (value: unknown) => void) => void };
+      }
+    ).emitter.on(DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT, activitySpy);
+
+    const createdSocket = (
+      plugin as unknown as { createWebSocket: (url: string) => typeof socket }
+    ).createWebSocket("wss://gateway.discord.gg");
+    (plugin as unknown as { ws: unknown }).ws = createdSocket;
+
+    try {
+      createdSocket.emit("message", Buffer.from("{}"));
+
+      expect(activitySpy).toHaveBeenCalledWith({ at: 1_700_000_000_000 });
+    } finally {
+      dateNowSpy.mockRestore();
+    }
+  });
+
+  it("ignores messages from stale gateway sockets", () => {
+    const staleSocket = new EventEmitter() as EventEmitter & { binaryType?: string };
+    const currentSocket = new EventEmitter();
+    const plugin = createPlugin({
+      webSocketCtor: function WebSocketCtor() {
+        return staleSocket;
+      } as unknown as NonNullable<
+        Parameters<typeof createDiscordGatewayPlugin>[0]["testing"]
+      >["webSocketCtor"],
+    });
+    const activitySpy = vi.fn();
+    (
+      plugin as unknown as {
+        emitter: { on: (event: string, listener: (value: unknown) => void) => void };
+      }
+    ).emitter.on(DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT, activitySpy);
+
+    const createdSocket = (
+      plugin as unknown as { createWebSocket: (url: string) => typeof staleSocket }
+    ).createWebSocket("wss://gateway.discord.gg");
+    expect(createdSocket).toBe(staleSocket);
+    (plugin as unknown as { ws: unknown }).ws = currentSocket;
+
+    staleSocket.emit("message", Buffer.from("{}"));
+
+    expect(activitySpy).not.toHaveBeenCalled();
+  });
+});