@gakr-gakr/discord 0.1.0

package/src/internal/event-queue.ts

@@ -0,0 +1,185 @@
+export type DiscordEventQueueOptions = {
+  maxQueueSize?: number;
+  maxConcurrency?: number;
+  listenerTimeout?: number;
+  slowListenerThreshold?: number;
+};
+
+type DiscordEventQueueJob = {
+  eventType: string;
+  listenerName: string;
+  run: () => Promise<void>;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+};
+
+type DiscordEventQueueMetrics = {
+  queueSize: number;
+  processing: number;
+  processed: number;
+  dropped: number;
+  timeouts: number;
+  maxQueueSize: number;
+  maxConcurrency: number;
+};
+
+const DEFAULT_MAX_QUEUE_SIZE = 10_000;
+const DEFAULT_MAX_CONCURRENCY = 50;
+const DEFAULT_LISTENER_TIMEOUT_MS = 120_000;
+const DEFAULT_SLOW_LISTENER_THRESHOLD_MS = 30_000;
+
+export class DiscordEventQueue {
+  private readonly options: Required<DiscordEventQueueOptions>;
+  private readonly queue: DiscordEventQueueJob[] = [];
+  private queueHead = 0;
+  private processing = 0;
+  private processedCount = 0;
+  private droppedCount = 0;
+  private timeoutCount = 0;
+
+  constructor(options: DiscordEventQueueOptions = {}) {
+    this.options = {
+      maxQueueSize: normalizePositiveInteger(options.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE),
+      maxConcurrency: normalizePositiveInteger(options.maxConcurrency, DEFAULT_MAX_CONCURRENCY),
+      listenerTimeout: normalizePositiveInteger(
+        options.listenerTimeout,
+        DEFAULT_LISTENER_TIMEOUT_MS,
+      ),
+      slowListenerThreshold: normalizePositiveInteger(
+        options.slowListenerThreshold,
+        DEFAULT_SLOW_LISTENER_THRESHOLD_MS,
+      ),
+    };
+  }
+
+  enqueue(params: Omit<DiscordEventQueueJob, "resolve" | "reject">): Promise<void> {
+    if (this.pendingQueueSize >= this.options.maxQueueSize) {
+      this.droppedCount += 1;
+      return Promise.reject(
+        new Error(
+          `Discord event queue is full for ${params.eventType}; maxQueueSize=${this.options.maxQueueSize}`,
+        ),
+      );
+    }
+    return new Promise<void>((resolve, reject) => {
+      this.queue.push({ ...params, resolve, reject });
+      this.processNext();
+    });
+  }
+
+  getMetrics(): DiscordEventQueueMetrics {
+    return {
+      queueSize: this.pendingQueueSize,
+      processing: this.processing,
+      processed: this.processedCount,
+      dropped: this.droppedCount,
+      timeouts: this.timeoutCount,
+      maxQueueSize: this.options.maxQueueSize,
+      maxConcurrency: this.options.maxConcurrency,
+    };
+  }
+
+  private get pendingQueueSize(): number {
+    return Math.max(0, this.queue.length - this.queueHead);
+  }
+
+  private takeNextJob(): DiscordEventQueueJob | undefined {
+    if (this.queueHead >= this.queue.length) {
+      this.queue.length = 0;
+      this.queueHead = 0;
+      return undefined;
+    }
+    const job = this.queue[this.queueHead];
+    this.queueHead += 1;
+    if (this.queueHead >= this.queue.length) {
+      this.queue.length = 0;
+      this.queueHead = 0;
+    } else if (this.queueHead > 256 && this.queueHead * 2 > this.queue.length) {
+      this.queue.splice(0, this.queueHead);
+      this.queueHead = 0;
+    }
+    return job;
+  }
+
+  private processNext(): void {
+    while (this.processing < this.options.maxConcurrency && this.pendingQueueSize > 0) {
+      const job = this.takeNextJob();
+      if (!job) {
+        return;
+      }
+      this.processing += 1;
+      void this.runJob(job)
+        .then(job.resolve, job.reject)
+        .finally(() => {
+          this.processing -= 1;
+          this.processedCount += 1;
+          this.processNext();
+        });
+    }
+  }
+
+  private async runJob(job: DiscordEventQueueJob): Promise<void> {
+    const startedAt = Date.now();
+    try {
+      await this.runWithTimeout(job);
+      this.logSlowListener(job, Date.now() - startedAt);
+    } catch (error) {
+      if (isListenerTimeoutError(error)) {
+        this.timeoutCount += 1;
+        console.error(
+          `[EventQueue] Listener ${job.listenerName} timed out after ${this.options.listenerTimeout}ms for event ${job.eventType}`,
+        );
+        return;
+      }
+      console.error(
+        `[EventQueue] Listener ${job.listenerName} failed for event ${job.eventType}:`,
+        error,
+      );
+    }
+  }
+
+  private async runWithTimeout(job: DiscordEventQueueJob): Promise<void> {
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        job.run(),
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(() => {
+            reject(createListenerTimeoutError(this.options.listenerTimeout));
+          }, this.options.listenerTimeout);
+          timeout.unref?.();
+        }),
+      ]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  }
+
+  private logSlowListener(job: DiscordEventQueueJob, durationMs: number): void {
+    if (durationMs < this.options.slowListenerThreshold) {
+      return;
+    }
+    console.warn(
+      `[EventQueue] Slow listener detected: ${job.listenerName} took ${durationMs}ms for event ${job.eventType}`,
+    );
+  }
+}
+
+function normalizePositiveInteger(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function createListenerTimeoutError(timeoutMs: number): Error {
+  const error = new Error(`Listener timeout after ${timeoutMs}ms`);
+  error.name = "DiscordEventQueueListenerTimeoutError";
+  return error;
+}
+
+function isListenerTimeoutError(error: unknown): boolean {
+  return error instanceof Error && error.name === "DiscordEventQueueListenerTimeoutError";
+}

package/src/internal/gateway-close-codes.ts

@@ -0,0 +1,25 @@
+import { GatewayCloseCodes } from "discord-api-types/v10";
+
+const fatalGatewayCloseCodes = new Set<GatewayCloseCodes>([
+  GatewayCloseCodes.AuthenticationFailed,
+  GatewayCloseCodes.InvalidShard,
+  GatewayCloseCodes.ShardingRequired,
+  GatewayCloseCodes.InvalidAPIVersion,
+  GatewayCloseCodes.InvalidIntents,
+  GatewayCloseCodes.DisallowedIntents,
+]);
+
+const nonResumableGatewayCloseCodes = new Set<GatewayCloseCodes>([
+  GatewayCloseCodes.NotAuthenticated,
+  GatewayCloseCodes.InvalidSeq,
+  GatewayCloseCodes.SessionTimedOut,
+  GatewayCloseCodes.AlreadyAuthenticated,
+]);
+
+export function isFatalGatewayCloseCode(code: GatewayCloseCodes): boolean {
+  return fatalGatewayCloseCodes.has(code);
+}
+
+export function canResumeAfterGatewayClose(code: GatewayCloseCodes): boolean {
+  return !nonResumableGatewayCloseCodes.has(code);
+}

package/src/internal/gateway-dispatch.ts

@@ -0,0 +1,96 @@
+import { GatewayDispatchEvents, type APIMessage, type APIUser } from "discord-api-types/v10";
+import type { Client } from "./client.js";
+import { Guild, Message, User } from "./structures.js";
+
+type VoicePluginAdapter = {
+  onVoiceServerUpdate?: (data: unknown) => void;
+  onVoiceStateUpdate?: (data: unknown) => void;
+};
+
+export function dispatchVoiceGatewayEvent(client: Client, type: string, data: unknown): void {
+  const guildId = readGuildId(data);
+  if (!guildId) {
+    return;
+  }
+  const adapters = client.getPlugin<{ adapters?: Map<string, VoicePluginAdapter> }>(
+    "voice",
+  )?.adapters;
+  const adapter = adapters?.get(guildId);
+  const voiceServerUpdate: string = GatewayDispatchEvents.VoiceServerUpdate;
+  const voiceStateUpdate: string = GatewayDispatchEvents.VoiceStateUpdate;
+  if (type === voiceServerUpdate) {
+    adapter?.onVoiceServerUpdate?.(data);
+  }
+  if (type === voiceStateUpdate) {
+    adapter?.onVoiceStateUpdate?.(data);
+  }
+}
+
+export function mapGatewayDispatchData(client: Client, type: string, data: unknown): unknown {
+  const messageCreate: string = GatewayDispatchEvents.MessageCreate;
+  const reactionAdd: string = GatewayDispatchEvents.MessageReactionAdd;
+  const reactionRemove: string = GatewayDispatchEvents.MessageReactionRemove;
+  if (type === messageCreate) {
+    return createMessageDispatchData(client, data as MessageCreatePayload);
+  }
+  if (type === reactionAdd || type === reactionRemove) {
+    return createReactionDispatchData(client, data as ReactionPayload);
+  }
+  return data;
+}
+
+type MessageCreatePayload = {
+  id: string;
+  channel_id: string;
+  guild_id?: string;
+  author?: APIUser;
+  member?: { roles?: string[] };
+};
+
+function createMessageDispatchData(client: Client, data: MessageCreatePayload) {
+  const message = new Message(client, data as APIMessage);
+  return {
+    ...data,
+    id: data.id,
+    channel_id: data.channel_id,
+    channelId: data.channel_id,
+    message,
+    author: message.author ?? (data.author ? new User(client, data.author) : null),
+    member: data.member,
+    rawMember: data.member,
+    guild: data.guild_id ? new Guild<true>(client, data.guild_id) : null,
+  };
+}
+
+type ReactionPayload = {
+  user_id: string;
+  channel_id: string;
+  message_id: string;
+  guild_id?: string;
+  member?: { user?: unknown; roles?: string[] };
+};
+
+function createReactionDispatchData(client: Client, data: ReactionPayload) {
+  const userRaw =
+    data.member?.user && typeof data.member.user === "object"
+      ? ({ id: data.user_id, username: "", ...data.member.user } as APIUser)
+      : ({ id: data.user_id, username: "" } as APIUser);
+  return {
+    ...data,
+    user: new User(client, userRaw),
+    rawMember: data.member,
+    guild: data.guild_id ? new Guild<true>(client, data.guild_id) : null,
+    message: new Message<true>(client, {
+      id: data.message_id,
+      channelId: data.channel_id,
+    }),
+  };
+}
+
+function readGuildId(data: unknown): string | undefined {
+  return data &&
+    typeof data === "object" &&
+    typeof (data as { guild_id?: unknown }).guild_id === "string"
+    ? (data as { guild_id: string }).guild_id
+    : undefined;
+}

package/src/internal/gateway-identify-limiter.ts

@@ -0,0 +1,26 @@
+const IDENTIFY_WINDOW_MS = 5_000;
+
+class GatewayIdentifyLimiter {
+  private nextAllowedAtByKey = new Map<number, number>();
+
+  async wait(params: { shardId?: number; maxConcurrency?: number }): Promise<void> {
+    const maxConcurrency = Math.max(1, Math.floor(params.maxConcurrency ?? 1));
+    const rateKey = (params.shardId ?? 0) % maxConcurrency;
+    const now = Date.now();
+    const nextAllowedAt = this.nextAllowedAtByKey.get(rateKey) ?? now;
+    const waitMs = Math.max(0, nextAllowedAt - now);
+    this.nextAllowedAtByKey.set(rateKey, Math.max(now, nextAllowedAt) + IDENTIFY_WINDOW_MS);
+    if (waitMs > 0) {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, waitMs);
+        timer.unref?.();
+      });
+    }
+  }
+
+  reset(): void {
+    this.nextAllowedAtByKey.clear();
+  }
+}
+
+export const sharedGatewayIdentifyLimiter = new GatewayIdentifyLimiter();

