@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/src/core/events.ts

@@ -0,0 +1,219 @@
+/**
+ * The events a TeamSpeak client receives from the server. Every kind of client
+ * shares these types.
+ */
+
+import type { ChannelID, ClientID, ServerGroupID, UID } from "./command/ids.js";
+import type { ClientEntry } from "./api/clients.js";
+import type { NotificationName } from "./notification-name.js";
+
+/** A text message, sent privately, to a channel, or to the whole server. */
+export interface TextMessageEvent {
+  /** The sender's nickname. */
+  readonly invokerName: string;
+  /** The sender's unique identifier. */
+  readonly invokerUID: UID;
+  /** The message, unescaped. */
+  readonly message: string;
+  /**
+   * The sender's server groups. A text message does not carry them; they are
+   * those of the sender as the client knows it, so they are `undefined` for a
+   * sender the client has not seen.
+   */
+  readonly invokerGroups: readonly ServerGroupID[] | undefined;
+  /**
+   * Private, channel or server; compare it with `TextMessageTarget`. A plain
+   * number, since a server may send a mode that table does not name.
+   */
+  readonly targetMode: number;
+  /**
+   * The client a private message was sent to. Channel and server messages
+   * carry no target, so it is 0 for them.
+   */
+  readonly targetID: ClientID;
+  /** The sender. */
+  readonly invokerID: ClientID;
+}
+
+/** A client changing channel, of its own accord or moved by someone. */
+export interface ClientMovedEvent {
+  /** Who moved the client; the client itself for a move of its own. */
+  readonly invokerName: string;
+  /** The mover's unique identifier. */
+  readonly invokerUID: UID;
+  /** The channel the client is now in. */
+  readonly targetChannelID: ChannelID;
+  /** Why the client moved; compare it with `Reason`. */
+  readonly reason: number;
+  /** The message that came with the move, such as a channel kick's reason; "" when none. */
+  readonly reasonMessage: string;
+  /** The client that moved. */
+  readonly clientID: ClientID;
+  /** The mover. */
+  readonly invokerID: ClientID;
+}
+
+/**
+ * A client going out of view: leaving the server, kicked or banned from it, or
+ * in a channel that stopped being subscribed.
+ */
+export interface ClientLeaveEvent {
+  /** The reason given for a kick or a ban, or the client's own parting message. */
+  readonly reasonMessage: string;
+  /** Why the client left; compare it with `Reason`. */
+  readonly reason: number;
+  /** The client that left. */
+  readonly clientID: ClientID;
+  /** Who kicked or banned the client; empty otherwise. */
+  readonly invokerName: string;
+  /** The kicker's unique identifier; empty unless kicked or banned. */
+  readonly invokerUID: UID;
+  /** The kicker; 0 unless kicked or banned. */
+  readonly invokerID: ClientID;
+}
+
+/** This client being kicked from its channel or the server. */
+export interface KickedEvent {
+  /** The reason the invoker gave. */
+  readonly reasonMessage: string;
+  /** `Reason.KickChannel`, `Reason.KickServer` or `Reason.KickServerBan`. */
+  readonly reason: number;
+  /** Who kicked this client. */
+  readonly invokerName: string;
+  /** The kicker's unique identifier. */
+  readonly invokerUID: UID;
+  /** The kicker. */
+  readonly invokerID: ClientID;
+}
+
+/**
+ * A client coming into view: the same record `listClients` returns, so one
+ * type describes a client however it was learned of; its own id is `id`, as
+ * in every record. The fields only `clientlist -times` reports are undefined
+ * here.
+ */
+export type ClientEnterEvent = ClientEntry;
+
+/** This client being poked. */
+export interface PokeEvent {
+  /** Who poked. */
+  readonly invokerName: string;
+  /** The poker's unique identifier. */
+  readonly invokerUID: UID;
+  /** The poker. */
+  readonly invokerID: ClientID;
+  /** The poke's message, unescaped. */
+  readonly message: string;
+}
+
+/** Audio from another client, in the channel or whispered. */
+export interface VoiceDataEvent {
+  /** Who is speaking. */
+  readonly clientID: ClientID;
+  /**
+   * How the audio is encoded; compare it with `Codec`. A plain number, since a
+   * server may relay a codec that table does not name.
+   */
+  readonly codec: number;
+  /** One encoded frame, copied: it stays valid after the listener returns. */
+  readonly data: Uint8Array;
+}
+
+/**
+ * A notification from the server, as it arrived: the escape hatch for one the
+ * SDK does not model, and for the ones it does. Match its `name` against
+ * `NotificationName`.
+ *
+ * This is the catch-all layer: the client delivers every notification as one
+ * of these, including the ones that also have a typed event of their own,
+ * which it delivers first. So a notification is never taken out of the
+ * catch-all by being given a typed event.
+ */
+export interface NotificationEvent {
+  /** The notification's name, such as `notifyserveredited`; `NotificationName` lists the known ones. */
+  readonly name: NotificationName | (string & {});
+  /** Its parameters, unescaped. */
+  readonly params: Readonly<Record<string, string>>;
+}
+
+/** What `connected` delivers. */
+export interface ConnectedEvent {
+  /**
+   * Whether the reconnect loop made this connection, rather than a call to
+   * `connect()`.
+   */
+  readonly reconnected: boolean;
+}
+
+/** What `disconnected` delivers. */
+export interface DisconnectedEvent {
+  /**
+   * `undefined` after `disconnect()`, and the cause otherwise, such as a failed
+   * handshake, the connection timing out, or the client being removed.
+   */
+  readonly error: Error | undefined;
+  /**
+   * Whether the reconnect loop will try again, as of this event. False after
+   * `disconnect()`, without `reconnect` options, when `shouldRetry` refuses
+   * this cause, and once `backoff.maxAttempts` is spent. A `disconnect()` or a
+   * manual `connect()` while it waits can still end the loop.
+   */
+  readonly willReconnect: boolean;
+}
+
+/**
+ * The events a server sends, by name, that every kind of client delivers.
+ *
+ * These are the modelled events; `notification` carries every notification
+ * besides, after the event it produced. Gaining a key is an additive change,
+ * so a minor release may add one; none is ever removed in a minor.
+ */
+export interface ServerEventMap {
+  /** A text message to this client, its channel or the server. */
+  textMessage: TextMessageEvent;
+  /** A client coming into view, including every client already there on connecting. */
+  clientEnter: ClientEnterEvent;
+  /** A client going out of view. */
+  clientLeave: ClientLeaveEvent;
+  /** A client changing channel. */
+  clientMoved: ClientMovedEvent;
+  /**
+   * Every notification the server sends, modelled or not, after any event it
+   * produces. A notification with an event of its own still arrives here: this
+   * is the catch-all layer, so the typed event is delivered alongside it, never
+   * instead of it.
+   */
+  notification: NotificationEvent;
+}
+
+/**
+ * The events about a connection's own life, by name, that every kind of client
+ * delivers.
+ *
+ * `connected` and `disconnected` come from the client's own lifecycle rather
+ * than from a notification, so nothing on the catch-all carries them. `kicked`
+ * is not of that kind: it is derived from the `notifyclientleftview` or
+ * `notifyclientmoved` that reports this client kicked, so that notification
+ * reaches the catch-all as well. What the three share is the delivery, not the
+ * origin: they go out on the client's own path, which event middleware does
+ * not see, because they are about the connection rather than about the
+ * server's event stream. `kicked` is the convenience event for the one case it
+ * names, this client kicked from the server or from its channel. Gaining a key
+ * is additive, and none is removed in a minor release.
+ */
+export interface SessionEventMap {
+  /** The handshake completing, on `connect()` and on every reconnection. */
+  connected: ConnectedEvent;
+  /**
+   * The connection ending, after `disconnect()`, a drop, or a failed attempt;
+   * the event says why and whether the reconnect loop will try again.
+   */
+  disconnected: DisconnectedEvent;
+  /**
+   * This client being kicked from its channel or the server: derived from the
+   * `notifyclientmoved` or `notifyclientleftview` that reports it, so that
+   * notification also arrives on the catch-all. A kick from the server ends
+   * the connection as well, which `disconnected` reports.
+   */
+  kicked: KickedEvent;
+}

