@av-pi-studio/client 0.0.116 → 0.0.118

package/dist/daemon-client.d.ts

@@ -21,6 +21,11 @@ export interface DaemonClientOptions {
     url: string;
     clientId: string;
     clientType: ClientType;
+    /**
+     * Free-form platform label sent as `hello.platform` when set (the desktop app sends `"desktop"`
+     * with `clientType: "browser"`). Informational; daemons that predate the field ignore it.
+     */
+    platform?: string;
     protocolVersion?: number;
     appVersion?: string;
     capabilities?: Record<string, boolean>;
@@ -67,6 +72,8 @@ export declare class DaemonClient {
     get serverId(): string | null;
     get features(): Record<string, unknown>;
     get serverCapabilities(): Record<string, unknown>;
+    /** The transport's unsent byte count, or `undefined` when the transport cannot report one. */
+    get bufferedAmount(): number | undefined;
     /** True iff the daemon advertised the given `server_info.features.*` flag truthy. */
     hasFeature(flag: string): boolean;
     /**

package/dist/daemon-client.js

@@ -70,6 +70,10 @@ export class DaemonClient {
     get serverCapabilities() {
         return this._serverCapabilities;
     }
+    /** The transport's unsent byte count, or `undefined` when the transport cannot report one. */
+    get bufferedAmount() {
+        return this.transport.bufferedAmount;
+    }
     /** True iff the daemon advertised the given `server_info.features.*` flag truthy. */
     hasFeature(flag) {
         return Boolean(this._features[flag]);
@@ -90,6 +94,7 @@ export class DaemonClient {
             type: "hello",
             clientId: this.options.clientId,
             clientType: this.options.clientType,
+            platform: this.options.platform,
             protocolVersion: this.options.protocolVersion ?? PROTOCOL_VERSION,
             appVersion: this.options.appVersion,
             capabilities: this.options.capabilities,
@@ -227,8 +232,7 @@ export class DaemonClient {
      */
     handleBinaryFrame(bytes) {
         const opcodeByte = bytes[0];
-        const isFileTransfer = opcodeByte !== undefined &&
-            Object.values(FileTransferOpcode).includes(opcodeByte);
+        const isFileTransfer = opcodeByte !== undefined && Object.values(FileTransferOpcode).includes(opcodeByte);
         if (isFileTransfer) {
             const frame = tryDecodeFileTransferFrame(bytes);
             if (!frame)

package/dist/file-transfer-client.d.ts

@@ -1,4 +1,25 @@
 import { type DaemonClient } from "./daemon-client.js";
+/**
+ * Upload pacing: `upload` waits before each chunk while the transport reports more than this many
+ * unsent bytes, so the socket queue stays within this plus one chunk. 1 MiB (32 chunks) is a
+ * chosen value, not a measured one — big enough to keep a fast link busy across a poll interval,
+ * small enough that a stalled link holds little memory and a cancel takes effect quickly.
+ */
+export declare const UPLOAD_HIGH_WATER_BYTES: number;
+/** What `FileTransferClient.upload` can stream from. */
+export type UploadSource = Uint8Array | Blob | AsyncIterable<Uint8Array>;
+export interface UploadOptions {
+    /** Called after each chunk is queued; `sent` is cumulative, `total` is unknown (`undefined`) for an async iterable. */
+    onProgress?(sent: number, total?: number): void;
+    /** Aborting sends an `Error` frame for the stream and rejects `upload` with an `AbortError`. */
+    signal?: AbortSignal;
+}
+export interface FileTransferClientOptions {
+    /** Override {@link UPLOAD_HIGH_WATER_BYTES} (tests). */
+    highWaterBytes?: number;
+    /** Override the pacing timer (tests); resolves after `ms`. */
+    sleep?(ms: number): Promise<void>;
+}
 export interface DownloadedFile {
     bytes: Uint8Array;
     fileName?: string;
@@ -10,10 +31,15 @@ export declare class FileTransferClient {
     /** Rotating hand-out point in the one-byte stream id space — ids are a pool, not a counter. */
     private streamCursor;
     private detach;
-    constructor(daemon: DaemonClient);
+    private readonly uploads;
+    private readonly highWaterBytes;
+    private readonly sleep;
+    constructor(daemon: DaemonClient, options?: FileTransferClientOptions);
+    /** Uploads that have not settled yet (0 once every upload has resolved, rejected, or been aborted). */
+    get pendingUploads(): number;
     /** Begin routing inbound file-transfer frames. Idempotent. */
     start(): void;
-    /** Stop routing inbound frames. Any downloads still pending are rejected. */
+    /** Stop routing inbound frames. Any downloads and uploads still pending are rejected. */
     stop(): void;
     /**
      * Download the file at `path`: requests a single-use token, then requests the chunked
@@ -29,12 +55,30 @@ export declare class FileTransferClient {
     download(path: string): Promise<DownloadedFile>;
     private attemptDownload;
     /**
-     * Upload `bytes` to `path` on the daemon: requests an upload stream, then pushes
+     * Upload `source` to `path` on the daemon: requests an upload stream, then pushes
      * `Begin → Chunk* → End` binary frames the server writes to disk (creating parent dirs,
      * overwriting any existing file). The server keys the transfer by `transferId`, which the
-     * `Begin` frame must echo. Resolves once every frame is flushed to the socket.
+     * `Begin` frame must echo.
+     *
+     * - **Streaming.** A `Blob` is sliced and read chunk by chunk and an async iterable is pulled one
+     *   item at a time, so memory stays at about one chunk (plus the pacing window) regardless of the
+     *   file size. `total` in `onProgress` is the byte length for a `Uint8Array`/`Blob` and
+     *   `undefined` for an async iterable.
+     * - **Pacing.** Before each chunk it waits while `transport.bufferedAmount` is above
+     *   {@link UPLOAD_HIGH_WATER_BYTES}; a transport that does not report it is never congested.
+     * - **Completion.** With the daemon's `fileTransferAck` feature it resolves when the matching
+     *   `file_upload_complete` push arrives and rejects with the daemon's error when `ok` is false;
+     *   there is no timeout on that wait. Without it, it resolves once the transport's buffer has
+     *   drained after `End` (the bytes have left this machine, not necessarily reached the disk).
+     * - **Cancel.** `signal` aborting sends an `Error` frame for the stream (so the daemon frees it)
+     *   and rejects with an `AbortError`. A dropped connection or {@link stop} rejects too.
+     *   Whatever way it ends, no listener or stream is left behind.
      */
-    upload(path: string, bytes: Uint8Array): Promise<void>;
+    upload(path: string, source: UploadSource, options?: UploadOptions): Promise<void>;
+    /** Poll `condition` on a timer until it clears, giving up as soon as the upload has failed. */
+    private waitWhile;
+    /** Best-effort `Error` frame for an upload stream; a dead connection has nothing to tell. */
+    private sendUploadError;
     private dispatch;
 }
 //# sourceMappingURL=file-transfer-client.d.ts.map

package/dist/file-transfer-client.js

@@ -12,6 +12,71 @@ import { randomId } from "./daemon-client.js";
 const UPLOAD_CHUNK_BYTES = 32 * 1024;
 /** The daemon's `startDownload` rejection when a token is unknown, spent, or past its TTL. */
 const EXPIRED_TOKEN = "invalid_or_expired_token";
+/**
+ * Upload pacing: `upload` waits before each chunk while the transport reports more than this many
+ * unsent bytes, so the socket queue stays within this plus one chunk. 1 MiB (32 chunks) is a
+ * chosen value, not a measured one — big enough to keep a fast link busy across a poll interval,
+ * small enough that a stalled link holds little memory and a cancel takes effect quickly.
+ */
+export const UPLOAD_HIGH_WATER_BYTES = 1024 * 1024;
+/** How often `upload` re-reads the transport's buffered amount while it is congested. */
+const UPLOAD_POLL_MS = 10;
+function createRun() {
+    // `new Promise`, not `Promise.withResolvers`: this SDK ships to browsers and React Native
+    // runtimes older than ES2024 (and compiles with `lib: ES2023`).
+    let reject;
+    const promise = new Promise((_, rej) => {
+        reject = rej;
+    });
+    promise.catch(() => { }); // only ever raced: never an unhandled rejection
+    let failed;
+    return {
+        failure: promise,
+        fail(error) {
+            if (failed)
+                return;
+            failed = error;
+            reject(error);
+        },
+        check() {
+            if (failed)
+                throw failed;
+        },
+    };
+}
+function abortError() {
+    return new DOMException("The upload was aborted", "AbortError");
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* sliceBytes(bytes) {
+    for (let offset = 0; offset < bytes.length; offset += UPLOAD_CHUNK_BYTES) {
+        yield bytes.subarray(offset, offset + UPLOAD_CHUNK_BYTES);
+    }
+}
+/** Reads one chunk at a time — the whole file is never in memory. */
+async function* sliceBlob(blob) {
+    for (let offset = 0; offset < blob.size; offset += UPLOAD_CHUNK_BYTES) {
+        yield new Uint8Array(await blob.slice(offset, offset + UPLOAD_CHUNK_BYTES).arrayBuffer());
+    }
+}
+/** Re-cuts whatever the iterable yields into chunks of at most `UPLOAD_CHUNK_BYTES`. */
+async function* splitItems(items) {
+    for await (const item of items)
+        yield* sliceBytes(item);
+}
+function uploadChunks(source) {
+    if (source instanceof Uint8Array)
+        return { total: source.length, chunks: sliceBytes(source) };
+    if (typeof Blob !== "undefined" && source instanceof Blob) {
+        return { total: source.size, chunks: sliceBlob(source) };
+    }
+    return { total: undefined, chunks: splitItems(source) };
+}
 function concat(chunks) {
     const total = chunks.reduce((sum, c) => sum + c.length, 0);
     const out = new Uint8Array(total);
@@ -28,8 +93,17 @@ export class FileTransferClient {
     /** Rotating hand-out point in the one-byte stream id space — ids are a pool, not a counter. */
     streamCursor = 1;
     detach = null;
-    constructor(daemon) {
+    uploads = new Set();
+    highWaterBytes;
+    sleep;
+    constructor(daemon, options = {}) {
         this.daemon = daemon;
+        this.highWaterBytes = options.highWaterBytes ?? UPLOAD_HIGH_WATER_BYTES;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    /** Uploads that have not settled yet (0 once every upload has resolved, rejected, or been aborted). */
+    get pendingUploads() {
+        return this.uploads.size;
     }
     /** Begin routing inbound file-transfer frames. Idempotent. */
     start() {
@@ -37,7 +111,7 @@ export class FileTransferClient {
             return;
         this.detach = this.daemon.onFileTransferFrame((frame) => this.dispatch(frame));
     }
-    /** Stop routing inbound frames. Any downloads still pending are rejected. */
+    /** Stop routing inbound frames. Any downloads and uploads still pending are rejected. */
     stop() {
         this.detach?.();
         this.detach = null;
@@ -45,6 +119,8 @@ export class FileTransferClient {
             pending.reject(new Error("file transfer router stopped"));
             this.pending.delete(stream);
         }
+        for (const run of this.uploads)
+            run.fail(new Error("file transfer router stopped"));
     }
     /**
      * Download the file at `path`: requests a single-use token, then requests the chunked
@@ -100,27 +176,145 @@ export class FileTransferClient {
         return result;
     }
     /**
-     * Upload `bytes` to `path` on the daemon: requests an upload stream, then pushes
+     * Upload `source` to `path` on the daemon: requests an upload stream, then pushes
      * `Begin → Chunk* → End` binary frames the server writes to disk (creating parent dirs,
      * overwriting any existing file). The server keys the transfer by `transferId`, which the
-     * `Begin` frame must echo. Resolves once every frame is flushed to the socket.
+     * `Begin` frame must echo.
+     *
+     * - **Streaming.** A `Blob` is sliced and read chunk by chunk and an async iterable is pulled one
+     *   item at a time, so memory stays at about one chunk (plus the pacing window) regardless of the
+     *   file size. `total` in `onProgress` is the byte length for a `Uint8Array`/`Blob` and
+     *   `undefined` for an async iterable.
+     * - **Pacing.** Before each chunk it waits while `transport.bufferedAmount` is above
+     *   {@link UPLOAD_HIGH_WATER_BYTES}; a transport that does not report it is never congested.
+     * - **Completion.** With the daemon's `fileTransferAck` feature it resolves when the matching
+     *   `file_upload_complete` push arrives and rejects with the daemon's error when `ok` is false;
+     *   there is no timeout on that wait. Without it, it resolves once the transport's buffer has
+     *   drained after `End` (the bytes have left this machine, not necessarily reached the disk).
+     * - **Cancel.** `signal` aborting sends an `Error` frame for the stream (so the daemon frees it)
+     *   and rejects with an `AbortError`. A dropped connection or {@link stop} rejects too.
+     *   Whatever way it ends, no listener or stream is left behind.
      */
-    async upload(path, bytes) {
-        const transferId = randomId();
-        const response = await this.daemon.request("file_upload_request", {
-            path,
-            transferId,
-        });
-        if (!response.ok || response.stream === undefined) {
-            throw new Error(response.error ?? "upload request failed");
+    async upload(path, source, options = {}) {
+        const { onProgress, signal } = options;
+        if (signal?.aborted)
+            throw abortError();
+        const run = createRun();
+        this.uploads.add(run);
+        const cleanups = [];
+        let stream;
+        let endSent = false;
+        let daemonDone = false;
+        try {
+            if (signal) {
+                const onAbort = () => run.fail(abortError());
+                signal.addEventListener("abort", onAbort, { once: true });
+                cleanups.push(() => signal.removeEventListener("abort", onAbort));
+            }
+            cleanups.push(this.daemon.onStateChange((state) => {
+                if (state !== "open")
+                    run.fail(new Error(`connection ${state} during upload`));
+            }));
+            if (this.daemon.state !== "open")
+                throw new Error("connection is not open");
+            const transferId = randomId();
+            const ack = this.daemon.hasFeature("fileTransferAck");
+            const request = this.daemon.request("file_upload_request", {
+                path,
+                transferId,
+                ...(ack ? { ack: true } : {}),
+            });
+            let response;
+            try {
+                response = await Promise.race([request, run.failure]);
+            }
+            catch (error) {
+                // The daemon may still answer and hand out a stream nobody will use — give it back.
+                void request.then((late) => {
+                    if (late.ok && late.stream !== undefined)
+                        this.sendUploadError(late.stream, "client_error");
+                }, () => { });
+                throw error;
+            }
+            if (!response.ok || response.stream === undefined) {
+                throw new Error(response.error ?? "upload request failed");
+            }
+            stream = response.stream;
+            // Registered before any frame is sent, so an early failure (or the final ack) cannot be missed.
+            let complete;
+            const completed = new Promise((resolve) => {
+                complete = resolve;
+            });
+            if (ack) {
+                cleanups.push(this.daemon.onSessionMessage((message) => {
+                    if (message.type !== "file_upload_complete" || message.transferId !== transferId)
+                        return;
+                    daemonDone = true; // the daemon freed the stream: nothing left for us to cancel
+                    if (message.ok)
+                        complete();
+                    else
+                        run.fail(new Error(message.error ?? "upload failed"));
+                }));
+            }
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Begin", stream, meta: { transferId } }));
+            const { total, chunks } = uploadChunks(source);
+            const iterator = chunks[Symbol.asyncIterator]();
+            cleanups.push(() => {
+                void Promise.resolve(iterator.return?.()).catch(() => { });
+            });
+            let sent = 0;
+            for (;;) {
+                await this.waitWhile(() => (this.daemon.bufferedAmount ?? 0) > this.highWaterBytes, run);
+                const next = iterator.next();
+                next.catch(() => { }); // if the race below is lost to a failure, `next` must not go unhandled
+                const step = await Promise.race([next, run.failure]);
+                if (step.done)
+                    break;
+                run.check();
+                this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Chunk", stream, data: step.value }));
+                sent += step.value.length;
+                onProgress?.(sent, total);
+            }
+            if (sent === 0)
+                onProgress?.(0, total);
+            run.check();
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
+            endSent = true;
+            if (ack)
+                await Promise.race([completed, run.failure]);
+            else
+                await this.waitWhile(() => (this.daemon.bufferedAmount ?? 0) > 0, run);
+        }
+        catch (error) {
+            // Before `End` the daemon still holds the stream and an open file; tell it to let go.
+            if (stream !== undefined && !endSent && !daemonDone) {
+                this.sendUploadError(stream, isAbortError(error) ? "client_aborted" : "client_error");
+            }
+            throw error;
+        }
+        finally {
+            for (const cleanup of cleanups)
+                cleanup();
+            this.uploads.delete(run);
+        }
+    }
+    /** Poll `condition` on a timer until it clears, giving up as soon as the upload has failed. */
+    async waitWhile(condition, run) {
+        while (condition()) {
+            run.check();
+            await Promise.race([this.sleep(UPLOAD_POLL_MS), run.failure]);
+        }
+    }
+    /** Best-effort `Error` frame for an upload stream; a dead connection has nothing to tell. */
+    sendUploadError(stream, message) {
+        if (this.daemon.state !== "open")
+            return;
+        try {
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Error", stream, message }));
         }
-        const stream = response.stream;
-        this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Begin", stream, meta: { transferId } }));
-        for (let offset = 0; offset < bytes.length; offset += UPLOAD_CHUNK_BYTES) {
-            const data = bytes.subarray(offset, offset + UPLOAD_CHUNK_BYTES);
-            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Chunk", stream, data }));
+        catch {
+            /* the socket died under us — the daemon frees the stream when it notices */
         }
-        this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
     }
     dispatch(frame) {
         const pending = this.pending.get(frame.stream);

package/dist/relay-transport.js

@@ -22,7 +22,7 @@
  * `packages/server/src/daemon/relay-transport.ts`'s choice (`{ type: "relay_register", sessionId
  * }`) — the real protocol is unresolved upstream (architecture/relay-e2ee.md § TODO(verify)).
  */
-import { createClientChannel, deriveRelaySessionId } from "@av-pi-studio/relay";
+import { createClientChannel, deriveRelaySessionId, } from "@av-pi-studio/relay";
 import { reasonString } from "./transport.js";
 /** Build the relay's own `ws://`/`wss://` dial URL from a pairing offer's `relay` info. */
 export function relayDialUrl(relay) {
@@ -49,6 +49,11 @@ export function createRelayTransport(opts) {
         get isOpen() {
             return ws !== null && ws.readyState === 1 && channel !== null && channel.ready;
         },
+        // The channel encrypts and writes synchronously, so the relay socket's queue is exactly the
+        // (base64-inflated) ciphertext still waiting to leave — the right number to pace against.
+        get bufferedAmount() {
+            return ws?.bufferedAmount;
+        },
         connect(url) {
             return new Promise((resolve, reject) => {
                 const create = opts.factory ?? (() => new WebSocket(url));

package/dist/transport.d.ts

@@ -16,6 +16,13 @@ export interface Transport {
     close(code?: number, reason?: string): void;
     /** Whether the transport is currently open and writeable. */
     readonly isOpen: boolean;
+    /**
+     * Bytes accepted by `sendText`/`sendBinary` but not yet handed to the network (the underlying
+     * socket's send queue). Optional: a transport that cannot report it leaves it `undefined` and
+     * is treated as never congested — `FileTransferClient.upload` then does not pace. Out-of-tree
+     * implementations (the desktop app's Rust bridge) may omit it.
+     */
+    readonly bufferedAmount?: number;
     onMessage: TransportMessageHandler | null;
     onClose: TransportCloseHandler | null;
     onError: TransportErrorHandler | null;
@@ -36,6 +43,8 @@ export type AnyWebSocket = {
     /** Browsers/RN default this to `"blob"`; Node's `ws` ignores it (always delivers `Buffer`).
      * `connect()` forces `"arraybuffer"` where the property exists — see its comment for why. */
     binaryType?: string;
+    /** Bytes queued by `send()` and not yet transmitted (browser/RN/`ws` all report it). */
+    readonly bufferedAmount?: number;
 };
 export type WsFactory = (url: string, protocols?: string[]) => AnyWebSocket;
 export declare function reasonString(reason: unknown): string;

package/dist/transport.js

@@ -23,6 +23,9 @@ export function createWebSocketTransport(factory) {
         get isOpen() {
             return ws !== null && ws.readyState === 1; // OPEN
         },
+        get bufferedAmount() {
+            return ws?.bufferedAmount;
+        },
         connect(url) {
             return new Promise((resolve, reject) => {
                 const create = factory ?? (() => new WebSocket(url));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@av-pi-studio/client",
-  "version": "0.0.116",
+  "version": "0.0.118",
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -20,8 +20,8 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@av-pi-studio/protocol": "^0.0.116",
-    "@av-pi-studio/relay": "^0.0.116"
+    "@av-pi-studio/protocol": "^0.0.118",
+    "@av-pi-studio/relay": "^0.0.118"
   },
   "repository": {
     "type": "git",