@honeybbq/teamspeak-client 0.3.0 → 1.0.0-beta.1

package/src/reconnect.ts

@@ -0,0 +1,141 @@
+/**
+ * Reconnection policy.
+ *
+ * A dropped connection is normal on a UDP voice session, so a bot that cannot
+ * recover is not usable unattended. Reconnecting is opt-in rather than
+ * automatic: a silent reconnect makes a dropped session look like a healthy
+ * one, and a caller that wanted to know about the drop never finds out.
+ *
+ * Backoff is not a nicety here. TeamSpeak bans an IP that opens several
+ * connections in quick succession — measured at roughly three, after which the
+ * server answers `error id=3329` and refuses everything. A reconnect loop
+ * without a delay therefore bans itself, and the ban outlasts the outage it was
+ * recovering from.
+ */
+
+import { ErrorCode, Reason, ServerError } from "@honeybbq/teamspeak-core";
+import { AlreadyConnectedError, InvalidAddressError, RemovedError } from "./errors.js";
+
+/** How long to wait before each attempt. */
+export interface BackoffPolicy {
+  /** Delay before the first retry, in milliseconds. */
+  readonly initialDelayMs: number;
+  /** Ceiling for the delay; it never grows past this. */
+  readonly maxDelayMs: number;
+  /** Multiplier applied after each failed attempt. */
+  readonly factor: number;
+  /**
+   * Fraction of the delay to randomise, 0 to 1.
+   *
+   * A fleet of bots that drop together would otherwise retry in lockstep and
+   * hit the server in a burst. Jitter spreads them out.
+   */
+  readonly jitter: number;
+  /** Give up after this many consecutive failures. 0 means never give up. */
+  readonly maxAttempts: number;
+}
+
+/** One second, doubling, capped at a minute, with 20% jitter, never giving up. */
+export const defaultBackoffPolicy: Readonly<BackoffPolicy> = Object.freeze({
+  initialDelayMs: 1_000,
+  maxDelayMs: 60_000,
+  factor: 2,
+  jitter: 0.2,
+  maxAttempts: 0,
+});
+
+/**
+ * How a client reconnects after its connection drops. Supplying it, even as
+ * `{}`, turns reconnecting on; a deliberate `disconnect()` never reconnects.
+ */
+export interface ReconnectOptions {
+  /** Tuning for the retry delays; unset fields keep {@link defaultBackoffPolicy}'s. */
+  readonly backoff?:
+    | { readonly [K in keyof BackoffPolicy]?: BackoffPolicy[K] | undefined }
+    | undefined;
+  /**
+   * Decide whether a given failure is worth retrying. Returning false stops the
+   * loop. Defaults to {@link defaultShouldRetry}.
+   */
+  readonly shouldRetry?: ((error: Error | undefined, attempt: number) => boolean) | undefined;
+}
+
+/**
+ * Compute the delay before an attempt.
+ *
+ * `attempt` is 1-based: the delay before the first retry is `initialDelayMs`,
+ * give or take the jitter, and the delay never grows past `maxDelayMs`.
+ */
+export function backoffDelay(policy: Readonly<BackoffPolicy>, attempt: number): number {
+  return jitteredDelay(policy, attempt, Math.random);
+}
+
+/** @internal The delay, with `random` supplying the jitter. */
+export function jitteredDelay(
+  policy: Readonly<BackoffPolicy>,
+  attempt: number,
+  random: () => number,
+): number {
+  const exponent = Math.max(0, attempt - 1);
+  const raw = policy.initialDelayMs * policy.factor ** exponent;
+  const capped = Math.min(raw, policy.maxDelayMs);
+
+  if (policy.jitter <= 0) return Math.round(capped);
+
+  // Full jitter would ignore the computed delay; this keeps the trend while
+  // spreading peers, so a whole fleet does not retry on the same millisecond.
+  // Kept under the ceiling, which a caller reasonably reads as a promise.
+  const spread = capped * Math.min(policy.jitter, 1);
+  const delay = capped + (random() * 2 - 1) * spread;
+  return Math.round(Math.max(0, Math.min(delay, policy.maxDelayMs)));
+}
+
+/**
+ * Server errors where retrying cannot help.
+ *
+ * Deliberately a short list of codes known to be refusals, rather than "any
+ * ServerError". The server also answers transiently: after a dropped
+ * connection it still holds the old session, and a reconnect with the same
+ * identity is refused with 521 "too many clones already connected" until it
+ * reaps the zombie — a condition that clears itself and is worth retrying.
+ *
+ * The asymmetry is deliberate. Retrying a permanent failure costs a few bounded
+ * attempts; not retrying a transient one means never recovering.
+ */
+const PERMANENT_SERVER_ERRORS: ReadonlySet<number> = new Set([
+  ErrorCode.ConnectFailedBanned,
+  ErrorCode.BanFlooding,
+  ErrorCode.ServerInvalidPassword,
+  ErrorCode.ChannelInvalidPassword,
+  ErrorCode.PermissionsClientInsufficient,
+]);
+
+/**
+ * Whether a failure is worth another attempt.
+ *
+ * Transport failures are retried; so is a server that stopped, and a server
+ * error other than the known refusals — a ban, flooding, a wrong server or
+ * channel password, missing permissions — since some, such as 521 "too many
+ * clones" right after a drop, clear by themselves. A kick or a ban is not:
+ * someone removed the client on purpose. Nor is an AlreadyConnectedError: the
+ * client was connected by other means; nor an InvalidAddressError.
+ */
+export function defaultShouldRetry(error: Error | undefined): boolean {
+  // The client is connected, or connecting, already: there is nothing to retry.
+  if (error instanceof AlreadyConnectedError) return false;
+  // An address that cannot be one stays that way.
+  if (error instanceof InvalidAddressError) return false;
+  if (error instanceof RemovedError) {
+    return error.reason !== Reason.KickServer && error.reason !== Reason.KickServerBan;
+  }
+  return !(error instanceof ServerError && PERMANENT_SERVER_ERRORS.has(error.code));
+}
+
+export function resolveBackoffPolicy(options: ReconnectOptions): BackoffPolicy {
+  const policy: Record<string, number> = { ...defaultBackoffPolicy };
+  // An explicit undefined keeps the default, as an unset field does.
+  for (const [key, value] of Object.entries(options.backoff ?? {})) {
+    if (value !== undefined) policy[key] = value;
+  }
+  return policy as unknown as BackoffPolicy;
+}

