@tusile/bot 0.2.1 → 0.4.0

package/src/bot.js

@@ -1,350 +1,615 @@
-import { CoreClient } from './core.js';
-import { Dispatcher } from './dispatch.js';
-import { Gateway, nextBackoff } from './gateway.js';
-import { Interaction } from './interaction.js';
-import { ServerClient } from './rest.js';
-
-/**
- * A bot, on every community that has added it.
- *
- * The shape of the problem: one identity held by Core, one short-lived token per
- * community, one socket per community, and a list of communities that changes while the
- * bot runs. None of that is a bot author's business, and all of it used to be. What is
- * left is `command`, `component`, `modal`, and `start`.
- */
-
-const DEFAULT_POLL_MS = 60 * 1000;
-
-/** How long to let Core hold a request open while the bot is on no communities at all. */
-const JOIN_WAIT_SECONDS = 25;
-
-const RECONNECT_MIN_MS = 1000;
-const RECONNECT_MAX_MS = 30 * 1000;
-
-export class Bot {
-  #core;
-  #dispatcher;
-  #links = new Map();
-  #listeners = new Map();
-  #connect;
-  #timers;
-  #sleep;
-  #fetch;
-  #pollMs;
-  #poll = null;
-  #stopped = false;
-
-  constructor({
-    coreUrl = process.env?.CORE_SERVER_URL,
-    key = process.env?.BOT_KEY,
-    secret = process.env?.BOT_SECRET,
-    fetch,
-    sleep,
-    connect,
-    timers = globalThis,
-    onError,
-    autoDeferMs,
-    pollMs = DEFAULT_POLL_MS,
-  } = {}) {
-    if (!coreUrl) throw new Error('no coreUrl: set CORE_SERVER_URL to the Tusile core server');
-    if (!key || !secret) {
-      // Said here rather than at the first request, because the first request happens
-      // inside a deploy where nobody is watching, and this happens at startup.
-      throw new Error(
-        'no bot credentials: set BOT_KEY and BOT_SECRET. Create a bot in the Tusile app, ' +
-          'under Settings, Bots, and copy them there.',
-      );
-    }
-
-    this.#core = new CoreClient({ url: coreUrl, key, secret, fetch, sleep });
-    this.#fetch = fetch;
-    this.#sleep = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
-    this.#connect = connect || null;
-    this.#timers = timers;
-    this.#pollMs = pollMs;
-    this.#dispatcher = new Dispatcher({
-      autoDeferMs,
-      onError: (err, interaction) => this.#report(err, interaction),
-    });
-    if (onError) this.on('error', onError);
-
-    /** This bot's own account, once it has asked. Its id is how it recognises itself. */
-    this.me = null;
-    /** Every community it is connected to, by id. */
-    this.servers = new Map();
-  }
-
-  // What the bot does.
-
-  command(definition, handler) {
-    this.#dispatcher.command(definition, handler);
-    return this;
-  }
-
-  component(customId, handler) {
-    this.#dispatcher.component(customId, handler);
-    return this;
-  }
-
-  modal(customId, handler) {
-    this.#dispatcher.modal(customId, handler);
-    return this;
-  }
-
-  /**
-   * ready    (bot, server)     connected to a community and registered there
-   * message  (message, server) something said in a channel the bot can see
-   * joined   (server)          added to a community
-   * left     (serverId)        removed from one
-   * error    (error, context)  anything that went wrong, including in a handler
-   */
-  on(event, listener) {
-    if (!this.#listeners.has(event)) this.#listeners.set(event, []);
-    this.#listeners.get(event).push(listener);
-    return this;
-  }
-
-  /**
-   * Connect, and stay connected.
-   *
-   * Resolves once every community known right now has a socket, so that a caller can
-   * reasonably look at `servers` afterwards. Keeps running until `stop`.
-   */
-  async start() {
-    // `ws` is loaded only if nobody supplied a socket, so a runtime with its own
-    // WebSocket, or a test, never pays for it.
-    if (!this.#connect) {
-      const { default: WebSocket } = await import('ws');
-      this.#connect = (url) => new WebSocket(url);
-    }
-    this.me = await this.#core.me();
-    await this.sync();
-    // Being added to a community is a change Core cannot push to a bot, so this is a
-    // poll. It is a slow one, because the empty case, which is the one somebody is
-    // watching, is handled by asking Core to hold the request open instead.
-    this.#poll = this.#timers.setInterval(() => {
-      this.sync().catch((err) => this.#report(err));
-    }, this.#pollMs);
-    return this;
-  }
-
-  /**
-   * Bring the set of connections in line with the set of communities.
-   *
-   * Called on a timer, and worth calling by hand after installing the bot somewhere if a
-   * caller happens to know that has just happened.
-   */
-  async sync() {
-    if (this.#stopped) return;
-    const waitSeconds = this.servers.size === 0 ? JOIN_WAIT_SECONDS : undefined;
-    let servers;
-    try {
-      servers = await this.#core.servers({ waitSeconds });
-    } catch (err) {
-      // Credentials Core refuses will be refused next minute too. Stopping is the honest
-      // answer: a bot that cannot authenticate is not running, and saying so once beats
-      // a 401 a minute for as long as nobody notices.
-      if (err?.isAuthFailure) {
-        this.#report(err);
-        await this.stop();
-      }
-      throw err;
-    }
-    if (this.#stopped) return;
-
-    const seen = new Set();
-    for (const server of servers) {
-      seen.add(server.serverId);
-      if (this.#links.has(server.serverId)) continue;
-      await this.#join(server);
-    }
-    // A community that removed the bot stops being listed, so its socket goes with it.
-    for (const serverId of [...this.#links.keys()]) {
-      if (!seen.has(serverId)) this.#leave(serverId);
-    }
-  }
-
-  /** Close every socket and stop looking for new communities. */
-  async stop() {
-    this.#stopped = true;
-    if (this.#poll) this.#timers.clearInterval(this.#poll);
-    this.#poll = null;
-    for (const serverId of [...this.#links.keys()]) this.#leave(serverId);
-  }
-
-  async #join({ serverId, apiUrl, raw }) {
-    const link = new Link({
-      serverId,
-      apiUrl,
-      raw,
-      core: this.#core,
-      fetch: this.#fetch,
-      sleep: this.#sleep,
-      connect: this.#connect,
-      timers: this.#timers,
-      onReady: (bot, client) => {
-        // Registered on every connect rather than once at startup: a bot redeployed with
-        // a changed command set, or added to a community while it was down, would
-        // otherwise go on offering whatever it registered last time.
-        client
-          .setCommands(this.#dispatcher.definitions())
-          .catch((err) => this.#report(err, { serverId }));
-        this.#emit('ready', bot, client);
-      },
-      onFrame: (frame, client) => this.#onFrame(frame, client),
-      onError: (err) => this.#report(err, { serverId }),
-      // A connection that has ended for good stops being this bot's connection to that
-      // community. Leaving it in place would make a community that removed the bot and
-      // added it again unreachable until the process was restarted: the next sync would
-      // see a link already there and skip it, and the bot would sit offline with nothing
-      // in any log to say why.
-      onFinished: () => {
-        if (this.#links.get(serverId) === link) this.#leave(serverId);
-      },
-    });
-
-    this.#links.set(serverId, link);
-    this.servers.set(serverId, link.client);
-    await link.start();
-    this.#emit('joined', link.client);
-  }
-
-  #leave(serverId) {
-    this.#links.get(serverId)?.stop();
-    this.#links.delete(serverId);
-    this.servers.delete(serverId);
-    this.#emit('left', serverId);
-  }
-
-  #onFrame(frame, client) {
-    if (frame?.type === 'interaction_create') {
-      const interaction = new Interaction(frame.data || {}, client);
-      this.#dispatcher.handle(interaction).catch((err) => this.#report(err, interaction));
-      return;
-    }
-    if (frame?.type === 'message_create') {
-      this.#emit('message', frame.data || {}, client);
-    }
-  }
-
-  #emit(event, ...args) {
-    for (const listener of this.#listeners.get(event) ?? []) {
-      try {
-        listener(...args);
-      } catch (err) {
-        // A throwing listener must not take down the socket that fed it.
-        if (event !== 'error') this.#report(err);
-      }
-    }
-  }
-
-  #report(err, context) {
-    const listeners = this.#listeners.get('error') ?? [];
-    if (!listeners.length) {
-      // Better a line on stderr than a bot that fails in total silence because nobody
-      // wired up an error handler.
-      console.error('[tusile-bot]', err);
-      return;
-    }
-    this.#emit('error', err, context);
-  }
-}
-
-/**
- * One community: its socket, its token, and its reconnects.
- *
- * Kept separate from the bot because everything here is per community. One community being
- * down, or having removed the bot, must leave every other connection alone.
- */
-class Link {
-  #gateway;
-  #core;
-  #sleep;
-  #onError;
-  #onReady;
-  #onFrame;
-  #onFinished;
-  #token = '';
-  #backoff = 0;
-  #stopped = false;
-
-  constructor({ serverId, apiUrl, raw, core, fetch, sleep, connect, timers, onReady, onFrame,
-    onError, onFinished }) {
-    this.serverId = serverId;
-    this.apiUrl = apiUrl;
-    this.raw = raw;
-    this.#core = core;
-    this.#sleep = sleep;
-    this.#onError = onError;
-    this.#onReady = onReady;
-    this.#onFrame = onFrame;
-    this.#onFinished = onFinished || (() => {});
-
-    this.client = new ServerClient({
-      apiUrl,
-      serverId,
-      // Read per request, so a reconnect that mints a new token does not leave the rest
-      // client holding an expired one.
-      token: () => this.#token,
-      fetch,
-      sleep,
-    });
-
-    this.#gateway = new Gateway({
-      url: apiUrl,
-      token: async () => {
-        this.#token = await this.#core.token(serverId);
-        return this.#token;
-      },
-      connect,
-      timers,
-      onReady: (bot) => this.#onReady(bot, this.client),
-      onFrame: (frame) => this.#onFrame(frame, this.client),
-    });
-  }
-
-  /** Open the socket, then keep it open in the background. */
-  async start() {
-    await this.#open();
-    this.#keepAlive().catch((err) => this.#onError(err));
-  }
-
-  stop() {
-    this.#stopped = true;
-    this.#gateway.stop();
-  }
-
-  async #open() {
-    try {
-      await this.#gateway.open();
-    } catch (err) {
-      // Core refusing a token, most likely. Swallowed here because the failure is also
-      // settled on the connection, and the loop below reports it from there: what
-      // matters is that it does not take the bot's other communities with it.
-    }
-  }
-
-  async #keepAlive() {
-    while (!this.#stopped) {
-      const { fatal, reason, wasLive } = await this.#gateway.closed();
-      if (reason) this.#onError(new Error(`[${this.serverId}] ${reason}`));
-      if (fatal || this.#stopped) return this.#finish();
-      // A connection that was up and then dropped is worth picking straight back up.
-      // Carrying the backoff over would leave a bot that reconnects cleanly once an hour
-      // eventually waiting half a minute every time, for nothing.
-      if (wasLive) this.#backoff = 0;
-      this.#backoff = nextBackoff(this.#backoff, RECONNECT_MIN_MS, RECONNECT_MAX_MS);
-      await this.#sleep(this.#backoff);
-      if (this.#stopped) return this.#finish();
-      await this.#open();
-    }
-    this.#finish();
-  }
-
-  /** Say, once, that this connection is over and will not come back by itself. */
-  #finish() {
-    const done = this.#onFinished;
-    this.#onFinished = () => {};
-    done();
-  }
-}
+import { CoreClient } from './core.js';
+import { Dispatcher } from './dispatch.js';
+import { Gateway, nextBackoff } from './gateway.js';
+import { Interaction } from './interaction.js';
+import { serversToken } from './known.js';
+import { toMask } from './permissions.js';
+import { ServerClient } from './rest.js';
+
+/**
+ * A bot, on every community that has added it.
+ *
+ * The shape of the problem: one identity held by Core, one short-lived token per
+ * community, one socket per community, and a list of communities that changes while the
+ * bot runs. None of that is a bot author's business, and all of it used to be. What is
+ * left is `command`, `component`, `modal`, and `start`.
+ */
+
+/**
+ * The fallback, for a Core that will not hold a request open: an older one, or one that
+ * answered and said nothing about watching. Not the mechanism any more.
+ */
+const DEFAULT_POLL_MS = 60 * 1000;
+
+/** How long Core may hold one request. Its own ceiling is the same number. */
+const WATCH_WAIT_SECONDS = 25;
+
+/**
+ * How much longer than that to wait before giving up on the request entirely.
+ *
+ * A hold that is never answered and never closed is the one way this loop can be worse than
+ * the timer it replaced: the loop that would ask again is waiting on that very request. So
+ * every held request carries a deadline of its own.
+ */
+const HOLD_PADDING_MS = 10 * 1000;
+
+/**
+ * The floor under asking again immediately. A Core that answers a held request honestly and
+ * instantly, over and over, must not turn into a request every few milliseconds: each one
+ * costs a bcrypt on Core.
+ */
+const MIN_POLL_GAP_MS = 1000;
+
+/** Spread, so a fleet redeployed together does not ask in lockstep. */
+const POLL_JITTER = 0.3;
+
+const POLL_RETRY_MIN_MS = 1000;
+const POLL_RETRY_MAX_MS = 60 * 1000;
+
+const RECONNECT_MIN_MS = 1000;
+const RECONNECT_MAX_MS = 30 * 1000;
+
+/**
+ * How many times a community that refuses the bot as uninstalled is tried again, but only
+ * when the connection was never live.
+ *
+ * Installing a bot writes rows in two places, and for a moment the community has recorded the
+ * installation without having written the member row the gateway checks. A bot that arrives in
+ * that moment is refused with the same reason as a bot that was removed. Telling them apart is
+ * not possible from the reason, but it is from the history: a connection that was never up has
+ * just arrived, and one that was up and is now refused has been removed.
+ */
+const UNINSTALL_RETRIES = 3;
+
+/**
+ * How many times to try telling Core what this bot needs.
+ *
+ * Not once, because a bot deployed alongside its Core can reach the route before it exists.
+ * Not forever, because a value Core refuses will be refused the same way at midnight, and a
+ * request a second for the life of the process is a strange way to give up.
+ */
+const DECLARE_TRIES = 60;
+
+function jitter(ms) {
+  return Math.round(ms * (1 - POLL_JITTER / 2 + Math.random() * POLL_JITTER));
+}
+
+/**
+ * Whether two community addresses are the same place.
+ *
+ * Compared after trimming trailing slashes, so a Core that starts or stops sending one does
+ * not look like a community that moved and set every bot reconnecting for nothing.
+ */
+function sameAddress(a, b) {
+  const tidy = (u) => String(u || '').replace(/\/+$/, '');
+  return tidy(a) === tidy(b);
+}
+
+export class Bot {
+  #core;
+  #dispatcher;
+  #links = new Map();
+  #listeners = new Map();
+  #connect;
+  #timers;
+  #sleep;
+  #fetch;
+  #pollMs;
+  #stopped = false;
+  #declared;
+  #declaredOk = false;
+  #declareTries = 0;
+  #watching = null;
+  #pollBackoff = 0;
+  #pendingDelay = null;
+  #releaseDelay = null;
+  // Reconciling one at a time. The check for a link that already exists sits before an await,
+  // so two overlapping syncs would both pass it and both dial the same community.
+  #reconciling = Promise.resolve();
+
+  constructor({
+    coreUrl = process.env?.CORE_SERVER_URL,
+    key = process.env?.BOT_KEY,
+    secret = process.env?.BOT_SECRET,
+    fetch,
+    sleep,
+    connect,
+    timers = globalThis,
+    onError,
+    autoDeferMs,
+    pollMs = DEFAULT_POLL_MS,
+    permissions,
+  } = {}) {
+    if (!coreUrl) throw new Error('no coreUrl: set CORE_SERVER_URL to the Tusile core server');
+    if (!key || !secret) {
+      // Said here rather than at the first request, because the first request happens
+      // inside a deploy where nobody is watching, and this happens at startup.
+      throw new Error(
+        'no bot credentials: set BOT_KEY and BOT_SECRET. Create a bot in the Tusile app, ' +
+          'under Settings, Bots, and copy them there.',
+      );
+    }
+
+    this.#core = new CoreClient({ url: coreUrl, key, secret, fetch, sleep });
+    this.#fetch = fetch;
+    this.#sleep = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.#connect = connect || null;
+    this.#timers = timers;
+    this.#pollMs = pollMs;
+    // Names, or a number, or nothing. Converted here so a typo is a stack trace at startup
+    // rather than a permission silently missing from the dialog somebody sees later.
+    this.#declared = permissions === undefined || permissions === null ? null : toMask(permissions);
+    this.#dispatcher = new Dispatcher({
+      autoDeferMs,
+      onError: (err, interaction) => this.#report(err, interaction),
+    });
+    if (onError) this.on('error', onError);
+
+    /** This bot's own account, once it has asked. Its id is how it recognises itself. */
+    this.me = null;
+    /** Every community it is connected to, by id. */
+    this.servers = new Map();
+    /**
+     * Core itself, for the facts no community holds.
+     *
+     * When somebody was last here, whether they are a guest, who owns a community: a
+     * community's members table knows when somebody joined and nothing else, so a bot that
+     * decides anything about a person has to ask Core. Without a way through, a bot writes
+     * its own fetch helper beside the client this package already built it, and then owns
+     * the timeouts and the retries twice.
+     */
+    this.core = this.#core;
+  }
+
+  // What the bot does.
+
+  command(definition, handler) {
+    this.#dispatcher.command(definition, handler);
+    return this;
+  }
+
+  component(customId, handler) {
+    this.#dispatcher.component(customId, handler);
+    return this;
+  }
+
+  modal(customId, handler) {
+    this.#dispatcher.modal(customId, handler);
+    return this;
+  }
+
+  /**
+   * ready    (bot, server)     connected to a community and registered there
+   * message  (message, server) something said in a channel the bot can see
+   * joined   (server)          added to a community
+   * left     (serverId)        removed from one
+   * error    (error, context)  anything that went wrong, including in a handler
+   */
+  on(event, listener) {
+    if (!this.#listeners.has(event)) this.#listeners.set(event, []);
+    this.#listeners.get(event).push(listener);
+    return this;
+  }
+
+  /**
+   * Connect, and stay connected.
+   *
+   * Resolves once every community known right now has a socket, so that a caller can
+   * reasonably look at `servers` afterwards. Keeps running until `stop`.
+   */
+  async start() {
+    // `ws` is loaded only if nobody supplied a socket, so a runtime with its own
+    // WebSocket, or a test, never pays for it.
+    if (!this.#connect) {
+      const { default: WebSocket } = await import('ws');
+      this.#connect = (url) => new WebSocket(url);
+    }
+    this.me = await this.#core.me();
+    await this.#declare();
+    // An eager pass that answers at once, so this resolves with every community known right
+    // now already connected, which is what a caller looking at `servers` afterwards expects.
+    // Then the loop, which spends its life inside a held request rather than waiting on a
+    // timer between them.
+    //
+    // The loop starts whether or not that first pass worked. Core being briefly unreachable at
+    // boot used to mean the timer was never registered at all, so the bot sat there having
+    // failed to start and never asked again: the caller was told, which is right, but a caller
+    // that decided to carry on had a bot that would never connect to anything.
+    const firstPass = this.sync();
+    const startLoop = () => {
+      this.#watching = this.#watchLoop();
+    };
+    firstPass.then(startLoop, startLoop);
+    await firstPass;
+    return this;
+  }
+
+  /**
+   * Tell Core what this bot needs, once it sticks.
+   *
+   * Retried on every pass of the loop until it lands, which matters more than it sounds: a bot
+   * deployed in the same breath as its Core can be up first, and a Core that does not yet know
+   * the route answers 404. Declaring once at startup and logging the failure left the bot
+   * running normally with an empty list, so the install dialog had nothing to show and whoever
+   * added it granted it nothing. Never fatal: this is a list for a dialog the bot is not part
+   * of, and refusing to run without it would be worse than running without it.
+   */
+  async #declare() {
+    // Nothing to say, or already said. A bot that declares nothing must not overwrite what its
+    // author ticked in the app with an empty list.
+    if (this.#declared === null || this.#declaredOk) return;
+    if (this.#declareTries >= DECLARE_TRIES) return;
+    this.#declareTries += 1;
+    try {
+      await this.#core.declarePermissions(this.#declared);
+      this.#declaredOk = true;
+    } catch (err) {
+      this.#report(err);
+      if (this.#declareTries >= DECLARE_TRIES) {
+        this.#report(new Error(
+          'giving up on declaring what this bot needs: whoever adds it will be shown nothing to allow',
+        ));
+      }
+    }
+  }
+
+  /**
+   * Keep asking Core, with the request held open while there is nothing to say.
+   *
+   * This replaced an interval. An interval ticks independently of the request, so the twenty
+   * five seconds Core would hold one left thirty five seconds of every minute uncovered, and
+   * an install landing in that gap waited for the next tick. Here the next request starts the
+   * moment the last one returns, so there is no gap to land in.
+   */
+  async #watchLoop() {
+    while (!this.#stopped) {
+      await this.#declare();
+      let outcome;
+      try {
+        outcome = await this.#syncWatching();
+      } catch (err) {
+        if (this.#stopped) return;
+        this.#report(err);
+        outcome = { watch: false, failed: true };
+      }
+      if (this.#stopped) return;
+      await this.#delay(this.#nextDelay(outcome));
+    }
+  }
+
+  /** One held request, plus whatever it says about the communities. */
+  async #syncWatching() {
+    const known = serversToken([...this.servers.keys()]);
+    const { servers, watch } = await this.#listServers({
+      waitSeconds: WATCH_WAIT_SECONDS,
+      known,
+      signal: this.#holdDeadline(),
+    });
+    if (this.#stopped) return { watch, failed: false };
+    await this.#reconcile(servers);
+    return { watch, failed: false };
+  }
+
+  /**
+   * How long to wait before asking again.
+   *
+   * The three cases are the whole design: Core is watching, so ask again now and spend the
+   * time inside the request; Core is not watching, so this is the old timer and it has to stay
+   * slow or an older Core is polled in a tight loop; or the request failed, in which case back
+   * off, because a Core that is down does not need every bot on the network arriving every
+   * second.
+   */
+  #nextDelay({ watch, failed }) {
+    if (failed) {
+      this.#pollBackoff = nextBackoff(this.#pollBackoff, POLL_RETRY_MIN_MS, POLL_RETRY_MAX_MS);
+      return jitter(this.#pollBackoff);
+    }
+    this.#pollBackoff = 0;
+    return watch ? MIN_POLL_GAP_MS : jitter(this.#pollMs);
+  }
+
+  #holdDeadline() {
+    if (typeof AbortSignal === 'undefined' || typeof AbortSignal.timeout !== 'function') {
+      return undefined;
+    }
+    return AbortSignal.timeout(WATCH_WAIT_SECONDS * 1000 + HOLD_PADDING_MS);
+  }
+
+  #delay(ms) {
+    return new Promise((resolve) => {
+      this.#releaseDelay = resolve;
+      this.#pendingDelay = this.#timers.setTimeout(() => {
+        this.#pendingDelay = null;
+        this.#releaseDelay = null;
+        resolve();
+      }, ms);
+    });
+  }
+
+  /**
+   * Bring the set of connections in line with the set of communities.
+   *
+   * Called on a timer, and worth calling by hand after installing the bot somewhere if a
+   * caller happens to know that has just happened.
+   */
+  async sync() {
+    if (this.#stopped) return;
+    // No wait. A bot author calling this wants the current answer, not to be held for
+    // twenty-five seconds; the loop is what waits.
+    const { servers } = await this.#listServers({});
+    if (this.#stopped) return;
+    await this.#reconcile(servers);
+  }
+
+  async #listServers(options) {
+    try {
+      return await this.#core.watchServers(options);
+    } catch (err) {
+      // Credentials Core refuses will be refused next minute too. Stopping is the honest
+      // answer: a bot that cannot authenticate is not running, and saying so once beats
+      // a 401 a minute for as long as nobody notices.
+      if (err?.isAuthFailure) {
+        this.#report(err);
+        await this.stop();
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Bring the connections in line with one answer from Core, one answer at a time.
+   *
+   * Serialised because the check for a link that already exists sits before an await: two
+   * overlapping calls would both find nothing and both dial.
+   */
+  #reconcile(servers) {
+    const run = () => this.#applyServers(servers);
+    const next = this.#reconciling.then(run, run);
+    this.#reconciling = next.then(
+      () => {},
+      () => {},
+    );
+    return next;
+  }
+
+  async #applyServers(servers) {
+    if (this.#stopped) return;
+    const seen = new Set();
+    for (const server of servers) {
+      seen.add(server.serverId);
+      const link = this.#links.get(server.serverId);
+      if (link) {
+        // A community can move: off a shared box onto its own, or onto a domain of its
+        // own. Core answers with the new address, and a loop that keys on the id alone
+        // never notices, because the old address usually goes on answering. The bot then
+        // holds a socket to a server nobody is looking at and reads as offline where it
+        // was added, until somebody restarts it. Found that way on prod 2026-10-07.
+        if (sameAddress(link.apiUrl, server.apiUrl)) continue;
+        this.#leave(server.serverId);
+      }
+      await this.#join(server);
+    }
+    // A community that removed the bot stops being listed, so its socket goes with it.
+    for (const serverId of [...this.#links.keys()]) {
+      if (!seen.has(serverId)) this.#leave(serverId);
+    }
+  }
+
+  /** Close every socket and stop looking for new communities. */
+  async stop() {
+    this.#stopped = true;
+    if (this.#pendingDelay !== null) {
+      // A pending timer keeps Node alive, so a bot that stops has to let go of it.
+      this.#timers.clearTimeout?.(this.#pendingDelay);
+      this.#pendingDelay = null;
+    }
+    if (this.#releaseDelay) {
+      const release = this.#releaseDelay;
+      this.#releaseDelay = null;
+      release();
+    }
+    for (const serverId of [...this.#links.keys()]) this.#leave(serverId);
+  }
+
+  async #join({ serverId, apiUrl, raw }) {
+    const link = new Link({
+      serverId,
+      apiUrl,
+      raw,
+      core: this.#core,
+      fetch: this.#fetch,
+      sleep: this.#sleep,
+      connect: this.#connect,
+      timers: this.#timers,
+      onReady: (bot, client) => {
+        // Registered on every connect rather than once at startup: a bot redeployed with
+        // a changed command set, or added to a community while it was down, would
+        // otherwise go on offering whatever it registered last time.
+        client
+          .setCommands(this.#dispatcher.definitions(), { requestedPermissions: this.#declared })
+          .catch((err) => this.#report(err, { serverId }));
+        this.#emit('ready', bot, client);
+      },
+      onFrame: (frame, client) => this.#onFrame(frame, client),
+      onError: (err) => this.#report(err, { serverId }),
+      // A connection that has ended for good stops being this bot's connection to that
+      // community. Leaving it in place would make a community that removed the bot and
+      // added it again unreachable until the process was restarted: the next sync would
+      // see a link already there and skip it, and the bot would sit offline with nothing
+      // in any log to say why.
+      onFinished: () => {
+        if (this.#links.get(serverId) === link) this.#leave(serverId);
+      },
+    });
+
+    this.#links.set(serverId, link);
+    this.servers.set(serverId, link.client);
+    await link.start();
+    this.#emit('joined', link.client);
+  }
+
+  #leave(serverId) {
+    this.#links.get(serverId)?.stop();
+    this.#links.delete(serverId);
+    this.servers.delete(serverId);
+    this.#emit('left', serverId);
+  }
+
+  #onFrame(frame, client) {
+    if (frame?.type === 'interaction_create') {
+      const interaction = new Interaction(frame.data || {}, client);
+      this.#dispatcher.handle(interaction).catch((err) => this.#report(err, interaction));
+      return;
+    }
+    if (frame?.type === 'message_create') {
+      this.#emit('message', frame.data || {}, client);
+    }
+  }
+
+  #emit(event, ...args) {
+    for (const listener of this.#listeners.get(event) ?? []) {
+      try {
+        listener(...args);
+      } catch (err) {
+        // A throwing listener must not take down the socket that fed it.
+        if (event !== 'error') this.#report(err);
+      }
+    }
+  }
+
+  #report(err, context) {
+    const listeners = this.#listeners.get('error') ?? [];
+    if (!listeners.length) {
+      // Better a line on stderr than a bot that fails in total silence because nobody
+      // wired up an error handler.
+      console.error('[tusile-bot]', err);
+      return;
+    }
+    this.#emit('error', err, context);
+  }
+}
+
+/**
+ * One community: its socket, its token, and its reconnects.
+ *
+ * Kept separate from the bot because everything here is per community. One community being
+ * down, or having removed the bot, must leave every other connection alone.
+ */
+class Link {
+  #gateway;
+  #core;
+  #sleep;
+  #onError;
+  #onReady;
+  #onFrame;
+  #onFinished;
+  #token = '';
+  #backoff = 0;
+  #stopped = false;
+  #refusals = 0;
+
+  constructor({ serverId, apiUrl, raw, core, fetch, sleep, connect, timers, onReady, onFrame,
+    onError, onFinished }) {
+    this.serverId = serverId;
+    this.apiUrl = apiUrl;
+    this.raw = raw;
+    this.#core = core;
+    this.#sleep = sleep;
+    this.#onError = onError;
+    this.#onReady = onReady;
+    this.#onFrame = onFrame;
+    this.#onFinished = onFinished || (() => {});
+
+    this.client = new ServerClient({
+      apiUrl,
+      serverId,
+      // Read per request, so a reconnect that mints a new token does not leave the rest
+      // client holding an expired one.
+      token: () => this.#token,
+      // And minted again when this community says the one it has is no longer good. A token
+      // lasts an hour; the socket it was minted for stays up for days, and nothing closes it
+      // when the token expires. Without this a bot that had been running since yesterday
+      // heard every command and could answer none of them.
+      refreshToken: async () => {
+        this.#token = await this.#core.token(serverId);
+        return this.#token;
+      },
+      fetch,
+      sleep,
+    });
+
+    this.#gateway = new Gateway({
+      url: apiUrl,
+      token: async () => {
+        this.#token = await this.#core.token(serverId);
+        return this.#token;
+      },
+      connect,
+      timers,
+      onReady: (bot) => this.#onReady(bot, this.client),
+      onFrame: (frame) => this.#onFrame(frame, this.client),
+    });
+  }
+
+  /** Open the socket, then keep it open in the background. */
+  async start() {
+    await this.#open();
+    this.#keepAlive().catch((err) => this.#onError(err));
+  }
+
+  stop() {
+    this.#stopped = true;
+    this.#gateway.stop();
+  }
+
+  async #open() {
+    try {
+      await this.#gateway.open();
+    } catch (err) {
+      // Core refusing a token, most likely. Swallowed here because the failure is also
+      // settled on the connection, and the loop below reports it from there: what
+      // matters is that it does not take the bot's other communities with it.
+    }
+  }
+
+  async #keepAlive() {
+    while (!this.#stopped) {
+      const { fatal, reason, wasLive } = await this.#gateway.closed();
+      if (reason) this.#onError(new Error(`[${this.serverId}] ${reason}`));
+      // A community that says this bot is not installed, on a connection that was never live,
+      // is an install that has not finished writing its rows rather than a removal. The two
+      // are indistinguishable from the reason and obvious from the history. Treating the first
+      // as final cost the bot a whole poll interval on an install that had in fact worked.
+      const stillSettling =
+        fatal &&
+        !wasLive &&
+        !this.#stopped &&
+        /bot_uninstalled/.test(reason || '') &&
+        this.#refusals < UNINSTALL_RETRIES;
+      if (stillSettling) {
+        this.#refusals++;
+      } else if (fatal || this.#stopped) {
+        return this.#finish();
+      }
+      // A connection that was up and then dropped is worth picking straight back up.
+      // Carrying the backoff over would leave a bot that reconnects cleanly once an hour
+      // eventually waiting half a minute every time, for nothing.
+      if (wasLive) {
+        this.#backoff = 0;
+        this.#refusals = 0;
+      }
+      this.#backoff = nextBackoff(this.#backoff, RECONNECT_MIN_MS, RECONNECT_MAX_MS);
+      await this.#sleep(this.#backoff);
+      if (this.#stopped) return this.#finish();
+      await this.#open();
+    }
+    this.#finish();
+  }
+
+  /** Say, once, that this connection is over and will not come back by itself. */
+  #finish() {
+    const done = this.#onFinished;
+    this.#onFinished = () => {};
+    done();
+  }
+}