@honeybbq/teamspeak 1.0.0-beta.19 → 1.0.0-beta.21

package/src/client/api/avatars.ts

@@ -23,6 +23,7 @@ import {
 import type { IconID, UID } from "@honeybbq/teamspeak";
 import type { Client } from "../client.js";
 import type { FileTransferOptions } from "../transfer.js";
+import { verifyStored, withDialCleanup } from "./upload-checks.js";
 
 /** Options for the avatar and icon transfers. */
 export type AvatarTransferOptions = Pick<FileTransferOptions, "signal" | "trace">;
@@ -84,7 +85,14 @@ export async function uploadAvatar(
     overwrite: true,
     ...(options.signal ? { signal: options.signal } : {}),
   });
-  await client.uploadFileData(client.host, info, Readable.from([data]), options);
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    client.uploadFileData(client.host, info, Readable.from([data]), options),
+  );
+  // Stored under a name the server derives from the uploader's uid, not the
+  // one asked for (measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0).
+  await verifyStored(client, CHANNEL_ZERO, `/${avatarFileName(client.uid)}`, BigInt(data.length), {
+    signal: options.signal,
+  });
   await updateClient(client, { avatar: md5 });
   return md5;
 }
@@ -150,7 +158,12 @@ export async function uploadIcon(
     overwrite: true,
     ...(options.signal ? { signal: options.signal } : {}),
   });
-  await client.uploadFileData(client.host, info, Readable.from([data]), options);
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    client.uploadFileData(client.host, info, Readable.from([data]), options),
+  );
+  await verifyStored(client, CHANNEL_ZERO, iconFileName(id), BigInt(data.length), {
+    signal: options.signal,
+  });
   return id;
 }
 

package/src/client/api/files.ts

@@ -10,8 +10,8 @@
  * (error 5120), on both servers.
  */
 
