@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.11

package/src/core/command/parser.ts

@@ -0,0 +1,68 @@
+import { unescape } from "./command.js";
+import type { Command } from "./command.js";
+
+/**
+ * Whether a token is a command name.
+ *
+ * A command name is a run of ASCII alphanumerics — the rule tsproto-packets
+ * uses (CommandParser::new). Everything that splits or parses a line asks this
+ * one function, so the parser and the row splitter cannot disagree about where
+ * a command's data begins.
+ */
+export function isCommandName(token: string): boolean {
+  return /^[A-Za-z0-9]+$/.test(token);
+}
+
+/**
+ * Parse one command line, or one row of it. Returns null for an empty line.
+ * A line whose first token is not a command name is a data row, with `name`
+ * `""`.
+ */
+export function parseCommand(s: string): Command | null {
+  if (s === "") return null;
+
+  // Skip leading non-printable bytes (< 0x20 or > 0x7E)
+  let startIndex = 0;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code >= 32 && code <= 126) {
+      startIndex = i;
+      break;
+    }
+  }
+  if (startIndex > 0) {
+    s = s.slice(startIndex);
+  }
+
+  const parts = s.split(" ");
+  if (parts.length === 0) return null;
+
+  // A command name is a run of alphanumerics followed by a space — the rule
+  // tsproto-packets uses (CommandParser::new). Anything else means the line is
+  // not a command at all: response rows carry no name ("clid=6 cid=2 ..."),
+  // and negative feedback is "-1 id=2 ...", naming the *rejected* command id
+  // rather than a command of its own. Returning those as a nameless row keeps
+  // the data intact instead of folding the first field into a name, which is
+  // how a clientlist row used to arrive as name="clid=6" and lose its clid.
+  const first = parts[0] ?? "";
+  if (first === "") return null;
+
+  // No prototype: a key is whatever the line says, and one named __proto__
+  // must be stored, not swallowed by Object.prototype's setter.
+  const params: Record<string, string> = Object.create(null) as Record<string, string>;
+  const name = isCommandName(first) ? first : "";
+  const start = name === "" ? 0 : 1;
+
+  for (let i = start; i < parts.length; i++) {
+    const p = parts[i];
+    if (p === undefined || p === "") continue;
+    const eqIdx = p.indexOf("=");
+    if (eqIdx >= 0) {
+      params[unescape(p.slice(0, eqIdx))] = unescape(p.slice(eqIdx + 1));
+    } else {
+      params[unescape(p)] = "";
+    }
+  }
+
+  return { name, params };
+}

package/src/core/command/request.ts

@@ -0,0 +1,119 @@
+/**
+ * A command as the typed layer describes it, before a transport encodes it.
+ *
+ * The typed commands run on any connection that can execute a command — the
+ * voice client today, ServerQuery later — and the two disagree about how some
+ * values go on the wire. A channel password is the case that matters: the
+ * voice protocol expects `base64(sha1(password))`, while ServerQuery takes the
+ * password itself and hashes it server-side. So a request says *which*
+ * parameters are passwords and leaves their encoding to the transport.
+ */
+
+import type { CommandName } from "../command-name.js";
+import { buildCommandOrdered } from "./command.js";
+
+/** A parameter value as a caller may supply it. */
+export type ParamValue = string | number | bigint | boolean | undefined;
+
+/** A command and its parameters, in the order they are sent. */
+export interface CommandRequest {
+  /** The command's name, such as `clientlist`; {@link CommandName} lists the known ones. */
+  readonly command: CommandName | (string & {});
+  /**
+   * Its parameters, as wire name and value pairs, in the order they are sent;
+   * an undefined value is omitted.
+   */
+  readonly params?: ReadonlyArray<readonly [string, ParamValue]> | undefined;
+  /**
+   * Further rows, for a command that takes a list: each is a group of
+   * parameters sent after a `|`, as `ftdeletefile cid=1 cpw= name=/a|name=/b`
+   * sends two names. The first row's parameters follow `params`.
+   */
+  readonly rows?: ReadonlyArray<ReadonlyArray<readonly [string, ParamValue]>> | undefined;
+  /** Names of the parameters that carry a channel password. */
+  readonly passwords?: readonly string[] | undefined;
+}
+
+/** How long a command may take, and how to abandon it. */
+export interface CommandOptions {
+  /** Abandons the command; it then rejects with the signal's reason. */
+  readonly signal?: AbortSignal | undefined;
+  /** Milliseconds to wait for the answer before failing with a CommandTimeoutError. */
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * A connection the typed commands can run on.
+ *
+ * It is deliberately this narrow. A caller implements it to run the typed
+ * commands over a transport of their own, and `CommandMiddleware` wraps its
+ * `send`, so a method added here would break every implementation and every
+ * middleware along with it: this interface gains no methods in a minor
+ * release. A new capability arrives as an interface, a function or an option
+ * of its own instead, and an implementer or a middleware author may rely on
+ * that.
+ */
+export interface CommandExecutor {
+  /** Send a command and return the rows that answer it. */
+  // oxlint-disable-next-line typescript/array-type -- the public API report spells this `[]`; respelling it changes the report
+  send(request: CommandRequest, options?: CommandOptions): Promise<Record<string, string>[]>;
+}
+
+/**
+ * Turn a value into its wire form.
+ *
+ * Returns undefined for values that should be omitted entirely — an unset
+ * optional field — because sending `foo=` is not the same as not sending it:
+ * for `channel_password` the first clears the password and the second leaves it
+ * alone. Callers distinguish "unset" from "empty string" by passing undefined
+ * versus "".
+ */
+function encodeValue(value: ParamValue): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "boolean") return value ? "1" : "0";
+  return String(value);
+}
+
+/**
+ * Render a request as a command line.
+ *
+ * `encodePassword` is the transport's rule for password parameters. An empty
+ * password is sent as is: it means "no password", in every encoding.
+ */
+export function encodeRequest(
+  request: CommandRequest,
+  encodePassword: (password: string) => string,
+): string {
+  const passwords = request.passwords ?? [];
+  const encode = (params: ReadonlyArray<readonly [string, ParamValue]>) =>
+    encodeParams(params, passwords, encodePassword);
+  const [first = [], ...rest] = request.rows ?? [];
+  const line = buildCommandOrdered(request.command, [
+    ...encode(request.params ?? []),
+    ...encode(first),
+  ]);
+  // A row is the parameters alone, with no command name before them.
+  return [line, ...rest.map((row) => buildCommandOrdered("", encode(row)).slice(1))].join("|");
+}
+
+function encodeParams(
+  params: ReadonlyArray<readonly [string, ParamValue]>,
+  passwords: readonly string[],
+  encodePassword: (password: string) => string,
+): Array<readonly [string, string]> {
+  const out: Array<readonly [string, string]> = [];
+  for (const [key, value] of params) {
+    // Flags (`-uid`) are switches: present when true, absent otherwise.
+    if (key.startsWith("-")) {
+      if (value === true) out.push([key, ""]);
+      continue;
+    }
+    if (passwords.includes(key) && typeof value === "string" && value !== "") {
+      out.push([key, encodePassword(value)]);
+      continue;
+    }
+    const encoded = encodeValue(value);
+    if (encoded !== undefined) out.push([key, encoded]);
+  }
+  return out;
+}

