@honeybbq/teamspeak 1.0.0-beta.19 → 1.0.0-beta.21

package/src/client/client.ts

@@ -50,6 +50,9 @@ import {
   buildCommand,
   buildCommandChain,
   encodeRequest,
+  floodHoldMs,
+  FLOOD_RETRIES,
+  floodRetryDelayMs,
   parseServerError,
   resolveBackoffPolicy,
 } from "../core/internal.js";
@@ -468,6 +471,8 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#clientInitOptions = normalizeClientInitOptions(options);
     this.#socketFactory = options.socketFactory;
     this.#fileTransferSocketFactory = options.fileTransferSocketFactory;
+    // Refused here, not when the loop first runs: a bad policy would flood.
+    if (options.reconnect !== undefined) resolveBackoffPolicy(options.reconnect);
     this.#reconnectOptions = options.reconnect;
     this.#trace = options.trace === undefined ? undefined : { ...options.trace };
     this.#viewStore = new ViewStore(
@@ -696,7 +701,10 @@ export class Client implements CommandExecutor, AsyncDisposable {
    * Leave the server and close the connection.
    *
    * Says goodbye first, waiting for the server's acknowledgement for a second
-   * at most, or less if `signal` aborts sooner. The connection is closed
+   * at most, or less if `signal` aborts sooner. The goodbye is sent at once,
+   * past the flood throttle, and also by a client still connecting whose
+   * clientinit is out; commands still waiting for their turn reject with a
+   * NotConnectedError and are never sent. The connection is closed
    * either way. A `connect()` still waiting for its handshake rejects with a
    * NotConnectedError, and so do the commands still waiting for an answer.
    * Resolves once `disconnected` has been delivered to the listeners, so one
@@ -728,13 +736,20 @@ export class Client implements CommandExecutor, AsyncDisposable {
     // still be on its way.
     if (this.#status === ClientStatus.Disconnected) return this.#disconnectedDelivered;
 
-    const wasConnected = this.#status === ClientStatus.Connected;
+    // The server may hold a session for this client from the moment clientinit
+    // is out, which is as soon as the keys exist, well before Connected.
+    const holdsSession =
+      this.#status === ClientStatus.Connected ||
+      (this.#status === ClientStatus.Connecting && this.#crypt.cryptoInitComplete);
     this.#status = ClientStatus.Disconnected;
+    // Whatever still waits for its turn is rejected and never sent; the
+    // goodbye does not wait for one.
+    this.#throttle.rejectAll(new NotConnectedError());
     let left!: () => void;
     this.#attempt.rejectAfter(new NotConnectedError(), new Promise<void>((r) => (left = r)));
 
     const leaving = this.#leave(
-      wasConnected,
+      holdsSession,
       options.signal,
       options.reasonMessage ?? "Shutdown",
     ).finally(left);
@@ -747,13 +762,13 @@ export class Client implements CommandExecutor, AsyncDisposable {
   }
 
   async #leave(
-    wasConnected: boolean,
+    holdsSession: boolean,
     signal: AbortSignal | undefined,
     reasonMessage: string,
   ): Promise<void> {
     this.#logger.info("disconnecting from server");
 
-    if (wasConnected) {
+    if (holdsSession) {
       this.#callHook(this.#trace?.disconnectStart, () => ({}));
       const goodbyeStarted = performance.now();
       // The server answers clientdisconnect with a notifyclientleftview about
@@ -771,6 +786,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
         }),
         { signal, timeoutMs: DISCONNECT_TIMEOUT_MS },
         true,
+        true,
       ).then(
         () => true,
         () => false,
@@ -806,6 +822,11 @@ export class Client implements CommandExecutor, AsyncDisposable {
    *
    * Rejects with a NotConnectedError unless the client is connected: while it
    * is still connecting, the session's keys may not exist yet.
+   *
+   * A command the server refuses as flooding (`ErrorCode.ClientIsFlooding`)
+   * with a time to wait is sent again after it, and every other command waits
+   * too, up to three times and while its timeout allows; the refusal that
+   * remains rejects as it is.
    */
   // oxlint-disable-next-line typescript/array-type -- the public API report spells this `[]`; respelling it changes the report
   exec(command: string, options: CommandOptions = {}): Promise<Record<string, string>[]> {
@@ -873,18 +894,28 @@ export class Client implements CommandExecutor, AsyncDisposable {
     command: string,
     options: CommandOptions,
     internal: boolean,
+    goodbye = false,
   ): Promise<Array<Record<string, string>>> {
-    if (!commandChannel.hasSubscribers) return this.#execUntraced(command, options, internal);
-    const trace: CommandTrace = { command: parseCommand(command)?.name ?? "", client: this };
-    return commandChannel.tracePromise(() => this.#execUntraced(command, options, internal), trace);
+    if (!commandChannel.hasSubscribers) {
+      return this.#execUntraced(command, options, internal, goodbye);
+    }
+    const trace: CommandTrace = {
+      command: parseCommand(command)?.name ?? "",
+      client: this,
+    };
+    return commandChannel.tracePromise(
+      () => this.#execUntraced(command, options, internal, goodbye),
+      trace,
+    );
   }
 
   async #execUntraced(
     command: string,
     options: CommandOptions,
     internal: boolean,
+    goodbye: boolean,
   ): Promise<Array<Record<string, string>>> {
-    const { signal, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = options;
+    const { signal, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS, onSent } = options;
     signal?.throwIfAborted();
     // A command sent on no socket used to vanish and surface 10 seconds later
     // as a timeout, which reads like a slow server rather than a usage error.
@@ -898,7 +929,8 @@ export class Client implements CommandExecutor, AsyncDisposable {
     const correlation = key === undefined ? undefined : parsed?.params[key];
     const echo = spec?.echoKey === undefined ? undefined : parsed?.params[spec.echoKey];
 
-    const [rc, answered] = this.#cmdTrack.register(spec, correlation, echo);
+    let [rc, answered] = this.#cmdTrack.register(spec, correlation, echo);
+    const deadline = performance.now() + timeoutMs;
     let timer: ReturnType<typeof setTimeout> | undefined;
     let onAbort: (() => void) | undefined;
     // Started before the throttle: the timeout bounds the whole command, its
@@ -911,19 +943,45 @@ export class Client implements CommandExecutor, AsyncDisposable {
     givenUp.catch(() => {});
     const throttleAbort = new AbortController();
     try {
-      const withRc = appendReturnCode(command, rc);
-      await Promise.race([this.#throttle.wait(throttleAbort.signal), givenUp]);
-      if (!this.#canSend(internal)) throw new NotConnectedError();
-      this.#sendLine(withRc);
-
-      const result = await Promise.race([answered, givenUp]);
-      if (result.err) throw result.err;
-      // The server took the rename, so it is what this client now asks for.
-      if (!internal && parsed?.name === "clientupdate") {
-        const renamed = parsed.params["client_nickname"];
-        if (renamed !== undefined) this.#requestedNickname = renamed;
+      for (let refused = 0; ; refused++) {
+        const withRc = appendReturnCode(command, rc);
+        // The goodbye of a disconnect goes out at once: queued behind other
+        // commands it would not leave in time, and the server would keep the
+        // session.
+        if (!goodbye) await Promise.race([this.#throttle.wait(throttleAbort.signal), givenUp]);
+        if (!this.#canSend(internal)) throw new NotConnectedError();
+        this.#sendLine(withRc);
+        if (refused === 0) onSent?.();
+
+        const result = await Promise.race([answered, givenUp]);
+        // Refused as flooding with a time to wait, which the command can
+        // afford: nothing is sent until then, and the command, which the
+        // server did not run, goes out again.
+        const wait = result.err ? floodRetryDelayMs(result.err) : undefined;
+        const hold = wait === undefined ? undefined : floodHoldMs(wait);
+        if (
+          hold !== undefined &&
+          !goodbye &&
+          refused < FLOOD_RETRIES &&
+          hold < deadline - performance.now()
+        ) {
+          this.#logger.debug("the server asked for a pause", {
+            command: parsed?.name,
+            waitMs: wait,
+          });
+          this.#throttle.hold(hold);
+          this.#cmdTrack.unregister(rc);
+          [rc, answered] = this.#cmdTrack.register(spec, correlation, echo);
+          continue;
+        }
+        if (result.err) throw result.err;
+        // The server took the rename, so it is what this client now asks for.
+        if (!internal && parsed?.name === "clientupdate") {
+          const renamed = parsed.params["client_nickname"];
+          if (renamed !== undefined) this.#requestedNickname = renamed;
+        }
+        return result.data;
       }
-      return result.data;
     } finally {
       // A command given up while it waited for its turn gives the turn back.
       throttleAbort.abort();
@@ -1159,8 +1217,10 @@ export class Client implements CommandExecutor, AsyncDisposable {
   }
 
   /**
-   * Send one encoded audio frame to the channel this client is in. Throws a
-   * NotConnectedError unless the client is connected.
+   * Send one encoded audio frame to the channel this client is in. An empty
+   * frame marks the end of speech: the server relays it, and listeners get a
+   * `voiceData` event with empty `data`. Throws a NotConnectedError unless the
+   * client is connected.
    */
   sendVoice(data: Uint8Array, codec: Codec, options?: VoiceOptions): void {
     // Reserved: VoiceOptions has no fields to read yet.
@@ -1213,7 +1273,10 @@ export class Client implements CommandExecutor, AsyncDisposable {
     // A privilege key is spent by the join that used it: a reconnection must
     // not present it again.
     if (this.#clientInitOptions.privilegeKey !== "") {
-      this.#clientInitOptions = { ...this.#clientInitOptions, privilegeKey: "" };
+      this.#clientInitOptions = {
+        ...this.#clientInitOptions,
+        privilegeKey: "",
+      };
     }
     // Settled before the hook runs, so that nothing it does can turn this
     // attempt into a failed one; connect() resumes only after the hook returns.
@@ -1417,7 +1480,9 @@ export class Client implements CommandExecutor, AsyncDisposable {
       this.#failConnection(
         error instanceof HandshakeError
           ? error
-          : new HandshakeError("the handshake failed on a malformed packet", { cause: error }),
+          : new HandshakeError("the handshake failed on a malformed packet", {
+              cause: error,
+            }),
       );
       return;
     }
@@ -1456,7 +1521,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
       return;
     }
 
-    if ((pType === 0 /* Voice */ || pType === 1) /* VoiceWhisper */ && p.data.length > 5) {
+    if ((pType === 0 /* Voice */ || pType === 1) /* VoiceWhisper */ && p.data.length >= 5) {
       this.#handleVoicePacket(p.data);
       return;
     }
@@ -1469,6 +1534,12 @@ export class Client implements CommandExecutor, AsyncDisposable {
   /**
    * Parse an incoming S2C voice packet.
    * Format: [VId: u16] [CId: u16] [Codec: u8] [Data: var]
+   *
+   * A packet with no data is how a speaker's last frame is followed: the
+   * server relays the empty frame a client sends when it stops talking, and it
+   * is delivered as an event with empty `data`. Measured on TeamSpeak 3 3.13.8
+   * and TeamSpeak 6 6.0.0: the frames of `sendVoice` arrive as 45-byte packets
+   * and an empty one as a 5-byte packet.
    */
   #handleVoicePacket(payload: Uint8Array): void {
     // Audio arrives fifty times a second per speaker; build no event nobody
@@ -1656,7 +1727,9 @@ export class Client implements CommandExecutor, AsyncDisposable {
   #answerConnectionInfoRequest(): void {
     const line = buildSetConnectionInfo(this.#handler.trafficSnapshot(), this.#handler.roundTrip);
     this.#execNoWait(line, undefined, false).catch((error: unknown) => {
-      this.#logger.debug("could not answer a connection info request", { error: String(error) });
+      this.#logger.debug("could not answer a connection info request", {
+        error: String(error),
+      });
     });
   }
 
@@ -1754,17 +1827,29 @@ export class Client implements CommandExecutor, AsyncDisposable {
         this.#emitServerEvent({ name: "clientUpdated", payload: result.event });
         break;
       case "clientServerGroupAdded":
-        this.#emitServerEvent({ name: "clientServerGroupAdded", payload: result.event });
+        this.#emitServerEvent({
+          name: "clientServerGroupAdded",
+          payload: result.event,
+        });
         break;
       case "clientServerGroupRemoved":
-        this.#emitServerEvent({ name: "clientServerGroupRemoved", payload: result.event });
+        this.#emitServerEvent({
+          name: "clientServerGroupRemoved",
+          payload: result.event,
+        });
         break;
       case "clientChannelGroupChanged":
-        this.#emitServerEvent({ name: "clientChannelGroupChanged", payload: result.event });
+        this.#emitServerEvent({
+          name: "clientChannelGroupChanged",
+          payload: result.event,
+        });
         break;
       case "channelCreated":
         this.#viewStore.applyCreated(result.event);
-        this.#emitServerEvent({ name: "channelCreated", payload: result.event });
+        this.#emitServerEvent({
+          name: "channelCreated",
+          payload: result.event,
+        });
         break;
       case "channelEdited":
         this.#viewStore.applyEdited(result.event);
@@ -1784,31 +1869,49 @@ export class Client implements CommandExecutor, AsyncDisposable {
         break;
       }
       case "channelDescriptionChanged":
-        this.#emitServerEvent({ name: "channelDescriptionChanged", payload: result.event });
+        this.#emitServerEvent({
+          name: "channelDescriptionChanged",
+          payload: result.event,
+        });
         break;
       case "channelPasswordChanged":
-        this.#emitServerEvent({ name: "channelPasswordChanged", payload: result.event });
+        this.#emitServerEvent({
+          name: "channelPasswordChanged",
+          payload: result.event,
+        });
         break;
       case "serverEdited":
         this.#viewStore.patchServer(result.event.changes);
         this.#emitServerEvent({ name: "serverEdited", payload: result.event });
         break;
       case "channelSubscribed":
-        this.#emitServerEvent({ name: "channelSubscribed", payload: result.event });
+        this.#emitServerEvent({
+          name: "channelSubscribed",
+          payload: result.event,
+        });
         break;
       case "channelUnsubscribed":
         // The server does not say the clients of the channel left.
         this.#viewStore.dropChannel(result.event.channelID);
