lunibee 0.2.3 → 0.3.0

package/dist/ws/decoder.d.ts

@@ -42,8 +42,12 @@ export declare class PlainTextDecoder implements GatewayDecoder {
  */
 export declare class ZlibStreamDecoder implements GatewayDecoder {
     #private;
-    /** @param create Inflater factory; injected in tests. */
-    constructor(create?: () => Inflate);
+    /**
+     * @param create Inflater factory; injected in tests.
+     * @param maxFrameBytes Largest inflated frame accepted (default 64 MiB);
+     * past it the stream fails instead of growing until memory runs out.
+     */
+    constructor(create?: () => Inflate, maxFrameBytes?: number);
     /**
      * A text frame on a compressed connection is already a complete frame, so
      * it is returned synchronously and never touches the inflater. Discord

package/dist/ws/dispatcher.d.ts

@@ -0,0 +1,19 @@
+/** Gateway event listener. */
+export type GatewayListener = (data: unknown) => unknown;
+/**
+ * Listener registry and emission for one Gateway.
+ *
+ * A listener that throws, or returns a promise that rejects, is isolated from
+ * the others and reported through `onFailure`, except for `error` listeners:
+ * a failing error listener must not report itself again.
+ */
+export declare class GatewayDispatcher {
+    #private;
+    constructor(onFailure: (error: unknown) => void);
+    /** Adds a listener. */
+    on(event: string, listener: GatewayListener): void;
+    /** Removes a listener. */
+    off(event: string, listener: GatewayListener): void;
+    /** Calls the listeners of `event` with `data`. */
+    emit(event: string, data: unknown): void;
+}

package/dist/ws/index.d.ts

@@ -1,29 +1,48 @@
 import { type SocketFactory } from "./transport.js";
 import { type GatewayPayload, type GatewayProperties, type GatewayPresence, type GatewayIntentResolvable } from "@lunibee/types";
-export { classifyFrame, classifyPayload, identifyPayload, resumePayload, heartbeatPayload, type GatewayAction, type ProtocolResult, type ProtocolViolation, type IdentifyOptions, type IdentifyProperties, } from "./protocol.js";
+export { classifyFrame, classifyPayload, identifyPayload, resumePayload, heartbeatPayload, type GatewayAction, type ProtocolResult, type ProtocolViolation, type IdentifyOptions, type IdentifyProperties, type IdentifyData, } from "./protocol.js";
 export { WebSocketTransport, type TransportHandlers, type TransportOptions, type SocketFactory, } from "./transport.js";
 export { createDecoder, PlainTextDecoder, ZlibStreamDecoder, type GatewayDecoder, } from "./decoder.js";
 export { GatewayReconnect, classifyCloseCode, FATAL_CLOSE_CODES, IDENTIFY_CLOSE_CODES, type CloseAction, type ReconnectOptions, type ScheduleResult, type ScheduleRefusal, } from "./reconnect.js";
 export { GatewayHeartbeat, type HeartbeatOptions, type HeartbeatTimeout, } from "./heartbeat.js";
 export { GatewaySession, type ResumeInfo, type HandshakeIntent, type InvalidationReason, } from "./session.js";
+export { GatewayDispatcher, type GatewayListener } from "./dispatcher.js";
+export { GatewaySendLimiter, SendBudget } from "./send-budget.js";
 export { GatewayOpcodes } from "./opcodes.js";
 export { GatewayCloseCodes } from "./close-codes.js";
 export { GatewayState, Status, GatewayError } from "./state.js";
 import { GatewayState } from "./state.js";
+import { type GatewayListener } from "./dispatcher.js";
 /** Gateway connection configuration. */
 export interface GatewayOptions {
-    /** Authentication token. */ token: string;
-    /** Gateway intent bitfield or resolvable. */ intents: GatewayIntentResolvable;
-    /** Shard identifier. */ shardId?: number;
-    /** Total shard count. */ shardCount?: number;
-    /** Whether automatic reconnect is enabled. */ reconnect?: boolean;
-    /** Maximum reconnect attempts. */ maxReconnectAttempts?: number;
-    /** Initial reconnect delay. */ reconnectBaseDelay?: number;
-    /** Maximum reconnect delay. */ reconnectMaxDelay?: number;
-    /** Heartbeat acknowledgement timeout. */ heartbeatAckTimeout?: number;
-    /** Zombie connection timeout. */ zombieTimeout?: number;
-    /** Identification properties. */ properties?: GatewayProperties;
-    /** Presence data. */ presence?: GatewayPresence;
+    /** Authentication token. */
+    token: string;
+    /** Gateway intent bitfield or resolvable. */
+    intents: GatewayIntentResolvable;
+    /** Shard identifier. */
+    shardId?: number;
+    /** Total shard count. */
+    shardCount?: number;
+    /** Whether automatic reconnect is enabled. */
+    reconnect?: boolean;
+    /** Maximum reconnect attempts. */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay. */
+    reconnectBaseDelay?: number;
+    /** Maximum reconnect delay. */
+    reconnectMaxDelay?: number;
+    /** Heartbeat acknowledgement timeout. */
+    heartbeatAckTimeout?: number;
+    /** Zombie connection timeout. */
+    zombieTimeout?: number;
+    /** Reconnects inside `reconnectStormWindow` after which the link counts as unstable: `unstable` is emitted and the delay keeps doubling. Default 5. */
+    reconnectStormLimit?: number;
+    /** The span over which reconnects are counted for storm detection, in ms. Default 60,000. */
+    reconnectStormWindow?: number;
+    /** Identification properties. */
+    properties?: GatewayProperties;
+    /** Presence data. */
+    presence?: GatewayPresence;
     /**
      * Whether to enable zlib-stream transport compression.
      * Decoded with a persistent `node:zlib` inflate stream, matching
@@ -37,8 +56,17 @@ export interface GatewayOptions {
      */
     createSocket?: SocketFactory;
 }
-/** Gateway event listener. */
-type GatewayListener = (data: unknown) => unknown;
+/** What {@link Gateway.health} reports. */
+export interface GatewayHealth {
+    /** Connection lifecycle state. */
+    state: GatewayState;
+    /** Round trip of the last acknowledged heartbeat in ms, or -1 before the first. */
+    latency: number;
+    /** Milliseconds since the last message from Discord, or 0 before any. */
+    silentFor: number;
+    /** Reconnects scheduled since this Gateway was created. */
+    reconnects: number;
+}
 /** Manages a Discord Gateway connection. */
 export declare class Gateway {
     #private;
@@ -57,12 +85,30 @@ export declare class Gateway {
     on(event: string, listener: GatewayListener): this;
     /** Removes a Gateway event listener. @param event Event name. @param listener Event callback. @returns This Gateway. */
     off(event: string, listener: GatewayListener): this;
+    /**
+     * A snapshot for dashboards and health checks: connection state, last
+     * heartbeat round trip, how long the link has been silent, and how many
+     * times it has reconnected.
+     */
+    health(): GatewayHealth;
     /** Sends a Gateway payload. @param payload Gateway payload. @returns Whether it was sent. */
     send(payload: GatewayPayload): boolean;
     /** Sends a presence update. @param data Presence payload. @returns Whether it was sent. */
     setPresence(data: GatewayPresence): boolean;
     /** Sends a voice state update. @param data Voice state payload. @returns Whether it was sent. */
     setVoiceState(data: Record<string, unknown>): boolean;
+    /**
+     * Joins, moves or leaves a voice channel (op 4). Returns `false` without
+     * sending when the guild belongs to another shard, or when disconnected.
+     * @param guildId Guild snowflake. @param channelId Channel to join, or `null` to leave.
+     * @param options `selfMute` and `selfDeaf`, both default `false`. @returns Whether it was sent.
+     */
+    sendVoiceState(guildId: string, channelId: string | null, options?: {
+        selfMute?: boolean;
+        selfDeaf?: boolean;
+    }): boolean;
+    /** Whether `guildId` maps to this Gateway's shard (`(id >> 22) % shardCount === shardId`). */
+    ownsGuild(guildId: string): boolean;
     /** Requests guild members. @param data Guild member request payload. @returns Whether it was sent. */
     requestGuildMembers(data: Record<string, unknown>): boolean;
 }

package/dist/ws/index.js

@@ -73,7 +73,26 @@ class GatewaySession {
     return resume ? { type: "resume", ...resume } : { type: "identify" };
   }
   connectURL(fallback) {
-    return this.resumeInfo()?.resumeURL ?? fallback;
+    const resume = this.resumeInfo()?.resumeURL;
+    return resume !== undefined && isTrustedGatewayURL(resume, fallback) ? resume : fallback;
+  }
+}
+function isTrustedGatewayURL(url, fallback) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "wss:" || parsed.username || parsed.password)
+    return false;
+  const host = parsed.hostname.toLowerCase();
+  if (host === "discord.gg" || host.endsWith(".discord.gg"))
+    return true;
+  try {
+    return host === new URL(fallback).hostname.toLowerCase();
+  } catch {
+    return false;
   }
 }
 
