chapterjs 0.3.0 → 0.5.0

package/dist/redis/client.js

@@ -0,0 +1,252 @@
+// The one connection of the process to Redis, on Node's `net` and `tls`
+// and nothing else. Commands are sent in order and answered in order
+// (RESP pipelines by itself), so every call is a promise of its reply.
+// The connection is opened on the first command, logs in and picks the
+// database by itself, and comes back alone when it was lost: a command
+// sent meanwhile fails at once with why, instead of waiting for nobody.
+// https://redis.io/docs/latest/commands/auth/ and /commands/select/
+import { connect as connectTcp } from 'node:net';
+import { connect as connectTls } from 'node:tls';
+import { encodeCommand, RedisError, ReplyReader, } from './protocol.js';
+import { describeRedis } from './url.js';
+/** A thrown reason, in plain words, with what to do. */
+function explain(address, error) {
+    const where = `Redis at ${describeRedis(address)}`;
+    // Already said in these words (a password refused during the handshake).
+    if (error instanceof Error && error.message.startsWith(where)) {
+        return error.message;
+    }
+    if (error instanceof RedisError) {
+        if (error.code === 'WRONGPASS') {
+            return `${where} refused the password: check REDIS_PASSWORD (or the password in REDIS_URL) in .env.`;
+        }
+        if (error.code === 'NOAUTH') {
+            return `${where} asks for a password: set REDIS_PASSWORD (or the password in REDIS_URL) in .env.`;
+        }
+        if (error.code === 'NOPERM') {
+            return `${where} refused the user: check the user in REDIS_URL, and what it may do.`;
+        }
+        return `${where} refused the connection: ${error.message}`;
+    }
+    const code = error?.code;
+    switch (code) {
+        case 'ECONNREFUSED':
+            return `${where} can't be reached: nothing answers there. Start Redis, or check REDIS_URL in .env.`;
+        case 'ENOTFOUND':
+        case 'EAI_AGAIN':
+            return `${where} can't be reached: the host is unknown. Check REDIS_URL in .env.`;
+        case 'ETIMEDOUT':
+            return `${where} can't be reached: it did not answer in time. Check REDIS_URL in .env, and that the machine lets you reach it.`;
+        case 'ECONNRESET':
+        case 'EPIPE':
+            return `${where} closed the connection.`;
+        default:
+            return `${where} can't be reached: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/** One connection to Redis, which only opens when a command needs it. */
+export class RedisClient {
+    address;
+    #options;
+    #socket = null;
+    #state = 'idle';
+    /** Commands sent, waiting for their reply, in order. */
+    #waiting = [];
+    /** Commands given while connecting, sent once the connection is ready. */
+    #queue = [];
+    /** Why the last attempt failed: what a command gets while waiting to retry. */
+    #outage = null;
+    #wasReady = false;
+    #attempts = 0;
+    #retryTimer = null;
+    constructor(address, options = {}) {
+        this.address = address;
+        this.#options = {
+            connectTimeout: 5000,
+            retryDelay: 1000,
+            maxRetryDelay: 30_000,
+            ...options,
+        };
+    }
+    /** `host:port` and the database, for messages. */
+    get where() {
+        return describeRedis(this.address);
+    }
+    /** Whether a command sent now goes out at once. */
+    get connected() {
+        return this.#state === 'ready';
+    }
+    /**
+     * Sends a command and resolves with its reply. An error reply (`-ERR`)
+     * rejects with a `RedisError`; a connection that fails or is lost
+     * rejects with what happened, in plain words.
+     */
+    send(...args) {
+        return new Promise((resolve, reject) => {
+            const pending = { resolve, reject };
+            switch (this.#state) {
+                case 'closed':
+                    reject(new Error(`Redis at ${this.where} is closed: the bot stopped.`));
+                    return;
+                case 'ready':
+                    this.#write(args, pending);
+                    return;
+                case 'connecting':
+                    this.#queue.push({ args, pending });
+                    return;
+                case 'idle':
+                    if (this.#outage && this.#retryTimer) {
+                        reject(new Error(this.#outage));
+                        return;
+                    }
+                    this.#queue.push({ args, pending });
+                    this.#connect();
+            }
+        });
+    }
+    /**
+     * Makes sure Redis answers: the connection is opened, logged in and on
+     * the right database, or the reason it can't be is thrown.
+     */
+    async ping() {
+        const reply = await this.send('PING');
+        if (reply !== 'PONG') {
+            throw new Error(`Redis at ${this.where} answered ${JSON.stringify(reply)} to PING: is REDIS_URL the address of a Redis server?`);
+        }
+    }
+    #write(args, pending) {
+        this.#waiting.push(pending);
+        this.#socket.write(encodeCommand(args));
+    }
+    #connect() {
+        this.#state = 'connecting';
+        const { host, port } = this.address;
+        const socket = this.address.tls
+            ? connectTls({ host, port, servername: host })
+            : connectTcp({ host, port });
+        this.#socket = socket;
+        socket.setNoDelay(true);
+        const reader = new ReplyReader();
+        const timer = setTimeout(() => {
+            socket.destroy(Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' }));
+        }, this.#options.connectTimeout);
+        // The end of this connection, whenever it comes: while connecting, or
+        // once it served. Told once: a destroyed socket says error, then close.
+        let ended = false;
+        const fail = (error) => {
+            clearTimeout(timer);
+            if (ended)
+                return;
+            ended = true;
+            if (socket !== this.#socket)
+                return;
+            this.#socket = null;
+            socket.destroy();
+            const message = explain(this.address, error);
+            // Everything sent or about to be sent fails: nobody is there.
+            const waiting = this.#waiting;
+            const queue = this.#queue;
+            this.#waiting = [];
+            this.#queue = [];
+            for (const pending of waiting)
+                pending.reject(new Error(message));
+            for (const { pending } of queue)
+                pending.reject(new Error(message));
+            if (this.#state === 'closed')
+                return;
+            this.#state = 'idle';
+            if (this.#outage === null) {
+                this.#options.onError?.(`${message} Trying again every few seconds.`);
+            }
+            const delay = Math.min(this.#options.retryDelay * 2 ** this.#attempts, this.#options.maxRetryDelay);
+            this.#attempts++;
+            this.#outage = `${message} Trying again in ${Math.round(delay / 1000) || 1} s.`;
+            this.#retryTimer = setTimeout(() => {
+                this.#retryTimer = null;
+                if (this.#state === 'idle')
+                    this.#connect();
+            }, delay);
+            this.#retryTimer.unref();
+        };
+        socket.on('error', fail);
+        socket.on('close', () => fail(Object.assign(new Error('closed'), { code: 'ECONNRESET' })));
+        socket.on('data', chunk => {
+            reader.push(chunk);
+            try {
+                let reply;
+                while ((reply = reader.next()) !== undefined) {
+                    const pending = this.#waiting.shift();
+                    if (!pending)
+                        continue;
+                    if (reply instanceof RedisError) {
+                        // A password refused, or missing, is about the connection, not
+                        // the command: said in the words of .env.
+                        pending.reject(reply.code === 'NOAUTH' || reply.code === 'WRONGPASS'
+                            ? new Error(explain(this.address, reply))
+                            : reply);
+                    }
+                    else
+                        pending.resolve(reply);
+                }
+            }
+            catch (error) {
+                socket.destroy(error);
+            }
+        });
+        socket.once(this.address.tls ? 'secureConnect' : 'connect', () => {
+            this.#handshake(socket)
+                .then(() => {
+                clearTimeout(timer);
+                if (this.#state !== 'connecting' || socket !== this.#socket)
+                    return;
+                this.#state = 'ready';
+                this.#attempts = 0;
+                const back = this.#outage !== null && this.#wasReady;
+                this.#outage = null;
+                this.#wasReady = true;
+                if (back)
+                    this.#options.onReconnect?.();
+                const queue = this.#queue;
+                this.#queue = [];
+                for (const { args, pending } of queue)
+                    this.#write(args, pending);
+            })
+                .catch(fail);
+        });
+    }
+    /** Logs in and picks the database, as the first commands of a connection. */
+    async #handshake(socket) {
+        const { username, password, db } = this.address;
+        const steps = [];
+        const ask = (...args) => {
+            steps.push(new Promise((resolve, reject) => {
+                this.#waiting.push({ resolve, reject });
+                socket.write(encodeCommand(args));
+            }));
+        };
+        if (password !== null) {
+            ask('AUTH', ...(username === null ? [password] : [username, password]));
+        }
+        if (db !== 0)
+            ask('SELECT', String(db));
+        await Promise.all(steps);
+    }
+    /** Ends the connection; every command sent from now on fails. */
+    async close() {
+        this.#state = 'closed';
+        if (this.#retryTimer) {
+            clearTimeout(this.#retryTimer);
+            this.#retryTimer = null;
+        }
+        const socket = this.#socket;
+        this.#socket = null;
+        const message = `Redis at ${this.where} is closed: the bot stopped.`;
+        for (const pending of this.#waiting)
+            pending.reject(new Error(message));
+        for (const { pending } of this.#queue)
+            pending.reject(new Error(message));
+        this.#waiting = [];
+        this.#queue = [];
+        socket?.destroy();
+    }
+}

package/dist/redis/protocol.d.ts

@@ -0,0 +1,22 @@
+/** What Redis answers: a text, a number, nothing, or a list of those. */
+export type RedisReply = string | number | null | RedisReply[];
+/** A `-ERR …` reply: Redis refused the command and says why. */
+export declare class RedisError extends Error {
+    name: string;
+    /** The first word of the message: `ERR`, `WRONGPASS`, `NOAUTH`… */
+    readonly code: string;
+    constructor(message: string);
+}
+/** A command as Redis reads it: an array of bulk strings. */
+export declare function encodeCommand(args: readonly (string | number)[]): Buffer;
+/**
+ * Reads replies out of the bytes received so far. `push()` adds what
+ * arrived, `next()` gives the next whole reply, or `undefined` while a
+ * reply is still incomplete: what was read of it is kept for the next
+ * push, so a reply cut anywhere by the network is read whole.
+ */
+export declare class ReplyReader {
+    #private;
+    push(chunk: Buffer): void;
+    next(): RedisReply | undefined;
+}

package/dist/redis/protocol.js

@@ -0,0 +1,99 @@
+// RESP, the protocol of Redis, on nothing but Buffers: how a command is
+// written on the wire, and how what comes back is read, one reply at a
+// time, from bytes that arrive in any number of pieces. RESP2 only: every
+// Redis speaks it, and the few commands the framework sends need no more.
+// https://redis.io/docs/latest/develop/reference/protocol-spec/
+/** A `-ERR …` reply: Redis refused the command and says why. */
+export class RedisError extends Error {
+    name = 'RedisError';
+    /** The first word of the message: `ERR`, `WRONGPASS`, `NOAUTH`… */
+    code;
+    constructor(message) {
+        super(message);
+        this.code = message.split(' ', 1)[0] ?? '';
+    }
+}
+const CRLF = '\r\n';
+/** A command as Redis reads it: an array of bulk strings. */
+export function encodeCommand(args) {
+    const parts = [Buffer.from(`*${args.length}${CRLF}`)];
+    for (const arg of args) {
+        const bytes = Buffer.from(String(arg));
+        parts.push(Buffer.from(`$${bytes.length}${CRLF}`), bytes, Buffer.from(CRLF));
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * Reads replies out of the bytes received so far. `push()` adds what
+ * arrived, `next()` gives the next whole reply, or `undefined` while a
+ * reply is still incomplete: what was read of it is kept for the next
+ * push, so a reply cut anywhere by the network is read whole.
+ */
+export class ReplyReader {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer =
+            this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
+    }
+    next() {
+        const read = this.#read(0);
+        if (!read)
+            return undefined;
+        this.#buffer = this.#buffer.subarray(read.end);
+        return read.reply;
+    }
+    /** A line ending in CRLF from `start`: its text and where the next starts. */
+    #line(start) {
+        const at = this.#buffer.indexOf(CRLF, start);
+        if (at === -1)
+            return null;
+        return { text: this.#buffer.toString('utf8', start, at), end: at + 2 };
+    }
+    #read(start) {
+        if (start >= this.#buffer.length)
+            return null;
+        const type = this.#buffer[start];
+        const line = this.#line(start + 1);
+        if (!line)
+            return null;
+        switch (type) {
+            case 0x2b: // +
+                return { reply: line.text, end: line.end };
+            case 0x2d: // -
+                return { reply: new RedisError(line.text), end: line.end };
+            case 0x3a: // :
+                return { reply: Number(line.text), end: line.end };
+            case 0x24: {
+                // $
+                const length = Number(line.text);
+                if (length === -1)
+                    return { reply: null, end: line.end };
+                const end = line.end + length + 2;
+                if (this.#buffer.length < end)
+                    return null;
+                return {
+                    reply: this.#buffer.toString('utf8', line.end, line.end + length),
+                    end,
+                };
+            }
+            case 0x2a: {
+                // *
+                const count = Number(line.text);
+                if (count === -1)
+                    return { reply: null, end: line.end };
+                const items = [];
+                let at = line.end;
+                for (let index = 0; index < count; index++) {
+                    const item = this.#read(at);
+                    if (!item)
+                        return null;
+                    items.push(item.reply);
+                    at = item.end;
+                }
+                return { reply: items, end: at };
+            }
+            default:
+                throw new Error(`Redis answered something that is not RESP (a line starting with ${JSON.stringify(String.fromCharCode(type ?? 0))}): is REDIS_URL the address of a Redis server?`);
+        }
+    }
+}

package/dist/redis/url.d.ts

@@ -0,0 +1,24 @@
+/** Where Redis is and how to connect: what the client is created with. */
+export interface RedisAddress {
+    host: string;
+    port: number;
+    /** `rediss://`: the connection is encrypted with TLS. */
+    tls: boolean;
+    /** The user of the ACL, when the URL names one; the default user otherwise. */
+    username: string | null;
+    password: string | null;
+    /** The database index: `0` unless the URL ends with `/N`. */
+    db: number;
+}
+export declare const REDIS_URL_HELP = "Write it like redis://localhost:6379 (rediss:// for a TLS connection, /1 at the end for a database other than 0), with the user and password when there are some: redis://user:password@host:6379.";
+/** `host:port`, and the database when it is not the first: what messages show. Never the password. */
+export declare const describeRedis: (address: RedisAddress) => string;
+/**
+ * Reads a `REDIS_URL`, with the `REDIS_PASSWORD` set beside it winning over
+ * the one of the URL. Answers what is wrong when it is not a Redis address.
+ */
+export declare function parseRedisUrl(text: string, password: string): {
+    address: RedisAddress;
+} | {
+    problem: string;
+};

package/dist/redis/url.js

@@ -0,0 +1,50 @@
+// What `REDIS_URL` (and `REDIS_PASSWORD`) say: where Redis is, how to
+// reach it, and as what. Read once from the environment by the CLI and
+// given to the client; a wrong value is explained in the words of `.env`.
+// https://redis.io/docs/latest/develop/clients/nodejs/connect/ (the
+// `redis://` and `rediss://` forms every client reads)
+export const REDIS_URL_HELP = 'Write it like redis://localhost:6379 (rediss:// for a TLS connection, /1 at the end for a database other than 0), with the user and password when there are some: redis://user:password@host:6379.';
+/** `host:port`, and the database when it is not the first: what messages show. Never the password. */
+export const describeRedis = (address) => `${address.host}:${address.port}${address.db === 0 ? '' : `/${address.db}`}`;
+/**
+ * Reads a `REDIS_URL`, with the `REDIS_PASSWORD` set beside it winning over
+ * the one of the URL. Answers what is wrong when it is not a Redis address.
+ */
+export function parseRedisUrl(text, password) {
+    let url;
+    try {
+        if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(text))
+            throw new Error('no scheme');
+        url = new URL(text);
+    }
+    catch {
+        return { problem: `is not an address. ${REDIS_URL_HELP}` };
+    }
+    if (url.protocol !== 'redis:' && url.protocol !== 'rediss:') {
+        return {
+            problem: `starts with "${url.protocol}//", and a Redis address starts with redis:// or rediss://. ${REDIS_URL_HELP}`,
+        };
+    }
+    if (url.hostname === '') {
+        return { problem: `names no host. ${REDIS_URL_HELP}` };
+    }
+    const port = url.port === '' ? 6379 : Number(url.port);
+    const path = url.pathname.replace(/^\//, '');
+    if (path !== '' && !/^\d+$/.test(path)) {
+        return {
+            problem: `ends with "/${path}", and what follows the host is the number of the database. ${REDIS_URL_HELP}`,
+        };
+    }
+    const own = password !== '' ? password : decodeURIComponent(url.password);
+    return {
+        address: {
+            // A URL keeps IPv6 brackets around the host; a socket wants none.
+            host: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+            port,
+            tls: url.protocol === 'rediss:',
+            username: url.username === '' ? null : decodeURIComponent(url.username),
+            password: own === '' ? null : own,
+            db: path === '' ? 0 : Number(path),
+        },
+    };
+}

package/dist/rest/errors.d.ts

@@ -15,7 +15,6 @@ export interface DiscordFieldError {
  * @see https://docs.discord.com/developers/reference#error-messages
  */
 export declare function flattenFieldErrors(errors: unknown, path?: string): DiscordFieldError[];
-/** Discord answered a request with an error. */
 export declare class DiscordApiError extends Error {
     readonly name = "DiscordApiError";
     /** The HTTP status of the response (403, 404...). */

package/dist/rest/errors.js

@@ -32,6 +32,19 @@ export function flattenFieldErrors(errors, path = '') {
     return found;
 }
 /** Discord answered a request with an error. */
+/**
+ * What a refusal means, in plain words, for the codes a bot meets most: the
+ * text of Discord names the problem, not what to do about it.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#json-json-error-codes
+ */
+const HINTS = {
+    50013: "The bot is missing a permission for this, or acts on someone above it: the owner of the server, or a member or role higher than the bot's highest role.",
+    50001: 'The bot can not see this channel or server: give it View Channel there, or check that it is still in the server.',
+    10008: 'The message does not exist any more: it was deleted.',
+    10003: 'The channel does not exist any more: it was deleted.',
+    10007: 'This person is not a member of the server any more.',
+    50007: 'This person does not accept private messages from the bot: they closed them, or share no server with it.',
+};
 export class DiscordApiError extends Error {
     name = 'DiscordApiError';
     /** The HTTP status of the response (403, 404...). */
@@ -62,7 +75,8 @@ export class DiscordApiError extends Error {
         const details = fieldErrors
             .map(error => `\n  ${error.path || 'request'}: ${error.message}`)
             .join('');
-        super(`Discord refused ${input.method} ${input.route}: ${reason} (${code || input.status})${details}`);
+        const hint = HINTS[code] ? ` ${HINTS[code]}` : '';
+        super(`Discord refused ${input.method} ${input.route}: ${reason} (${code || input.status}).${hint}${details}`);
         this.status = input.status;
         this.code = code;
         this.fieldErrors = fieldErrors;

package/dist/rest/rest.js

@@ -1,5 +1,6 @@
 // The only place that sends HTTP requests to Discord.
 // https://docs.discord.com/developers/reference#http-api
+import { callSite, fromSite } from '../util/call-site.js';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { API_BASE_URL, API_VERSION, AUDIT_LOG_REASON_MAX_LENGTH, userAgent, } from '../discord/api.js';
 import { HttpStatus } from '../discord/codes.js';
@@ -68,7 +69,15 @@ export class RestClient {
             onWait: options.onRateLimit,
         });
     }
-    async request(endpoint, params, options = {}) {
+    request(endpoint, params, options = {}) {
+        // Taken now, while the files are in the stack: a refusal that comes
+        // later still names their line, even when they did not await.
+        const site = callSite();
+        return this.#send(endpoint, params, options).catch((error) => {
+            throw fromSite(error, site);
+        });
+    }
+    async #send(endpoint, params, options) {
         const auth = options.auth ?? true;
         if (auth && this.#tokenRefused)
             throw new InvalidTokenError();

package/dist/store/backend.d.ts

@@ -1,3 +1,6 @@
+/** Where a store keeps its data: what `storage` of its config names. */
+export type StoreStorage = 'file' | 'redis';
+export declare const STORAGES: readonly StoreStorage[];
 /** One value of a store, with when it expires. */
 export interface StoreEntry {
     value: unknown;
@@ -10,6 +13,7 @@ export type StoreKeyParts = readonly string[];
 export interface StoreListedEntry extends StoreEntry {
     key: StoreKeyParts;
 }
+import type { RankingBackend } from './ranking-backend.js';
 /** What keeps the data of every store. Expired entries are never given. */
 export interface StoreBackend {
     get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
@@ -17,9 +21,35 @@ export interface StoreBackend {
     delete(store: string, key: StoreKeyParts): Promise<boolean>;
     /** The entries whose key starts with `prefix`, in no particular order. */
     entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    /**
+     * Reads the entry at `key` and keeps what `change` returns, with nothing
+     * written there by anyone in between: two updates never lose one
+     * another, in one process or in several. `change` may run more than
+     * once, when the entry changed meanwhile; `undefined` writes nothing.
+     * Resolves with the entry kept.
+     */
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    /** Forgets every entry whose key starts with `prefix`; how many there were. */
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
+    /**
+     * A native way to keep rankings, when the backend has one. Without it,
+     * rankings are kept as entries of the backend (`StoreRankingBackend`).
+     */
+    rankings?(): RankingBackend;
     /** Writes what is pending, if anything. */
     close(): Promise<void>;
 }
+/** What `update()` makes of the current entry: the next one, or `undefined` for none. */
+export type StoreChange = (current: StoreEntry | undefined) => StoreEntry | undefined;
+/**
+ * Runs what is given for one key one after the other, in this process:
+ * updates of one key here never compete with each other, only with the
+ * other processes. Keys that are not busy cost nothing.
+ */
+export declare class KeyQueue {
+    #private;
+    run<T>(id: string, fn: () => Promise<T>): Promise<T>;
+}
 /** The map key of a key: unambiguous whatever the parts hold. */
 export declare const encodeKey: (key: StoreKeyParts) => string;
 export declare const decodeKey: (encoded: string) => string[];
@@ -27,7 +57,22 @@ export declare const decodeKey: (encoded: string) => string[];
 export declare function startsWith(key: StoreKeyParts, prefix: StoreKeyParts): boolean;
 /** Whether an entry is still good at `now`. */
 export declare const alive: (entry: StoreEntry, now?: number) => boolean;
-/** Gives every store its backend: called by the CLI, once per process. */
-export declare function setStoreBackend(backend: StoreBackend | null): void;
-/** The backend of the process, or an error that says when stores work. */
-export declare function storeBackend(): StoreBackend;
+/**
+ * Gives every store of one storage its backend: called by the CLI, once
+ * per process and per storage the project has a backend for; `null`
+ * takes it away.
+ */
+export declare function setStoreBackend(storage: StoreStorage, backend: StoreBackend | null): void;
+/** The backends of the process, by storage. */
+export declare const storeBackends: () => ReadonlyMap<StoreStorage, StoreBackend>;
+/** A store of a storage the process has no backend for: nothing to fix in the file. */
+export declare class NowhereToKeepError extends TypeError {
+    name: string;
+}
+/** Why a store of `storage` can't be used: the process has no backend for it. */
+export declare function nowhereToKeep(storage: StoreStorage, name: string, what?: string): string;
+/**
+ * The backend of a storage, or an error that says when stores work: for
+ * Redis, that the project gave no address.
+ */
+export declare function storeBackend(storage: StoreStorage, name?: string): StoreBackend;