package/src/throttle.ts

@@ -0,0 +1,92 @@
+interface Waiter {
+  readonly resolve: () => void;
+  readonly signal: AbortSignal | undefined;
+  readonly onAbort: () => void;
+}
+
+/**
+ * Token-bucket limiter for outbound TS3 commands.
+ * Mirrors Go's commandThrottle.
+ *
+ * Waiters are released in the order they arrived: each used to poll for a
+ * token on its own timer, so a command that came later could take the turn of
+ * one that had waited longer, and the commands went out of order.
+ */
+export class CommandThrottle {
+  static readonly TOKEN_RATE = 4.0; // tokens per second
+  static readonly TOKEN_MAX = 8.0; // bucket capacity
+
+  #tokens = 5.0;
+  #lastUpdate = Date.now();
+  readonly #waiters: Waiter[] = [];
+  #timer: ReturnType<typeof setTimeout> | undefined;
+
+  /**
+   * Wait for a token, behind every earlier waiter. Aborting `signal` rejects
+   * with its reason and gives the place in line up; the abort listener is
+   * removed however the wait ends.
+   */
+  wait(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    this.#refill();
+    if (this.#waiters.length === 0 && this.#tokens >= 1.0) {
+      this.#tokens -= 1.0;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      const waiter: Waiter = {
+        resolve,
+        signal,
+        onAbort: () => {
+          const index = this.#waiters.indexOf(waiter);
+          if (index >= 0) this.#waiters.splice(index, 1);
+          if (this.#waiters.length === 0) this.#stopTimer();
+          reject(signal!.reason);
+        },
+      };
+      signal?.addEventListener("abort", waiter.onAbort, { once: true });
+      this.#waiters.push(waiter);
+      this.#schedule();
+    });
+  }
+
+  #refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.#lastUpdate) / 1000;
+    this.#tokens = Math.min(
+      this.#tokens + elapsed * CommandThrottle.TOKEN_RATE,
+      CommandThrottle.TOKEN_MAX,
+    );
+    this.#lastUpdate = now;
+  }
+
+  /** 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 =
+      this.#tokens >= 1.0
+        ? 0
+        : Math.ceil(((1.0 - this.#tokens) / CommandThrottle.TOKEN_RATE) * 1000) + 10;
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      this.#release();
+    }, waitMs);
+  }
+
+  #stopTimer(): void {
+    clearTimeout(this.#timer);
+    this.#timer = undefined;
+  }
+
+  /** Hand the tokens there are to the waiters at the head of the line. */
+  #release(): void {
+    this.#refill();
+    while (this.#waiters.length > 0 && this.#tokens >= 1.0) {
+      this.#tokens -= 1.0;
+      const waiter = this.#waiters.shift()!;
+      waiter.signal?.removeEventListener("abort", waiter.onAbort);
+      waiter.resolve();
+    }
+    this.#schedule();
+  }
+}

