chapterjs 0.2.3 → 0.4.0

package/dist/testing/websocket.js

@@ -0,0 +1,167 @@
+// A WebSocket server on Node built-ins, for the fake servers of Discord
+// (the gateway, voice): the real connection code of the framework runs
+// against it. Masked and fragmented client frames, text and binary, pings.
+// https://datatracker.ietf.org/doc/html/rfc6455#section-5
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+function frame(opcode, payload) {
+    const length = payload.length;
+    let header;
+    if (length < 126) {
+        header = Buffer.from([0x80 | opcode, length]);
+    }
+    else if (length < 65536) {
+        header = Buffer.alloc(4);
+        header[0] = 0x80 | opcode;
+        header[1] = 126;
+        header.writeUInt16BE(length, 2);
+    }
+    else {
+        header = Buffer.alloc(10);
+        header[0] = 0x80 | opcode;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(length), 2);
+    }
+    return Buffer.concat([header, payload]);
+}
+/**
+ * A local WebSocket server: it accepts every client, reads their (masked,
+ * possibly fragmented) messages and answers pings. The caller closes it.
+ */
+export async function webSocketServer(onConnection) {
+    const sockets = new Set();
+    const server = createServer((_, res) => res.writeHead(426).end());
+    server.on('upgrade', (req, socket) => {
+        const key = req.headers['sec-websocket-key'];
+        const accept = createHash('sha1')
+            .update(key + GUID)
+            .digest('base64');
+        socket.write('HTTP/1.1 101 Switching Protocols\r\n' +
+            'Upgrade: websocket\r\n' +
+            'Connection: Upgrade\r\n' +
+            `Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
+        sockets.add(socket);
+        const closeWaiters = [];
+        const markClosed = (code) => {
+            if (peer.closed)
+                return;
+            peer.closed = { code };
+            sockets.delete(socket);
+            for (const resolve of closeWaiters.splice(0))
+                resolve(code);
+        };
+        let handler = () => { };
+        const peer = {
+            query: Object.fromEntries(new URL(req.url ?? '/', 'http://localhost').searchParams),
+            closed: null,
+            sendText(text) {
+                if (!peer.closed)
+                    socket.write(frame(0x1, Buffer.from(text)));
+            },
+            sendBinary(data) {
+                if (!peer.closed)
+                    socket.write(frame(0x2, data));
+            },
+            close(code) {
+                if (peer.closed)
+                    return;
+                const body = Buffer.alloc(2);
+                body.writeUInt16BE(code);
+                socket.end(frame(0x8, body));
+                markClosed(null);
+            },
+            drop() {
+                socket.destroy();
+                markClosed(null);
+            },
+            waitForClose(timeout = 2000) {
+                if (peer.closed)
+                    return Promise.resolve(peer.closed.code);
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`The fake server waited ${timeout}ms for the connection to close.`)), timeout);
+                    closeWaiters.push(code => {
+                        clearTimeout(timer);
+                        resolve(code);
+                    });
+                });
+            },
+        };
+        // Client frames are masked; a message may come in several frames.
+        let buffer = Buffer.alloc(0);
+        let fragments = [];
+        let binary = false;
+        socket.on('data', (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            for (;;) {
+                if (buffer.length < 2)
+                    return;
+                const fin = (buffer[0] & 0x80) !== 0;
+                const opcode = buffer[0] & 0x0f;
+                let length = buffer[1] & 0x7f;
+                let offset = 2;
+                if (length === 126) {
+                    if (buffer.length < 4)
+                        return;
+                    length = buffer.readUInt16BE(2);
+                    offset = 4;
+                }
+                else if (length === 127) {
+                    if (buffer.length < 10)
+                        return;
+                    length = Number(buffer.readBigUInt64BE(2));
+                    offset = 10;
+                }
+                if (buffer.length < offset + 4 + length)
+                    return;
+                const mask = buffer.subarray(offset, offset + 4);
+                const data = Buffer.from(buffer.subarray(offset + 4, offset + 4 + length));
+                for (let index = 0; index < data.length; index++) {
+                    data[index] ^= mask[index % 4];
+                }
+                buffer = buffer.subarray(offset + 4 + length);
+                if (opcode === 0x8) {
+                    const code = data.length >= 2 ? data.readUInt16BE(0) : null;
+                    if (!peer.closed)
+                        socket.end(frame(0x8, data.subarray(0, 2)));
+                    markClosed(code);
+                    return;
+                }
+                if (opcode === 0x9) {
+                    socket.write(frame(0xa, data));
+                    continue;
+                }
+                if (opcode === 0xa)
+                    continue;
+                if (opcode === 0x1 || opcode === 0x2)
+                    binary = opcode === 0x2;
+                fragments.push(data);
+                if (fin) {
+                    const message = Buffer.concat(fragments);
+                    fragments = [];
+                    handler(binary ? message : message.toString('utf8'));
+                }
+            }
+        });
+        socket.on('close', () => markClosed(null));
+        socket.on('error', () => markClosed(null));
+        onConnection(peer, req, {
+            message: next => {
+                handler = next;
+            },
+        });
+    });
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address();
+    return {
+        url: `ws://127.0.0.1:${port}`,
+        host: '127.0.0.1',
+        port,
+        close: () => new Promise(resolve => {
+            for (const socket of sockets)
+                socket.destroy();
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/testing/world.d.ts

@@ -0,0 +1,145 @@
+import type { RawApplicationCommand } from '../discord/types/application-command.js';
+import { ChannelType, type RawChannel } from '../discord/types/channel.js';
+import type { Locale, Snowflake } from '../discord/types/common.js';
+import type { RawGuild, RawGuildMember } from '../discord/types/guild.js';
+import { type RawInteraction, type RawInteractionCallbackAutocompleteData, type RawInteractionCallbackModalData, type RawInteractionResponse } from '../discord/types/interaction.js';
+import { type RawMessage } from '../discord/types/message.js';
+import { type RawRole } from '../discord/types/permissions.js';
+import type { RawUser } from '../discord/types/user.js';
+import { type FakeDiscord, type FakeDiscordRequest } from './fake-discord.js';
+import { type FakeGateway } from './fake-gateway.js';
+/** An interaction someone made, and everything the bot answered to it. */
+export interface InteractionRecord {
+    readonly id: Snowflake;
+    readonly token: string;
+    readonly raw: RawInteraction;
+    /** The message the component was on, for a component or a form it opened. */
+    message: RawMessage | null;
+    /** Every callback sent to `/callback`, in order (Discord takes one). */
+    readonly callbacks: RawInteractionResponse[];
+    /** The first answer, as a message: sent, deferred, or the updated one. */
+    original: RawMessage | null;
+    /** The messages sent after the first answer. */
+    readonly followUps: RawMessage[];
+    /** The form opened, when the answer was one. */
+    modal: RawInteractionCallbackModalData | null;
+    /** The suggestions given, for an autocomplete. */
+    suggestions: RawInteractionCallbackAutocompleteData['choices'] | null;
+    /** Whether the first answer was "thinking…" (deferred). */
+    deferred: boolean;
+    /** Whether the answer changed the message of the component. */
+    updated: boolean;
+}
+export interface WorldOptions {
+    /** The name of the server. Default: "Test Server". */
+    guildName?: string;
+    /** The name of the bot. Default: "Test Bot". */
+    botName?: string;
+}
+export interface WorldUserOptions {
+    bot?: boolean;
+    locale?: Locale;
+}
+export interface WorldMemberOptions {
+    roles?: readonly Snowflake[];
+    nick?: string | null;
+}
+export interface WorldRoleOptions {
+    permissions?: bigint;
+    position?: number;
+    color?: number;
+}
+export interface WorldChannelOptions {
+    type?: ChannelType;
+    parentId?: Snowflake | null;
+    topic?: string | null;
+}
+/**
+ * The Discord of a test: one server, the bot in it, people who come and go,
+ * and everything the bot does kept where a test can read it.
+ */
+export declare class World {
+    #private;
+    readonly botId: Snowflake;
+    readonly applicationId: Snowflake;
+    readonly guildId: Snowflake;
+    readonly ownerId: Snowflake;
+    guildName: string;
+    readonly users: Map<string, RawUser>;
+    /** The members of the server, by user id. */
+    readonly members: Map<string, RawGuildMember>;
+    readonly roles: Map<string, RawRole>;
+    /** The channels of the server, its threads and the private channels. */
+    readonly channels: Map<string, RawChannel>;
+    /** The messages of each channel, oldest first. */
+    readonly messages: Map<string, RawMessage[]>;
+    readonly bans: Map<string, {
+        user: RawUser;
+        reason: string | null;
+    }>;
+    /** Who is in each thread. */
+    readonly threadMembers: Map<string, Set<string>>;
+    /** Every interaction made, by id and by token. */
+    readonly interactions: Map<string, InteractionRecord>;
+    /** The commands registered, for the server and for everyone. */
+    guildCommands: RawApplicationCommand[];
+    globalCommands: RawApplicationCommand[];
+    /** Every gateway event the world sent to the bot, in order. */
+    readonly sent: {
+        type: string;
+        data: unknown;
+    }[];
+    discord: FakeDiscord;
+    gateway: FakeGateway;
+    constructor(options?: WorldOptions);
+    /** The environment that points the CLI at this Discord. */
+    get env(): Record<string, string>;
+    /** The user of the bot. */
+    get bot(): RawUser;
+    /** Starts the fake REST API and gateway. */
+    start(): Promise<void>;
+    close(): Promise<void>;
+    /** A new id, later than every id given before, in this world or another. */
+    snowflake(): Snowflake;
+    addUser(name: string, options?: WorldUserOptions): RawUser;
+    /** The user named so, if any. */
+    findUser(name: string): RawUser | undefined;
+    addMember(userId: Snowflake, options?: WorldMemberOptions): RawGuildMember;
+    addRole(name: string, options?: WorldRoleOptions): RawRole;
+    addChannel(name: string, options?: WorldChannelOptions): RawChannel;
+    /** The channel of the server named so, if any. */
+    findChannel(name: string): RawChannel | undefined;
+    /** The private channel with a user, made the first time it is asked. */
+    dm(userId: Snowflake): RawChannel;
+    /** The permissions of a member in the server (channel overwrites left aside). */
+    permissionsOf(userId: Snowflake): bigint;
+    /** The server as Discord sends it in Guild Create. */
+    guildPayload(): RawGuild & Record<string, unknown>;
+    /** The server as Get Guild returns it. */
+    guildFields(): RawGuild;
+    isThread(channel: RawChannel): boolean;
+    /** The connection of the bot, once it identified. */
+    get connection(): import("./fake-gateway.js").FakeGatewayConnection;
+    /** Sends a gateway event to the bot. */
+    dispatch(type: string, data: unknown): void;
+    /** Makes an interaction happen: records it and sends it to the bot. */
+    interaction(raw: RawInteraction): InteractionRecord;
+    /** Puts a message in its channel and tells the bot, as Discord does. */
+    createMessage(channelId: Snowflake, author: RawUser, data: Record<string, unknown>, files?: FakeDiscordRequest['files'], extra?: Partial<RawMessage>): RawMessage;
+    /** The message with this id, wherever it is. */
+    findMessage(id: Snowflake): RawMessage | undefined;
+    editMessage(message: RawMessage, data: Record<string, unknown>): RawMessage;
+    deleteMessage(message: RawMessage): void;
+    removeMember(userId: Snowflake): void;
+    memberUpdated(member: RawGuildMember): void;
+}
+/** The raw interaction type of a kind of thing someone does. */
+export declare const INTERACTION_TYPES: {
+    readonly Ping: 1;
+    readonly ApplicationCommand: 2;
+    readonly MessageComponent: 3;
+    readonly ApplicationCommandAutocomplete: 4;
+    readonly ModalSubmit: 5;
+};
+/** Every permission, for the roles of tests. */
+export declare const EVERY_PERMISSION: bigint;