@tusile/bot 0.1.0

package/src/dispatch.js

@@ -0,0 +1,173 @@
+/**
+ * Which handler wants this interaction, and what to do when none of them does.
+ *
+ * The routing is the easy half. The half worth writing carefully is the part that runs
+ * when a handler throws, forgets to answer, or takes longer than the server's ten second
+ * window: the person who ran the command is sitting in front of a spinner, and every one
+ * of those cases ends with them being told "the bot did not respond", which reads as a
+ * dead bot rather than a bug in one command. So every path through here answers.
+ */
+
+/**
+ * When to defer on the handler's behalf.
+ *
+ * The server's window is ten seconds. Two seconds of margin covers the round trip from
+ * wherever the bot is running, and a bot author who never thinks about any of this gets
+ * the same behaviour as one who deferred by hand.
+ */
+const DEFAULT_AUTO_DEFER_MS = 8000;
+
+export class Dispatcher {
+  #commands = new Map();
+  #components = [];
+  #modals = [];
+  #onError;
+  #autoDeferMs;
+
+  constructor({ onError = () => {}, autoDeferMs = DEFAULT_AUTO_DEFER_MS } = {}) {
+    this.#onError = onError;
+    this.#autoDeferMs = autoDeferMs;
+  }
+
+  /**
+   * A slash command and what runs it.
+   *
+   * The definition is what people see in the app: name, description, and options that are
+   * checked and turned into pickers before the bot is ever asked anything.
+   */
+  command(definition, handler) {
+    const name = definition?.name;
+    if (!name) throw new Error('a command needs a name');
+    if (typeof handler !== 'function') throw new Error(`/${name} needs a handler`);
+    if (this.#commands.has(name)) throw new Error(`/${name} is already registered`);
+    this.#commands.set(name, { definition: { ...definition }, handler });
+    return this;
+  }
+
+  /**
+   * A button or select, matched on its custom id exactly or by prefix.
+   *
+   * A custom id is the bot's own: the server echoes it back without ever parsing it, so
+   * `vote:close:99` is how a control carries its state. Prefix matching is what makes
+   * that usable, and an exact registration still wins over a prefix that would match it.
+   */
+  component(customId, handler) {
+    if (!customId) throw new Error('a component handler needs a custom id');
+    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
+    this.#components.push({ customId, handler });
+    return this;
+  }
+
+  /** A form submission, matched the same way. */
+  modal(customId, handler) {
+    if (!customId) throw new Error('a modal handler needs a custom id');
+    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
+    this.#modals.push({ customId, handler });
+    return this;
+  }
+
+  /** What to send the server as this bot's command list. */
+  definitions() {
+    return [...this.#commands.values()].map((c) => c.definition);
+  }
+
+  async handle(interaction) {
+    const found = this.#route(interaction);
+    if (!found) return;
+    if (!found.handler) {
+      // Something is offered that this bot no longer implements: a command list left over
+      // from an older deploy, or a button on a message from one. Say so quietly rather
+      // than leave somebody watching a spinner run out.
+      await this.#sayQuietly(interaction, found.missing);
+      return;
+    }
+
+    const deferring = this.#deferAfterAWhile(interaction);
+    try {
+      await found.handler(interaction);
+      if (!interaction.answered) {
+        // The commonest bot bug there is, and from the outside identical to a crash.
+        throw new Error(`${describe(interaction)} was handled without an answer`);
+      }
+    } catch (err) {
+      this.#onError(err, interaction);
+      await this.#apologise(interaction);
+    } finally {
+      deferring.cancel();
+    }
+  }
+
+  #route(interaction) {
+    if (interaction.isCommand) {
+      const found = this.#commands.get(interaction.command);
+      return found || { missing: `I do not know /${interaction.command} any more.` };
+    }
+    if (interaction.isComponent) {
+      const found = longestMatch(this.#components, interaction.customId);
+      return found || { missing: 'That control belongs to an older version of this bot.' };
+    }
+    if (interaction.isModalSubmit) {
+      const found = longestMatch(this.#modals, interaction.customId);
+      return found || { missing: 'That form belongs to an older version of this bot.' };
+    }
+    // A kind of interaction newer than this package. Answering it could say the wrong
+    // thing, and it is not a bug in the bot, so it goes no further.
+    return null;
+  }
+
+  /**
+   * Defer if the handler is still working when the window is nearly up.
+   *
+   * Cancelled the moment the handler returns, and it checks again before sending: an
+   * unasked-for defer arriving after a normal answer would be refused every time.
+   */
+  #deferAfterAWhile(interaction) {
+    if (!(this.#autoDeferMs > 0)) return { cancel() {} };
+    const timer = setTimeout(() => {
+      if (interaction.answered) return;
+      interaction.defer().catch((err) => this.#onError(err, interaction));
+    }, this.#autoDeferMs);
+    return { cancel: () => clearTimeout(timer) };
+  }
+
+  async #apologise(interaction) {
+    if (interaction.answered) return;
+    try {
+      await interaction.replyPrivately('Something went wrong. The bot author has been told.');
+    } catch (err) {
+      // Nothing left to try. The person will see the server's own timeout notice, which
+      // at least is true.
+      this.#onError(err, interaction);
+    }
+  }
+
+  async #sayQuietly(interaction, text) {
+    try {
+      await interaction.replyPrivately(text);
+    } catch (err) {
+      this.#onError(err, interaction);
+    }
+  }
+}
+
+/**
+ * The most specific registration that matches.
+ *
+ * An exact id is the longest possible match, so this is one rule rather than two: a
+ * general `vote` handler cannot swallow presses meant for `vote:close`.
+ */
+function longestMatch(entries, customId) {
+  const id = customId || '';
+  let best = null;
+  for (const entry of entries) {
+    if (id !== entry.customId && !id.startsWith(entry.customId)) continue;
+    if (!best || entry.customId.length > best.customId.length) best = entry;
+  }
+  return best;
+}
+
+function describe(interaction) {
+  if (interaction.isCommand) return `/${interaction.command}`;
+  if (interaction.customId) return `\`${interaction.customId}\``;
+  return interaction.type || 'an interaction';
+}

package/src/errors.js

@@ -0,0 +1,49 @@
+/** What a refusal from Tusile looks like by the time a bot author sees it. */
+export class ApiError extends Error {
+  constructor({ method, path, status, body, retryAfterMs = null }) {
+    const code = codeIn(body);
+    // Everything needed to work out what happened, in the one line that reaches a log:
+    // which call, what the server said, and the server's own word for why.
+    super(`${method} ${path} failed: ${status}${code ? ` ${code}` : ''}${detail(body, code)}`);
+    this.name = 'TusileApiError';
+    this.method = method;
+    this.path = path;
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.retryAfterMs = retryAfterMs;
+  }
+
+  /**
+   * The community removed this bot.
+   *
+   * Worth its own question, because it is the one failure that will never come right: a
+   * bot that keeps reconnecting to a community that dropped it is doing nothing but
+   * making noise in two sets of logs.
+   */
+  get isUninstalled() {
+    return this.code === 'bot_uninstalled';
+  }
+
+  get isRateLimited() {
+    return this.status === 429;
+  }
+
+  /** Permission, usually. Nothing to retry, something to fix in the bot's roles. */
+  get isForbidden() {
+    return this.status === 403;
+  }
+}
+
+function codeIn(body) {
+  if (!body || typeof body !== 'object') return '';
+  return String(body.error || body.code || '');
+}
+
+function detail(body, code) {
+  if (typeof body === 'string' && body.trim() && body.length < 200) return `: ${body.trim()}`;
+  if (body && typeof body === 'object' && body.message && body.message !== code) {
+    return `: ${body.message}`;
+  }
+  return '';
+}

package/src/gateway.js

@@ -0,0 +1,180 @@
+/**
+ * The socket a bot keeps open to one community.
+ *
+ * A Tusile bot dials out. There is no inbound port and no public url to arrange, which is
+ * most of why the webhook bots this replaces went unwritten: a hobby bot on a laptop
+ * cannot be called back. The cost of dialling out is that the connection is now the bot's
+ * problem, and that is what this file is: the auth frame first, a heartbeat at whatever
+ * interval the server asks for, and a clear answer to the only question that matters when
+ * a socket dies, which is whether to try again.
+ */
+
+const DEFAULT_HEARTBEAT_SECONDS = 30;
+
+/** Where the gateway lives, given where the community's api lives. */
+export function gatewayUrl(apiUrl) {
+  return String(apiUrl || '').replace(/\/+$/, '').replace(/^http/, 'ws') + '/bot/gateway';
+}
+
+/**
+ * How long to wait before trying a dead connection again.
+ *
+ * Doubling, and capped: a community that is down for the afternoon should not be asked
+ * every millisecond, and a bot should not sit out an hour because of one bad minute.
+ */
+export function nextBackoff(current, min, max) {
+  if (!current) return min;
+  return Math.min(current * 2, max);
+}
+
+export class Gateway {
+  #token;
+  #connect;
+  #timers;
+  #onReady;
+  #onFrame;
+  #heartbeat = null;
+  #settle = null;
+  #closed = null;
+  #generation = 0;
+  #wasLive = false;
+
+  constructor({ url, token, connect, timers = globalThis, onReady = () => {}, onFrame = () => {} }) {
+    this.url = url;
+    this.socket = null;
+    this.stopped = false;
+    this.#token = token;
+    this.#connect = connect;
+    this.#timers = timers;
+    this.#onReady = onReady;
+    this.#onFrame = onFrame;
+  }
+
+  /**
+   * Mint a token and open the socket.
+   *
+   * Resolves once the socket exists and is wired up, not once it is authenticated: a
+   * caller that wants to know the connection worked waits on `closed()`, which is the
+   * same thing as waiting for it to stop working.
+   */
+  async open() {
+    this.#generation += 1;
+    const generation = this.#generation;
+    this.#wasLive = false;
+    this.#closed = new Promise((resolve) => {
+      this.#settle = (outcome) => {
+        if (generation !== this.#generation) return;
+        this.#stopHeartbeat();
+        // Whether this connection ever worked is the difference between a community
+        // that is down and one that drops a socket now and then: the first should be
+        // asked less and less often, the second should be picked up at once.
+        resolve({ ...outcome, wasLive: this.#wasLive });
+      };
+    });
+
+    try {
+      // A token is minted per community and lives an hour, so every connect gets a fresh
+      // one rather than guessing whether the last one is still good.
+      const token = await this.#token();
+      if (this.stopped) {
+        this.#settle({ fatal: true, reason: 'stopped' });
+        return;
+      }
+
+      const socket = this.#connect(gatewayUrl(this.url));
+      this.socket = socket;
+
+      // The auth frame goes first, before anything else is sent or expected.
+      socket.on('open', () => this.#send({ type: 'auth', token }));
+      socket.on('message', (raw) => this.#onMessage(raw));
+      socket.on('close', (code, reason) => {
+        const why = reason ? reason.toString() : '';
+        // The server says this distinctly rather than just closing, so that a bot which
+        // has been removed can stop instead of reconnecting for the rest of its life.
+        this.#settle({ fatal: this.stopped || why.includes('bot_uninstalled'), reason: why });
+      });
+      socket.on('error', (err) => {
+        this.#settle({ fatal: this.stopped, reason: String(err?.message || err) });
+      });
+    } catch (err) {
+      // Core refusing a token, or a socket that would not even be constructed. Settled as
+      // well as thrown: a caller waiting on `closed` would otherwise wait for good.
+      this.#settle({ fatal: err?.isUninstalled === true, reason: String(err?.message || err) });
+      throw err;
+    }
+  }
+
+  /** Resolves when this connection ends, saying whether trying again is worth anything. */
+  closed() {
+    return (
+      this.#closed ?? Promise.resolve({ fatal: this.stopped, reason: 'never opened', wasLive: false })
+    );
+  }
+
+  /** Open it and wait for it to end. Never throws: the outcome says what happened. */
+  async run() {
+    try {
+      await this.open();
+    } catch (err) {
+      // Core refusing to mint a token, usually. Not a reason to give up on the community.
+      return { fatal: err?.isUninstalled === true, reason: String(err?.message || err), wasLive: false };
+    }
+    return this.closed();
+  }
+
+  stop() {
+    this.stopped = true;
+    this.#stopHeartbeat();
+    const settle = this.#settle;
+    // Settled before the close event arrives, so that a bot on its way out does not
+    // reconnect on the strength of its own goodbye.
+    if (settle) settle({ fatal: true, reason: 'stopped' });
+    try {
+      this.socket?.close();
+    } catch {
+      // Closing an already-dead socket is not news.
+    }
+  }
+
+  #onMessage(raw) {
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      // A proxy answering with html, most often. Not worth taking a running bot down for.
+      return;
+    }
+    if (frame?.type === 'ready') {
+      this.#wasLive = true;
+      this.#startHeartbeat(frame.heartbeat_interval_seconds);
+      this.#onReady(frame.bot || {}, frame);
+      return;
+    }
+    this.#onFrame(frame);
+  }
+
+  /**
+   * Check in at the interval the server names.
+   *
+   * A socket that goes quiet is dropped, and on a phone network or behind an idle proxy
+   * that is otherwise indistinguishable from one that is working perfectly well.
+   */
+  #startHeartbeat(seconds) {
+    this.#stopHeartbeat();
+    const ms = (Number(seconds) > 0 ? Number(seconds) : DEFAULT_HEARTBEAT_SECONDS) * 1000;
+    this.#heartbeat = this.#timers.setInterval(() => this.#send({ type: 'heartbeat' }), ms);
+  }
+
+  #stopHeartbeat() {
+    if (this.#heartbeat) this.#timers.clearInterval(this.#heartbeat);
+    this.#heartbeat = null;
+  }
+
+  #send(frame) {
+    try {
+      this.socket?.send(JSON.stringify(frame));
+    } catch {
+      // The socket died between the timer firing and this line. The close handler has it.
+    }
+  }
+}

package/src/http.js

@@ -0,0 +1,136 @@
+import { ApiError } from './errors.js';
+
+/**
+ * Making a request and living with the answer.
+ *
+ * The one thing here that is not obvious: some failures are worth trying again and most
+ * are not. A bot over its budget and a community mid-deploy both come back in a second or
+ * two; a bad request will be refused just as firmly on the fifth attempt as the first.
+ * Retrying the first two is what keeps a redeploy from reading as a bot that lost a
+ * message, and not retrying the rest is what keeps a bug from turning into a flood.
+ */
+
+/** Over budget, or something in front of the server having a moment. */
+const RETRY_STATUS = new Set([429, 502, 503, 504]);
+
+const DEFAULT_MAX_RETRIES = 3;
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class Transport {
+  #fetch;
+  #sleep;
+  #authorization;
+  #maxRetries;
+
+  constructor({
+    baseUrl,
+    authorization,
+    fetch = globalThis.fetch,
+    sleep = wait,
+    maxRetries = DEFAULT_MAX_RETRIES,
+  }) {
+    if (typeof fetch !== 'function') {
+      throw new Error('no fetch available: Node 20 or newer, or pass one in');
+    }
+    this.baseUrl = String(baseUrl || '').replace(/\/+$/, '');
+    this.#authorization = authorization;
+    this.#fetch = fetch;
+    this.#sleep = sleep;
+    this.#maxRetries = maxRetries;
+    /** What the budget looked like on the last answer, for a bot that wants to pace itself. */
+    this.rateLimit = null;
+  }
+
+  async request(method, path, body) {
+    const url = this.baseUrl + path;
+    const headers = { Accept: 'application/json', Authorization: this.#authorization() };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const init = { method, headers, body: body === undefined ? undefined : JSON.stringify(body) };
+
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+      let res;
+      try {
+        res = await this.#fetch(url, init);
+      } catch (err) {
+        // A dropped connection, dns, a laptop that slept. Worth another try; the bot has
+        // nothing else to do and the alternative is a handler that dies for no reason.
+        lastError = err;
+        if (attempt === this.#maxRetries) throw err;
+        await this.#sleep(backoffFor(attempt));
+        continue;
+      }
+
+      this.rateLimit = readRateLimit(res);
+
+      if (res.ok) return parse(await textOf(res));
+
+      const raw = await textOf(res);
+      const parsed = parse(raw);
+      const retryAfterMs = readRetryAfter(res);
+
+      if (RETRY_STATUS.has(res.status) && attempt < this.#maxRetries) {
+        // The server said when to come back. Guessing instead is how a bot stays over
+        // budget for as long as it keeps guessing.
+        await this.#sleep(retryAfterMs ?? backoffFor(attempt));
+        continue;
+      }
+
+      throw new ApiError({
+        method,
+        path,
+        status: res.status,
+        body: parsed ?? raw,
+        retryAfterMs,
+      });
+    }
+    throw lastError || new Error(`${method} ${path} failed`);
+  }
+}
+
+/** Query strings, with anything nobody asked for left out. */
+export function query(params = {}) {
+  const parts = Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+  return parts.length ? `?${parts.join('&')}` : '';
+}
+
+function backoffFor(attempt) {
+  return 500 * 2 ** attempt;
+}
+
+async function textOf(res) {
+  try {
+    return await res.text();
+  } catch {
+    return '';
+  }
+}
+
+function parse(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    // A proxy answering with html, most likely. The status is the real information.
+    return null;
+  }
+}
+
+function readRetryAfter(res) {
+  const raw = res.headers?.get?.('Retry-After');
+  const seconds = Number(raw);
+  return raw && Number.isFinite(seconds) ? Math.max(0, seconds) * 1000 : null;
+}
+
+function readRateLimit(res) {
+  const limit = Number(res.headers?.get?.('X-RateLimit-Limit'));
+  if (!Number.isFinite(limit) || !res.headers?.get?.('X-RateLimit-Limit')) return null;
+  return {
+    limit,
+    remaining: Number(res.headers.get('X-RateLimit-Remaining')),
+    resetSeconds: Number(res.headers.get('X-RateLimit-Reset')),
+  };
+}

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * @tusile/bot
+ *
+ * Everything a Tusile bot needs, in one place. The short version:
+ *
+ *   import { Bot } from '@tusile/bot';
+ *
+ *   const bot = new Bot();                       // reads CORE_SERVER_URL, BOT_KEY, BOT_SECRET
+ *   bot.command({ name: 'ping', description: 'Check the bot is awake' },
+ *               (i) => i.reply('pong'));
+ *   await bot.start();
+ *
+ * That is a working bot on every community that has added it. No inbound port, no public
+ * url, no webhook to register: it dials out.
+ *
+ * The pieces are exported as well, for a bot that wants one without the rest: a script
+ * that only posts a message needs a CoreClient and a ServerClient and no gateway at all.
+ */
+
+export { Bot } from './bot.js';
+export { CoreClient } from './core.js';
+export { ServerClient } from './rest.js';
+export { Gateway, gatewayUrl, nextBackoff } from './gateway.js';
+export { Dispatcher } from './dispatch.js';
+export { Interaction, ANSWER_WINDOW_MS } from './interaction.js';
+export { ApiError } from './errors.js';