-import { Readable, Writable } from "node:stream";
-import { initFileDownload, initFileUpload } from "@honeybbq/teamspeak";
+import { Readable, Transform, Writable, pipeline } from "node:stream";
+import { initFileDownload, initFileUpload, stopFileTransfer } from "@honeybbq/teamspeak";
 import type {
   ChannelID,
   CommandExecutor,
@@ -22,15 +22,15 @@ import type {
 } from "@honeybbq/teamspeak";
 import { FileTransferError } from "../errors.js";
 import { downloadFileData, uploadFileData } from "../transfer.js";
+import { verifyStored, withDialCleanup } from "./upload-checks.js";
 import type { FileTransferOptions } from "../transfer.js";
 
 /**
  * How {@link uploadFile} negotiates and moves the file: the options of
- * `initFileUpload`, without `resume` (the whole file is sent), and those of
- * `uploadFileData`. `signal` and `timeoutMs` apply to the negotiation, and the
- * signal to the transfer too.
+ * `initFileUpload` and those of `uploadFileData`. `signal` and `timeoutMs`
+ * apply to the negotiation, and the signal to the transfer too.
  */
-export interface UploadFileOptions extends Omit<FileUploadOptions, "resume">, FileTransferOptions {
+export interface UploadFileOptions extends FileUploadOptions, FileTransferOptions {
   /**
    * The host of the file transfer port. A voice client sends to the host it
    * connected to, so it needs none; any other connection must name it. A host
@@ -40,26 +40,30 @@ export interface UploadFileOptions extends Omit<FileUploadOptions, "resume">, Fi
   /**
    * The size in bytes of a stream passed as the data, which the server needs
    * before it takes the file. Required for a `Readable`; for bytes it is their
-   * length, and a different value here is refused.
+   * length, and a different value here is refused. A stream that gives fewer
+   * or more bytes fails the upload.
    */
   readonly size?: bigint | number | undefined;
 }
 
-/** How {@link downloadFile} negotiates and moves the file. */
-export interface DownloadFileOptions
-  extends Omit<FileDownloadOptions, "seekPosition">, FileTransferOptions {
+/**
+ * How {@link downloadFile} negotiates and moves the file. With a
+ * `seekPosition` the bytes are the file's from there to its end.
+ */
+export interface DownloadFileOptions extends FileDownloadOptions, FileTransferOptions {
   /** The host of the file transfer port, as for {@link UploadFileOptions}. */
   readonly host?: string | undefined;
   /**
    * Write the file into this stream instead of returning its bytes. The stream
-   * is not ended, as for `downloadFileData`.
+   * is neither ended nor destroyed, as for `downloadFileData`, so it may take
+   * several downloads; a failed transfer still rejects the call.
    */
   readonly dest?: Writable | undefined;
   /**
-   * The largest file, in bytes, to hold in memory when no `dest` is given;
-   * 268435456 (256 MiB) by default. A larger file is refused with a
-   * {@link FileTransferError} before any byte is read; the transfer the server
-   * negotiated is left unused.
+   * The most bytes to hold in memory when no `dest` is given; 268435456
+   * (256 MiB) by default. A larger download is refused with a
+   * {@link FileTransferError} before any byte is read, and the transfer the
+   * server negotiated is stopped.
    */
   readonly maxSize?: number | undefined;
 }
@@ -147,12 +151,43 @@ function sizeOf(data: Uint8Array | Readable, declared: bigint | number | undefin
   return size;
 }
 
+/** Drops the first `count` bytes of a stream. */
+function skipBytes(count: number): Transform {
+  let left = count;
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (left >= chunk.length) {
+        left -= chunk.length;
+        callback();
+        return;
+      }
+      const rest = chunk.subarray(left);
+      left = 0;
+      callback(null, rest);
+    },
+  });
+}
+
 /**
  * Upload a file into a channel's file area: negotiate the transfer
  * (`initFileUpload`) and send the bytes (`uploadFileData`), in one call.
  *
  * `data` is the bytes, or a `Readable` with `options.size` the number of bytes
- * it will give. An existing file is not replaced unless `overwrite` is set, and
+ * it will give. It resolves once the server has closed the transfer
+ * connection and, by `ftgetfileinfo` (one more command), holds a file of
+ * exactly that size: the server does not say whether it stored a file, so a
+ * close alone could be a transfer someone stopped. A size that differs, or a
+ * file that is not there, fails the call with a {@link FileTransferError}; a
+ * client with no browse power cannot ask (2568) and resolves on the close. A
+ * stream that gives fewer or more bytes than `size` fails the call, and the
+ * connection is closed. When the connection to the file transfer port is
+ * refused or times out, the negotiated transfer is stopped on the server (else
+ * it lingers in `ftlist` for about 10 seconds), as it is for `downloadFile`.
+ *
+ * With `resume`, `data` is still the whole file: the server says how much it
+ * already holds from an interrupted upload (a file that is not there is
+ * refused with 2054), and only the rest is sent; `overwrite` cannot go with it
+ * (2056). An existing file is not replaced unless `overwrite` is set, and
  * the directory the file goes in must exist (a missing one is refused with
  * 2054, invalid file path): make it with `createDirectory` first. A refusal of
  * the negotiation is thrown as the ServerError it is, before anything is sent;
@@ -175,11 +210,21 @@ export async function uploadFile(
   const info = await initFileUpload(client, channelID, path, size, {
     password: options.password,
     overwrite: options.overwrite,
+    resume: options.resume,
     signal: options.signal,
     timeoutMs: options.timeoutMs,
   });
-  const source = data instanceof Uint8Array ? Readable.from([data]) : data;
-  await route.upload(info, source, transferOptions(options));
+  // What the server holds is not sent again; a position past the end is for
+  // the transfer to refuse.
+  const skip = Number(info.seekPosition);
+  let source: Readable;
+  if (data instanceof Uint8Array) source = Readable.from([data.subarray(skip)]);
+  else if (skip === 0) source = data;
+  else source = pipeline(data, skipBytes(skip), () => {});
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    route.upload(info, source, transferOptions(options)),
+  );
+  await verifyStored(client, channelID, path, size, options);
 }
 
 /**
@@ -188,7 +233,11 @@ export async function uploadFile(
  * call. With `options.dest` the bytes go into that stream instead and nothing
  * is held, which is the way to fetch a large file.
  *
- * A file over `maxSize` (256 MiB unless set) is refused when no `dest` is given.
+ * With `seekPosition` the bytes are the file's from there to its end, which is
+ * how to resume a partial download: append them to what was already fetched.
+ *
+ * More than `maxSize` bytes (256 MiB unless set) is refused when no `dest` is
+ * given, and the transfer the server negotiated is stopped.
  * A file that is not there is the ServerError of the negotiation: 2051 on TS3
  * 3.13.8 and TS6 beta13.1. A path that names a directory is not refused by the
  * server: it announces a size and sends nothing, so the call rejects with a
@@ -223,16 +272,25 @@ export async function downloadFile(
   const route = routeFor(client, options);
   const info = await initFileDownload(client, channelID, path, {
     password: options.password,
+    seekPosition: options.seekPosition,
     signal: options.signal,
     timeoutMs: options.timeoutMs,
   });
   if (options.dest !== undefined) {
-    await route.download(info, options.dest, transferOptions(options));
+    const dest = options.dest;
+    await withDialCleanup(client, info.serverFileTransferID, () =>
+      route.download(info, dest, transferOptions(options)),
+    );
     return;
   }
-  if (info.size > BigInt(maxSize)) {
+  const wanted = info.size - info.seekPosition;
+  if (wanted > BigInt(maxSize)) {
+    // The server holds the negotiated transfer, and lists it among the active
+    // ones, until it is used or stopped. It is this connection's own, which is
+    // the only kind `ftstop` is safe to send.
+    await stopFileTransfer(client, info.serverFileTransferID).catch(() => {});
     throw new FileTransferError(
-      `the file is ${info.size} bytes, over the ${maxSize} bytes maxSize allows in memory`,
+      `the download is ${wanted} bytes, over the ${maxSize} bytes maxSize allows in memory`,
     );
   }
   const chunks: Buffer[] = [];
@@ -242,7 +300,9 @@ export async function downloadFile(
       done();
     },
   });
-  await route.download(info, sink, transferOptions(options));
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    route.download(info, sink, transferOptions(options)),
+  );
   return Buffer.concat(chunks);
 }
 

package/src/client/api/upload-checks.ts

@@ -0,0 +1,96 @@
+/**
+ * What an upload does around its data phase: stop a transfer whose connection
+ * was never made, and check what the server stored once it closed the
+ * connection. Shared by the file and avatar helpers; not exported from the
+ * package.
+ */
+
+import { ErrorCode, ServerError, getFileInfo, stopFileTransfer } from "@honeybbq/teamspeak";
+import type { ChannelID, CommandExecutor, FileUploadInfo } from "@honeybbq/teamspeak";
+import { FileTransferError } from "../errors.js";
+import { failedToConnect } from "../transfer.js";
+
+/**
+ * The server drops a transfer nobody dialled after about 10 seconds (measured
+ * on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0: it is gone from `ftlist` at
+ * 10.05 s, and the voice client hears 2059). `ftstop` of a transfer the server
+ * no longer has crashes TeamSpeak 6, so a stop is only sent well inside that.
+ */
+const STOP_WITHIN_MS = 5_000;
+
+/**
+ * Runs the data phase of a transfer the server has negotiated. When it fails
+ * because the connection to the file transfer port was refused or timed out,
+ * nothing has reached the server, and the transfer would sit in its list until
+ * it expires: stop it, as a refused `maxSize` download does. The stop is best
+ * effort and never replaces the dial's error. Not sent once the connection
+ * opened (the key may be written and the server may have dropped the transfer),
+ * nor after `STOP_WITHIN_MS`.
+ */
+export async function withDialCleanup(
+  client: CommandExecutor,
+  serverFileTransferID: FileUploadInfo["serverFileTransferID"],
+  move: () => Promise<void>,
+): Promise<void> {
+  const negotiatedAt = performance.now();
+  try {
+    await move();
+  } catch (error) {
+    if (failedToConnect(error) && performance.now() - negotiatedAt < STOP_WITHIN_MS) {
+      await stopFileTransfer(client, serverFileTransferID).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+/**
+ * Checks that the server holds the whole file after an upload's connection
+ * closed. Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0: a completed
+ * upload gets no status from the server, so a close after the last byte looks
+ * the same whether the file was stored or the transfer was stopped (the voice
+ * protocol reports that, 2066, only after the close), and `ftgetfileinfo`
+ * already answers the final size 6 to 45 ms after the close, in every case.
+ * Permissions are checked at the negotiation only, so no refusal comes later.
+ *
+ * A client without browse power gets 2568 for `ftgetfileinfo`: the file cannot
+ * be checked, and the upload resolves on the close. Any other failure of the
+ * command is thrown as it is.
+ */
+export async function verifyStored(
+  client: CommandExecutor,
+  channelID: ChannelID,
+  path: string,
+  size: bigint,
+  options: {
+    readonly password?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+  },
+): Promise<void> {
+  let stored: bigint;
+  try {
+    stored = (
+      await getFileInfo(client, channelID, path, {
+        password: options.password,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+      })
+    ).size;
+  } catch (error) {
+    if (error instanceof ServerError) {
+      if (error.code === ErrorCode.PermissionsClientInsufficient) return;
+      // 2051 on TeamSpeak 6, 2052 on TeamSpeak 3 for a file that is not there.
+      if (error.code === ErrorCode.FileNotFound || error.code === ErrorCode.FileIOError) {
+        throw new FileTransferError(`the server closed the upload but has no file ${path}`, {
+          cause: error,
+        });
+      }
+    }
+    throw error;
+  }
+  if (stored !== size) {
+    throw new FileTransferError(
+      `the server closed the upload but holds ${stored} of the ${size} bytes of ${path}`,
+    );
+  }
+}

package/src/client/api/voice.ts

@@ -14,7 +14,8 @@ import type { ChannelID, ClientID, CommandOptions } from "@honeybbq/teamspeak";
 /**
  * The channel's description, which `listChannels` omits for bandwidth. The
  * server answers with a `notifychanneledited` that the client does not report as
- * a `channelEdited` event, since it is no edit.
+ * a `channelEdited` event, since it is no edit. Rejects with a NoDataError if
+ * the server sends no such answer.
  */
 export async function getChannelDescription(
   client: Client,
@@ -29,7 +30,9 @@ export async function getChannelDescription(
   // can arrive while the command waits, a real edit with other properties,
   // and the first row is then not the answer.
   const answer = rows.find((row) => row["cid"] === String(cid) && "channel_description" in row);
-  return answer?.["channel_description"] ?? "";
+  // A missing answer is not an empty description.
+  if (answer === undefined) throw new NoDataError("channelgetdescription");
+  return answer["channel_description"] ?? "";
 }
 
 /**