@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/src/client/transport/index.ts

@@ -0,0 +1,14 @@
+export { PacketHandler } from "./handler.js";
+export {
+  PacketType,
+  PacketFlags,
+  packetType,
+  packetFlags,
+  isUnencrypted,
+  buildC2SHeader,
+  parseS2CHeader,
+  parseC2SHeader,
+} from "./packet.js";
+export type { Packet } from "./packet.js";
+export { GenerationWindow } from "./generation-window.js";
+export { Qlz } from "./quicklz.js";

package/src/client/transport/packet.ts

@@ -0,0 +1,69 @@
+export const enum PacketType {
+  Voice = 0,
+  VoiceWhisper = 1,
+  Command = 2,
+  CommandLow = 3,
+  Ping = 4,
+  Pong = 5,
+  Ack = 6,
+  AckLow = 7,
+  Init1 = 8,
+}
+
+export const enum PacketFlags {
+  Fragmented = 0x10,
+  NewProtocol = 0x20,
+  Compressed = 0x40,
+  Unencrypted = 0x80,
+}
+
+export interface Packet {
+  /** Type byte combined with flags (low nibble = type, high nibble = flags). */
+  typeFlagged: number;
+  id: number;
+  clientID: number;
+  generationID: number;
+  data: Uint8Array;
+  receivedAt: number; // performance.now(), a monotonic clock
+}
+
+export function packetType(p: Packet): PacketType {
+  return p.typeFlagged & 0x0f;
+}
+
+export function packetFlags(p: Packet): number {
+  return p.typeFlagged & 0xf0;
+}
+
+export function isUnencrypted(p: Packet): boolean {
+  return (packetFlags(p) & PacketFlags.Unencrypted) !== 0;
+}
+
+/** Build the 5-byte client-to-server header: [packetID(2), clientID(2), typeFlagged(1)]. */
+export function buildC2SHeader(p: Packet): Uint8Array {
+  const header = new Uint8Array(5);
+  const view = new DataView(header.buffer);
+  view.setUint16(0, p.id, false);
+  view.setUint16(2, p.clientID, false);
+  header[4] = p.typeFlagged;
+  return header;
+}
+
+/** Parse a 3-byte server-to-client header. */
+export function parseS2CHeader(raw: Uint8Array): Pick<Packet, "id" | "typeFlagged"> {
+  const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+  return {
+    id: view.getUint16(0, false),
+    typeFlagged: raw[2]!,
+  };
+}
+
+/** Parse a 5-byte client-to-server header. */
+export function parseC2SHeader(raw: Uint8Array): Pick<Packet, "id" | "clientID" | "typeFlagged"> {
+  const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+  return {
+    id: view.getUint16(0, false),
+    clientID: view.getUint16(2, false),
+    typeFlagged: raw[4]!,
+  };
+}

package/src/client/transport/quicklz.ts