package/src/internal/gateway-lifecycle.ts

@@ -0,0 +1,75 @@
+type GatewayTimer = NodeJS.Timeout;
+
+export class GatewayHeartbeatTimers {
+  heartbeatInterval?: GatewayTimer;
+  firstHeartbeatTimeout?: GatewayTimer;
+
+  private scheduleHeartbeatCycle(params: {
+    intervalMs: number;
+    isAcked: () => boolean;
+    onAckTimeout: () => void;
+    onHeartbeat: () => void;
+  }): void {
+    this.heartbeatInterval = setTimeout(() => {
+      this.heartbeatInterval = undefined;
+      if (!params.isAcked()) {
+        params.onAckTimeout();
+        return;
+      }
+      params.onHeartbeat();
+      this.scheduleHeartbeatCycle(params);
+    }, params.intervalMs);
+    this.heartbeatInterval.unref?.();
+  }
+
+  start(params: {
+    intervalMs: number;
+    isAcked: () => boolean;
+    onAckTimeout: () => void;
+    onHeartbeat: () => void;
+    random?: () => number;
+  }): void {
+    this.stop();
+    const random = params.random ?? Math.random;
+    this.firstHeartbeatTimeout = setTimeout(
+      () => {
+        this.firstHeartbeatTimeout = undefined;
+        params.onHeartbeat();
+        this.scheduleHeartbeatCycle(params);
+      },
+      Math.max(0, params.intervalMs * random()),
+    );
+    this.firstHeartbeatTimeout.unref?.();
+  }
+
+  stop(): void {
+    if (this.heartbeatInterval) {
+      clearTimeout(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+    if (this.firstHeartbeatTimeout) {
+      clearTimeout(this.firstHeartbeatTimeout);
+      this.firstHeartbeatTimeout = undefined;
+    }
+  }
+}
+
+export class GatewayReconnectTimer {
+  timeout?: GatewayTimer;
+
+  stop(): void {
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+      this.timeout = undefined;
+    }
+  }
+
+  schedule(delayMs: number, callback: () => void): void {
+    this.stop();
+    this.timeout = setTimeout(() => {
+      this.timeout = undefined;
+      callback();
+    }, delayMs);
+    this.timeout.unref?.();
+  }
+}

package/src/internal/gateway-rate-limit.ts

@@ -0,0 +1,104 @@
+const GATEWAY_SEND_LIMIT = 120;
+const GATEWAY_SEND_WINDOW_MS = 60_000;
+
+type QueuedGatewaySend = {
+  payload: string;
+};
+
+export class GatewaySendLimiter {
+  private outboundSendTimestamps: number[] = [];
+  private outboundQueue: QueuedGatewaySend[] = [];
+  private outboundFlushTimer?: NodeJS.Timeout;
+
+  constructor(
+    private sendNow: (payload: string) => void,
+    private emitError: (error: Error) => void,
+  ) {}
+
+  send(serialized: string, options?: { critical?: boolean }): void {
+    if (options?.critical || this.canSend(Date.now())) {
+      this.sendSerialized(serialized);
+      return;
+    }
+    this.outboundQueue.push({ payload: serialized });
+    this.scheduleFlush();
+  }
+
+  clear(): void {
+    if (this.outboundFlushTimer) {
+      clearTimeout(this.outboundFlushTimer);
+      this.outboundFlushTimer = undefined;
+    }
+    this.outboundQueue = [];
+  }
+
+  getStatus() {
+    const now = Date.now();
+    this.pruneWindow(now);
+    const oldest = this.outboundSendTimestamps[0] ?? now;
+    return {
+      remainingEvents: Math.max(0, GATEWAY_SEND_LIMIT - this.outboundSendTimestamps.length),
+      resetTime:
+        this.outboundSendTimestamps.length > 0
+          ? oldest + GATEWAY_SEND_WINDOW_MS
+          : now + GATEWAY_SEND_WINDOW_MS,
+      currentEventCount: this.outboundSendTimestamps.length,
+      queuedEvents: this.outboundQueue.length,
+    };
+  }
+
+  private pruneWindow(now: number): void {
+    const windowStart = now - GATEWAY_SEND_WINDOW_MS;
+    while (
+      this.outboundSendTimestamps.length > 0 &&
+      (this.outboundSendTimestamps[0] ?? 0) <= windowStart
+    ) {
+      this.outboundSendTimestamps.shift();
+    }
+  }
+
+  private canSend(now: number): boolean {
+    this.pruneWindow(now);
+    return this.outboundSendTimestamps.length < GATEWAY_SEND_LIMIT;
+  }
+
+  private sendSerialized(serialized: string): void {
+    this.outboundSendTimestamps.push(Date.now());
+    this.sendNow(serialized);
+  }
+
+  private scheduleFlush(): void {
+    if (this.outboundFlushTimer || this.outboundQueue.length === 0) {
+      return;
+    }
+    const now = Date.now();
+    this.pruneWindow(now);
+    const oldest = this.outboundSendTimestamps[0] ?? now;
+    const delayMs =
+      this.outboundSendTimestamps.length >= GATEWAY_SEND_LIMIT
+        ? Math.max(0, oldest + GATEWAY_SEND_WINDOW_MS - now)
+        : 0;
+    this.outboundFlushTimer = setTimeout(() => {
+      this.outboundFlushTimer = undefined;
+      this.flush();
+    }, delayMs);
+    this.outboundFlushTimer.unref?.();
+  }
+
+  private flush(): void {
+    while (this.outboundQueue.length > 0 && this.canSend(Date.now())) {
+      const queued = this.outboundQueue.shift();
+      if (!queued) {
+        continue;
+      }
+      try {
+        this.sendSerialized(queued.payload);
+      } catch (error) {
+        this.emitError(error instanceof Error ? error : new Error(String(error), { cause: error }));
+        this.clear();
+        return;
+      }
+    }
+    this.scheduleFlush();
+  }
+}