-        this.#emitServerEvent({ name: "channelUnsubscribed", payload: result.event });
+        this.#emitServerEvent({
+          name: "channelUnsubscribed",
+          payload: result.event,
+        });
         break;
       case "pluginCommand":
         this.#emitServerEvent({ name: "pluginCommand", payload: result.event });
         break;
       case "clientChatComposing":
-        this.#emitServerEvent({ name: "clientChatComposing", payload: result.event });
+        this.#emitServerEvent({
+          name: "clientChatComposing",
+          payload: result.event,
+        });
         break;
       case "clientChatClosed":
-        this.#emitServerEvent({ name: "clientChatClosed", payload: result.event });
+        this.#emitServerEvent({
+          name: "clientChatClosed",
+          payload: result.event,
+        });
         break;
       case "poked":
         this.#emitServerEvent({ name: "poked", payload: result.event });
@@ -1970,7 +2073,9 @@ export class Client implements CommandExecutor, AsyncDisposable {
     try {
       retry = (options.shouldRetry ?? defaultShouldRetry)(err, attempt);
     } catch (error) {
-      this.#logger.error("shouldRetry threw; not reconnecting", { error: String(error) });
+      this.#logger.error("shouldRetry threw; not reconnecting", {
+        error: String(error),
+      });
       retry = false;
       threw = true;
     }
