@tusile/bot 0.2.1 → 0.5.0

package/src/gateway.js

@@ -1,191 +1,191 @@
-/**
- * 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.
-      //
-      // Credentials Core refuses are final. The bot was deleted, or its secret was
-      // rotated, and every retry from here is a 401 in somebody's log until the process
-      // is stopped, plus a share of the rate limit the working bots need.
-      this.#settle({
-        fatal: err?.isUninstalled === true || err?.isAuthFailure === 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 || err?.isAuthFailure === 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.
-    }
-  }
-}
+/**
+ * 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.
+      //
+      // Credentials Core refuses are final. The bot was deleted, or its secret was
+      // rotated, and every retry from here is a 401 in somebody's log until the process
+      // is stopped, plus a share of the rate limit the working bots need.
+      this.#settle({
+        fatal: err?.isUninstalled === true || err?.isAuthFailure === 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 || err?.isAuthFailure === 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.
+    }
+  }
+}