@tusile/bot 0.2.1 → 0.5.0

package/src/http.js

@@ -1,136 +1,155 @@
-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')),
-  };
-}
+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;
+  #onRefused;
+
+  constructor({
+    baseUrl,
+    authorization,
+    fetch = globalThis.fetch,
+    sleep = wait,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    // Called once when a request is refused as unauthorized. Returns true if it did something
+    // about it, in which case the request is sent again. This is how an expired token is
+    // noticed: the refusal is the only moment anybody learns the old one is no longer good.
+    onRefused,
+  }) {
+    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;
+    this.#onRefused = onRefused || null;
+    /** 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, { signal, refreshed = false } = {}) {
+    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) };
+    // Carried through the retries as well: a request meant to be held open needs the same
+    // deadline on every attempt, or the second attempt is the one that hangs forever.
+    if (signal) init.signal = signal;
+
+    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);
+
+      // A token a community issues lasts an hour and the socket it was minted for stays up for
+      // days, so this is the ordinary state of any bot that has been running a while: it hears
+      // every command and can act on none of them, with nothing visibly wrong. Once per call,
+      // so a community that refuses whatever it is given is an error rather than a loop.
+      if (res.status === 401 && !refreshed && this.#onRefused) {
+        if (await this.#onRefused()) {
+          return this.request(method, path, body, { signal, refreshed: true });
+        }
+      }
+
+      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/interaction.js

@@ -1,140 +1,156 @@
-/**
- * One thing somebody asked a bot to do, and the ways of answering it.
- *
- * The protocol underneath is a response type and a JSON body. Written out by hand that is
- * four lines of ceremony around every answer, repeated at every branch of a switch, which
- * is how a bot ends up with a `defer` it forgot to follow up and an `ephemeral` it meant
- * to be public. These are the same four lines, named after what they do.
- */
-
-/** How long the server gives a bot to say something before the person is told it did not. */
-export const ANSWER_WINDOW_MS = 10_000;
-
-export class Interaction {
-  constructor(data, server) {
-    this.raw = data;
-    this.server = server;
-
-    this.id = data.id;
-    this.type = data.type;
-    this.command = data.command || '';
-    this.options = data.options || {};
-    this.customId = data.custom_id || '';
-    this.values = data.values || [];
-    this.fields = data.fields || {};
-    this.channelId = data.channel_id;
-    this.userId = data.user_id;
-    /** The message a control came from, when there is one. */
-    this.messageId = data.message_id || '';
-    /** The earlier answer a control came from, for a control on a private answer. */
-    this.sourceInteractionId = data.source_interaction_id || '';
-
-    this.answered = false;
-  }
-
-  get isCommand() {
-    return this.type === 'command';
-  }
-
-  get isComponent() {
-    return this.type === 'component';
-  }
-
-  get isModalSubmit() {
-    return this.type === 'modal_submit';
-  }
-
-  /**
-   * Answer it.
-   *
-   * A string is the common case and means a public message. An object is passed through,
-   * so anything the API accepts is still reachable.
-   */
-  reply(response, { ephemeral = false } = {}) {
-    const body =
-      typeof response === 'string'
-        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
-        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
-    return this.#answer(body);
-  }
-
-  /** Answer only the person who asked. Not channel history, and gone within a day. */
-  replyPrivately(response) {
-    return this.reply(response, { ephemeral: true });
-  }
-
-  /**
-   * Say "give me a moment".
-   *
-   * Buys fifteen minutes. Without it a bot that takes longer than ten seconds is reported
-   * to the person as not having responded, which is a lie about a bot that is working.
-   */
-  defer() {
-    return this.#answer({ type: 'defer' });
-  }
-
-  /**
-   * Rewrite the message the control is on.
-   *
-   * The usual answer to a press: a confirm that removes its own buttons, a page that
-   * turns, a toggle that redraws. `components: []` is how the buttons come off.
-   */
-  update(response) {
-    const body = typeof response === 'string' ? { content: response } : response;
-    return this.#answer({ type: 'update_message', ...body });
-  }
-
-  /** Acknowledge a press that needs no visible change, because it did its work elsewhere. */
-  acknowledge() {
-    return this.#answer({ type: 'defer_update' });
-  }
-
-  /** Ask the person to fill something in. The submission arrives as a modal_submit. */
-  showModal(modal) {
-    return this.#answer({ type: 'modal', modal });
-  }
-
-  /** Another message after the first. Only after defer or a first answer. */
-  followUp(response, { ephemeral = false } = {}) {
-    const body =
-      typeof response === 'string'
-        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
-        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
-    return this.server.request('POST', `/bot/interactions/${this.id}/followup`, body);
-  }
-
-  /**
-   * Change the answer already given.
-   *
-   * What a slow bot wants: defer, say "working on it", then say what happened, in the
-   * same message rather than a second one underneath the first.
-   */
-  editReply(response) {
-    const body = typeof response === 'string' ? { content: response } : response;
-    return this.server.request('PATCH', `/bot/interactions/${this.id}/response`, body);
-  }
-
-  /** Take the answer back. */
-  deleteReply() {
-    return this.server.request('DELETE', `/bot/interactions/${this.id}/response`);
-  }
-
-  async #answer(body) {
-    // Guarded here as well as on the server, because the server's refusal arrives as a
-    // 409 in a log somewhere and this arrives in the bot author's own stack trace.
-    if (this.answered) {
-      throw new Error(
-        `interaction ${this.id} has already been answered; use followUp or editReply`,
-      );
-    }
-    this.answered = true;
-    try {
-      return await this.server.request('POST', `/bot/interactions/${this.id}/callback`, body);
-    } catch (err) {
-      // Not answered after all, so a retry is allowed. Otherwise one dropped connection
-      // makes the interaction unanswerable for the rest of its life.
-      this.answered = false;
-      throw err;
-    }
-  }
-}
+/**
+ * One thing somebody asked a bot to do, and the ways of answering it.
+ *
+ * The protocol underneath is a response type and a JSON body. Written out by hand that is
+ * four lines of ceremony around every answer, repeated at every branch of a switch, which
+ * is how a bot ends up with a `defer` it forgot to follow up and an `ephemeral` it meant
+ * to be public. These are the same four lines, named after what they do.
+ */
+
+/** How long the server gives a bot to say something before the person is told it did not. */
+export const ANSWER_WINDOW_MS = 10_000;
+
+export class Interaction {
+  constructor(data, server) {
+    this.raw = data;
+    this.server = server;
+
+    this.id = data.id;
+    this.type = data.type;
+    this.command = data.command || '';
+    this.options = data.options || {};
+    this.customId = data.custom_id || '';
+    this.values = data.values || [];
+    this.fields = data.fields || {};
+    this.channelId = data.channel_id;
+    this.userId = data.user_id;
+    /**
+     * The voice channel the person who did this is sitting in, or '' for none.
+     *
+     * Carried on the interaction rather than fetched, so a bot asked to do something in
+     * voice can use the room they are already in instead of making them name one. It is
+     * also the only channel id a bot can act on without wondering whether the caller was
+     * allowed to name it: they are demonstrably in it.
+     *
+     * Communities older than this send nothing, so treat '' as "they did not say", not as
+     * "they are nowhere".
+     */
+    this.userVoiceChannelId = data.user_voice_channel_id || '';
+    /** The message a control came from, when there is one. */
+    this.messageId = data.message_id || '';
+    /** The earlier answer a control came from, for a control on a private answer. */
+    this.sourceInteractionId = data.source_interaction_id || '';
+
+    this.answered = false;
+  }
+
+  get isCommand() {
+    return this.type === 'command';
+  }
+
+  get isComponent() {
+    return this.type === 'component';
+  }
+
+  get isModalSubmit() {
+    return this.type === 'modal_submit';
+  }
+
+  /**
+   * Answer it.
+   *
+   * A string is the common case and means a public message. An object is passed through,
+   * so anything the API accepts is still reachable.
+   */
+  reply(response, { ephemeral = false } = {}) {
+    const body =
+      typeof response === 'string'
+        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
+        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
+    return this.#answer(body);
+  }
+
+  /** Answer only the person who asked. Not channel history, and gone within a day. */
+  replyPrivately(response) {
+    return this.reply(response, { ephemeral: true });
+  }
+
+  /**
+   * Say "give me a moment".
+   *
+   * Buys fifteen minutes. Without it a bot that takes longer than ten seconds is reported
+   * to the person as not having responded, which is a lie about a bot that is working.
+   *
+   * `ephemeral` says who the answer will be for when it arrives, because this is the only
+   * call that can: a defer delivers nothing, and the edit that carries the answer later
+   * has no type of its own. Left out, the answer goes to the channel.
+   */
+  defer({ ephemeral = false } = {}) {
+    return this.#answer(ephemeral ? { type: 'defer', ephemeral: true } : { type: 'defer' });
+  }
+
+  /**
+   * Rewrite the message the control is on.
+   *
+   * The usual answer to a press: a confirm that removes its own buttons, a page that
+   * turns, a toggle that redraws. `components: []` is how the buttons come off.
+   */
+  update(response) {
+    const body = typeof response === 'string' ? { content: response } : response;
+    return this.#answer({ type: 'update_message', ...body });
+  }
+
+  /** Acknowledge a press that needs no visible change, because it did its work elsewhere. */
+  acknowledge() {
+    return this.#answer({ type: 'defer_update' });
+  }
+
+  /** Ask the person to fill something in. The submission arrives as a modal_submit. */
+  showModal(modal) {
+    return this.#answer({ type: 'modal', modal });
+  }
+
+  /** Another message after the first. Only after defer or a first answer. */
+  followUp(response, { ephemeral = false } = {}) {
+    const body =
+      typeof response === 'string'
+        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
+        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
+    return this.server.request('POST', `/bot/interactions/${this.id}/followup`, body);
+  }
+
+  /**
+   * Change the answer already given.
+   *
+   * What a slow bot wants: defer, say "working on it", then say what happened, in the
+   * same message rather than a second one underneath the first.
+   */
+  editReply(response) {
+    const body = typeof response === 'string' ? { content: response } : response;
+    return this.server.request('PATCH', `/bot/interactions/${this.id}/response`, body);
+  }
+
+  /** Take the answer back. */
+  deleteReply() {
+    return this.server.request('DELETE', `/bot/interactions/${this.id}/response`);
+  }
+
+  async #answer(body) {
+    // Guarded here as well as on the server, because the server's refusal arrives as a
+    // 409 in a log somewhere and this arrives in the bot author's own stack trace.
+    if (this.answered) {
+      throw new Error(
+        `interaction ${this.id} has already been answered; use followUp or editReply`,
+      );
+    }
+    this.answered = true;
+    try {
+      return await this.server.request('POST', `/bot/interactions/${this.id}/callback`, body);
+    } catch (err) {
+      // Not answered after all, so a retry is allowed. Otherwise one dropped connection
+      // makes the interaction unanswerable for the rest of its life.
+      this.answered = false;
+      throw err;
+    }
+  }
+}

package/src/known.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * What this bot already knows, as one short string.
+ *
+ * Sent to Core as ?known= alongside ?wait=, so Core can hold the request open until the
+ * answer would actually be different. Before this, Core would only hold a request for a bot
+ * that was on no communities at all, which meant every bot already serving one heard about
+ * the next one on its own sixty-second timer: half a minute of nothing, on average, after
+ * somebody pressed Add.
+ *
+ * Mirrors core-server/internal/bots/known.go exactly, and the same three vectors are pinned
+ * in both test suites. A count would have been easier and wrong: removed from one community
+ * and added to another between two polls is the same count, so Core would hold the request
+ * while the bot served the wrong place.
+ */
+const VERSION = 'v1';
+
+export function serversToken(serverIds) {
+  const unique = [...new Set(serverIds ?? [])].map(String).sort();
+  const digest = createHash('sha256').update(unique.join('\n')).digest('hex');
+  return `${VERSION}:${digest.slice(0, 16)}`;
+}