@gakr-gakr/discord 0.1.0

package/src/internal/gateway.ts

@@ -0,0 +1,479 @@
+import { EventEmitter } from "node:events";
+import {
+  GatewayCloseCodes,
+  GatewayDispatchEvents,
+  GatewayIntentBits,
+  GatewayOpcodes,
+  type APIGatewayBotInfo,
+  type GatewayDispatchPayload,
+  type GatewayHeartbeat,
+  type GatewayIdentify,
+  type GatewayPresenceUpdateData,
+  type GatewayReceivePayload,
+  type GatewaySendPayload,
+  type GatewayVoiceStateUpdateData,
+} from "discord-api-types/v10";
+import * as ws from "ws";
+import { Plugin, type Client } from "./client.js";
+import { canResumeAfterGatewayClose, isFatalGatewayCloseCode } from "./gateway-close-codes.js";
+import { dispatchVoiceGatewayEvent, mapGatewayDispatchData } from "./gateway-dispatch.js";
+import { sharedGatewayIdentifyLimiter } from "./gateway-identify-limiter.js";
+import { GatewayHeartbeatTimers, GatewayReconnectTimer } from "./gateway-lifecycle.js";
+import { GatewaySendLimiter } from "./gateway-rate-limit.js";
+
+export { GatewayCloseCodes };
+export const GatewayIntents = GatewayIntentBits;
+export type Activity = NonNullable<GatewayPresenceUpdateData["activities"]>[number];
+export type UpdatePresenceData = Omit<GatewayPresenceUpdateData, "status"> & {
+  status: "online" | "idle" | "dnd" | "invisible" | "offline";
+};
+type UpdateVoiceStateData = GatewayVoiceStateUpdateData;
+type RequestGuildMembersData = {
+  guild_id: string;
+  query?: string;
+  limit: number;
+  presences?: boolean;
+  user_ids?: string | string[];
+  nonce?: string;
+};
+type GatewayPluginOptions = {
+  reconnect?: { maxAttempts?: number };
+  intents?: number;
+  autoInteractions?: boolean;
+  shard?: [number, number];
+  url?: string;
+};
+
+const READY_STATE_OPEN = 1;
+const DEFAULT_GATEWAY_URL = "wss://gateway.discord.gg/";
+const DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES = 4096;
+const INVALID_SESSION_MIN_DELAY_MS = 1_000;
+const INVALID_SESSION_JITTER_MS = 4_000;
+
+function ensureGatewayParams(url: string): string {
+  const parsed = new URL(url);
+  parsed.searchParams.set("v", parsed.searchParams.get("v") ?? "10");
+  parsed.searchParams.set("encoding", parsed.searchParams.get("encoding") ?? "json");
+  return parsed.toString();
+}
+
+function decodeGatewayMessage(incoming: unknown): GatewayReceivePayload | null {
+  const text = Buffer.isBuffer(incoming)
+    ? incoming.toString("utf8")
+    : incoming instanceof ArrayBuffer
+      ? Buffer.from(incoming).toString("utf8")
+      : Array.isArray(incoming)
+        ? Buffer.concat(incoming.map((entry) => Buffer.from(entry))).toString("utf8")
+        : String(incoming);
+  try {
+    return JSON.parse(text) as GatewayReceivePayload;
+  } catch {
+    return null;
+  }
+}
+
+export class GatewayPlugin extends Plugin {
+  readonly id = "gateway";
+  protected client?: Client;
+  readonly options: Required<Pick<GatewayPluginOptions, "autoInteractions">> & GatewayPluginOptions;
+  public ws: ws.WebSocket | null = null;
+  public sequence: number | null = null;
+  public lastHeartbeatAck = true;
+  public emitter = new EventEmitter();
+  public shardId?: number;
+  public totalShards?: number;
+  protected gatewayInfo?: APIGatewayBotInfo;
+  public isConnected = false;
+  private sessionId: string | null = null;
+  private resumeGatewayUrl: string | null = null;
+  private reconnectAttempts = 0;
+  private shouldReconnect = false;
+  private isConnecting = false;
+  private readonly heartbeatTimers = new GatewayHeartbeatTimers();
+  private readonly reconnectTimer = new GatewayReconnectTimer();
+  private outboundLimiter = new GatewaySendLimiter(
+    (payload) => this.sendSerializedGatewayEvent(payload),
+    (error) => this.emitter.emit("error", error),
+  );
+
+  constructor(options: GatewayPluginOptions, gatewayInfo?: APIGatewayBotInfo) {
+    super();
+    this.options = {
+      ...options,
+      reconnect: { maxAttempts: 50, ...options.reconnect },
+      autoInteractions: options.autoInteractions ?? true,
+      intents: options.intents ?? 0,
+    };
+    this.gatewayInfo = gatewayInfo;
+  }
+
+  get ping(): number | null {
+    return null;
+  }
+
+  get heartbeatInterval(): NodeJS.Timeout | undefined {
+    return this.heartbeatTimers.heartbeatInterval;
+  }
+
+  set heartbeatInterval(timer: NodeJS.Timeout | undefined) {
+    this.heartbeatTimers.heartbeatInterval = timer;
+  }
+
+  get firstHeartbeatTimeout(): NodeJS.Timeout | undefined {
+    return this.heartbeatTimers.firstHeartbeatTimeout;
+  }
+
+  set firstHeartbeatTimeout(timer: NodeJS.Timeout | undefined) {
+    this.heartbeatTimers.firstHeartbeatTimeout = timer;
+  }
+
+  override async registerClient(client: Client): Promise<void> {
+    this.client = client;
+    if (this.options.shard) {
+      client.shardId = this.options.shard[0];
+      client.totalShards = this.options.shard[1];
+      this.shardId = this.options.shard[0];
+      this.totalShards = this.options.shard[1];
+    }
+    this.shouldReconnect = true;
+    this.connect(false);
+  }
+
+  connect(resume = false): void {
+    this.stopReconnectTimer();
+    this.stopHeartbeat();
+    if (this.isConnecting) {
+      return;
+    }
+    this.shouldReconnect = true;
+    this.lastHeartbeatAck = true;
+    this.ws?.close(1000, "Reconnecting");
+    const baseUrl =
+      resume && this.resumeGatewayUrl
+        ? this.resumeGatewayUrl
+        : (this.gatewayInfo?.url ?? this.options.url ?? DEFAULT_GATEWAY_URL);
+    this.ws = this.createWebSocket(ensureGatewayParams(baseUrl));
+    this.isConnecting = true;
+    this.isConnected = false;
+    this.setupWebSocket(resume);
+  }
+
+  disconnect(): void {
+    this.shouldReconnect = false;
+    this.stopReconnectTimer();
+    this.stopHeartbeat();
+    this.outboundLimiter.clear();
+    this.ws?.close(1000, "Client disconnect");
+    this.ws = null;
+    this.isConnecting = false;
+    this.isConnected = false;
+    this.reconnectAttempts = 0;
+  }
+
+  protected createWebSocket(url: string): ws.WebSocket {
+    return new ws.WebSocket(url);
+  }
+
+  private setupWebSocket(resume: boolean): void {
+    const socket = this.ws;
+    if (!socket) {
+      return;
+    }
+    socket.on("open", () => {
+      if (socket !== this.ws) {
+        return;
+      }
+      this.isConnecting = false;
+      this.emitter.emit("debug", "Gateway websocket opened");
+    });
+    socket.on("message", (incoming) => {
+      if (socket !== this.ws) {
+        return;
+      }
+      const payload = decodeGatewayMessage(incoming);
+      if (!payload) {
+        this.emitter.emit("error", new Error("Invalid gateway payload"));
+        return;
+      }
+      this.handlePayload(payload, resume, socket);
+    });
+    socket.on("close", (code) => {
+      if (socket !== this.ws) {
+        return;
+      }
+      const closeCode = code as GatewayCloseCodes;
+      this.stopHeartbeat();
+      this.outboundLimiter.clear();
+      this.isConnecting = false;
+      this.isConnected = false;
+      this.emitter.emit("debug", `Gateway websocket closed: ${code}`);
+      if (!this.shouldReconnect) {
+        return;
+      }
+      if (isFatalGatewayCloseCode(closeCode)) {
+        this.shouldReconnect = false;
+        this.emitter.emit("error", new Error(`Fatal gateway close code: ${code}`));
+        return;
+      }
+      const canResume = canResumeAfterGatewayClose(closeCode);
+      if (!canResume) {
+        this.resetSessionState();
+      }
+      this.scheduleReconnect(canResume, closeCode);
+    });
+    socket.on("error", (error) => {
+      if (socket !== this.ws) {
+        return;
+      }
+      this.emitter.emit("error", error);
+    });
+  }
+
+  private handlePayload(
+    payload: GatewayReceivePayload,
+    resume: boolean,
+    sourceSocket?: ws.WebSocket,
+  ): void {
+    if (payload.s !== null && payload.s !== undefined) {
+      this.sequence = payload.s;
+    }
+    switch (payload.op) {
+      case GatewayOpcodes.Hello:
+        this.startHeartbeat(
+          (payload.d as { heartbeat_interval?: number }).heartbeat_interval ?? 45_000,
+        );
+        if (resume && this.sessionId) {
+          this.send(
+            {
+              op: GatewayOpcodes.Resume,
+              d: {
+                token: this.client?.options.token ?? "",
+                session_id: this.sessionId,
+                seq: this.sequence ?? 0,
+              },
+            } as GatewaySendPayload,
+            true,
+          );
+        } else {
+          void this.identifyWithConcurrency(sourceSocket).catch((error: unknown) => {
+            this.emitter.emit(
+              "error",
+              error instanceof Error ? error : new Error(String(error), { cause: error }),
+            );
+          });
+        }
+        break;
+      case GatewayOpcodes.HeartbeatAck:
+        this.lastHeartbeatAck = true;
+        break;
+      case GatewayOpcodes.Heartbeat:
+        this.sendHeartbeat();
+        break;
+      case GatewayOpcodes.Dispatch:
+        void this.handleDispatch(payload).catch((error: unknown) => {
+          this.emitter.emit(
+            "error",
+            error instanceof Error ? error : new Error(String(error), { cause: error }),
+          );
+        });
+        break;
+      case GatewayOpcodes.InvalidSession:
+        if (!payload.d) {
+          this.resetSessionState();
+        }
+        this.scheduleReconnect(
+          payload.d,
+          undefined,
+          INVALID_SESSION_MIN_DELAY_MS + Math.floor(Math.random() * INVALID_SESSION_JITTER_MS),
+        );
+        break;
+      case GatewayOpcodes.Reconnect:
+        this.scheduleReconnect(true);
+        break;
+    }
+  }
+
+  private startHeartbeat(intervalMs: number): void {
+    this.heartbeatTimers.start({
+      intervalMs,
+      isAcked: () => this.lastHeartbeatAck,
+      onHeartbeat: () => this.sendHeartbeat(),
+      onAckTimeout: () => {
+        this.emitter.emit("error", new Error("Gateway heartbeat ACK timeout"));
+        this.scheduleReconnect(true);
+      },
+    });
+  }
+
+  private stopHeartbeat(): void {
+    this.heartbeatTimers.stop();
+  }
+
+  private stopReconnectTimer(): void {
+    this.reconnectTimer.stop();
+  }
+
+  private sendHeartbeat(): void {
+    if (!this.ws || this.ws.readyState !== READY_STATE_OPEN) {
+      return;
+    }
+    this.lastHeartbeatAck = false;
+    this.send({ op: GatewayOpcodes.Heartbeat, d: this.sequence } as GatewayHeartbeat, true);
+  }
+
+  private identify(): void {
+    this.send(
+      {
+        op: GatewayOpcodes.Identify,
+        d: {
+          token: this.client?.options.token ?? "",
+          intents: this.options.intents ?? 0,
+          properties: { os: process.platform, browser: "autobot", device: "autobot" },
+          shard: this.options.shard,
+        },
+      } as GatewayIdentify,
+      true,
+    );
+  }
+
+  private async identifyWithConcurrency(sourceSocket?: ws.WebSocket): Promise<void> {
+    await sharedGatewayIdentifyLimiter.wait({
+      shardId: this.shardId,
+      maxConcurrency: this.gatewayInfo?.session_start_limit.max_concurrency,
+    });
+    const socket = sourceSocket ?? this.ws;
+    if (!socket || socket !== this.ws) {
+      return;
+    }
+    if (socket.readyState !== READY_STATE_OPEN) {
+      this.scheduleReconnect(false);
+      return;
+    }
+    this.identify();
+  }
+
+  send(payload: GatewaySendPayload | GatewayReceivePayload, skipRateLimit = false): void {
+    if (!this.ws || this.ws.readyState !== READY_STATE_OPEN) {
+      throw new Error("Discord gateway socket is not open");
+    }
+    const serialized = JSON.stringify(payload);
+    const payloadSize =
+      typeof Buffer !== "undefined"
+        ? Buffer.byteLength(serialized, "utf8")
+        : new TextEncoder().encode(serialized).byteLength;
+    if (payloadSize > DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES) {
+      throw new Error(
+        `Discord gateway payload exceeds ${DISCORD_GATEWAY_PAYLOAD_LIMIT_BYTES}-byte limit`,
+      );
+    }
+    this.outboundLimiter.send(serialized, { critical: skipRateLimit });
+  }
+
+  private sendSerializedGatewayEvent(serialized: string): void {
+    if (!this.ws || this.ws.readyState !== READY_STATE_OPEN) {
+      throw new Error("Discord gateway socket is not open");
+    }
+    this.ws.send(serialized);
+  }
+
+  private async handleDispatch(payload: GatewayDispatchPayload): Promise<void> {
+    if (!this.client || !payload.t) {
+      return;
+    }
+    if (payload.t === GatewayDispatchEvents.Ready) {
+      const ready = payload.d as { session_id?: string; resume_gateway_url?: string };
+      this.sessionId = ready.session_id ?? null;
+      this.resumeGatewayUrl = ready.resume_gateway_url ?? null;
+      this.reconnectAttempts = 0;
+      this.isConnected = true;
+    }
+    if (payload.t === GatewayDispatchEvents.Resumed) {
+      this.reconnectAttempts = 0;
+      this.isConnected = true;
+    }
+    dispatchVoiceGatewayEvent(this.client, payload.t, payload.d);
+    const data = mapGatewayDispatchData(this.client, payload.t, payload.d);
+    await this.client.dispatchGatewayEvent(payload.t, data);
+    if (payload.t === GatewayDispatchEvents.InteractionCreate && this.options.autoInteractions) {
+      await this.client.handleInteraction(payload.d);
+    }
+  }
+
+  private resetSessionState(): void {
+    this.sessionId = null;
+    this.resumeGatewayUrl = null;
+    this.sequence = null;
+  }
+
+  private scheduleReconnect(resume: boolean, closeCode?: number, minDelayMs = 0): void {
+    if (!this.shouldReconnect) {
+      return;
+    }
+    this.stopHeartbeat();
+    this.stopReconnectTimer();
+    this.ws?.close();
+    this.ws = null;
+    this.isConnecting = false;
+    this.isConnected = false;
+    this.outboundLimiter.clear();
+    this.reconnectAttempts += 1;
+    if (this.reconnectAttempts > (this.options.reconnect?.maxAttempts ?? 50)) {
+      const maxAttempts = this.options.reconnect?.maxAttempts ?? 50;
+      this.emitter.emit(
+        "error",
+        new Error(
+          `Max reconnect attempts (${maxAttempts}) reached${closeCode !== undefined ? ` after close code ${closeCode}` : ""}`,
+        ),
+      );
+      return;
+    }
+    const delay = Math.max(
+      minDelayMs,
+      Math.min(30_000, 1_000 * 2 ** Math.min(this.reconnectAttempts, 5)),
+    );
+    this.reconnectTimer.schedule(delay, () => {
+      this.connect(resume);
+    });
+  }
+
+  updatePresence(data: UpdatePresenceData): void {
+    this.send({ op: GatewayOpcodes.PresenceUpdate, d: data } as GatewaySendPayload);
+  }
+
+  updateVoiceState(data: UpdateVoiceStateData): void {
+    this.send({ op: GatewayOpcodes.VoiceStateUpdate, d: data } as GatewaySendPayload, true);
+  }
+
+  requestGuildMembers(data: RequestGuildMembersData): void {
+    if (!this.hasIntent(GatewayIntentBits.GuildMembers)) {
+      throw new Error("GUILD_MEMBERS intent is required for requestGuildMembers");
+    }
+    if (data.presences && !this.hasIntent(GatewayIntentBits.GuildPresences)) {
+      throw new Error("GUILD_PRESENCES intent is required when requesting presences");
+    }
+    if (!data.query && data.query !== "" && !data.user_ids) {
+      throw new Error("Either query or user_ids is required for requestGuildMembers");
+    }
+    this.send({ op: GatewayOpcodes.RequestGuildMembers, d: data } as GatewaySendPayload);
+  }
+
+  getRateLimitStatus() {
+    return this.outboundLimiter.getStatus();
+  }
+
+  getIntentsInfo() {
+    const intents = this.options.intents ?? 0;
+    return {
+      intents,
+      hasGuilds: this.hasIntent(GatewayIntentBits.Guilds),
+      hasGuildMembers: this.hasIntent(GatewayIntentBits.GuildMembers),
+      hasGuildPresences: this.hasIntent(GatewayIntentBits.GuildPresences),
+      hasGuildMessages: this.hasIntent(GatewayIntentBits.GuildMessages),
+      hasMessageContent: this.hasIntent(GatewayIntentBits.MessageContent),
+    };
+  }
+
+  hasIntent(intent: number): boolean {
+    return Boolean((this.options.intents ?? 0) & intent);
+  }
+}