@@ -0,0 +1,209 @@
+const TABLE_SIZE = 4096;
+
+/**
+ * The largest decompressed command accepted. A command is reassembled from at
+ * most a receive window of fragments, and the largest real answers (a full
+ * permission list, the welcome channel list of a big server) are a few
+ * hundred kilobytes; a header declaring more is refused before anything is
+ * allocated.
+ */
+export const MAX_DECOMPRESSED_SIZE: number = 1 << 20;
+
+/**
+ * How much larger than its compressed bytes a level-1 block can be. The most
+ * a 3-byte back-reference yields is 255 bytes, and every 32 entries also cost
+ * a 4-byte control word, which bounds the ratio at about 82; a block declaring
+ * more cannot be honest, and is refused before its output is allocated.
+ */
+const MAX_EXPANSION = 128;
+
+interface QlzState {
+  control: number;
+  sourcePos: number;
+  destPos: number;
+  nextHashed: number;
+}
+
+/** A QuickLZ block that cannot be decompressed: truncated, oversized or inconsistent. */
+export class QuickLZError extends Error {
+  constructor(message: string) {
+    super(`QuickLZ: ${message}`);
+    this.name = "QuickLZError";
+  }
+}
+
+/**
+ * QuickLZ level 1 decompression, as the server compresses large commands.
+ *
+ * The input comes from the network, so every read and every back-reference is
+ * checked, and malformed input throws a QuickLZError rather than reading out
+ * of range or producing a partly filled buffer.
+ */
+export class Qlz {
+  #hashtable = new Int32Array(TABLE_SIZE);
+
+  decompress(data: Uint8Array): Uint8Array {
+    const { headerLen, decompressedSize, flags } = parseQlzHeader(data);
+
+    if ((flags & 0x01) === 0) {
+      if (headerLen + decompressedSize > data.length) {
+        throw new QuickLZError("stored block is shorter than its declared size");
+      }
+      return data.slice(headerLen, headerLen + decompressedSize);
+    }
+
+    if (decompressedSize > (data.length - headerLen) * MAX_EXPANSION) {
+      throw new QuickLZError(
+        `declared size ${decompressedSize} is more than ${data.length - headerLen} bytes can expand to`,
+      );
+    }
+    const dest = new Uint8Array(decompressedSize);
+    this.#hashtable.fill(0);
+
+    const state: QlzState = {
+      control: 1,
+      sourcePos: headerLen,
+      destPos: 0,
+      nextHashed: 0,
+    };
+
+    while (state.destPos < decompressedSize) {
+      this.#ensureControl(data, state);
+      if ((state.control & 1) !== 0) {
+        this.#processReference(data, dest, state);
+      } else if (this.#processLiteral(data, dest, decompressedSize, state)) {
+        break;
+      }
+    }
+
+    if (state.destPos !== decompressedSize) throw new QuickLZError("block ends early");
+    return dest;
+  }
+
+  #ensureControl(data: Uint8Array, st: QlzState): void {
+    if (st.control !== 1) return;
+    if (st.sourcePos + 4 > data.length) throw new QuickLZError("block ends early");
+    st.control =
+      (data[st.sourcePos]! |
+        (data[st.sourcePos + 1]! << 8) |
+        (data[st.sourcePos + 2]! << 16) |
+        (data[st.sourcePos + 3]! << 24)) >>>
+      0;
+    st.sourcePos += 4;
+  }
+
+  #processReference(data: Uint8Array, dest: Uint8Array, st: QlzState): void {
+    st.control = (st.control >>> 1) >>> 0;
+    if (st.sourcePos + 2 > data.length) throw new QuickLZError("block ends early");
+
+    const b1 = data[st.sourcePos]!;
+    const b2 = data[st.sourcePos + 1]!;
+    st.sourcePos += 2;
+
+    const hash = (b1 >> 4) | (b2 << 4);
+    let matchlen = b1 & 0x0f;
+    if (matchlen !== 0) {
+      matchlen += 2;
+    } else {
+      if (st.sourcePos >= data.length) throw new QuickLZError("block ends early");
+      matchlen = data[st.sourcePos]!;
+      st.sourcePos++;
+    }
+
+    const offset = this.#hashtable[hash]!;
+    // The copy may overlap its own output, so only its start must precede it.
+    if (offset >= st.destPos) throw new QuickLZError("back-reference points ahead of the output");
+    if (st.destPos + matchlen > dest.length) {
+      throw new QuickLZError("back-reference overruns the declared size");
+    }
+    for (let i = 0; i < matchlen; i++) {
+      dest[st.destPos] = dest[offset + i]!;
+      st.destPos++;
+    }
+
+    const end = st.destPos + 1 - matchlen;
+    this.#updateHashtable(dest, st, end);
+    st.nextHashed = st.destPos;
+  }
+
+  /** Copy literals; returns true once the tail of the block has been copied. */
+  #processLiteral(
+    data: Uint8Array,
+    dest: Uint8Array,
+    decompressedSize: number,
+    st: QlzState,
+  ): boolean {
+    const threshold = Math.max(decompressedSize, 10) - 10;
+    if (st.destPos >= threshold) {
+      while (st.destPos < decompressedSize) {
+        if (st.control === 1) {
+          if (st.sourcePos + 4 > data.length) throw new QuickLZError("block ends early");
+          st.control =
+            (data[st.sourcePos]! |
+              (data[st.sourcePos + 1]! << 8) |
+              (data[st.sourcePos + 2]! << 16) |
+              (data[st.sourcePos + 3]! << 24)) >>>
+            0;
+          st.sourcePos += 4;
+        }
+        if (st.sourcePos >= data.length) throw new QuickLZError("block ends early");
+        dest[st.destPos++] = data[st.sourcePos++]!;
+        st.control = (st.control >>> 1) >>> 0;
+      }
+      return true;
+    }
+
+    if (st.sourcePos >= data.length) throw new QuickLZError("block ends early");
+
+    dest[st.destPos++] = data[st.sourcePos++]!;
+    st.control = (st.control >>> 1) >>> 0;
+
+    const end = Math.max(st.destPos - 2, 0);
+    this.#updateHashtable(dest, st, end);
+    if (st.nextHashed < end) st.nextHashed = end;
+
+    return false;
+  }
+
+  #updateHashtable(dest: Uint8Array, st: QlzState, end: number): void {
+    while (st.nextHashed < end) {
+      if (st.nextHashed + 3 > dest.length) break;
+      const v =
+        (dest[st.nextHashed]! |
+          (dest[st.nextHashed + 1]! << 8) |
+          (dest[st.nextHashed + 2]! << 16)) >>>
+        0;
+      const hash = ((v >> 12) ^ v) & 0xfff;
+      this.#hashtable[hash] = st.nextHashed;
+      st.nextHashed++;
+    }
+  }
+}
+
+function parseQlzHeader(data: Uint8Array): {
+  headerLen: number;
+  decompressedSize: number;
+  flags: number;
+} {
+  if (data.length < 3) throw new QuickLZError("data too short");
+
+  const flags = data[0]!;
+  const level = (flags >> 2) & 0x03;
+  if (level !== 1) throw new QuickLZError("only level 1 is supported");
+
+  const long = (flags & 0x02) !== 0;
+  const headerLen = long ? 9 : 3;
+  if (data.length < headerLen) throw new QuickLZError("data too short for header");
+
+  // The header also carries the compressed size, which the reads below make
+  // redundant: each one is checked against the data itself.
+  const decompressedSize = long
+    ? (data[5]! | (data[6]! << 8) | (data[7]! << 16) | (data[8]! << 24)) >>> 0
+    : data[2]!;
+
+  if (decompressedSize > MAX_DECOMPRESSED_SIZE) {
+    throw new QuickLZError(`declared size ${decompressedSize} exceeds ${MAX_DECOMPRESSED_SIZE}`);
+  }
+
+  return { headerLen, decompressedSize, flags };
+}