@@ -245,6 +264,7 @@ class GatewayReconnect {
   #options;
   #random;
   #attempt = 0;
+  #recent = [];
   #timer;
   #promise;
   #resolve;
@@ -285,14 +305,29 @@ class GatewayReconnect {
     if (this.exhausted)
       return { scheduled: false, reason: "exhausted" };
     const attempt = this.#attempt;
-    const delay = Math.min(this.#options.maxDelay, this.#options.baseDelay * 2 ** this.#attempt++);
+    const now = (this.#options.now ?? Date.now)();
+    const window = this.#options.stormWindow ?? 60000;
+    const limit = this.#options.stormLimit ?? 5;
+    while (this.#recent.length && now - this.#recent[0] >= window)
+      this.#recent.shift();
+    const over = this.#recent.length - limit;
+    this.#recent.push(now);
+    let delay = Math.min(this.#options.maxDelay, this.#options.baseDelay * 2 ** this.#attempt++);
+    const unstable = over >= 0;
+    if (unstable)
+      delay = Math.min(this.#options.maxDelay, Math.max(delay, this.#options.baseDelay * 2 ** (over + 1)));
     const jitter = this.#random() * Math.max(1, delay * 0.25);
     const delayMs = delay + jitter;
     this.#timer = setTimeout(() => {
       this.#timer = undefined;
       run();
     }, delayMs);
-    return { scheduled: true, delayMs, attempt };
+    return {
+      scheduled: true,
+      delayMs,
+      attempt,
+      ...unstable ? { unstable: { reconnects: this.#recent.length } } : {}
+    };
   }
   cancel() {
     if (this.#timer)
@@ -349,12 +384,15 @@ class PlainTextDecoder {
 
 class ZlibStreamDecoder {
   #create;
+  #maxFrameBytes;
   #inflate;
   #chunks = [];
+  #size = 0;
   #failure;
   #pendingReject;
-  constructor(create = () => createInflate()) {
+  constructor(create = () => createInflate(), maxFrameBytes = 64 * 1024 * 1024) {
     this.#create = create;
+    this.#maxFrameBytes = maxFrameBytes;
   }
   push(data) {
     if (typeof data === "string")
@@ -373,6 +411,7 @@ class ZlibStreamDecoder {
     await this.#awaiting((settle) => inflate.flush(zlibConstants.Z_SYNC_FLUSH, () => settle()));
     const parts = this.#chunks;
     this.#chunks = [];
+    this.#size = 0;
     if (parts.length === 0)
       return [];
     const total = parts.reduce((size, part) => size + part.length, 0);
@@ -388,6 +427,7 @@ class ZlibStreamDecoder {
     const inflate = this.#inflate;
     this.#inflate = undefined;
     this.#chunks = [];
+    this.#size = 0;
     this.#failure = undefined;
     this.#pendingReject = undefined;
     if (!inflate)
@@ -415,7 +455,17 @@ class ZlibStreamDecoder {
   }
   #open() {
     const inflate = this.#create();
-    inflate.on("data", (chunk) => this.#chunks.push(chunk));
+    inflate.on("data", (chunk) => {
+      if (this.#failure)
+        return;
+      this.#size += chunk.length;
+      if (this.#size > this.#maxFrameBytes) {
+        this.#chunks = [];
+        inflate.emit("error", new Error(`Gateway frame inflated past ${this.#maxFrameBytes} bytes.`));
+        return;
+      }
+      this.#chunks.push(chunk);
+    });
     inflate.on("error", (error) => {
       this.#failure = error;
       const reject = this.#pendingReject;
@@ -658,9 +708,9 @@ function classifyPayload(payload) {
 }
 function identifyPayload(options) {
   const props = options.properties ?? {};
-  const os = props.os ?? "Android";
-  const browser = props.browser ?? "Discord Android";
-  const device = props.device ?? "Discord Android";
+  const os = props.os ?? process.platform;
+  const browser = props.browser ?? "Lunibee";
+  const device = props.device ?? "Lunibee";
   return {
     op: GatewayOpcodes.Identify,
     d: {
@@ -703,6 +753,21 @@ function heartbeatPayload(sequence) {
   return { op: GatewayOpcodes.Heartbeat, d: sequence, s: null, t: null };
 }
 
+// packages/types/src/channel-kind.ts
+var ChannelKinds = {
+  text: [0],
+  dm: [1],
+  voice: [2],
+  "group-dm": [3],
+  category: [4],
+  announcement: [5],
+  thread: [10, 11, 12],
+  stage: [13],
+  directory: [14],
+  forum: [15],
+  media: [16]
+};
+var KIND_OF_TYPE = new Map(Object.keys(ChannelKinds).flatMap((kind) => ChannelKinds[kind].map((type) => [type, kind])));
 // packages/types/src/gateway.ts
 var GatewayIntentBits = {
   Guilds: 1 << 0,
@@ -756,52 +821,59 @@ var IntentBits = {
   directMessagePolls: 1 << 25
 };
 function resolveGatewayIntents(intents) {
-  if (typeof intents === "number")
-    return intents;
-  if (intents && typeof intents === "object" && !Array.isArray(intents))
-    return intents.bitfield;
-  if (Array.isArray(intents)) {
-    return intents.reduce((acc, intent) => {
-      return acc | resolveGatewayIntents(intent);
-    }, 0);
-  }
-  if (typeof intents === "string") {
-    if (intents in GatewayIntentBits)
-      return GatewayIntentBits[intents];
-    if (intents in IntentBits)
-      return IntentBits[intents];
-    const lower = intents.charAt(0).toLowerCase() + intents.slice(1);
-    if (lower in IntentBits)
-      return IntentBits[lower];
-    const num = Number(intents);
-    if (!Number.isNaN(num))
-      return num;
-  }
-  return 0;
+  if (!Array.isArray(intents))
+    throw new TypeError("Gateway intents must be an array, e.g. [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages].");
+  return intents.reduce((acc, intent) => acc | resolveIntent(intent), 0);
 }
-// packages/ws/src/state.ts
-var GatewayState;
-((GatewayState) => {
-  GatewayState["Connect"] = "CONNECT";
-  GatewayState["Hello"] = "HELLO";
-  GatewayState["Identify"] = "IDENTIFY";
-  GatewayState["Resume"] = "RESUME";
-  GatewayState["Ready"] = "READY";
-  GatewayState["Dispatch"] = "DISPATCH";
-  GatewayState["Heartbeat"] = "HEARTBEAT";
-  GatewayState["Reconnect"] = "RECONNECT";
-  GatewayState["Closed"] = "CLOSED";
-})(GatewayState ||= {});
-class GatewayError extends Error {
-  code;
-  constructor(message, code, options) {
-    super(message, options);
-    this.name = "GatewayError";
-    this.code = code;
+function resolveIntent(intent) {
+  if (typeof intent === "number")
+    return intent;
+  const bits = {
+    ...IntentBits,
+    ...GatewayIntentBits
+  };
+  const lower = intent.charAt(0).toLowerCase() + intent.slice(1);
+  if (Object.hasOwn(bits, intent))
+    return bits[intent];
+  if (Object.hasOwn(bits, lower))
+    return bits[lower];
+  const num = Number(intent);
+  return Number.isNaN(num) ? 0 : num;
+}
+// packages/ws/src/dispatcher.ts
+class GatewayDispatcher {
+  #listeners = new Map;
+  #onFailure;
+  constructor(onFailure) {
+    this.#onFailure = onFailure;
+  }
+  on(event, listener) {
+    let listeners = this.#listeners.get(event);
+    if (!listeners)
+      this.#listeners.set(event, listeners = new Set);
+    listeners.add(listener);
+  }
+  off(event, listener) {
+    this.#listeners.get(event)?.delete(listener);
+  }
+  emit(event, data) {
+    for (const listener of this.#listeners.get(event) ?? []) {
+      try {
+        const result = listener(data);
+        if (result && typeof result.then === "function")
+          Promise.resolve(result).catch((error) => {
+            if (event !== "error")
+              this.#onFailure(error);
+          });
+      } catch (error) {
+        if (event !== "error")
+          this.#onFailure(error);
+      }
+    }
   }
 }
 // packages/ws/src/send-budget.ts
-class SendBudget {
+class GatewaySendLimiter {
   #timestamps = [];
   #limit;
   #windowMs;
@@ -821,7 +893,28 @@ class SendBudget {
     this.#timestamps.push(now);
   }
 }
-
+var SendBudget = GatewaySendLimiter;
+// packages/ws/src/state.ts
+var GatewayState;
+((GatewayState) => {
+  GatewayState["Connect"] = "CONNECT";
+  GatewayState["Hello"] = "HELLO";
+  GatewayState["Identify"] = "IDENTIFY";
+  GatewayState["Resume"] = "RESUME";
+  GatewayState["Ready"] = "READY";
+  GatewayState["Dispatch"] = "DISPATCH";
+  GatewayState["Heartbeat"] = "HEARTBEAT";
+  GatewayState["Reconnect"] = "RECONNECT";
+  GatewayState["Closed"] = "CLOSED";
+})(GatewayState ||= {});
+class GatewayError extends Error {
+  code;
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "GatewayError";
+    this.code = code;
+  }
+}
 // packages/ws/src/index.ts
 var RESUMABLE_CLOSE_CODE = 4900;
 var DEFAULT_GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json";
@@ -835,8 +928,9 @@ class Gateway {
   #heartbeat;
   #closed = false;
   #reconnect;
-  #listeners = new Map;
-  #sendBudget = new SendBudget;
+  #events = new GatewayDispatcher((error) => this.#emitError(error));
+  #sendBudget = new GatewaySendLimiter;
+  #reconnects = 0;
   ping = -1;
   constructor(options) {
     if (!options.token?.trim())
@@ -854,9 +948,9 @@ class Gateway {
       heartbeatAckTimeout: 1e4,
       zombieTimeout: 30000,
       properties: {
-        os: "Android",
-        browser: "Discord Android",
-        device: "Discord Android"
+        os: process.platform,
+        browser: "Lunibee",
+        device: "Lunibee"
       },
       presence: {
         status: "online",
@@ -887,7 +981,9 @@ class Gateway {
       enabled: this.#options.reconnect,
       maxAttempts: this.#options.maxReconnectAttempts,
       baseDelay: this.#options.reconnectBaseDelay,
-      maxDelay: this.#options.reconnectMaxDelay
+      maxDelay: this.#options.reconnectMaxDelay,
+      stormLimit: options.reconnectStormLimit,
+      stormWindow: options.reconnectStormWindow
     });
     this.#heartbeat = new GatewayHeartbeat({
       ackTimeout: this.#options.heartbeatAckTimeout,
@@ -938,16 +1034,21 @@ class Gateway {
   on(event, listener) {
     if (!event || typeof listener !== "function")
       throw new TypeError("Gateway event and listener are required.");
-    let listeners = this.#listeners.get(event);
-    if (!listeners)
-      this.#listeners.set(event, listeners = new Set);
-    listeners.add(listener);
+    this.#events.on(event, listener);
     return this;
   }
   off(event, listener) {
-    this.#listeners.get(event)?.delete(listener);
+    this.#events.off(event, listener);
     return this;
   }
+  health() {
+    return {
+      state: this.state,
+      latency: this.#heartbeat.latency,
+      silentFor: this.#heartbeat.silentFor,
+      reconnects: this.#reconnects
+    };
+  }
   send(payload) {
     if (!payload || !Number.isInteger(payload.op))
       throw new TypeError("Gateway payload must contain an integer opcode.");
@@ -989,6 +1090,22 @@ class Gateway {
       t: null
     });
   }
+  sendVoiceState(guildId, channelId, options = {}) {
+    if (!this.ownsGuild(guildId))
+      return false;
+    return this.setVoiceState({
+      guild_id: guildId,
+      channel_id: channelId,
+      self_mute: options.selfMute ?? false,
+      self_deaf: options.selfDeaf ?? false
+    });
+  }
+  ownsGuild(guildId) {
+    const count = this.#options.shardCount;
+    if (count <= 1)
+      return true;
+    return Number((BigInt(guildId) >> 22n) % BigInt(count)) === this.#options.shardId;
+  }
   requestGuildMembers(data) {
     return this.send({
       op: GatewayOpcodes.RequestGuildMembers,
@@ -1126,7 +1243,16 @@ class Gateway {
     if (this.#closed)
       return;
     const result = this.#reconnect.schedule(() => this.#open(this.#session.connectURL(DEFAULT_GATEWAY_URL)));
-    if (result.scheduled || result.reason !== "exhausted")
+    if (result.scheduled) {
+      this.#reconnects++;
+      if (result.unstable)
+        this.#emit("unstable", {
+          reconnects: result.unstable.reconnects,
+          delay: result.delayMs
+        });
+      return;
+    }
+    if (result.reason !== "exhausted")
       return;
     this.#reconnect.settle(new GatewayError("Gateway reconnect attempts exhausted."));
     this.#setState("CONNECT" /* Connect */);
@@ -1147,19 +1273,7 @@ class Gateway {
     this.#emit("error", error instanceof Error ? error : new GatewayError(String(error)));
   }
   #emit(event, data) {
-    for (const listener of this.#listeners.get(event) ?? []) {
-      try {
-        const result = listener(data);
-        if (result && typeof result.then === "function")
-          Promise.resolve(result).catch((error) => {
-            if (event !== "error")
-              this.#emitError(error);
-          });
-      } catch (error) {
-        if (event !== "error")
-          this.#emitError(error);
-      }
-    }
+    this.#events.emit(event, data);
   }
   #setState(next) {
     if (this.state === next)
@@ -1173,14 +1287,17 @@ export {
   FATAL_CLOSE_CODES,
   Gateway,
   GatewayCloseCodes,
+  GatewayDispatcher,
   GatewayError,
   GatewayHeartbeat,
   GatewayOpcodes,
   GatewayReconnect,
+  GatewaySendLimiter,
   GatewaySession,
   GatewayState,
   IDENTIFY_CLOSE_CODES,
   PlainTextDecoder,
+  SendBudget,
   GatewayState as Status,
   WebSocketTransport,
   ZlibStreamDecoder,
@@ -1193,4 +1310,4 @@ export {
   resumePayload
 };
 
-//# debugId=3B9E4067E44200CD64756E2164756E21
+//# debugId=BCA247EAFCA9772B64756E2164756E21