package/src/transfer.ts

@@ -0,0 +1,127 @@
+/**
+ * File transfer data.
+ *
+ * Negotiating a transfer is a command (`initFileUpload`, `initFileDownload`);
+ * the bytes then go over a separate TCP connection to the server's file
+ * transfer port, opened with the key the negotiation returned.
+ */
+
+import { connect } from "node:net";
+import { pipeline } from "node:stream/promises";
+import type { Duplex, Readable, Writable } from "node:stream";
+import type { FileUploadInfo, FileDownloadInfo } from "@honeybbq/teamspeak-core";
+import type { FileTransferSocketFactory } from "./types.js";
+import { FileTransferError } from "./errors.js";
+
+/** How long dialing may take before it fails, unless a signal says otherwise. */
+const DIAL_TIMEOUT_MS = 10_000;
+
+/** Options for a file transfer. */
+export interface FileTransferOptions {
+  /** Abandons the transfer; it then rejects with the signal's reason. */
+  readonly signal?: AbortSignal | undefined;
+  /**
+   * Opens the connection instead of a direct TCP dial, to route the transfer
+   * through a proxy or tunnel.
+   */
+  readonly socketFactory?: FileTransferSocketFactory | undefined;
+}
+
+/**
+ * Open a connection to the file transfer port and send the transfer key.
+ * The caller owns the returned stream and must end or destroy it.
+ */
+export async function dialFileTransfer(
+  host: string,
+  port: number,
+  key: string,
+  options: FileTransferOptions = {},
+): Promise<Duplex> {
+  const { signal, socketFactory } = options;
+  signal?.throwIfAborted();
+  const socket: Duplex = socketFactory ? socketFactory(host, port) : connect({ host, port });
+
+  // Until the caller takes the stream over, its errors are this function's to
+  // report: a stream's unhandled `error` event takes the process down.
+  const swallow = (): void => {};
+  socket.on("error", swallow);
+  try {
+    await connected(socket, signal);
+    await new Promise<void>((resolve, reject) => {
+      socket.write(key, (err) =>
+        err
+          ? reject(
+              new FileTransferError(`failed to send transfer key: ${err.message}`, { cause: err }),
+            )
+          : resolve(),
+      );
+    });
+  } catch (error) {
+    socket.destroy();
+    throw error;
+  } finally {
+    socket.off("error", swallow);
+  }
+  return socket;
+}
+
+/**
+ * Wait for a stream to be connected. A `node:net` socket says so with
+ * `connect`; a stream from elsewhere that is already writable is taken as
+ * connected.
+ */
+function connected(socket: Duplex, signal: AbortSignal | undefined): Promise<void> {
+  const pending = (socket as { pending?: boolean }).pending;
+  if (pending === false || (pending === undefined && socket.writable)) return Promise.resolve();
+
+  return new Promise<void>((resolve, reject) => {
+    const timeout = AbortSignal.timeout(DIAL_TIMEOUT_MS);
+    const done = (error?: unknown): void => {
+      socket.off("connect", onConnect);
+      socket.off("ready", onConnect);
+      socket.off("error", onError);
+      signal?.removeEventListener("abort", onAbort);
+      timeout.removeEventListener("abort", onTimeout);
+      if (error === undefined) resolve();
+      else reject(error);
+    };
+    const onConnect = (): void => done();
+    const onError = (error: Error): void =>
+      done(
+        new FileTransferError(`file transfer connection failed: ${error.message}`, {
+          cause: error,
+        }),
+      );
+    const onAbort = (): void => done(signal!.reason);
+    const onTimeout = (): void => done(new FileTransferError("file transfer connection timed out"));
+    socket.once("connect", onConnect);
+    socket.once("ready", onConnect);
+    socket.once("error", onError);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    timeout.addEventListener("abort", onTimeout, { once: true });
+  });
+}
+
+/** Upload `data` over a negotiated transfer. Resolves once every byte is sent. */
+export async function uploadFileData(
+  host: string,
+  info: FileUploadInfo,
+  data: Readable,
+  options: FileTransferOptions = {},
+): Promise<void> {
+  const socket = await dialFileTransfer(host, info.port, info.fileTransferKey, options);
+  await pipeline(data, socket, options.signal ? { signal: options.signal } : {});
+}
+
+/** Download a negotiated transfer into `dest`. Resolves once the file is written. */
+export async function downloadFileData(
+  host: string,
+  info: FileDownloadInfo,
+  dest: Writable,
+  options: FileTransferOptions = {},
+): Promise<void> {
+  const socket = await dialFileTransfer(host, info.port, info.fileTransferKey, options);
+  await pipeline(socket, dest, options.signal ? { signal: options.signal } : {});
+}
+
+export { FileTransferError };