package/src/internal/interaction-dispatch.ts

@@ -0,0 +1,162 @@
+import { InteractionType, type APIInteraction } from "discord-api-types/v10";
+import {
+  type BaseCommand,
+  deferCommandInteractionIfNeeded,
+  resolveFocusedCommandOptionAutocompleteHandler,
+} from "./commands.js";
+import {
+  AutocompleteInteraction,
+  BaseComponentInteraction,
+  CommandInteraction,
+  ModalInteraction,
+  createInteraction,
+  parseComponentInteractionData,
+  type RawInteraction,
+} from "./interactions.js";
+
+type DispatchComponent = {
+  defer: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  ephemeral: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  run(interaction: BaseComponentInteraction, data: Record<string, unknown>): unknown;
+  customIdParser(id: string): { data: Record<string, unknown> };
+};
+
+type DispatchModal = {
+  run(interaction: ModalInteraction, data: Record<string, unknown>): unknown;
+  customIdParser(id: string): { data: Record<string, unknown> };
+};
+
+type DispatchClient = Parameters<typeof createInteraction>[0] & {
+  commands: BaseCommand[];
+  componentHandler: {
+    resolve(customId: string, options?: { componentType?: number }): DispatchComponent | undefined;
+    resolveOneOffComponent(params: {
+      channelId?: string;
+      customId: string;
+      messageId?: string;
+      values?: string[];
+    }): boolean;
+  };
+  modalHandler: { resolve(customId: string): DispatchModal | undefined };
+};
+
+export async function dispatchInteraction(
+  client: DispatchClient,
+  rawData: APIInteraction,
+): Promise<void> {
+  const interaction = createInteraction(client, rawData as RawInteraction);
+  if (rawData.type === InteractionType.ApplicationCommandAutocomplete) {
+    const command = client.commands.find((entry) => entry.name === readInteractionName(rawData));
+    if (!command) {
+      return;
+    }
+    const autocompleteInteraction = interaction as AutocompleteInteraction;
+    const optionAutocomplete = resolveFocusedCommandOptionAutocompleteHandler(
+      command,
+      autocompleteInteraction,
+    );
+    if (optionAutocomplete) {
+      await optionAutocomplete(autocompleteInteraction);
+      return;
+    }
+    if ("autocomplete" in command) {
+      await (
+        command as { autocomplete: (interaction: AutocompleteInteraction) => Promise<void> }
+      ).autocomplete(autocompleteInteraction);
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.ApplicationCommand) {
+    const command = client.commands.find((entry) => entry.name === readInteractionName(rawData));
+    if (command && "run" in command) {
+      await deferCommandInteractionIfNeeded(command, interaction as CommandInteraction);
+      await (command as { run: (interaction: CommandInteraction) => Promise<void> }).run(
+        interaction as CommandInteraction,
+      );
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.MessageComponent) {
+    const customId = readCustomId(rawData);
+    if (!customId) {
+      return;
+    }
+    const componentInteraction = interaction as BaseComponentInteraction;
+    if (
+      client.componentHandler.resolveOneOffComponent({
+        channelId: readMessageChannelId(rawData),
+        customId,
+        messageId: readMessageId(rawData),
+        values: readComponentValues(rawData),
+      })
+    ) {
+      await componentInteraction.acknowledge();
+      return;
+    }
+    const component = client.componentHandler.resolve(customId, {
+      componentType: (rawData as { data?: { component_type?: number } }).data?.component_type,
+    });
+    if (component) {
+      await deferComponentInteractionIfNeeded(component, componentInteraction);
+      await component.run(componentInteraction, parseComponentInteractionData(component, customId));
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.ModalSubmit) {
+    const customId = readCustomId(rawData);
+    if (!customId) {
+      return;
+    }
+    const modal = client.modalHandler.resolve(customId);
+    if (modal) {
+      await modal.run(interaction as ModalInteraction, modal.customIdParser(customId).data);
+    }
+  }
+}
+
+function resolveConditionalComponentOption(
+  value: boolean | ((interaction: BaseComponentInteraction) => boolean),
+  interaction: BaseComponentInteraction,
+): boolean {
+  return typeof value === "function" ? value(interaction) : value;
+}
+
+async function deferComponentInteractionIfNeeded(
+  component: {
+    defer: boolean | ((interaction: BaseComponentInteraction) => boolean);
+    ephemeral: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  },
+  interaction: BaseComponentInteraction,
+): Promise<void> {
+  if (!resolveConditionalComponentOption(component.defer, interaction)) {
+    return;
+  }
+  if (resolveConditionalComponentOption(component.ephemeral, interaction)) {
+    await interaction.defer({ ephemeral: true });
+    return;
+  }
+  await interaction.acknowledge();
+}
+
+function readInteractionName(rawData: APIInteraction): string | undefined {
+  return (rawData as { data?: { name?: string } }).data?.name;
+}
+
+function readCustomId(rawData: APIInteraction): string | undefined {
+  return (rawData as { data?: { custom_id?: string } }).data?.custom_id;
+}
+
+function readComponentValues(rawData: APIInteraction): string[] | undefined {
+  const values = (rawData as { data?: { values?: unknown } }).data?.values;
+  return Array.isArray(values) ? values.map(String) : undefined;
+}
+
+function readMessageId(rawData: APIInteraction): string | undefined {
+  const messageId = (rawData as { message?: { id?: unknown } }).message?.id;
+  return typeof messageId === "string" ? messageId : undefined;
+}
+
+function readMessageChannelId(rawData: APIInteraction): string | undefined {
+  const channelId = (rawData as { message?: { channel_id?: unknown } }).message?.channel_id;
+  return typeof channelId === "string" ? channelId : undefined;
+}