chapterjs 0.1.1 → 0.1.4

package/dist/cli/start.js

@@ -0,0 +1,225 @@
+// `chapterjs start`: runs for everyone the bot `chapterjs build` prepared.
+// Nothing is reloaded, commands are registered for every server, and a
+// large bot is spread over several processes by itself.
+import { registerCommands } from '../commands/register.js';
+import { buildCommands } from '../commands/tree.js';
+import { GLOBAL_REQUESTS_PER_SECOND } from '../discord/api.js';
+import { messageOf } from '../loader/locate.js';
+import { GetGatewayBot } from '../discord/endpoints.js';
+import { SessionLimitError } from '../gateway/errors.js';
+import { RestClient } from '../rest/rest.js';
+import { connectToPrimary, planProcesses, REFUSED, runCluster, } from './cluster.js';
+import { loadBundle, readBuild } from './build.js';
+import { readStartEnv } from './env.js';
+import { describeIntents, ensurePrivilegedIntents, fetchApplication, } from './preflight.js';
+import { createProject, explain } from './project.js';
+/** Runs until stopped. Resolves with the exit code of the process. */
+export async function start(options) {
+    const { cwd, log, signal } = options;
+    const assignment = options.assignment ?? null;
+    // 1. What the bot must have before anything is tried.
+    const read = await readStartEnv(cwd, options.env);
+    if ('problems' in read) {
+        for (const problem of read.problems)
+            log.error(problem);
+        return 1;
+    }
+    const { token, devGuildId } = read.env;
+    // 2. What `chapterjs build` prepared: production runs that, and only
+    // that.
+    const built = await readBuild(cwd, options.version);
+    if ('problem' in built) {
+        if (!assignment)
+            log.error(built.problem);
+        return 1;
+    }
+    if (built.stale && !assignment) {
+        log.warn('Your files changed since the last build: the bot runs the build, not your changes. Run "chapterjs build" to put them online.');
+    }
+    let files;
+    try {
+        files = await loadBundle(cwd);
+    }
+    catch (error) {
+        // The build ran when it was made: something changed around it since
+        // (a package, the version of Node).
+        if (!assignment) {
+            log.error(`The build of your bot can't run any more: ${messageOf(error)}\nRun "chapterjs build" again: it says what to fix.`);
+        }
+        return 1;
+    }
+    const project = createProject({
+        cwd,
+        version: options.version,
+        log,
+        built: files,
+        joinsVoice: built.info.voice === true,
+        ...(options.deferAfter === undefined
+            ? {}
+            : { deferAfter: options.deferAfter }),
+    });
+    const failures = await project.load();
+    if (failures.length > 0) {
+        for (const failure of failures)
+            project.report(failure);
+        if (!assignment) {
+            log.error(`${failures.length === 1 ? 'This file' : `These ${failures.length} files`} of the build can't run any more, so the bot was not started. Run "chapterjs build" again: it says what to fix.`);
+        }
+        return 1;
+    }
+    const apiUrl = options.env.CHAPTERJS_API_URL;
+    const interval = Number(options.env.CHAPTERJS_IDENTIFY_INTERVAL);
+    const identifyInterval = Number.isFinite(interval) && interval > 0 ? interval : undefined;
+    const connection = {
+        token,
+        apiUrl,
+        identifyInterval,
+        // The dev server belongs to `chapterjs dev`: with the same token, the
+        // two never answer the same thing.
+        ...(devGuildId
+            ? { guildFilter: (id) => id !== devGuildId }
+            : {}),
+    };
+    try {
+        if (assignment)
+            return await runShare(project, options, connection, assignment);
+        // 3. What Discord must agree with, checked once for every process.
+        const rest = new RestClient({
+            token,
+            version: options.version,
+            ...(apiUrl ? { baseUrl: apiUrl } : {}),
+        });
+        const application = await fetchApplication(rest);
+        const intents = project.intents();
+        await ensurePrivilegedIntents({ rest, log, interactive: false, pollInterval: 0, signal }, application, intents, project.filesNeeding);
+        if (await registerCommands({
+            rest,
+            projectDir: cwd,
+            applicationId: application.id,
+            commands: buildCommands([...project.commands.values()], {
+                guild: false,
+            }),
+        })) {
+            log.success('Commands updated for everyone');
+        }
+        // 4. How the bot is split: Discord says in how many shards, the size
+        // of the machine in how many processes.
+        const plan = await rest.request(GetGatewayBot, []);
+        const limit = plan.session_start_limit;
+        if (limit.remaining < plan.shards) {
+            throw new SessionLimitError(plan.shards, limit.remaining, limit.reset_after);
+        }
+        const processes = planProcesses(plan.shards, options.processes);
+        const online = (user, guilds) => {
+            const split = [
+                ...(plan.shards > 1 ? [`${plan.shards} shards`] : []),
+                ...(processes > 1 ? [`${processes} processes`] : []),
+            ].join(', ');
+            log.success(`Online as ${user} in ${guilds} ${guilds === 1 ? 'server' : 'servers'}${split ? ` (${split})` : ''}`);
+            log.info(`Intents computed from your files: ${describeIntents(intents)}`);
+            (project.isEmpty() ? log.info : log.success)(project.summary());
+        };
+        if (processes === 1) {
+            return await runAlone(project, options, connection, online);
+        }
+        const code = await runCluster({
+            script: options.script,
+            args: options.args,
+            env: options.env,
+            shards: plan.shards,
+            processes,
+            maxConcurrency: limit.max_concurrency,
+            signal,
+            identifyInterval,
+            write: options.write,
+            onReady: ({ user, guilds }) => online(user, guilds),
+            onRestart: (index, why) => log.warn(`Process ${index + 1} of ${processes} stopped by itself (${why}): starting it again. Its servers are back in a moment.`),
+        });
+        if (code === 0)
+            log.success('Disconnected');
+        return code;
+    }
+    catch (error) {
+        if (signal.aborted)
+            return 0;
+        explain(error, log);
+        return assignment ? REFUSED : 1;
+    }
+}
+/** Runs a bot until it is stopped or Discord refuses it. */
+async function run(project, connection, stopped, connected, { tasks = true } = {}) {
+    let refuse;
+    const refused = new Promise(resolve => (refuse = () => resolve('refused')));
+    let bot = null;
+    const memory = project.watchMemory(() => bot);
+    try {
+        bot = await project.connect({ ...connection, onFatal: refuse });
+        connected(bot);
+        project.ready(bot);
+        // A task runs once for the whole bot: in one process only.
+        if (tasks)
+            project.startTasks(() => bot);
+        return await Promise.race([
+            stopped.then(() => 'stopped'),
+            refused,
+        ]);
+    }
+    finally {
+        project.stopTasks();
+        memory.stop();
+        await bot?.close();
+    }
+}
+/** The whole bot in this process. */
+async function runAlone(project, options, connection, online) {
+    const { signal, log } = options;
+    const stopped = new Promise(resolve => {
+        if (signal.aborted)
+            resolve();
+        else
+            signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    const result = await run(project, connection, stopped, bot => {
+        const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+        online(user.username, bot.ctx.cache.guilds.size);
+    });
+    if (result === 'refused')
+        return 1;
+    log.success('Disconnected');
+    return 0;
+}
+/** The share of the bot another process gave this one. */
+async function runShare(project, options, connection, assignment) {
+    const primary = connectToPrimary();
+    const { signal } = options;
+    const stopped = Promise.race([
+        primary.stopped,
+        new Promise(resolve => {
+            if (signal.aborted)
+                resolve();
+            else
+                signal.addEventListener('abort', () => resolve(), { once: true });
+        }),
+    ]);
+    const result = await run(project, {
+        ...connection,
+        shards: { ids: assignment.ids, count: assignment.count },
+        identifyGate: primary.gate,
+        // Discord counts the requests of the whole bot: each process takes
+        // its share, so that together they stay under the limit.
+        globalLimit: Math.max(1, Math.floor(GLOBAL_REQUESTS_PER_SECOND / assignment.processes)),
+    }, stopped, bot => {
+        const user = bot.ctx.cache.users.get(bot.ctx.self.userId);
+        primary.ready({
+            guilds: bot.ctx.cache.guilds.size,
+            user: user.username,
+        });
+    }, 
+    // The first process of the cluster runs the tasks for all of them.
+    { tasks: assignment.index === 0 });
+    if (result === 'refused') {
+        primary.refused();
+        return REFUSED;
+    }
+    return 0;
+}

package/dist/commands/autocomplete.d.ts

@@ -0,0 +1,13 @@
+import { type RawApplicationCommandInteractionDataOption, type RawInteraction } from '../discord/types/interaction.js';
+import { type Reporter } from '../interactions/dispatch.js';
+import type { Context } from '../structures/context.js';
+import { type CommandEntry } from './tree.js';
+/** How many suggestions Discord shows. */
+export declare const MAX_SUGGESTIONS = 25;
+/**
+ * Answers an autocomplete interaction with what the `autocomplete`
+ * function of the command returns. Discord shows nothing when the answer
+ * is empty, so every path ends with an answer, even when the function
+ * fails: the person is never left with a spinner.
+ */
+export declare function suggest(ctx: Context, raw: RawInteraction, entry: CommandEntry | undefined, given: readonly RawApplicationCommandInteractionDataOption[], reporter: Reporter, warnedOnce: Set<string>): void;

package/dist/commands/autocomplete.js

@@ -0,0 +1,159 @@
+// Suggestions while the person types in an option: Discord sends an
+// Application Command Autocomplete interaction with what they typed so
+// far, and waits 3 seconds for up to 25 choices. Nothing else can be
+// answered to it: the `autocomplete` function of the file returns the
+// suggestions, and this module checks them and sends them.
+// https://docs.discord.com/developers/interactions/application-commands#autocomplete
+import { CreateInteractionResponse } from '../discord/endpoints.js';
+import { InteractionCallbackType, } from '../discord/types/interaction.js';
+import { authorOf, placeContext, resolvePlace, } from '../interactions/dispatch.js';
+import { translation } from '../messages/translate.js';
+import { DiscordApiError } from '../rest/errors.js';
+import { commandName } from './tree.js';
+/** How many suggestions Discord shows. */
+export const MAX_SUGGESTIONS = 25;
+/** The longest name of a suggestion, and the longest text it may carry. */
+const MAX_LENGTH = 100;
+/** How long Discord waits for the suggestions. */
+const DEADLINE = 3000;
+/** Discord says it when the interaction expired before the answer. */
+const UNKNOWN_INTERACTION = 10062;
+/**
+ * Answers an autocomplete interaction with what the `autocomplete`
+ * function of the command returns. Discord shows nothing when the answer
+ * is empty, so every path ends with an answer, even when the function
+ * fails: the person is never left with a spinner.
+ */
+export function suggest(ctx, raw, entry, given, reporter, warnedOnce) {
+    const focused = given.find(option => option.focused);
+    const started = Date.now();
+    const answer = (choices) => {
+        ctx.rest
+            .request(CreateInteractionResponse, [raw.id, raw.token], {
+            body: {
+                type: InteractionCallbackType.ApplicationCommandAutocompleteResult,
+                data: { choices },
+            },
+            auth: false,
+        })
+            .catch((error) => {
+            if (!entry || !focused)
+                return;
+            const name = `${commandName(entry.command.path)} ${focused.name}`;
+            if (error instanceof DiscordApiError &&
+                error.code === UNKNOWN_INTERACTION) {
+                // Too late, or the person typed on and Discord dropped this one.
+                if (Date.now() - started < DEADLINE)
+                    return;
+                reporter.onWarning(entry.file, `The suggestions for ${name} took ${((Date.now() - started) / 1000).toFixed(1)} s: Discord waits 3 seconds, then shows none. Make the autocomplete function faster.`);
+                return;
+            }
+            reporter.onError(entry.file, error);
+        });
+    };
+    // The command, the option or its function is gone: nothing to suggest.
+    const fn = focused && entry?.command.autocomplete[focused.name];
+    if (!entry || !focused || !fn) {
+        answer([]);
+        if (entry && focused) {
+            // Still registered with suggestions, but the file has no function.
+            reporter.onWarning(entry.file, `Discord asked suggestions for ${commandName(entry.command.path)} ${focused.name}, which has none in "autocomplete": the command was registered with an older version of this file.`);
+        }
+        return;
+    }
+    const { command, file } = entry;
+    const name = `${commandName(command.path)} ${focused.name}`;
+    const option = command.options.find(one => one.name === focused.name);
+    const isText = option.type === 'string';
+    const author = authorOf(raw);
+    if (!author)
+        return answer([]);
+    const user = ctx.entities.user(author.user);
+    const placed = resolvePlace(ctx, raw, user, author.member, command.where, message => reporter.onWarning(file, `${name} ${message}`));
+    // Used where the command can't run: no suggestion, the use is refused.
+    if (!placed.place)
+        return answer([]);
+    // What was typed: a text, maybe empty; a number only once it is one.
+    const typed = focused.value;
+    const value = isText
+        ? String(typed ?? '')
+        : typeof typed === 'number'
+            ? typed
+            : undefined;
+    const soFar = {};
+    for (const one of given) {
+        if (one.value === undefined)
+            continue;
+        // Ids and numbers arrive as what they are; the focused one may be
+        // partial, and stays what the person typed.
+        soFar[one.name] = one.name === focused.name ? value : one.value;
+    }
+    const context = Object.freeze({
+        value,
+        options: Object.freeze(soFar),
+        user,
+        locale: raw.locale,
+        ...placeContext(placed.place, command.where),
+        // Suggestions are shown to the person alone: their language.
+        ...translation(ctx, raw.locale ?? null),
+    });
+    new Promise(resolve => resolve(fn(context)))
+        .then(suggestions => {
+        answer(toChoices(suggestions, {
+            name,
+            isText,
+            integer: option.type === 'integer',
+            warn: message => {
+                // Said once per option: it happens on every keystroke.
+                if (warnedOnce.has(`${file} ${name} ${message}`))
+                    return;
+                warnedOnce.add(`${file} ${name} ${message}`);
+                reporter.onWarning(file, `${name}: ${message}`);
+            },
+        }));
+    })
+        .catch((error) => {
+        reporter.onError(file, error);
+        answer([]);
+    });
+}
+/**
+ * What the function returned, as the choices Discord takes. What can be
+ * fixed is fixed and said once (too many, a name too long); what can't
+ * (not a list, a value of the wrong kind) is an error, and nothing is
+ * suggested.
+ */
+function toChoices(suggestions, { name, isText, integer, warn, }) {
+    if (!Array.isArray(suggestions)) {
+        throw new TypeError(`The autocomplete function of ${name} must return a list of suggestions, like ['a', 'b'] or [{ name: 'Shown', value: 'a' }]: got ${JSON.stringify(suggestions) ?? typeof suggestions}.`);
+    }
+    const kept = suggestions.length > MAX_SUGGESTIONS
+        ? suggestions.slice(0, MAX_SUGGESTIONS)
+        : suggestions;
+    if (kept !== suggestions) {
+        warn(`the autocomplete function returned ${suggestions.length} suggestions, Discord shows ${MAX_SUGGESTIONS} at most: only the first ${MAX_SUGGESTIONS} are sent. Return fewer, the best ones first.`);
+    }
+    return kept.map(suggestion => {
+        const pair = typeof suggestion === 'object' && suggestion !== null
+            ? suggestion
+            : { name: String(suggestion), value: suggestion };
+        const { value } = pair;
+        if (typeof value !== (isText ? 'string' : 'number')) {
+            throw new TypeError(`A suggestion of ${name} has the value ${JSON.stringify(value) ?? typeof value}: the option is a ${isText ? 'text' : 'number'}, so its suggestions must be ${isText ? 'texts' : 'numbers'}.`);
+        }
+        if (integer && !Number.isInteger(value)) {
+            throw new TypeError(`A suggestion of ${name} has the value ${String(value)}, which is not a whole number: the option is an integer.`);
+        }
+        if (isText && value.length > MAX_LENGTH) {
+            throw new TypeError(`A suggestion of ${name} has a value of ${value.length} characters: Discord accepts ${MAX_LENGTH} at most. Suggest a shorter value, like an id, with the text to show as its name.`);
+        }
+        let shown = typeof pair.name === 'string' && pair.name.length > 0
+            ? pair.name
+            : String(value);
+        if (shown.length > MAX_LENGTH) {
+            warn(`a suggestion is shown as ${shown.length} characters, Discord shows ${MAX_LENGTH} at most: it is cut. Give it a shorter name.`);
+            shown = `${shown.slice(0, MAX_LENGTH - 1)}…`;
+        }
+        return { name: shown, value: value };
+    });
+}