@kodelyth/discord 2026.5.42 → 2026.6.1

package/src/monitor/gateway-metadata.ts

@@ -1,298 +0,0 @@
-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

@@ -1,320 +0,0 @@
-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();
-  });
-});