package/src/transport/generation-window.ts

@@ -0,0 +1,77 @@
+export class GenerationWindow {
+  #mappedBaseOffset = 0;
+  #generation = 0;
+  readonly #mod: number;
+  readonly #receiveWindow: number;
+
+  constructor(mod: number, windowSize: number) {
+    this.#mod = mod;
+    this.#receiveWindow = windowSize;
+  }
+
+  get generation(): number {
+    return this.#generation;
+  }
+
+  advance(amount: number): void {
+    if (amount <= 0) return;
+    const newBaseOffset = this.#mappedBaseOffset + amount;
+    const genStep = Math.floor(newBaseOffset / this.#mod);
+    if (genStep > 0) {
+      this.#generation = Math.min(this.#generation + genStep, 0xffff_ffff);
+    }
+    this.#mappedBaseOffset = newBaseOffset % this.#mod;
+  }
+
+  advanceToExcluded(mappedValue: number): void {
+    let moveDist = mappedValue - this.#mappedBaseOffset;
+    if (moveDist < 0) moveDist += this.#mod;
+    this.advance(moveDist + 1);
+  }
+
+  syncTo(mappedValue: number): void {
+    let moveDist = mappedValue - this.#mappedBaseOffset;
+    if (moveDist < 0) moveDist += this.#mod;
+    this.advance(moveDist);
+  }
+
+  isInWindow(mappedValue: number): boolean {
+    const maxOffset = this.#mappedBaseOffset + this.#receiveWindow;
+    if (maxOffset < this.#mod) {
+      return mappedValue >= this.#mappedBaseOffset && mappedValue < maxOffset;
+    }
+    return mappedValue >= this.#mappedBaseOffset || mappedValue < maxOffset - this.#mod;
+  }
+
+  mappedToIndex(mappedValue: number): number {
+    if (this.#isNextGen(mappedValue)) {
+      return mappedValue + this.#mod - this.#mappedBaseOffset;
+    }
+    return mappedValue - this.#mappedBaseOffset;
+  }
+
+  isOldPacket(mappedValue: number): boolean {
+    return this.mappedToIndex(mappedValue) < 0;
+  }
+
+  isFuturePacket(mappedValue: number): boolean {
+    return this.mappedToIndex(mappedValue) >= this.#receiveWindow;
+  }
+
+  #isNextGen(mappedValue: number): boolean {
+    return (
+      this.#mappedBaseOffset > this.#mod - this.#receiveWindow &&
+      mappedValue < this.#mappedBaseOffset + this.#receiveWindow - this.#mod
+    );
+  }
+
+  getGeneration(mappedValue: number): number {
+    if (this.#isNextGen(mappedValue)) return this.#generation + 1;
+    return this.#generation;
+  }
+
+  reset(): void {
+    this.#mappedBaseOffset = 0;
+    this.#generation = 0;
+  }
+}