@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/src/client/index.ts

@@ -0,0 +1,93 @@
+/**
+ * A clean-room TeamSpeak client: it connects over the voice protocol, the way
+ * the TeamSpeak application does.
+ *
+ * Only what belongs to the voice protocol is exported here. The typed commands,
+ * ids and errors every client shares come from `@honeybbq/teamspeak`.
+ *
+ * @module @honeybbq/teamspeak/client
+ */
+
+// The client
+export { Client } from "./client.js";
+export { EventName } from "./types.js";
+
+export type {
+  EventMap,
+  EventMiddleware,
+  ServerEvent,
+  ServerEventName,
+  VoiceOptions,
+  WhisperTargets,
+  AddrResolver,
+  ClientOptions,
+  ResolvedAddr,
+  DatagramSocket,
+  SocketFactory,
+  FileTransferSocketFactory,
+} from "./types.js";
+
+export {
+  FileTransferError,
+  HandshakeError,
+  InvalidAddressError,
+  InvalidIdentityError,
+  RemovedError,
+  ConnectionTimeoutError,
+} from "./errors.js";
+
+// Commands only the voice protocol has.
+export * from "./api/voice.js";
+
+// File transfer data
+export { dialFileTransfer, uploadFileData, downloadFileData } from "./transfer.js";
+export type {
+  FileTransferOptions,
+  FileTransferTrace,
+  FileTransferStage,
+  FileTransferDialStartInfo,
+  FileTransferDialDoneInfo,
+  FileTransferProgressInfo,
+  FileTransferDoneInfo,
+  FileTransferFailedInfo,
+} from "./transfer.js";
+
+// Tracing a connection attempt
+export { ConnectPhase } from "./trace.js";
+export type {
+  ClientTrace,
+  ResolveStartInfo,
+  ResolveDoneInfo,
+  ConnectStartInfo,
+  ConnectDoneInfo,
+  HandshakeDoneInfo,
+  SessionStartInfo,
+  WelcomeDoneInfo,
+  AttemptFailedInfo,
+  ReconnectScheduledInfo,
+  DisconnectStartInfo,
+  DisconnectDoneInfo,
+  SessionEndInfo,
+  ReconnectStoppedInfo,
+} from "./trace.js";
+
+// Server capabilities, read from the handshake
+export { unknownServerCapabilities } from "./capabilities.js";
+export type { ServerCapabilities } from "./capabilities.js";
+
+// Tracing points for diagnostics_channel subscribers
+export { commandChannel, incomingChannel } from "./diagnostics.js";
+export type { CommandTrace, IncomingTrace } from "./diagnostics.js";
+
+// Reconnection policy
+export { defaultShouldRetry } from "./reconnect.js";
+
+// Identity
+export {
+  Identity,
+  parseIdentity,
+  generateIdentity,
+  generateIdentitySync,
+  uidFromPublicKey,
+} from "./crypto/index.js";
+export type { UIDAlgorithm } from "./crypto/index.js";

package/src/client/reconnect.ts