package/src/core/helpers.ts

@@ -0,0 +1,161 @@
+import { isCommandName } from "./command/parser.js";
+
+const MAX_UINT64 = (1n << 64n) - 1n;
+const MAX_UINT64_DIGITS = String(MAX_UINT64).length;
+
+/**
+ * Read an unsigned 64-bit decimal: digits only, 0 to 2^64-1. Anything else — a
+ * sign, a hex or binary prefix, a fraction, a value that does not fit — reads as
+ * 0, which names nothing, instead of throwing: the text comes off the network.
+ * `BigInt()` alone takes all of those, in any width.
+ */
+export function parseUint64(s: string): bigint {
+  if (!/^[0-9]+$/.test(s)) return 0n;
+  // Leading zeros are dropped first so that no long run of digits reaches BigInt.
+  const digits = s.replace(/^0+(?=[0-9])/, "");
+  if (digits.length > MAX_UINT64_DIGITS) return 0n;
+  const value = BigInt(digits);
+  return value > MAX_UINT64 ? 0n : value;
+}
+
+export function parseUint16(s: string): number {
+  const v = parseInt(s, 10);
+  if (isNaN(v) || v < 0 || v > 65535) return 0;
+  return v;
+}
+
+export function parseInt10(s: string): number {
+  const v = parseInt(s, 10);
+  return isNaN(v) ? 0 : v;
+}
+
+/** The bytes the rows of a line may hold together, see {@link rowLimits}. */
+const MIN_ROW_BUDGET = 64 * 1024;
+const ROW_GROWTH = 4;
+const MAX_ROW_AMPLIFICATION = 64;
+
+/**
+ * Expand a pipe-separated multi-row TS3 command line into individual rows.
+ *
+ * A named line (`notifyclientleftview a=1|a=2`) keeps its name on every row; a
+ * nameless response (`cldbid=1|cldbid=2`) stays nameless. Whether the first
+ * token is a name is decided by the parser's own rule — deciding it here by
+ * position is how a nameless batch with no space in it went through unsplit and
+ * a one-field-per-row response came back as a single row. Tokens are split on
+ * the space and on nothing else, as the parser splits them.
+ *
+ * TeamSpeak compresses a batch by leaving out of a row the fields whose value
+ * is unchanged from the previous row: in a notifycliententerview batch, ctid is
+ * often present only on the first row. A row is therefore the fields of the
+ * previous row, as that row came out, that it does not name itself, followed by
+ * its own. Tokens stay escaped so the command parser can still perform the
+ * single unescape pass later.
+ *
+ * A row that names a field of its own each time makes every row carry all the
+ * fields before it, so the rows would grow with the square of the line. The
+ * rows of a real server's line are a little larger than their own parts and
+ * never come near the limits that stop this: once the rows together would hold
+ * more than the larger of four times the line and 64 KiB, the rows after that
+ * carry only their own tokens. A name repeated on every row can grow them on its
+ * own, so at twice that the rows stop, and the rest of the line is dropped.
+ * Neither limit passes 64 times the line. Lengths are counted in characters.
+ */
+export function splitCommandRows(line: string): string[] {
+  const spaceIdx = line.indexOf(" ");
+  const head = spaceIdx < 0 ? line : line.slice(0, spaceIdx);
+  const name = isCommandName(head) ? head : "";
+  const rest = name === "" ? line : spaceIdx < 0 ? "" : line.slice(spaceIdx + 1);
+
+  if (!rest.includes("|")) return [line];
+
+  const prefix = name === "" ? "" : `${name} `;
+  const { inherit: inheritLimit, drop: dropLimit } = rowLimits(line.length);
+  const rows: string[] = [];
+  let used = 0;
+  // The fields of the row before, each once, with the token that row gave it;
+  // empty once rows stop inheriting.
+  let previous: string[] = [];
+  let inheriting = true;
+
+  for (const part of rest.split("|")) {
+    if (part === "") continue;
+    const tokens = part.split(" ").filter(Boolean);
+
+    let row = prefix + tokens.join(" ");
+    if (inheriting) {
+      const resolved = resolveRow(previous, tokens);
+      const inherited = prefix + resolved.join(" ");
+      if (used + inherited.length <= inheritLimit) {
+        row = inherited;
+        previous = lastPerField(resolved);
+      } else {
+        inheriting = false;
+        previous = [];
+      }
+    }
+    if (used + row.length > dropLimit) break;
+    used += row.length;
+    rows.push(row);
+  }
+  return rows.length === 0 ? [line] : rows;
+}
+
+/**
+ * The tokens of a row: the fields of the previous row that the row does not
+ * name, then the row's own tokens.
+ */
+function resolveRow(previous: string[], tokens: string[]): string[] {
+  const named = new Set<string>();
+  for (const token of tokens) named.add(fieldName(token));
+  return [...previous.filter((token) => !named.has(fieldName(token))), ...tokens];
+}
+
+/** The last token of each field, in the order the fields first appear. */
+function lastPerField(tokens: string[]): string[] {
+  const at = new Map<string, number>();
+  const kept: string[] = [];
+  for (const token of tokens) {
+    const key = fieldName(token);
+    const i = at.get(key);
+    if (i === undefined) {
+      at.set(key, kept.length);
+      kept.push(token);
+    } else {
+      kept[i] = token;
+    }
+  }
+  return kept;
+}
+
+/**
+ * How many characters the rows of a line of `n` may hold together before they
+ * stop inheriting fields, and before they stop.
+ */
+function rowLimits(n: number): { inherit: number; drop: number } {
+  const inherit = Math.max(ROW_GROWTH * n, MIN_ROW_BUDGET);
+  const drop = Math.min(2 * inherit, MAX_ROW_AMPLIFICATION * n);
+  return { inherit: Math.min(inherit, drop), drop };
+}
+
+function fieldName(token: string): string {
+  const equalIndex = token.indexOf("=");
+  return equalIndex > 0 ? token.slice(0, equalIndex) : token;
+}
+
+/**
+ * Sleep, or wake early once `signal` aborts. Resolves either way, never
+ * rejects. The timer keeps the process alive while it runs.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0 || signal?.aborted) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}

package/src/core/index.ts

@@ -0,0 +1,126 @@
+/**
+ * What every TeamSpeak connection shares: the command language, ids, errors,
+ * and the typed commands that run on any connection able to execute a command.
+ *
+ * The voice client is in `@honeybbq/teamspeak/client`.
+ *
+ * @module @honeybbq/teamspeak
+ */
+
+// Escaping, for a raw line sent with a client's `exec`.
+export { escape, unescape } from "./command/command.js";
+
+// Requests and the connections that execute them.
+export type {
+  CommandExecutor,
+  CommandOptions,
+  CommandRequest,
+  ParamValue,
+} from "./command/request.js";
+
+// Branded ids: a ChannelID cannot be passed where a ClientID is meant.
+export {
+  asBanID,
+  asChannelID,
+  asClientFileTransferID,
+  asMessageID,
+  asServerFileTransferID,
+  asServerID,
+  asChannelGroupID,
+  asClientDBID,
+  asClientID,
+  asIconID,
+  asPermissionID,
+  asServerGroupID,
+  asUID,
+  asChannelUID,
+} from "./command/ids.js";
+export type {
+  BanID,
+  ClientFileTransferID,
+  MessageID,
+  ServerFileTransferID,
+  ServerID,
+  ChannelGroupID,
+  ChannelID,
+  ClientDBID,
+  ClientID,
+  IconID,
+  PermissionID,
+  ServerGroupID,
+  UID,
+  ChannelUID,
+} from "./command/ids.js";
+
+export {
+  TeamspeakError,
+  ServerError,
+  CommandTimeoutError,
+  NotConnectedError,
+  NoDataError,
+  AlreadyConnectedError,
+} from "./errors.js";
+export { ErrorCode } from "./errorcode.js";
+export { Reason } from "./reason.js";
+
+// Small-integer enumerations, as named values and types.
+export {
+  ClientType,
+  Codec,
+  GroupNameMode,
+  GroupType,
+  HostMessageMode,
+  LogLevel,
+  PermissionTarget,
+  TextMessageTarget,
+  PrivilegeKeyType,
+} from "./enums.js";
+
+// Permissions, by id or by name.
+export { permissionByID, permissionByName } from "./permission.js";
+export { PermissionName } from "./permission-name.js";
+export { CommandName } from "./command-name.js";
+export { NotificationName } from "./notification-name.js";
+export { PropertyName } from "./property-name.js";
+export type { Permission } from "./permission.js";
+
+export { noopLogger, consoleLogger, ClientStatus } from "./types.js";
+export type {
+  ClientVersion,
+  Listener,
+  ServerFamily,
+  Unsubscribe,
+  CommandMiddleware,
+  FileDownloadInfo,
+  FileUploadInfo,
+  Logger,
+} from "./types.js";
+
+// The events a server sends, shared by every client.
+export type {
+  TextMessageEvent,
+  ClientMovedEvent,
+  ClientLeaveEvent,
+  KickedEvent,
+  ClientEnterEvent,
+  PokeEvent,
+  VoiceDataEvent,
+  NotificationEvent,
+  ConnectedEvent,
+  DisconnectedEvent,
+  ServerEventMap,
+  SessionEventMap,
+} from "./events.js";
+
+// Reconnection policy, whose retry decision each client supplies.
+export { backoffDelay, defaultBackoffPolicy } from "./reconnect.js";
+export type { BackoffPolicy, ReconnectOptions } from "./reconnect.js";
+
+// Typed commands, one module per area of the protocol.
+export * from "./api/channels.js";
+export * from "./api/clients.js";
+export * from "./api/server.js";
+export * from "./api/groups.js";
+export * from "./api/moderation.js";
+export * from "./api/files.js";
+export type { Channel, PagingOptions, PermissionEntry } from "./api/command.js";

