chapterjs 0.1.2 → 0.2.0

package/dist/gateway/shard.js

@@ -0,0 +1,414 @@
+// One WebSocket connection to the Discord gateway, kept alive for as long
+// as the bot runs: handshake, heartbeats, resuming after a disconnect.
+// https://docs.discord.com/developers/events/gateway#connections
+import { setTimeout as sleep } from 'node:timers/promises';
+import { API_VERSION } from '../discord/api.js';
+import { FATAL_GATEWAY_CLOSE_CODES, GatewayCloseCode, GatewayOpcode, } from '../discord/codes.js';
+import { onSocketEnd } from '../util/websocket.js';
+import { GatewayFatalError } from './errors.js';
+/**
+ * Apps can send 120 gateway events per connection every 60 seconds.
+ * @see https://docs.discord.com/developers/events/gateway#rate-limiting
+ */
+const SEND_LIMIT = 120;
+const SEND_WINDOW = 60_000;
+/** Kept free for heartbeats, which must never wait. */
+const SEND_RESERVE = 5;
+/**
+ * An event sent to Discord must not exceed 4096 bytes.
+ * @see https://docs.discord.com/developers/events/gateway#sending-events
+ */
+const MAX_PAYLOAD_BYTES = 4096;
+/**
+ * "Clients may only update their game status 5 times per 20 seconds."
+ * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+ */
+const PRESENCE_LIMIT = 5;
+const PRESENCE_WINDOW = 20_000;
+/**
+ * The code used to close a connection the shard wants to resume: any code
+ * but 1000 and 1001 keeps the session alive.
+ * @see https://docs.discord.com/developers/events/gateway#initiating-a-disconnect
+ */
+const CLOSE_AND_RESUME = 4000;
+/**
+ * Close codes after which the session is gone: the shard reconnects and
+ * identifies again.
+ */
+const SESSION_LOST = new Set([
+    1000,
+    1001,
+    GatewayCloseCode.NotAuthenticated,
+    GatewayCloseCode.InvalidSeq,
+    GatewayCloseCode.SessionTimedOut,
+]);
+const defaultBackoff = (attempt) => attempt === 0
+    ? 0
+    : Math.min(1000 * 2 ** (attempt - 1), 60_000) * (0.5 + Math.random() / 2);
+export class Shard {
+    id;
+    #options;
+    #status = 'idle';
+    #ws = null;
+    /** Whether the current connection got its Hello. */
+    #greeted = false;
+    // What a Resume needs, kept from the Ready event and the last dispatch.
+    #sessionId = null;
+    #resumeUrl = null;
+    #sequence = null;
+    // Heartbeats.
+    #heartbeatTimer = null;
+    #acknowledged = true;
+    #heartbeatSentAt = 0;
+    #ping = null;
+    /** Tries in a row that did not reach Ready or Resumed. */
+    #attempts = 0;
+    #retryTimer = null;
+    /** When the last events were sent, to respect the send limit. */
+    #sent = [];
+    // The presence: what Identify sends, and what Update Presence changes.
+    #presence;
+    /** Whether the current presence still has to be sent to Discord. */
+    #presencePending = false;
+    /** When the last presence updates were sent, to respect their limit. */
+    #presenceSent = [];
+    #presenceTimer = null;
+    // Who is waiting for the shard to be ready.
+    #readyWaiters = [];
+    #fatal = null;
+    constructor(options) {
+        this.id = options.id;
+        this.#options = options;
+        this.#presence = options.presence;
+    }
+    get status() {
+        return this.#status;
+    }
+    /**
+     * How long Discord took to acknowledge the last heartbeat, in
+     * milliseconds; `null` before the first one.
+     */
+    get ping() {
+        return this.#ping;
+    }
+    /**
+     * Connects, and resolves once Discord said the shard is ready. Rejects if
+     * Discord refuses the connection for good. After that the shard stays
+     * connected by itself.
+     */
+    connect() {
+        if (this.#status !== 'idle') {
+            throw new Error(`Shard ${this.id} was already started.`);
+        }
+        const ready = this.#whenReady();
+        this.#open();
+        return ready;
+    }
+    /**
+     * Sends an event to Discord, once the shard is ready and the send limit
+     * allows it.
+     * @see https://docs.discord.com/developers/events/gateway-events#send-events
+     */
+    async send(op, data) {
+        const text = JSON.stringify({ op, d: data });
+        const bytes = Buffer.byteLength(text);
+        if (bytes > MAX_PAYLOAD_BYTES) {
+            throw new RangeError(`This gateway event is ${bytes} bytes long: Discord accepts ${MAX_PAYLOAD_BYTES} at most.`);
+        }
+        for (;;) {
+            if (this.#status !== 'ready')
+                await this.#whenReady();
+            const now = Date.now();
+            while (this.#sent.length > 0 && now - this.#sent[0] >= SEND_WINDOW) {
+                this.#sent.shift();
+            }
+            if (this.#sent.length < SEND_LIMIT - SEND_RESERVE)
+                break;
+            await sleep(this.#sent[0] + SEND_WINDOW - now);
+        }
+        this.#write(text);
+    }
+    /**
+     * Changes the presence of the bot on this shard. It is sent right away
+     * when the shard is ready and Discord's limit allows it, otherwise as
+     * soon as one of them does (only the latest presence is sent then); a
+     * session started later identifies with it.
+     * @see https://docs.discord.com/developers/events/gateway-events#update-presence
+     */
+    setPresence(presence) {
+        this.#presence = presence;
+        this.#presencePending = true;
+        this.#flushPresence();
+    }
+    #flushPresence() {
+        if (!this.#presencePending || this.#presenceTimer)
+            return;
+        // Not connected: the next Identify carries it, or Resumed calls again.
+        if (this.#status !== 'ready')
+            return;
+        const now = Date.now();
+        const window = this.#options.presenceWindow ?? PRESENCE_WINDOW;
+        const sent = this.#presenceSent;
+        while (sent.length > 0 && now - sent[0] >= window)
+            sent.shift();
+        if (sent.length >= PRESENCE_LIMIT) {
+            this.#presenceTimer = setTimeout(() => {
+                this.#presenceTimer = null;
+                this.#flushPresence();
+            }, sent[0] + window - now);
+            return;
+        }
+        this.#presencePending = false;
+        sent.push(now);
+        this.#write(JSON.stringify({ op: GatewayOpcode.PresenceUpdate, d: this.#presence }));
+    }
+    /**
+     * Closes the connection for good. The session is ended, so the bot
+     * appears offline right away instead of staying online as a ghost.
+     * @see https://docs.discord.com/developers/events/gateway#initiating-a-disconnect
+     */
+    async close() {
+        if (this.#status === 'closed')
+            return;
+        const ws = this.#ws;
+        this.#finish(new Error(`Shard ${this.id} was closed.`));
+        if (!ws || ws.readyState === WebSocket.CLOSED)
+            return;
+        await new Promise(resolve => {
+            const timer = setTimeout(resolve, 2000);
+            ws.addEventListener('close', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            ws.close(1000);
+        });
+    }
+    // -- Connection ------------------------------------------------------------
+    #whenReady() {
+        if (this.#fatal)
+            return Promise.reject(this.#fatal);
+        return new Promise((resolve, reject) => {
+            this.#readyWaiters.push({ resolve, reject });
+        });
+    }
+    #open() {
+        this.#status = 'connecting';
+        this.#greeted = false;
+        const base = (this.#sessionId && this.#resumeUrl ? this.#resumeUrl : this.#options.url).replace(/\/+$/, '');
+        // When resuming, the same version and encoding must be given again.
+        const ws = new WebSocket(`${base}/?v=${API_VERSION}&encoding=json`);
+        this.#ws = ws;
+        ws.addEventListener('message', event => {
+            if (ws === this.#ws)
+                this.#onMessage(String(event.data));
+        });
+        onSocketEnd(ws, closeCode => {
+            // 1005 and 1006 mean "no close code was received".
+            const code = closeCode === 1005 || closeCode === 1006 ? null : closeCode;
+            if (ws === this.#ws)
+                this.#onClose(code);
+        });
+    }
+    #write(text) {
+        const ws = this.#ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        this.#sent.push(Date.now());
+        ws.send(text);
+    }
+    #onMessage(text) {
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        switch (payload.op) {
+            case GatewayOpcode.Hello:
+                this.#greeted = true;
+                this.#startHeartbeat(payload.d.heartbeat_interval);
+                void this.#handshake();
+                break;
+            case GatewayOpcode.HeartbeatAck:
+                this.#acknowledged = true;
+                this.#ping = Date.now() - this.#heartbeatSentAt;
+                break;
+            case GatewayOpcode.Heartbeat:
+                // Discord asks for a heartbeat right now.
+                this.#sendHeartbeat();
+                break;
+            case GatewayOpcode.Reconnect:
+                this.#reconnect(true);
+                break;
+            case GatewayOpcode.InvalidSession:
+                // `d` says whether the session may be resumed.
+                this.#reconnect(payload.d === true);
+                break;
+            case GatewayOpcode.Dispatch:
+                this.#onDispatch(payload);
+                break;
+        }
+    }
+    async #handshake() {
+        const ws = this.#ws;
+        if (this.#sessionId !== null && this.#sequence !== null) {
+            this.#status = 'resuming';
+            const resume = {
+                token: this.#options.token,
+                session_id: this.#sessionId,
+                seq: this.#sequence,
+            };
+            this.#write(JSON.stringify({ op: GatewayOpcode.Resume, d: resume }));
+            return;
+        }
+        this.#status = 'identifying';
+        await this.#options.identifyGate.wait(this.id);
+        // The connection may have dropped while waiting for its turn.
+        if (ws !== this.#ws)
+            return;
+        const identify = {
+            token: this.#options.token,
+            intents: this.#options.intents,
+            properties: {
+                os: process.platform,
+                browser: 'chapterjs',
+                device: 'chapterjs',
+            },
+            shard: [this.id, this.#options.count],
+            ...(this.#presence ? { presence: this.#presence } : {}),
+        };
+        // The new session starts with the current presence.
+        this.#presencePending = false;
+        this.#write(JSON.stringify({ op: GatewayOpcode.Identify, d: identify }));
+    }
+    #onDispatch(payload) {
+        if (payload.s !== null && payload.s !== undefined) {
+            this.#sequence = payload.s;
+        }
+        const event = payload.t;
+        if (event === 'READY') {
+            const ready = payload.d;
+            this.#sessionId = ready.session_id;
+            this.#resumeUrl = ready.resume_gateway_url;
+        }
+        // The cache must know about Ready before anyone is told the shard is.
+        this.#options.onDispatch(event, payload.d, this.id);
+        if (event === 'READY' || event === 'RESUMED') {
+            this.#status = 'ready';
+            this.#attempts = 0;
+            this.#options.onEvent?.({
+                type: 'ready',
+                shardId: this.id,
+                resumed: event === 'RESUMED',
+            });
+            for (const waiter of this.#readyWaiters.splice(0))
+                waiter.resolve();
+            // A presence changed while disconnected: a resumed session kept the
+            // old one.
+            this.#flushPresence();
+        }
+    }
+    // -- Heartbeats ------------------------------------------------------------
+    /** @see https://docs.discord.com/developers/events/gateway#sending-heartbeats */
+    #startHeartbeat(interval) {
+        this.#stopHeartbeat();
+        this.#acknowledged = true;
+        // The first heartbeat is sent after `heartbeat_interval * jitter`.
+        this.#heartbeatTimer = setTimeout(() => {
+            this.#sendHeartbeat();
+            this.#heartbeatTimer = setInterval(() => {
+                if (!this.#acknowledged) {
+                    // A "zombied" connection: terminate it and resume.
+                    this.#reconnect(true);
+                    return;
+                }
+                this.#sendHeartbeat();
+            }, interval);
+        }, interval * Math.random());
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearTimeout(this.#heartbeatTimer);
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = null;
+        }
+    }
+    #sendHeartbeat() {
+        this.#acknowledged = false;
+        this.#heartbeatSentAt = Date.now();
+        this.#write(JSON.stringify({ op: GatewayOpcode.Heartbeat, d: this.#sequence }));
+    }
+    // -- Disconnections --------------------------------------------------------
+    /** Drops the current connection, whose events are ignored from now on. */
+    #detach(code) {
+        this.#stopHeartbeat();
+        const ws = this.#ws;
+        this.#ws = null;
+        if (ws && ws.readyState !== WebSocket.CLOSED) {
+            try {
+                ws.close(code);
+            }
+            catch {
+                // Already closing.
+            }
+        }
+    }
+    /** The shard itself decides to reconnect (Discord asked, or no ACK). */
+    #reconnect(resume) {
+        // Ending the session cleanly when it can't be resumed anyway.
+        this.#detach(resume ? CLOSE_AND_RESUME : 1000);
+        this.#retry(null, resume);
+    }
+    /** The connection was closed by Discord or by the network. */
+    #onClose(code) {
+        this.#stopHeartbeat();
+        this.#ws = null;
+        if (code !== null && FATAL_GATEWAY_CLOSE_CODES.has(code)) {
+            const error = new GatewayFatalError(code, this.#options.intents);
+            this.#finish(error);
+            this.#options.onEvent?.({ type: 'fatal', shardId: this.id, error });
+            return;
+        }
+        // A resume that could not even reach Discord: start over from the URL
+        // of Get Gateway Bot, as the documentation says.
+        const resumeFailed = this.#status === 'connecting' && !this.#greeted;
+        this.#retry(code, !(resumeFailed || (code !== null && SESSION_LOST.has(code))));
+    }
+    #retry(code, resume) {
+        const resumable = resume && this.#sessionId !== null && this.#sequence !== null;
+        if (!resumable) {
+            this.#sessionId = null;
+            this.#resumeUrl = null;
+            this.#sequence = null;
+        }
+        this.#status = 'reconnecting';
+        const retryIn = Math.round((this.#options.backoff ?? defaultBackoff)(this.#attempts++));
+        this.#options.onEvent?.({
+            type: 'disconnected',
+            shardId: this.id,
+            code,
+            resumable,
+            retryIn,
+        });
+        this.#retryTimer = setTimeout(() => {
+            this.#retryTimer = null;
+            this.#open();
+        }, retryIn);
+    }
+    /** Stops everything, for good. */
+    #finish(error) {
+        this.#status = 'closed';
+        this.#fatal = error;
+        this.#stopHeartbeat();
+        if (this.#retryTimer)
+            clearTimeout(this.#retryTimer);
+        this.#retryTimer = null;
+        if (this.#presenceTimer)
+            clearTimeout(this.#presenceTimer);
+        this.#presenceTimer = null;
+        this.#ws = null;
+        for (const waiter of this.#readyWaiters.splice(0))
+            waiter.reject(error);
+    }
+}

package/dist/gateway/state.d.ts

@@ -0,0 +1,11 @@
+import type { GatewayDispatchEventName, GatewayDispatchEvents } from '../discord/types/gateway-events.js';
+import type { Context } from '../structures/context.js';
+/** Where an event comes from. */
+export interface DispatchOrigin {
+    shardId: number;
+    shardCount: number;
+}
+/** Whether an event changes what the bot remembers. */
+export declare function tracksState(event: GatewayDispatchEventName): boolean;
+/** Applies one dispatched event to the cache. */
+export declare function applyDispatch<E extends GatewayDispatchEventName>(ctx: Context, event: E, data: GatewayDispatchEvents[E], origin: DispatchOrigin): void;

package/dist/gateway/state.js

@@ -0,0 +1,184 @@
+// Keeps the cache up to date with what Discord dispatches, so that reading
+// it never costs a request. One entry per event; an event that changes
+// nothing the bot remembers has no entry.
+// https://docs.discord.com/developers/events/gateway#tracking-state
+import { dataOf, patch } from '../structures/base.js';
+import { messagesOf } from '../structures/channel.js';
+import { storesOf } from '../structures/guild.js';
+import { shardIdFor } from './gateway.js';
+const guildOf = (ctx, id) => id ? ctx.cache.guilds.get(id) : undefined;
+/** Adds to the member count of a server, when it is known exactly. */
+function countMembers(guild, change) {
+    const count = dataOf(guild).member_count;
+    if (typeof count === 'number') {
+        patch(guild, { member_count: Math.max(0, count + change) });
+    }
+}
+const upsertChannel = (ctx, data) => {
+    ctx.entities.channel(data);
+};
+const handlers = {
+    READY(ctx, data, origin) {
+        ctx.self = { userId: data.user.id, applicationId: data.application.id };
+        ctx.entities.user(data.user);
+        // A new session: servers the bot left while it was away are forgotten.
+        const current = new Set(data.guilds.map(guild => guild.id));
+        for (const id of [...ctx.cache.guilds.keys()]) {
+            if (shardIdFor(id, origin.shardCount) === origin.shardId &&
+                !current.has(id)) {
+                ctx.entities.removeGuild(id);
+            }
+        }
+    },
+    USER_UPDATE(ctx, data) {
+        ctx.entities.user(data);
+    },
+    GUILD_CREATE(ctx, data) {
+        if (!('name' in data)) {
+            // Still unavailable because of an outage.
+            const guild = guildOf(ctx, data.id);
+            if (guild)
+                patch(guild, { unavailable: true });
+            return;
+        }
+        const guild = ctx.entities.guild(data);
+        patch(guild, { unavailable: false });
+        // The payload lists every channel and active thread: what is no longer
+        // in it was deleted while the bot was away.
+        const listed = new Set([...data.channels, ...data.threads].map(channel => channel.id));
+        for (const id of [...storesOf(guild).channels.keys()]) {
+            if (!listed.has(id))
+                ctx.entities.removeChannel(id);
+        }
+    },
+    GUILD_UPDATE(ctx, data) {
+        ctx.entities.guild(data);
+    },
+    GUILD_DELETE(ctx, data) {
+        // With `unavailable`, an outage; without, the bot is no longer in it.
+        const guild = guildOf(ctx, data.id);
+        if (!guild)
+            return;
+        if (data.unavailable)
+            patch(guild, { unavailable: true });
+        else
+            ctx.entities.removeGuild(data.id);
+    },
+    GUILD_ROLE_CREATE(ctx, data) {
+        ctx.entities.role(data.guild_id, data.role);
+    },
+    GUILD_ROLE_UPDATE(ctx, data) {
+        ctx.entities.role(data.guild_id, data.role);
+    },
+    GUILD_ROLE_DELETE(ctx, data) {
+        const guild = guildOf(ctx, data.guild_id);
+        if (guild)
+            storesOf(guild).roles.delete(data.role_id);
+    },
+    GUILD_MEMBER_ADD(ctx, data) {
+        const guild = guildOf(ctx, data.guild_id);
+        const { guild_id: guildId, ...member } = data;
+        if (guild && !guild.members.has(member.user.id))
+            countMembers(guild, 1);
+        ctx.entities.member(guildId, member);
+    },
+    GUILD_MEMBER_UPDATE(ctx, data) {
+        const { guild_id: guildId, ...member } = data;
+        // Fields this event leaves out keep the value they had.
+        ctx.entities.member(guildId, member);
+    },
+    GUILD_MEMBER_REMOVE(ctx, data) {
+        const guild = guildOf(ctx, data.guild_id);
+        if (!guild)
+            return;
+        storesOf(guild).members.delete(data.user.id);
+        storesOf(guild).voiceStates.delete(data.user.id);
+        countMembers(guild, -1);
+    },
+    GUILD_MEMBERS_CHUNK(ctx, data) {
+        for (const member of data.members) {
+            ctx.entities.member(data.guild_id, member);
+        }
+    },
+    VOICE_STATE_UPDATE(ctx, data) {
+        if (!data.guild_id)
+            return;
+        if (data.member)
+            ctx.entities.member(data.guild_id, data.member);
+        ctx.entities.voiceState(data.guild_id, data);
+    },
+    GUILD_EMOJIS_UPDATE(ctx, data) {
+        const guild = guildOf(ctx, data.guild_id);
+        if (!guild)
+            return;
+        storesOf(guild).emojis.clear();
+        for (const emoji of data.emojis)
+            ctx.entities.emoji(data.guild_id, emoji);
+    },
+    CHANNEL_CREATE: upsertChannel,
+    CHANNEL_UPDATE: upsertChannel,
+    CHANNEL_DELETE(ctx, data) {
+        ctx.entities.removeChannel(data.id);
+    },
+    CHANNEL_PINS_UPDATE(ctx, data) {
+        const channel = ctx.cache.channels.get(data.channel_id);
+        if (channel && data.last_pin_timestamp !== undefined) {
+            patch(channel, { last_pin_timestamp: data.last_pin_timestamp });
+        }
+    },
+    THREAD_CREATE: upsertChannel,
+    THREAD_UPDATE: upsertChannel,
+    THREAD_DELETE(ctx, data) {
+        ctx.entities.removeChannel(data.id);
+    },
+    THREAD_LIST_SYNC(ctx, data) {
+        const guild = guildOf(ctx, data.guild_id);
+        if (guild) {
+            // Threads of the synced channels (all of them when none is named)
+            // that are not listed are no longer active.
+            const synced = data.channel_ids ? new Set(data.channel_ids) : null;
+            const active = new Set(data.threads.map(thread => thread.id));
+            for (const channel of [...guild.channels.values()]) {
+                if (channel.isThread() &&
+                    !active.has(channel.id) &&
+                    (!synced || (channel.parentId && synced.has(channel.parentId)))) {
+                    ctx.entities.removeChannel(channel.id);
+                }
+            }
+        }
+        for (const thread of data.threads) {
+            ctx.entities.channel(thread, data.guild_id);
+        }
+    },
+    MESSAGE_CREATE(ctx, data) {
+        const channel = ctx.cache.channels.get(data.channel_id);
+        if (channel)
+            patch(channel, { last_message_id: data.id });
+        ctx.entities.message(data, data.guild_id);
+    },
+    MESSAGE_UPDATE(ctx, data) {
+        ctx.entities.message(data, data.guild_id);
+    },
+    MESSAGE_DELETE(ctx, data) {
+        const channel = ctx.cache.channels.get(data.channel_id);
+        if (channel)
+            messagesOf(channel).delete(data.id);
+    },
+    MESSAGE_DELETE_BULK(ctx, data) {
+        const channel = ctx.cache.channels.get(data.channel_id);
+        if (!channel)
+            return;
+        const messages = messagesOf(channel);
+        for (const id of data.ids)
+            messages.delete(id);
+    },
+};
+/** Whether an event changes what the bot remembers. */
+export function tracksState(event) {
+    return event in handlers;
+}
+/** Applies one dispatched event to the cache. */
+export function applyDispatch(ctx, event, data, origin) {
+    const handler = handlers[event];
+    handler?.(ctx, data, origin);
+}