@@ -0,0 +1,43 @@
+import { ErrorCode, Reason, ServerError, AlreadyConnectedError } from "@honeybbq/teamspeak";
+import { InvalidAddressError, RemovedError } from "./errors.js";
+
+/**
+ * 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));
+}

package/src/client/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 = performance.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 = performance.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/client/trace.ts

@@ -0,0 +1,237 @@
+import type { ChannelID, ClientID } from "@honeybbq/teamspeak";
+import type { ServerCapabilities } from "./capabilities.js";
+import type { ResolvedAddr } from "./types.js";
+
+/** The values of the table below, before freezing. */
+const connectPhaseValues = {
+  /** Opening the socket, or the address was not usable once resolved. */
+  Open: "open",
+  /** The handshake, from the first packet until the shared secret exists. */
+  Handshake: "handshake",
+  /** After the handshake, waiting for the server to accept the client: a wrong password, a ban or an invalid nickname end here. */
+  Join: "join",
+} as const;
+/** Where a connection attempt can fail; see {@link AttemptFailedInfo}. */
+export const ConnectPhase: typeof connectPhaseValues =
+  /* @__PURE__ */ Object.freeze(connectPhaseValues);
+/**
+ * One of {@link ConnectPhase}. May gain members in a minor release: a
+ * `switch` over it needs a default case.
+ */
+export type ConnectPhase = (typeof ConnectPhase)[keyof typeof ConnectPhase];
+
+/** What every milestone of one connection attempt says about the attempt. */
+interface AttemptInfo {
+  /**
+   * The attempt's number, from 1. The attempt `connect()` starts is 1; a
+   * reconnection attempt carries the retry number the reconnect policy uses,
+   * the one `shouldRetry` and the backoff see.
+   */
+  readonly attempt: number;
+  /** Whether the reconnect loop started this attempt rather than a call to `connect()`. */
+  readonly reconnect: boolean;
+}
+
+/** The address is about to be resolved. */
+export interface ResolveStartInfo extends AttemptInfo {
+  /** The address as the client was given it. */
+  readonly addr: string;
+}
+
+/** The address has been resolved, or the lookup failed and the address is used as given. */
+export interface ResolveDoneInfo extends AttemptInfo {
+  /** The address as the client was given it. */
+  readonly addr: string;
+  /** The `host:port` that will be dialled. */
+  readonly target: string;
+  /** What the resolver reports as the source of the answer dialled; may be empty. */
+  readonly source: string;
+  /** Every answer the resolver gave, in order; empty when the address is used as given. */
+  readonly candidates: readonly ResolvedAddr[];
+  /** Why the lookup failed, when the address is used as given; `undefined` otherwise. */
+  readonly error: unknown;
+  /** How long the resolution took, in milliseconds. */
+  readonly durationMs: number;
+}
+
+/** The socket is about to be opened. */
+export interface ConnectStartInfo extends AttemptInfo {
+  /** The `host:port` being dialled. */
+  readonly target: string;
+}
+
+/** The socket is open; the first handshake packet has not been sent yet. */
+export interface ConnectDoneInfo extends AttemptInfo {
+  /** The `host:port` being dialled. */
+  readonly target: string;
+  /** The local socket's `host:port`; empty when the socket does not say. */
+  readonly localAddr: string;
+  /** Milliseconds since `connectStart`. */
+  readonly durationMs: number;
+}
+
+/** The encrypted session exists; `clientinit` has not been sent yet. */
+export interface HandshakeDoneInfo extends AttemptInfo {
+  /** Milliseconds since `connectStart`. */
+  readonly durationMs: number;
+  /** The level of the RSA puzzle the server demanded; 0 if it sent none. */
+  readonly puzzleLevel: number;
+  /** Milliseconds spent solving the puzzle. */
+  readonly puzzleDurationMs: number;
+  /**
+   * The packets sent again from `connectStart` to now, for want of an
+   * acknowledgement: the Init1 steps and the handshake's command packets.
+   */
+  readonly resends: number;
+  /**
+   * The server's public key exactly as it sent it, base64, so that a caller can
+   * pin a server's identity.
+   */
+  readonly serverPublicKey: string;
+}
+
+/** The server accepted the client, which is now connected. */
+export interface SessionStartInfo extends AttemptInfo {
+  /** The client's ID on the server, the same as `client.clientID`. */
+  readonly clientID: ClientID;
+  /**
+   * The nickname the server accepted (`acn`), which differs from the one asked
+   * for when that was taken. The one asked for when the server did not say.
+   */
+  readonly nickname: string;
+  /** The client's talk power (`client_talk_power`); 0 when the server did not say. */
+  readonly talkPower: number;
+  /**
+   * Every parameter of `initserver`, unescaped, except those that could carry a
+   * secret: `client_server_password`, `client_default_channel_password`,
+   * `client_default_token` and `client_key_offset`. Frozen.
+   */
+  readonly initServer: Readonly<Record<string, string>>;
+  /** What the server said about itself in this handshake. */
+  readonly capabilities: ServerCapabilities;
+  /** Milliseconds since `connectStart`. */
+  readonly durationMs: number;
+}
+
+/** The server's welcome sequence ended: the channel list and the clients already there have arrived. */
+export interface WelcomeDoneInfo extends AttemptInfo {
+  /**
+   * The channel the client is in at the end of the welcome: where it landed,
+   * which differs from the default channel asked for when that was refused.
+   */
+  readonly channelID: ChannelID;
+  /** How many channel rows the welcome delivered. */
+  readonly channels: number;
+  /** How many clients are in view at the end of the welcome, this client included. */
+  readonly clients: number;
+  /** Milliseconds since `connectStart`. */
+  readonly durationMs: number;
+}
+
+/** An attempt ended without a session. */
+export interface AttemptFailedInfo extends AttemptInfo {
+  /** Where the attempt failed. */
+  readonly phase: ConnectPhase;
+  /** Why: the error `connect()` rejects with, or the one that ended the reconnection attempt. */
+  readonly error: unknown;
+  /** The `host:port` being dialled; empty when the attempt failed before `resolveDone`. */
+  readonly target: string;
+  /** Milliseconds since `resolveStart`. */
+  readonly durationMs: number;
+}
+
+/** The reconnect loop will retry, after a wait. */
+export interface ReconnectScheduledInfo {
+  /** The attempt that will follow, numbered as in {@link ResolveStartInfo.attempt}. */
+  readonly attempt: number;
+  /** How long the loop waits first, in milliseconds. */
+  readonly delayMs: number;
+  /** The error that ended the previous connection or attempt. */
+  readonly cause: unknown;
+}
+
+/** A connected session is about to be left with `disconnect()`. It has no fields yet. */
+export interface DisconnectStartInfo {}
+
+/** The goodbye of `disconnect()` is over. */
+export interface DisconnectDoneInfo {
+  /** Whether the server acknowledged the goodbye before the goodbye timeout. */
+  readonly acknowledged: boolean;
+  /** Milliseconds since `disconnectStart`. */
+  readonly durationMs: number;
+}
+
+/** A session that had a `sessionStart` has ended, however it ended. */
+export interface SessionEndInfo {
+  /** The client's ID on the server during the session. */
+  readonly clientID: ClientID;
+  /**
+   * `undefined` after `disconnect()`, and otherwise the cause the
+   * `disconnected` event gets.
+   */
+  readonly error: unknown;
+  /** Milliseconds since `sessionStart`. */
+  readonly durationMs: number;
+  /** The number of the attempt that started the session. */
+  readonly attempt: number;
+  /** Whether the reconnect loop started the attempt that started the session. */
+  readonly reconnect: boolean;
+}
+
+/** The reconnect loop ended without a session. */
+export interface ReconnectStoppedInfo {
+  /** How many reconnection attempts the loop made. */
+  readonly attempts: number;
+  /**
+   * The error `shouldRetry` declined, or the last attempt's when the attempts
+   * ran out; `undefined` when `disconnect()` stopped the loop.
+   */
+  readonly cause: unknown;
+}
+
+/**
+ * Hooks that observe a client for timing, metrics, logs or a progress
+ * display: the milestones of every connection attempt, the end of a session,
+ * and the reconnect loop. Every hook is optional.
+ *
+ * A hook is called synchronously, at the moment of the milestone, and the
+ * client waits for it to return: keep it quick, and hand slow work to your own
+ * task. What it returns is ignored, and a returned promise is never awaited. A
+ * hook that throws, or whose promise rejects, is reported the way a throwing
+ * event listener is, and the client carries on. A hook may read the
+ * client's state. It must not call `connect()` or `disconnect()`: to give up
+ * on an attempt, abort the signal passed to `connect()`, and to leave once
+ * connected, call `disconnect()` from a `connected` listener.
+ *
+ * Every attempt ends with exactly one of `sessionStart` and `attemptFailed`,
+ * and every session that started with exactly one `sessionEnd`. The hooks are
+ * read when the client is made, from a copy of this object.
+ */
+export interface ClientTrace {
+  /** Before the address is resolved. */
+  readonly resolveStart?: (info: ResolveStartInfo) => void;
+  /** After the address is resolved, also when it fell back to the address as given. */
+  readonly resolveDone?: (info: ResolveDoneInfo) => void;
+  /** Right before the socket is opened. */
+  readonly connectStart?: (info: ConnectStartInfo) => void;
+  /** Once the socket is open, before the first handshake packet is sent. */
+  readonly connectDone?: (info: ConnectDoneInfo) => void;
+  /** When the shared secret is derived, before `clientinit` is sent. */
+  readonly handshakeDone?: (info: HandshakeDoneInfo) => void;
+  /** When the server accepts the client: before `connect()` resolves and before `connected` is delivered. */
+  readonly sessionStart?: (info: SessionStartInfo) => void;
+  /** When the server's welcome sequence ends; at most once per attempt, and only after `sessionStart`. */
+  readonly welcomeDone?: (info: WelcomeDoneInfo) => void;
+  /** When an attempt ends without `sessionStart`, for any reason, an abort or `disconnect()` included. */
+  readonly attemptFailed?: (info: AttemptFailedInfo) => void;
+  /** When `disconnect()` begins saying goodbye to a connected session. */
+  readonly disconnectStart?: (info: DisconnectStartInfo) => void;
+  /** When that goodbye is over. */
+  readonly disconnectDone?: (info: DisconnectDoneInfo) => void;
+  /** When a session ends, however it ends; before `disconnected` is queued. */
+  readonly sessionEnd?: (info: SessionEndInfo) => void;
+  /** When the reconnect loop has decided to retry and is about to wait. */
+  readonly reconnectScheduled?: (info: ReconnectScheduledInfo) => void;
+  /** When the reconnect loop ends without a session. */
+  readonly reconnectStopped?: (info: ReconnectStoppedInfo) => void;
+}