package/src/core/internal.ts

@@ -0,0 +1,23 @@
+/**
+ * Protocol plumbing for the modules next to the core, `client` and `query`.
+ *
+ * Not public API and not exported by the package: they import it by relative
+ * path, so it can change in any release.
+ *
+ * @packageDocumentation
+ */
+
+export { isCommandName, parseCommand } from "./command/parser.js";
+export { encodeRequest } from "./command/request.js";
+export { buildCommandChain } from "./middleware.js";
+export { buildCommand, buildCommandOrdered } from "./command/command.js";
+export type { Command } from "./command/command.js";
+export { parseClient } from "./api/parse.js";
+export { handleNotification } from "./notifications.js";
+export type { NotificationResult } from "./notifications.js";
+export { parseIconID } from "./command/ids.js";
+export { responseSpec } from "./command/responses.js";
+export type { ResponseSpec } from "./command/responses.js";
+export { parseErrorCode, parseServerError } from "./errors.js";
+export { splitCommandRows, parseUint64, parseUint16, parseInt10, sleep } from "./helpers.js";
+export { jitteredDelay, resolveBackoffPolicy } from "./reconnect.js";

package/src/core/middleware.ts

@@ -0,0 +1,24 @@
+/**
+ * Command middleware, and the chain it makes.
+ *
+ * Both clients wrap the typed command layer the same way, so the composing
+ * lives here; each supplies its own base handler.
+ */
+
+import type { CommandExecutor } from "./command/request.js";
+import type { CommandMiddleware } from "./types.js";
+
+/**
+ * Compose a chain of middlewares around a base handler.
+ * Rightmost middleware wraps the base first.
+ */
+export function buildCommandChain(
+  middlewares: readonly CommandMiddleware[],
+  base: CommandExecutor["send"],
+): CommandExecutor["send"] {
+  let handler = base;
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    handler = middlewares[i]!(handler);
+  }
+  return handler;
+}