@@ -2030,7 +2135,9 @@ export class Client implements CommandExecutor, AsyncDisposable {
         // Connected, or connecting, by hand during the wait: nothing is left to
         // retry, and an attempt now would only fail with AlreadyConnectedError.
         if (this.#status !== ClientStatus.Disconnected) {
-          this.#logger.info("reconnect loop ended: connected by other means", { attempt });
+          this.#logger.info("reconnect loop ended: connected by other means", {
+            attempt,
+          });
           return;
         }
 
@@ -2059,12 +2166,17 @@ export class Client implements CommandExecutor, AsyncDisposable {
               : new TeamspeakError(String(retryErr), { cause: retryErr });
         }
       }
-      this.#logger.warn("reconnect attempts exhausted", { attempts: policy.maxAttempts });
+      this.#logger.warn("reconnect attempts exhausted", {
+        attempts: policy.maxAttempts,
+      });
       stoppedBy = { cause: err };
     } finally {
       if (stoppedBy !== undefined) {
         const { cause } = stoppedBy;
-        this.#callHook(this.#trace?.reconnectStopped, () => ({ attempts: made, cause }));
+        this.#callHook(this.#trace?.reconnectStopped, () => ({
+          attempts: made,
+          cause,
+        }));
       }
       this.#reconnecting = false;
       this.#loopAttempt = 0;

