@tusile/bot 0.2.1 → 0.5.0

package/src/core.js

@@ -1,68 +1,207 @@
-import { Transport, query } from './http.js';
-
-/**
- * Tusile Core: who this bot is, and which communities have added it.
- *
- * A bot has one identity across the whole network and a separate short-lived token for
- * each community it is in. Core is where both come from. The key and secret only ever go
- * here; a community never sees them.
- */
-export class CoreClient {
-  #transport;
-
-  constructor({ url, key, secret, fetch, sleep, maxRetries }) {
-    this.url = String(url || '').replace(/\/+$/, '');
-    this.#transport = new Transport({
-      baseUrl: this.url,
-      authorization: () => 'Bot ' + base64(`${key}:${secret}`),
-      fetch,
-      sleep,
-      maxRetries,
-    });
-  }
-
-  /** The bot's own account: id, name, picture. */
-  me() {
-    return this.#transport.request('GET', '/bots/me');
-  }
-
-  /**
-   * Every community this bot is in.
-   *
-   * `waitSeconds` asks Core to hold the request open until something changes, which is for
-   * the case that matters: a bot running on no servers at all. Polling that once a minute
-   * means somebody adds the bot, watches nothing happen, and concludes it is broken.
-   */
-  async servers({ waitSeconds } = {}) {
-    const out = await this.#transport.request(
-      'GET',
-      `/bots/me/servers${query({ wait: waitSeconds })}`,
-    );
-    return (out?.servers ?? []).map((row) => ({
-      serverId: row.server_id,
-      apiUrl: row.api_url,
-      // Whatever else Core said about it, kept as it came, so a field added later is
-      // already available without a release of this package.
-      raw: row,
-    }));
-  }
-
-  /**
-   * A token for one community.
-   *
-   * Good for an hour and for that community only, so every connect mints a new one rather
-   * than trying to work out whether the last one is still alive.
-   */
-  async token(serverId) {
-    const out = await this.#transport.request('POST', '/bots/token', { server_id: serverId });
-    if (!out?.token) throw new Error(`Core issued no token for ${serverId}`);
-    return out.token;
-  }
-}
-
-function base64(text) {
-  if (typeof Buffer !== 'undefined') return Buffer.from(text, 'utf8').toString('base64');
-  // Not Node. Nothing in this package needs it, but failing here would be a strange way
-  // to find that out.
-  return btoa(text);
-}
+import { Transport, query } from './http.js';
+
+/**
+ * Tusile Core: who this bot is, and which communities have added it.
+ *
+ * A bot has one identity across the whole network and a separate short-lived token for
+ * each community it is in. Core is where both come from. The key and secret only ever go
+ * here; a community never sees them.
+ */
+/** How long a display name is good for. Names change rarely; a stale one costs nothing. */
+const NAME_TTL_MS = 10 * 60 * 1000;
+
+export class CoreClient {
+  #transport;
+  #names = new Map();
+  #nameTtlMs;
+
+  constructor({ url, key, secret, fetch, sleep, maxRetries, nameTtlMs = NAME_TTL_MS }) {
+    this.url = String(url || '').replace(/\/+$/, '');
+    this.#transport = new Transport({
+      baseUrl: this.url,
+      authorization: () => 'Bot ' + base64(`${key}:${secret}`),
+      fetch,
+      sleep,
+      maxRetries,
+    });
+    this.#nameTtlMs = nameTtlMs;
+  }
+
+  /**
+   * Anything at all, with this bot's own credentials.
+   *
+   * The escape hatch, and not a second-class one: everything below is written in terms of
+   * it, so a bot reaching a Core endpoint this package has never heard of is in exactly the
+   * same position as one calling a named method. ServerClient has had this since it was
+   * written; without it here, a bot filing a support ticket built its own authenticated
+   * fetch and owned the base url, the timeout and the retry policy twice.
+   */
+  request(method, path, body) {
+    return this.#transport.request(method, path, body);
+  }
+
+  /** The bot's own account: id, name, picture. */
+  me() {
+    return this.#transport.request('GET', '/bots/me');
+  }
+
+  /**
+   * Every community this bot is in.
+   *
+   * Answers at once. Returns a plain array, which is what it has always returned: this is
+   * public API, and a bot author calling it wants the list rather than a wrapper.
+   */
+  async servers({ waitSeconds } = {}) {
+    const { servers } = await this.watchServers({ waitSeconds });
+    return servers;
+  }
+
+  /**
+   * The same list, with the request held open until it would be different.
+   *
+   * `waitSeconds` is how long Core may hold it. `known` is a digest of what the bot already
+   * serves (see known.js): Core compares, and holds only while the two agree. Without it
+   * Core falls back to its older rule and holds only for a bot on no communities at all,
+   * which left every bot already serving one to hear about the next on its own timer.
+   *
+   * `watch` in the answer is Core saying it understood the token and will hold the next
+   * request. It matters because the body alone cannot distinguish a Core that held this
+   * request for twenty-five seconds and found nothing new from an older Core that ignored
+   * the parameter and answered instantly: a bot that guesses wrong either polls the old one
+   * in a tight loop or throws away the feature against the new one. Timing does not settle
+   * it either, because a duplicate install wakes every waiter while changing nothing.
+   *
+   * `signal` gives up on a hold that is never answered. Mandatory for the loop that drives
+   * this: without it one blackholed request silences the bot until it is restarted.
+   */
+  async watchServers({ waitSeconds, known, signal } = {}) {
+    const out = await this.#transport.request(
+      'GET',
+      `/bots/me/servers${query({ wait: waitSeconds, known })}`,
+      undefined,
+      { signal },
+    );
+    return {
+      watch: out?.watch === true,
+      servers: (out?.servers ?? []).map((row) => ({
+        serverId: row.server_id,
+        apiUrl: row.api_url,
+        // Whatever else Core said about it, kept as it came, so a field added later is
+        // already available without a release of this package.
+        raw: row,
+      })),
+    };
+  }
+
+  /**
+   * Say what this bot needs to do its job.
+   *
+   * A declaration, not a grant. It is the list shown to whoever adds the bot to a community,
+   * and they decide what of it to allow; the bot ends up with what they ticked and nothing
+   * more. Declaring it here rather than in a form somewhere means it lives next to the
+   * commands that need it, and a bot that grows a command that needs Manage Channels says so
+   * in the same commit.
+   */
+  declarePermissions(mask) {
+    return this.#transport.request('PUT', '/bots/me/permissions', {
+      requested_permissions: mask,
+    });
+  }
+
+  /**
+   * A token for one community.
+   *
+   * Good for an hour and for that community only, so every connect mints a new one rather
+   * than trying to work out whether the last one is still alive.
+   */
+  async token(serverId) {
+    const out = await this.#transport.request('POST', '/bots/token', { server_id: serverId });
+    if (!out?.token) throw new Error(`Core issued no token for ${serverId}`);
+    return out.token;
+  }
+
+  /**
+   * Somebody's public profile: when they were last here, and whether they are a guest.
+   *
+   * Neither fact is on a community's /bot routes. A community's members table knows when
+   * somebody joined and nothing else, so a bot that decides anything about a person, who to
+   * warn, who to retire, who to leave alone, has to ask Core, once per person.
+   *
+   * Null for a profile that is not there or cannot be read, rather than a throw. That is the
+   * difference between this and everything else on this client, and it is deliberate: a bot
+   * sweeping a community of two hundred must not lose the whole pass to one lookup, and
+   * somebody it knows nothing about is somebody to leave alone. A caller that treats null as
+   * "no information" gets the safe behaviour for free.
+   */
+  profile(userId) {
+    return this.#publicRead(`/profiles/${encodeURIComponent(String(userId ?? ''))}`);
+  }
+
+  /**
+   * A community's public row, which is where its owner is named.
+   *
+   * A bot holding Manage Members can remove the owner of the community that installed it:
+   * the bot kick route checks the permission bit and whether the target is a bot, and
+   * nothing else. Knowing who the owner is, is how a bot refuses to.
+   *
+   * Null on anything that is not an answer, for the same reason as [profile]: not knowing
+   * who the owner is must read as "do not touch anybody", not as a crash.
+   */
+  community(serverId) {
+    return this.#publicRead(`/servers/${encodeURIComponent(String(serverId ?? ''))}`);
+  }
+
+  /**
+   * What to call somebody, from their id, remembered.
+   *
+   * A message frame carries who wrote it and not what they are called. A transcript where
+   * everybody is "someone" is worse than no names at all: "she said it is broken" then has
+   * nobody to attach to. Without a cache this is a call per message.
+   *
+   * Null when Core cannot name them, rather than a word of its own: "someone", "unknown",
+   * "a member" are all decisions about tone and language, and this package ships no copy.
+   * A failure is not remembered, so somebody unnameable during a deploy is named afterwards.
+   */
+  async displayName(userId) {
+    const key = String(userId ?? '');
+    if (!key) return null;
+    const held = this.#names.get(key);
+    if (held && held.at > Date.now() - this.#nameTtlMs) return held.name;
+    const profile = await this.profile(key);
+    const name = profile?.display_name || profile?.username || null;
+    if (name === null) return null;
+    // A community is a few hundred people, and only the ones who have spoken land here.
+    // Cleared rather than evicted one by one: the next few messages pay a call each, which
+    // is cheaper than carrying a policy nobody will ever tune.
+    if (this.#names.size > 500) this.#names.clear();
+    this.#names.set(key, { name, at: Date.now() });
+    return name;
+  }
+
+  /** Forget every remembered name, for a bot that has reason to think one changed. */
+  forgetNames() {
+    this.#names.clear();
+  }
+
+  /**
+   * A public Core route, where absent and unreachable are the same answer: null.
+   *
+   * It goes through the same transport as everything else, so it carries the bot's own
+   * credentials. Core ignores them on these routes, and sending them keeps one place that
+   * knows the base url, the timeout and the retry policy.
+   */
+  async #publicRead(path) {
+    try {
+      return (await this.#transport.request('GET', path)) ?? null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function base64(text) {
+  if (typeof Buffer !== 'undefined') return Buffer.from(text, 'utf8').toString('base64');
+  // Not Node. Nothing in this package needs it, but failing here would be a strange way
+  // to find that out.
+  return btoa(text);
+}