package/src/client/types.ts

@@ -0,0 +1,268 @@
+import type {
+  ClientID,
+  ClientVersion,
+  CommandMiddleware,
+  Logger,
+  PokeEvent,
+  ReconnectOptions,
+  ServerEventMap,
+  SessionEventMap,
+  VoiceDataEvent,
+} from "@honeybbq/teamspeak";
+import type { Duplex } from "node:stream";
+import type { ClientTrace } from "./trace.js";
+
+// ---- Events ---------------------------------------------------------------
+
+/**
+ * The events `Client.on()` takes, and what each delivers.
+ *
+ * The typed events here are the first of the two layers a notification
+ * reaches; the second is `notification`, which carries every notification the
+ * server sends, the ones with an event here among them, after that event. So a
+ * typed event is only ever added, never removed, and adding one takes nothing
+ * away from the catch-all. May gain events in a minor release; code that
+ * handles every event generically should expect names it does not know.
+ */
+export interface EventMap extends ServerEventMap, SessionEventMap {
+  /** This client being poked. */
+  poked: PokeEvent;
+  /**
+   * Audio from another client. Only decoded with a listener or event
+   * middleware. Voice is dropped, counted and reported in a warning at most
+   * every ten seconds, while more than 256 deliveries are waiting: a listener
+   * that cannot keep up loses audio rather than memory.
+   */
+  voiceData: VoiceDataEvent;
+}
+
+/**
+ * Who `sendWhisper` sends to. The whisper framing the client writes carries
+ * client ids only, so there is no field for channels yet; one can be added
+ * without changing a call that names `clients`.
+ */
+export interface WhisperTargets {
+  /** The clients to whisper to: at least one and at most 32. */
+  readonly clients?: readonly ClientID[] | undefined;
+}
+
+/** What `sendVoice` can be told. Reserved: it has no fields yet. */
+export interface VoiceOptions {}
+
+/** The values of the table below, before freezing. */
+const eventNameValues = {
+  /** A text message to this client, its channel or the server. */
+  TextMessage: "textMessage",
+  /** A client coming into view, including every client already there on connecting. */
+  ClientEnter: "clientEnter",
+  /** A client going out of view. */
+  ClientLeave: "clientLeave",
+  /** A client changing channel. */
+  ClientMoved: "clientMoved",
+  /** This client being poked. */
+  Poked: "poked",
+  /** Audio from another client. Only decoded with a listener or event middleware. */
+  VoiceData: "voiceData",
+  /**
+   * Every notification the server sends, modelled or not, after any event it
+   * produces; one with a typed event arrives here as well, not only there.
+   */
+  Notification: "notification",
+  /** The handshake completing, on `connect()` and on every reconnection. */
+  Connected: "connected",
+  /** The connection ending, with its cause and whether a reconnection follows. */
+  Disconnected: "disconnected",
+  /** A kick from the server, which also ends the connection. */
+  Kicked: "kicked",
+} as const;
+/**
+ * The names of the events `Client.on()` takes, as constants. `on(EventName.TextMessage, ...)`
+ * and `on("textMessage", ...)` are the same call, and both give the listener
+ * the same payload type.
+ */
+export const EventName: typeof eventNameValues = /* @__PURE__ */ Object.freeze(eventNameValues);
+/**
+ * One of {@link EventName}, and so a key of {@link EventMap}. May gain members
+ * in a minor release: a `switch` over it needs a default case.
+ */
+export type EventName = (typeof EventName)[keyof typeof EventName];
+
+// Each direction fails to compile when `EventMap` and `EventName` drift: an
+// event without a name, and a name that is not an event.
+const eventNamesCoverEventMap: [Exclude<keyof EventMap, EventName>] extends [never] ? true : never =
+  true;
+const eventMapCoversEventNames: [Exclude<EventName, keyof EventMap>] extends [never]
+  ? true
+  : never = true;
+void eventNamesCoverEventMap;
+void eventMapCoversEventNames;
+
+/**
+ * The events that come from the server, and so pass through event middleware.
+ * May gain members in a minor release: a `switch` over an event's name needs
+ * a default case.
+ */
+export type ServerEventName =
+  | "textMessage"
+  | "clientEnter"
+  | "clientLeave"
+  | "clientMoved"
+  | "poked"
+  | "voiceData"
+  | "notification";
+
+/** A server event as event middleware sees it. */
+export type ServerEvent = {
+  [K in ServerEventName]: { readonly name: K; readonly payload: EventMap[K] };
+}[ServerEventName];
+
+// ---- Transport seam ---------------------------------------------------------
+
+/**
+ * The part of a UDP socket the client uses. A `node:dgram` socket is one; so
+ * is anything else with these methods, such as a tunnel or a test double.
+ *
+ * Should a later release use more of a socket, the new members will be
+ * optional here, so an implementation of this interface keeps compiling.
+ */
+export interface DatagramSocket {
+  /** Fix the peer, then call `callback`; failure is reported as an `error` event. */
+  connect(port: number, address: string, callback: () => void): void;
+  /** Send one datagram to the peer. */
+  send(data: Uint8Array, callback: (error: Error | null) => void): void;
+  /** Close the socket; it then emits `close`. */
+  close(): void;
+  /** Listen for each datagram received. */
+  on(event: "message", listener: (message: Uint8Array) => void): unknown;
+  /** Listen for a failure, which ends the connection. */
+  on(event: "error", listener: (error: Error) => void): unknown;
+  /** Listen for the socket closing. */
+  on(event: "close", listener: () => void): unknown;
+  /** Listen for the next failure only, while connecting. */
+  once(event: "error", listener: (error: Error) => void): unknown;
+  /** Stop listening for failures. */
+  off(event: "error", listener: (error: Error) => void): unknown;
+  /**
+   * The local end of the socket, for a trace to report. Optional: a socket that
+   * cannot say is reported with an empty local address.
+   */
+  address?(): { readonly address: string; readonly port: number };
+}
+
+/** Creates the UDP socket the client talks through, for the given address family. */
+export type SocketFactory = (family: 4 | 6) => DatagramSocket;
+
+/**
+ * Opens the connection a file transfer runs over, to `host:port`. A
+ * `node:net` socket is one, as is the socket a SOCKS or HTTP proxy library
+ * returns. It may still be connecting when returned: the transfer waits for
+ * it.
+ */
+export type FileTransferSocketFactory = (host: string, port: number) => Duplex;
+
+/** Wraps the delivery of server events; it may observe, alter or drop them. */
+export type EventMiddleware = (next: (event: ServerEvent) => void) => (event: ServerEvent) => void;
+
+// ---- Resolved address (from discovery) --------------------------------------
+
+/**
+ * An address a server's name resolved to. Only `addr` is needed to connect;
+ * the rest describes the answer.
+ */
+export interface ResolvedAddr {
+  /** The endpoint, as `host:port`. */
+  readonly addr: string;
+  /** How it was found, such as `SRV`, `TSDNS-SRV`, `TSDNS-Direct` or `Direct`. */
+  readonly source?: string | undefined;
+  /** When the answer stops being valid; unset for no stated lifetime. */
+  readonly expiry?: Date | undefined;
+}
+
+// ---- AddrResolver interface -------------------------------------------------
+
+/**
+ * Turns the address a client was given — a host, `host:port`, or a TeamSpeak
+ * name — into endpoints to connect to. The default follows SRV records and
+ * TSDNS, as the TeamSpeak application does.
+ */
+export interface AddrResolver {
+  /**
+   * The endpoints for `addr`, best first. An empty answer falls back to `addr`
+   * itself. `signal` aborts when the connection attempt is given up, or once
+   * resolution has taken 10 seconds, after which the client connects to
+   * `addr` as given; a resolver that ignores it is abandoned all the same.
+   */
+  resolve(
+    addr: string,
+    options?: { readonly signal?: AbortSignal | undefined },
+  ): Promise<readonly ResolvedAddr[]>;
+}
+
+// ---- ClientOptions ----------------------------------------------------------
+
+/** How a `Client` connects, logs and behaves; every field is optional. */
+export interface ClientOptions {
+  /** Where the client logs. Silent unless set: a library has no business writing to the console. */
+  readonly logger?: Logger | undefined;
+  /**
+   * Creates the UDP socket the client talks through, given the address family
+   * the server's address resolved to.
+   *
+   * Supplying one lets an application route traffic through a proxy or tunnel,
+   * or drive the client from something other than a real socket. It is the only
+   * seam into the transport: without it the SDK always creates its own.
+   */
+  readonly socketFactory?: SocketFactory | undefined;
+  /**
+   * Reconnect after a dropped connection.
+   *
+   * Off by default: a silent reconnect makes an outage look like an ordinary
+   * session. An explicit `disconnect()` never reconnects regardless.
+   */
+  readonly reconnect?: ReconnectOptions | undefined;
+  /**
+   * Hooks called at each milestone of every connection attempt, for timing,
+   * metrics and progress. The object is copied when the client is made, so
+   * changing it afterwards has no effect. See {@link ClientTrace} for the
+   * rules a hook follows.
+   */
+  readonly trace?: ClientTrace | undefined;
+  /**
+   * Creates the TCP socket a file transfer runs over.
+   *
+   * Separate from `socketFactory` because file transfer dials its own
+   * connection to a different port, on demand. Set both to route everything
+   * through a proxy.
+   */
+  readonly fileTransferSocketFactory?: FileTransferSocketFactory | undefined;
+  /**
+   * Look a dot-less address up as a server nickname at named.myteamspeak.com,
+   * as the TeamSpeak application does. Off by default, since it sends the name
+   * to a third party; without it a dot-less name is resolved like any host.
+   * Ignored with a custom `resolver`.
+   */
+  readonly nicknameLookup?: boolean | undefined;
+  /** Replaces the SRV and TSDNS resolution `connect()` performs. */
+  readonly resolver?: AddrResolver | undefined;
+  /**
+   * Wraps every typed command, outermost first; see `CommandMiddleware`. Raw
+   * lines sent with `exec` and `execNoWait` do not pass through it. Fixed for
+   * the client's life.
+   */
+  readonly commandMiddleware?: readonly CommandMiddleware[] | undefined;
+  /** Wraps the delivery of every server event, outermost first. Fixed for the client's life. */
+  readonly eventMiddleware?: readonly EventMiddleware[] | undefined;
+  /**
+   * The platform, version and signature `clientinit` sends. Default: a recent
+   * Windows build. Pick another from `@honeybbq/teamspeak/versions`; a version
+   * the server does not know, or a build below its minimum, is refused when
+   * connecting. A bad value throws when the client is made.
+   */
+  readonly version?: ClientVersion | undefined;
+  /** Server password sent during the initial `clientinit` handshake. */
+  readonly serverPassword?: string | undefined;
+  /** Default channel name to join during the initial `clientinit` handshake. */
+  readonly defaultChannel?: string | undefined;
+  /** Password for `defaultChannel`, sent during the initial `clientinit` handshake. */
+  readonly defaultChannelPassword?: string | undefined;
+}