package/src/client/crypto/crypt.ts

@@ -140,18 +140,26 @@ export class Crypt {
     this.setSharedSecret(alphaBytes, betaBytes, sharedSecret);
   }
 
+  /**
+   * Build the IV from `alpha` and `beta` XORed into `sharedKey` and complete
+   * crypto init. The values come from the server, so a length that does not fit
+   * is refused rather than padded: alpha must be 10 bytes, beta at least one,
+   * and the key as long as the IV, 10 bytes plus beta.
+   */
   setSharedSecret(alpha: Uint8Array, beta: Uint8Array, sharedKey: Uint8Array): void {
+    if (
+      alpha.length !== IV_ALPHA_SIZE ||
+      beta.length === 0 ||
+      IV_ALPHA_SIZE + beta.length > sharedKey.length
+    ) {
+      throw new HandshakeError("alpha, beta and the shared secret do not fit together");
+    }
     this.#ivStruct = new Uint8Array(IV_ALPHA_SIZE + beta.length);
     for (let i = 0; i < IV_ALPHA_SIZE; i++) {
-      const a = sharedKey[i];
-      const b = alpha[i];
-      this.#ivStruct[i] = ((a !== undefined ? a : 0) ^ (b !== undefined ? b : 0)) & 0xff;
+      this.#ivStruct[i] = (sharedKey[i]! ^ alpha[i]!) & 0xff;
     }
     for (let i = 0; i < beta.length; i++) {
-      const a = sharedKey[IV_ALPHA_SIZE + i];
-      const b = beta[i];
-      this.#ivStruct[IV_ALPHA_SIZE + i] =
-        ((a !== undefined ? a : 0) ^ (b !== undefined ? b : 0)) & 0xff;
+      this.#ivStruct[IV_ALPHA_SIZE + i] = (sharedKey[IV_ALPHA_SIZE + i]! ^ beta[i]!) & 0xff;
     }
 
     // Keys derive from the IV: any cached before it changed belong to another

package/src/client/crypto/eax.ts

@@ -81,9 +81,13 @@ function aesCtr(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Uint8Array {
 
 // ---- AES-CMAC (RFC 4493) ----------------------------------------------------
 
+/**
+ * The CMAC subkeys of each key, derived once: a session uses one key for every
+ * packet, and deriving them costs a cipher of its own.
+ */
+const subkeyCache = new WeakMap<Uint8Array, [Uint8Array, Uint8Array]>();
+
 function aesEcb(key: Uint8Array, block: Uint8Array): Uint8Array {
-  // Node.js does not expose ECB directly; simulate via CTR with zero IV and
-  // a zero-input (CTR of 0-block XOR with input = ECB)
   const cipher = createCipheriv("aes-128-ecb", Buffer.from(key), null);
   cipher.setAutoPadding(false);
   return Buffer.concat([cipher.update(Buffer.from(block)), cipher.final()]);
@@ -110,6 +114,8 @@ const RB = new Uint8Array(EAX_BLOCK_SIZE);
 RB[EAX_BLOCK_SIZE - 1] = 0x87;
 
 function generateSubkeys(key: Uint8Array): [Uint8Array, Uint8Array] {
+  const cached = subkeyCache.get(key);
+  if (cached !== undefined) return cached;
   const zero = new Uint8Array(EAX_BLOCK_SIZE);
   const L = aesEcb(key, zero);
 
@@ -119,34 +125,33 @@ function generateSubkeys(key: Uint8Array): [Uint8Array, Uint8Array] {
   let K2 = shiftLeft1(K1);
   if ((K1[0]! & 0x80) !== 0) K2 = xorBlock(K2, RB);
 
-  return [K1, K2];
+  const subkeys: [Uint8Array, Uint8Array] = [K1, K2];
+  subkeyCache.set(key, subkeys);
+  return subkeys;
 }
 
+const ZERO_IV = Buffer.alloc(EAX_BLOCK_SIZE);
+
+/**
+ * AES-CMAC: the last block of AES-CBC with a zero IV over the message, its last
+ * block padded and XORed with a subkey. One cipher for the whole message.
+ */
 export function aesCmac(key: Uint8Array, message: Uint8Array): Uint8Array {
   const [K1, K2] = generateSubkeys(key);
 
   const n = Math.max(1, Math.ceil(message.length / EAX_BLOCK_SIZE));
   const lastBlockComplete = message.length > 0 && message.length % EAX_BLOCK_SIZE === 0;
 
-  let X: Uint8Array = new Uint8Array(EAX_BLOCK_SIZE);
-
-  for (let i = 0; i < n - 1; i++) {
-    const block = message.slice(i * EAX_BLOCK_SIZE, (i + 1) * EAX_BLOCK_SIZE);
-    X = Uint8Array.from(aesEcb(key, xorBlock(X, block)));
-  }
-
-  const lastBlock = new Uint8Array(EAX_BLOCK_SIZE);
+  const padded = Buffer.alloc(n * EAX_BLOCK_SIZE);
+  padded.set(message);
   const lastStart = (n - 1) * EAX_BLOCK_SIZE;
-  const lastSlice = message.slice(lastStart);
-  lastBlock.set(lastSlice);
-
-  let Mn: Uint8Array;
-  if (lastBlockComplete) {
-    Mn = xorBlock(lastBlock, K1);
-  } else {
-    if (lastSlice.length < EAX_BLOCK_SIZE) lastBlock[lastSlice.length] = 0x80;
-    Mn = xorBlock(lastBlock, K2);
-  }
+  if (!lastBlockComplete) padded[message.length] = 0x80;
+  const subkey = lastBlockComplete ? K1 : K2;
+  for (let i = 0; i < EAX_BLOCK_SIZE; i++)
+    padded[lastStart + i] = padded[lastStart + i]! ^ subkey[i]!;
 
-  return Uint8Array.from(aesEcb(key, xorBlock(X, Mn)));
+  const cipher = createCipheriv("aes-128-cbc", Buffer.from(key), ZERO_IV);
+  cipher.setAutoPadding(false);
+  const out = cipher.update(padded);
+  return Uint8Array.from(out.subarray(out.length - EAX_BLOCK_SIZE));
 }

package/src/client/errors.ts

@@ -195,6 +195,31 @@ export class ConnectionTimeoutError extends TeamspeakError {
   }
 }
 
+/**
+ * The server's command stream broke: a command packet stayed missing for
+ * seconds while later ones arrived, although the server sends one again until
+ * it is acknowledged. The connection is ended rather than carry on without the
+ * missing command, which would drop an answer or a notification and could
+ * leave the view out of step with the server's; a reconnect starts from a
+ * consistent state.
+ */
+export class ConnectionStalledError extends TeamspeakError {
+  /** {@inheritDoc @honeybbq/teamspeak!TeamspeakError.kind} */
+  static override readonly kind: string = "ConnectionStalledError";
+  static {
+    Object.defineProperty(this.prototype, "name", {
+      value: "ConnectionStalledError",
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  constructor() {
+    super("connection stalled: a command from the server never arrived");
+  }
+}
+
 /**
  * The server ended this client's session: a kick, a ban, or the server
  * stopping. The default reconnect policy retries a server that stopped, but

package/src/client/handshake/crypt-handshake.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { buildCommandOrdered } from "../../core/internal.js";
 import { MAX_RSA_CHALLENGE_LEVEL, type Crypt } from "../crypto/crypt.js";
-import { HandshakeError, PuzzleTooHardError } from "../errors.js";
+import { PuzzleTooHardError } from "../errors.js";
 
 export const INIT_VERSION = 1566914096; // 3.5.0 [Stable]
 
@@ -35,7 +35,8 @@ export function puzzleOf(crypt: Crypt): { readonly level: number; readonly durat
 /**
  * Handle the TS3INIT1 handshake steps.
  * Returns the response bytes to send, or null if nothing should be sent.
- * Throws a HandshakeError for a step that cannot be answered.
+ * A step that cannot be answered is ignored (null); a puzzle out of range
+ * throws a PuzzleTooHardError.
  *
  * The puzzle step is the only one that takes time, so a challenge not answered
  * before returns a promise of the response, which gives the event loop back
@@ -56,7 +57,9 @@ export function processInit1(
   if (data === null || (data.length >= 1 && data[0] === 0x7f)) {
     return buildInit1StartPacket();
   }
-  if (data.length === 0) throw new HandshakeError("empty Init1 packet");
+  // Init1 is not authenticated: a step that cannot be answered, an empty one
+  // included, is ignored, and the attempt goes on with the real server's.
+  if (data.length === 0) return null;
 
   switch (data[0]) {
     case 0:

package/src/client/index.ts

@@ -38,6 +38,7 @@ export {
   InvalidIdentityError,
   RemovedError,
   ConnectionTimeoutError,
+  ConnectionStalledError,
 } from "./errors.js";
 
 // Commands only the voice protocol has.

package/src/client/throttle.ts

@@ -1,5 +1,6 @@
 interface Waiter {
   readonly resolve: () => void;
+  readonly reject: (reason: unknown) => void;
   readonly signal: AbortSignal | undefined;
   readonly onAbort: () => void;
 }
@@ -18,6 +19,8 @@ export class CommandThrottle {
 
   #tokens = 5.0;
   #lastUpdate = performance.now();
+  /** Until when nothing is released: the server asked this client to wait. */
+  #holdUntil = 0;
   readonly #waiters: Waiter[] = [];
   #timer: ReturnType<typeof setTimeout> | undefined;
 
@@ -29,13 +32,14 @@ export class CommandThrottle {
   wait(signal?: AbortSignal): Promise<void> {
     if (signal?.aborted) return Promise.reject(signal.reason);
     this.#refill();
-    if (this.#waiters.length === 0 && this.#tokens >= 1.0) {
+    if (this.#waiters.length === 0 && this.#tokens >= 1.0 && performance.now() >= this.#holdUntil) {
       this.#tokens -= 1.0;
       return Promise.resolve();
     }
     return new Promise<void>((resolve, reject) => {
       const waiter: Waiter = {
         resolve,
+        reject,
         signal,
         onAbort: () => {
           const index = this.#waiters.indexOf(waiter);
@@ -50,9 +54,35 @@ export class CommandThrottle {
     });
   }
 
+  /**
+   * Release nothing for `ms` milliseconds, then go on at the usual rate with no
+   * burst saved up: the server refused a command as flooding and said when to
+   * try again, and anything sent sooner is refused too and adds to the debt.
+   */
+  hold(ms: number): void {
+    this.#refill();
+    this.#holdUntil = Math.max(this.#holdUntil, performance.now() + ms);
+    this.#tokens = 0;
+    this.#stopTimer();
+    this.#schedule();
+  }
+
+  /**
+   * Reject every waiter still in line with `reason`, so none of them is ever
+   * released to send. Commands that ask afterwards wait as before.
+   */
+  rejectAll(reason: unknown): void {
+    this.#stopTimer();
+    for (const waiter of this.#waiters.splice(0)) {
+      waiter.signal?.removeEventListener("abort", waiter.onAbort);
+      waiter.reject(reason);
+    }
+  }
+
   #refill(): void {
     const now = performance.now();
-    const elapsed = (now - this.#lastUpdate) / 1000;
+    // Nothing accrues while held.
+    const elapsed = Math.max(0, now - Math.max(this.#lastUpdate, this.#holdUntil)) / 1000;
     this.#tokens = Math.min(
       this.#tokens + elapsed * CommandThrottle.TOKEN_RATE,
       CommandThrottle.TOKEN_MAX,
@@ -63,10 +93,13 @@ export class CommandThrottle {
   /** Arm the timer for when the next token is due, unless it already is. */
   #schedule(): void {
     if (this.#timer !== undefined || this.#waiters.length === 0) return;
-    const waitMs =
+    const forTokens =
       this.#tokens >= 1.0
         ? 0
         : Math.ceil(((1.0 - this.#tokens) / CommandThrottle.TOKEN_RATE) * 1000) + 10;
+    const held = Math.ceil(this.#holdUntil - performance.now());
+    // Tokens accrue only once the hold is over.
+    const waitMs = Math.max(0, held) + forTokens;
     this.#timer = setTimeout(() => {
       this.#timer = undefined;
       this.#release();
@@ -81,6 +114,11 @@ export class CommandThrottle {
   /** Hand the tokens there are to the waiters at the head of the line. */
   #release(): void {
     this.#refill();
+    // Woken early, or the hold was extended meanwhile.
+    if (performance.now() < this.#holdUntil) {
+      this.#schedule();
+      return;
+    }
     while (this.#waiters.length > 0 && this.#tokens >= 1.0) {
       this.#tokens -= 1.0;
       const waiter = this.#waiters.shift()!;