package/src/core/command/responses.ts

@@ -0,0 +1,152 @@
+/**
+ * Where each command's answer actually arrives.
+ *
+ * ServerQuery answers a query with nameless rows followed by `error`. The voice
+ * protocol often does not: it answers `servergrouplist` with a named
+ * `notifyservergrouplist` command, `clientgetuidfromclid` with
+ * `notifyclientuidfromclid`, and so on. A client that only collects nameless
+ * rows reports an empty success for every one of those — which this SDK did,
+ * and documented as a property of the protocol.
+ *
+ * Notifications carry no return_code, so nothing on the wire ties one to the
+ * command that caused it. The pairing is a property of the command, and this
+ * table is where it lives. It was measured command by command
+ * against TS3 3.13.8 and TS6 6.0.0-beta13.1, which answer identically — see
+ * scripts/probe-response-shapes.mts to re-run that measurement.
+ *
+ * Commands not listed answer with nameless rows, or with nothing.
+ */
+
+/** How the voice protocol delivers one command's data. */
+export interface ResponseSpec {
+  /**
+   * Notifications carrying the data, sent before the command's `error`.
+   *
+   * Rows of these are attributed to the command whose `error` follows them.
+   * The same notification can also arrive unprompted — `notifyservergrouplist`
+   * after someone else edits a group — so they are still dispatched as events.
+   */
+  readonly notifications?: readonly string[];
+  /**
+   * Keep only rows whose `invokerid` is the client itself.
+   *
+   * `notifychannelcreated` is broadcast for every channel anyone creates; the
+   * one answering our `channelcreate` is the one we invoked.
+   */
+  readonly ownRowsOnly?: boolean;
+  /**
+   * The request parameter the answer echoes back, to tell the row that answers
+   * from the same notification sent for someone else.
+   *
+   * `notifyclientupdated` goes out whenever any client changes, and
+   * `notifychanneledited` whenever any channel does, so the row answering
+   * `clientgetvariables clid=7` is the one with `clid=7`. A row that names
+   * another value is no answer; one that does not carry the key is taken, as is
+   * every row when the request did not carry it.
+   */
+  readonly echoKey?: string;
+  /**
+   * Notifications that answer a command wherever they fall against its
+   * `error`, matched on a request field. A row that arrived before the `error`
+   * counts; if none has, the command waits for one, until its timeout or
+   * signal gives up.
+   *
+   * File transfer negotiation reports its key once the command has already
+   * succeeded, echoing the `clientftfid` the request carried; that echo is the
+   * only link between the two.
+   */
+  readonly correlated?: {
+    readonly notifications: readonly string[];
+    /** Request parameter the answer echoes back. */
+    readonly key: string;
+    /**
+     * A notification that reports failure rather than data. Its `status` is an
+     * ordinary server error id: an `ftinitupload` refused for permissions
+     * answers `error id=0` and then this with `status=2568`.
+     */
+    readonly failure?: string;
+  };
+}
+
+const inline = (...notifications: string[]): ResponseSpec => ({ notifications });
+
+/** An inline answer that is also sent unprompted, for any `key` the request names. */
+const echoing = (notification: string, key: string): ResponseSpec => ({
+  notifications: [notification],
+  echoKey: key,
+});
+
+const fileTransfer = (answer: string): ResponseSpec => ({
+  correlated: {
+    notifications: [answer, "notifystatusfiletransfer"],
+    key: "clientftfid",
+    failure: "notifystatusfiletransfer",
+  },
+});
+
+/** The table behind {@link responseSpec}, by command name; exported for the tests that check it against the name tables. */
+export const RESPONSES: Readonly<Record<string, ResponseSpec>> = {
+  apikeyadd: inline("notifyapikeyadd"),
+  apikeylist: inline("notifyapikeylist"),
+  banlist: inline("notifybanlist"),
+  channelclientpermlist: inline("notifychannelclientpermlist"),
+  channelcreate: { notifications: ["notifychannelcreated"], ownRowsOnly: true },
+  channelgetdescription: echoing("notifychanneledited", "cid"),
+  channelgroupadd: inline("notifychannelgrouplist"),
+  channelgroupclientlist: inline("notifychannelgroupclientlist"),
+  channelgroupcopy: inline("notifychannelgrouplist"),
+  channelgrouplist: inline("notifychannelgrouplist"),
+  channelgrouppermlist: inline("notifychannelgrouppermlist"),
+  channelpermlist: inline("notifychannelpermlist"),
+  clientdbfind: inline("notifyclientdbfind"),
+  clientdblist: inline("notifyclientdblist"),
+  clientgetdbidfromuid: inline("notifyclientdbidfromuid"),
+  clientgetids: inline("notifyclientids"),
+  clientgetnamefromdbid: inline("notifyclientnamefromdbid"),
+  clientgetnamefromuid: inline("notifyclientnamefromuid"),
+  clientgetuidfromclid: inline("notifyclientuidfromclid"),
+  clientgetvariables: echoing("notifyclientupdated", "clid"),
+  clientsetserverquerylogin: inline("notifyclientserverqueryloginpassword"),
+  clientpermlist: inline("notifyclientpermlist"),
+  complainlist: inline("notifycomplainlist"),
+  // Matched on the echoed `clid`, wherever the row falls against the `error`:
+  // TeamSpeak 6 sent `error id=0` ahead of the `notifyconnectioninfo` row in
+  // about 3% of the commands (6 of 240) when four were in flight at once, never
+  // with one at a time (over 800 sequential commands, both servers); TeamSpeak
+  // 3 never did. Rows for the same client also arrive unprompted, when the
+  // target answers the server's `notifyconnectioninforequest`, so a row's
+  // position says nothing about which command it answers; the echo does.
+  getconnectioninfo: {
+    correlated: { notifications: ["notifyconnectioninfo"], key: "clid" },
+  },
+  ftgetfileinfo: inline("notifyfileinfo"),
+  ftgetfilelist: inline("notifyfilelist"),
+  ftinitdownload: fileTransfer("notifystartdownload"),
+  ftinitupload: fileTransfer("notifystartupload"),
+  ftlist: inline("notifyfiletransferlist"),
+  logview: inline("notifyserverlog"),
+  messageget: inline("notifymessage"),
+  messagelist: inline("notifymessagelist"),
+  permfind: inline("notifypermfind"),
+  permget: inline("notifypermget"),
+  permissionlist: inline("notifypermissionlist"),
+  permoverview: inline("notifypermoverview"),
+  privilegekeyadd: inline("notifytokenadd"),
+  privilegekeylist: inline("notifytokenlist"),
+  servergetvariables: inline("notifyserverupdated"),
+  servergroupadd: inline("notifyservergrouplist"),
+  servergroupclientlist: inline("notifyservergroupclientlist"),
+  servergroupcopy: inline("notifyservergrouplist"),
+  servergrouplist: inline("notifyservergrouplist"),
+  servergrouppermlist: inline("notifyservergrouppermlist"),
+  servergroupsbyclientid: inline("notifyservergroupsbyclientid"),
+  serverrequestconnectioninfo: inline("notifyserverconnectioninfo"),
+  servertemppasswordlist: inline("notifyservertemppasswordlist"),
+  tokenadd: inline("notifytokenadd"),
+  tokenlist: inline("notifytokenlist"),
+};
+
+/** The response shape of a command, or undefined for plain rows. */
+export function responseSpec(command: string): ResponseSpec | undefined {
+  return Object.hasOwn(RESPONSES, command) ? RESPONSES[command] : undefined;
+}