@muhkoo/connect 0.15.0-alpha.0 → 0.15.0-alpha.2

package/dist/connect.d.ts

@@ -2463,7 +2463,7 @@ declare class ShardClient {
     private readonly pathPrefix;
     private readonly fetchFn;
     private readonly cache?;
-    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     private pendingShards;
     private batchTimer;
     /** False once the server is known not to have the batch route. */
@@ -2496,8 +2496,13 @@ declare class ShardClient {
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
+     *
+     * `size`, the shard's byte length when known (a manifest's `shardSize`),
+     * lets concurrent reads be batched within what the server will send.
      */
-    getShard(hash: string): Promise<Uint8Array | null>;
+    getShard(hash: string, opts?: {
+        size?: number;
+    }): Promise<Uint8Array | null>;
     /**
      * Fetch from origin, COALESCING concurrent requests into one batch.
      *
@@ -2520,6 +2525,8 @@ declare class ShardClient {
     private fetchFromOrigin;
     /** Send one batch of whatever has accumulated, and settle those callers. */
     private flushShardBatch;
+    /** POST one batch and settle everyone waiting on it. Never throws. */
+    private sendShardBatch;
     /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
      *  cache is present, so RS recovery can proceed); throws otherwise. */
     private fetchOneFromOrigin;
@@ -6737,11 +6744,19 @@ declare class VfsLimitError extends Error {
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
  * child or it does not. Two tabs writing different directories never conflict;
- * two tabs writing the SAME directory resolve last-writer-wins at the personal
- * space, which carries an HLC per key. Orphaned records (a directory whose
- * parent entry lost the race) are unreachable rather than corrupting — they
- * cost storage until a future sweep, which is the trade this shape makes in
+ * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
+ * write sends no HLC and the personal space has no compare-and-swap: it applies
+ * puts of one key in the order they arrive, so whichever arrives last is kept,
+ * and the other tab's edit is lost. Orphaned records (a directory whose parent
+ * entry lost the race) are unreachable rather than corrupting — they cost
+ * storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
+ *
+ * Within ONE tab, writes of a record are queued and sent one at a time, in the
+ * order they were made, and a read that has to fetch a record waits for its
+ * write in flight (see `writing`). That ordering is per namespace instance
+ * only; nothing orders writes across tabs or devices - that would take a
+ * compare-and-swap at the server.
  */
 
 /**
@@ -6757,6 +6772,8 @@ interface VfsContentStore {
     write(data: Uint8Array | Blob, meta: {
         name: string;
         type: string;
+    }, opts?: {
+        onProgress?: (done: number, total: number) => void;
     }): Promise<{
         manifest: FileManifest;
         size: number;
@@ -6817,6 +6834,20 @@ declare class VfsNamespace {
      * than by TTL — a stale directory listing shows files that are not there.
      */
     private cache;
+    /**
+     * The write of each directory record still in flight, by id.
+     *
+     * Two writes of one record must land in the order they were made. The
+     * personal space has no compare-and-swap: of two writes of one key that
+     * are in flight together it keeps whichever request finishes last, and
+     * that is often the one sent first. Then the earlier write, sealed before
+     * the later edit was made, undoes it. That is how a file deleted forever
+     * from the Trash, while the move that put it there was still being
+     * written, came back. So each write waits for the one before it, and a
+     * read that has to fetch the record waits for its write too: see
+     * `openDirById`.
+     */
+    private readonly writing;
     private readonly historyLimit;
     private readonly maxEntries;
     private readonly maxPathChars;
@@ -6975,6 +7006,7 @@ declare class VfsNamespace {
      */
     writeFile(path: string, data: Uint8Array | string | Blob, opts?: {
         type?: string;
+        onProgress?: (done: number, total: number) => void;
     }): Promise<VfsStat>;
     /**
      * Delete a file, or a directory when `recursive`.
@@ -7037,8 +7069,11 @@ declare class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs edit the same directory, last-writer-wins at the personal space can
-     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * tabs or devices edit the same directory, the personal space keeps
+     * whichever put arrives last (a VFS write sends no HLC, and the space
+     * applies puts of one key in arrival order), which can leave a child whose
+     * parent entry lost the race. The per-record write queue (`writing`) only
+     * orders writes within one tab. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -7088,6 +7123,14 @@ declare class VfsNamespace {
     private readRecord;
     /** Apply an edit to a directory record and persist it. */
     private mutate;
+    /**
+     * Seal a directory record as it stands NOW and put it in the store.
+     *
+     * Read at the moment of sending, not when the edit was made, so a write
+     * that waited behind another carries every edit made to the record by
+     * then, its own included.
+     */
+    private writeRecord;
     private createDir;
     /**
      * Every directory record in a subtree, each once, opened - and nothing
@@ -8975,7 +9018,7 @@ declare function getId(row: {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-declare const VERSION = "0.15.0-alpha.0";
+declare const VERSION = "0.15.0-alpha.2";
 
 /**
  * The SDK's process-global logger.

package/dist/server/index.js

@@ -5862,6 +5862,34 @@ class ReedSolomonCodec {
 const SHARD_BATCH_WINDOW_MS = 6;
 /** Hashes per batch. Must not exceed what the server will accept. */
 const SHARD_BATCH_MAX = 256;
+/**
+ * Expected response bytes per batch, which a batch is split to stay under.
+ *
+ * The server refuses a batch above 24 MiB of shard bytes with a 413, and the
+ * reads in a refused batch fail. Counting hashes alone, about 25 one-MiB
+ * shards in one window - a few large files read at once - drew it. This
+ * leaves the server's ceiling well clear.
+ */
+const SHARD_BATCH_BUDGET_BYTES = 16 * 1024 * 1024;
+/** An entry's JSON around its base64: the quoted hash, a colon, quotes and a comma, rounded up. */
+const SHARD_BATCH_ENTRY_BYTES = 128;
+/**
+ * What a shard adds to a batch's response: base64 is 4 bytes for every 3.
+ *
+ * A shard whose size the caller did not give counts as its entry alone, so
+ * reads without sizes batch by count, as they always have — kept for the
+ * pinned "many concurrent reads → ONE request" test
+ * (`shard-batching.test.ts`). No SDK read path is size-less today:
+ * `FileStorage.readChunk` always passes `shardSize`. The server reads and
+ * base64-encodes every shard before it checks the total
+ * (`ShardsController.ts`), so a very large size-less batch can fail with a
+ * 5xx before the client ever sees a 413. The split in `sendShardBatch` is a
+ * best-effort net for that case, not a guarantee.
+ */
+function batchCost(size) {
+    const bytes = typeof size === "number" && Number.isFinite(size) && size > 0 ? size : 0;
+    return Math.ceil(bytes / 3) * 4 + SHARD_BATCH_ENTRY_BYTES;
+}
 /** Decode base64 without `atob`'s per-character loop cost on large shards. */
 function bytesFromBase64(b64) {
     const binary = atob(b64);
@@ -5889,7 +5917,7 @@ class ShardClient {
     pathPrefix;
     fetchFn;
     cache;
-    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     pendingShards;
     batchTimer;
     /** False once the server is known not to have the batch route. */
@@ -6038,8 +6066,11 @@ class ShardClient {
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
+     *
+     * `size`, the shard's byte length when known (a manifest's `shardSize`),
+     * lets concurrent reads be batched within what the server will send.
      */
-    async getShard(hash) {
+    async getShard(hash, opts = {}) {
         // Cache-first: a hit is content-verified by construction (key == hash).
         if (this.cache) {
             const cached = await this.cache.get(hash);
@@ -6048,7 +6079,7 @@ class ShardClient {
         }
         // No peers → straight to origin.
         if (!this.peers)
-            return this.fetchFromOrigin(hash);
+            return this.fetchFromOrigin(hash, opts.size);
         // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow
         // or missing peer stall delivery — give the peer a short head start, then
         // start origin in parallel and take whichever returns the block first.
@@ -6079,7 +6110,7 @@ class ShardClient {
                     clearTimeout(timer);
                     timer = null;
                 }
-                this.fetchFromOrigin(hash).then(win, fail);
+                this.fetchFromOrigin(hash, opts.size).then(win, fail);
             };
             timer = setTimeout(startOrigin, HEDGE_MS);
             peers.getBlock(hash).then((b) => {
@@ -6113,16 +6144,17 @@ class ShardClient {
      * Falls back permanently to one-at-a-time if the server has no batch route,
      * so a new SDK keeps working against an older deployment.
      */
-    fetchFromOrigin(hash) {
+    fetchFromOrigin(hash, size) {
         if (!this.batchSupported)
             return this.fetchOneFromOrigin(hash);
         return new Promise((resolve, reject) => {
-            const waiting = this.pendingShards.get(hash);
-            if (waiting) {
-                waiting.push({ resolve, reject });
+            const pending = this.pendingShards.get(hash);
+            if (pending) {
+                pending.waiters.push({ resolve, reject });
+                pending.size ??= size;
                 return;
             }
-            this.pendingShards.set(hash, [{ resolve, reject }]);
+            this.pendingShards.set(hash, { size, waiters: [{ resolve, reject }] });
             if (this.batchTimer === null) {
                 this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
             }
@@ -6133,17 +6165,33 @@ class ShardClient {
         this.batchTimer = null;
         if (this.pendingShards.size === 0)
             return;
-        const hashes = [...this.pendingShards.keys()].slice(0, SHARD_BATCH_MAX);
-        const waiters = hashes.map((h) => {
-            const w = this.pendingShards.get(h);
+        // As many as fit: at most SHARD_BATCH_MAX hashes, and a response
+        // expected to stay within SHARD_BATCH_BUDGET_BYTES. One that does not
+        // fit is skipped for a smaller one behind it. The first always goes,
+        // so a shard over the budget by itself is fetched alone.
+        const waiters = [];
+        let cost = 0;
+        for (const [h, pending] of this.pendingShards) {
+            if (waiters.length === SHARD_BATCH_MAX)
+                break;
+            const next = batchCost(pending.size);
+            if (waiters.length > 0 && cost + next > SHARD_BATCH_BUDGET_BYTES)
+                continue;
+            waiters.push([h, pending.waiters]);
+            cost += next;
+        }
+        for (const [h] of waiters)
             this.pendingShards.delete(h);
-            return [h, w];
-        });
-        // Anything over the cap waits for the next window rather than being
-        // dropped or silently truncated.
+        // Anything over the cap or the budget waits for the next window
+        // rather than being dropped or silently truncated.
         if (this.pendingShards.size > 0 && this.batchTimer === null) {
             this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
         }
+        await this.sendShardBatch(waiters);
+    }
+    /** POST one batch and settle everyone waiting on it. Never throws. */
+    async sendShardBatch(waiters) {
+        const hashes = waiters.map(([h]) => h);
         let shards;
         try {
             const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {
@@ -6151,6 +6199,21 @@ class ShardClient {
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ hashes }),
             });
+            if (res.status === 413 && waiters.length > 1) {
+                // Too large for the server after all: a size was not given,
+                // or was wrong. Ask for each half on its own. Halving reaches
+                // one hash per batch within log2(n) levels, and one hash the
+                // server refuses is an error like any other, below.
+                // Release the body first: under undici (the CLI, Node), an
+                // unread body holds the connection until garbage collection.
+                await res.body?.cancel().catch(() => { });
+                const half = Math.ceil(waiters.length / 2);
+                await Promise.all([
+                    this.sendShardBatch(waiters.slice(0, half)),
+                    this.sendShardBatch(waiters.slice(half)),
+                ]);
+                return;
+            }
             if (res.status === 404 || res.status === 405) {
                 // No batch route on this deployment. Stop trying, and serve
                 // everyone individually — including the batch we just gathered.
@@ -6526,7 +6589,8 @@ class FileStorage {
         const fetched = new Array(total).fill(null);
         const fetchInto = async (indexes) => {
             await this.runWithConcurrency(indexes.map((i) => async () => {
-                fetched[i] = await this.shards.getShard(manifest.shardHashes[i]);
+                // The size keeps a batch of concurrent reads within what the server will send.
+                fetched[i] = await this.shards.getShard(manifest.shardHashes[i], { size: manifest.shardSize });
             }));
         };
         await fetchInto(Array.from({ length: dataCount }, (_, i) => i));
@@ -6675,7 +6739,7 @@ async function parseOrThrow(response, op) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.15.0-alpha.0";
+const VERSION = "0.15.0-alpha.2";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -15082,11 +15146,19 @@ function nextTurn() {
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
  * child or it does not. Two tabs writing different directories never conflict;
- * two tabs writing the SAME directory resolve last-writer-wins at the personal
- * space, which carries an HLC per key. Orphaned records (a directory whose
- * parent entry lost the race) are unreachable rather than corrupting — they
- * cost storage until a future sweep, which is the trade this shape makes in
+ * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
+ * write sends no HLC and the personal space has no compare-and-swap: it applies
+ * puts of one key in the order they arrive, so whichever arrives last is kept,
+ * and the other tab's edit is lost. Orphaned records (a directory whose parent
+ * entry lost the race) are unreachable rather than corrupting — they cost
+ * storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
+ *
+ * Within ONE tab, writes of a record are queued and sent one at a time, in the
+ * order they were made, and a read that has to fetch a record waits for its
+ * write in flight (see `writing`). That ordering is per namespace instance
+ * only; nothing orders writes across tabs or devices - that would take a
+ * compare-and-swap at the server.
  */
 /** Refuse a directory at `path` if it would be deeper than MAX_DEPTH from the root. */
 function assertWritableDepth(path) {
@@ -15458,6 +15530,20 @@ class VfsNamespace {
      * than by TTL — a stale directory listing shows files that are not there.
      */
     cache = new Map();
+    /**
+     * The write of each directory record still in flight, by id.
+     *
+     * Two writes of one record must land in the order they were made. The
+     * personal space has no compare-and-swap: of two writes of one key that
+     * are in flight together it keeps whichever request finishes last, and
+     * that is often the one sent first. Then the earlier write, sealed before
+     * the later edit was made, undoes it. That is how a file deleted forever
+     * from the Trash, while the move that put it there was still being
+     * written, came back. So each write waits for the one before it, and a
+     * read that has to fetch the record waits for its write too: see
+     * `openDirById`.
+     */
+    writing = new Map();
     historyLimit;
     maxEntries;
     maxPathChars;
@@ -15921,10 +16007,7 @@ class VfsNamespace {
         const parentPath = dirname(target);
         await this.mkdir(parentPath, { recursive: true });
         const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
-        const { manifest, size } = await this.deps.content.write(bytes, {
-            name,
-            type: opts.type ?? contentTypeFor(name),
-        });
+        const { manifest, size } = await this.deps.content.write(bytes, { name, type: opts.type ?? contentTypeFor(name) }, { onProgress: opts.onProgress });
         const parent = await this.openDir(parentPath);
         const prior = entryIn(parent.node, name);
         if (prior?.kind === "dir")
@@ -16211,8 +16294,11 @@ class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs edit the same directory, last-writer-wins at the personal space can
-     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * tabs or devices edit the same directory, the personal space keeps
+     * whichever put arrives last (a VFS write sends no HLC, and the space
+     * applies puts of one key in arrival order), which can leave a child whose
+     * parent entry lost the race. The per-record write queue (`writing`) only
+     * orders writes within one tab. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -16370,7 +16456,41 @@ class VfsNamespace {
         // every concurrent reader to miss and fire its own request for the same
         // record — which is how loading one project turned into thousands of
         // identical `vfs/d/<id>` fetches, most of them in flight at once.
-        const pending = (async () => {
+        // Reads `pending` only after its first `await`: before that, the const is not yet initialised.
+        const load = async () => {
+            // Not while a write of this record is still in flight: see
+            // `writing`. Our own writes echo back over the personal-space
+            // socket, and `watch` drops the record each one names, so a read
+            // can miss with the write still on its way - and the store would
+            // answer with the copy from BEFORE it. An edit made to that copy
+            // is queued behind the write, and then stored over it. So wait
+            // for the latest write queued, which waits on every one before it,
+            // to land or fail - and then for any queued while this read
+            // waited, since the one it waited for may have failed with that
+            // one still on its way. A record with no write in flight is
+            // fetched at once.
+            let awaited;
+            for (let inFlight = this.writing.get(id); inFlight && inFlight !== awaited; inFlight = this.writing.get(id)) {
+                awaited = inFlight;
+                await inFlight.catch(() => { });
+            }
+            if (awaited) {
+                // A write that landed put the record it wrote back in the
+                // cache, and the next edit of this directory is made to that.
+                // Answer with it rather than fetch a second copy: two copies
+                // of one record, each edited and written, undo each other's
+                // edits. When the cache holds nothing else - the write failed,
+                // or a change since has dropped the record - ask the store.
+                const now = this.cache.get(id);
+                if (now && now !== pending)
+                    return now;
+                // Empty, when the write failed: it dropped what the cache held,
+                // and after an echo that was this very read. Put it back before
+                // asking the store, so a read that comes in meanwhile shares
+                // this copy instead of fetching a second one.
+                if (!now)
+                    this.cache.set(id, pending);
+            }
             const raw = await this.deps.store.get(dirKey(id));
             // An absent record is an EMPTY directory, not an error: the root
             // exists before anything has been written to it, and a directory is
@@ -16396,7 +16516,8 @@ class VfsNamespace {
                 throw err;
             }
             return this.readRecord(id, key, value, path);
-        })().catch((err) => {
+        };
+        const pending = load().catch((err) => {
             // A failed read must not be remembered, or one blip poisons the
             // directory for the life of the session.
             if (this.cache.get(id) === pending)
@@ -16482,24 +16603,14 @@ class VfsNamespace {
             if (Object.hasOwn(dir.node.entries, name))
                 delete dir.hidden[name];
         }
-        const stored = Object.keys(dir.hidden).length
-            ? { ...dir.node, entries: Object.assign(Object.create(null), dir.hidden, dir.node.entries) }
-            : dir.node;
+        // Not sent until any earlier write of this record has landed: see
+        // `writing`. Whether that one worked or not, this one still goes.
+        const before = this.writing.get(dir.id);
+        const send = () => this.writeRecord(dir);
+        const write = before ? before.then(send, send) : send();
+        this.writing.set(dir.id, write);
         try {
-            let sealed;
-            try {
-                sealed = await seal(dir.key, stored);
-            }
-            catch (err) {
-                // JSON.stringify's own failures: a value too deeply nested to
-                // write. Reading drops those from a stored record, so this is
-                // what the write itself was given.
-                if (!(err instanceof RangeError || err instanceof TypeError))
-                    throw err;
-                const where = dir.path ?? `the directory stored as record ${printable(dir.id, 40)}`;
-                throw new VfsConflictError(`cannot write to ${where}: it would hold a value nested too deeply to store`);
-            }
-            await this.deps.store.put(dirKey(dir.id), sealed);
+            await write;
         }
         catch (err) {
             // The edit above was made in place, on the very object the cache
@@ -16507,11 +16618,48 @@ class VfsNamespace {
             // change the store never took - a deleted file gone from every
             // listing while it is still stored, and a retry told it does not
             // exist. Drop it, so the next read asks the store.
-            this.cache.delete(dir.id);
+            //
+            // Unless a later write of this record is already queued. It
+            // seals the record as it stands when it is sent, this edit
+            // included, so the cache shows what is about to be stored, and
+            // dropping it would only send readers to the store for an older
+            // copy. If that write fails too, it drops the cache itself.
+            if (this.writing.get(dir.id) === write)
+                this.cache.delete(dir.id);
             throw err;
         }
+        finally {
+            if (this.writing.get(dir.id) === write)
+                this.writing.delete(dir.id);
+        }
         this.cache.set(dir.id, Promise.resolve(dir));
     }
+    /**
+     * Seal a directory record as it stands NOW and put it in the store.
+     *
+     * Read at the moment of sending, not when the edit was made, so a write
+     * that waited behind another carries every edit made to the record by
+     * then, its own included.
+     */
+    async writeRecord(dir) {
+        const stored = Object.keys(dir.hidden).length
+            ? { ...dir.node, entries: Object.assign(Object.create(null), dir.hidden, dir.node.entries) }
+            : dir.node;
+        let sealed;
+        try {
+            sealed = await seal(dir.key, stored);
+        }
+        catch (err) {
+            // JSON.stringify's own failures: a value too deeply nested to
+            // write. Reading drops those from a stored record, so this is
+            // what the write itself was given.
+            if (!(err instanceof RangeError || err instanceof TypeError))
+                throw err;
+            const where = dir.path ?? `the directory stored as record ${printable(dir.id, 40)}`;
+            throw new VfsConflictError(`cannot write to ${where}: it would hold a value nested too deeply to store`);
+        }
+        await this.deps.store.put(dirKey(dir.id), sealed);
+    }
     async createDir(parentPath, name) {
         assertValidName(name);
         const parent = await this.openDir(parentPath);
@@ -19488,9 +19636,9 @@ class Client {
                 // GC. `storage.writeFile` would additionally index the manifest
                 // in the space — a second, diverging source of truth for a file
                 // whose handle the VFS already holds.
-                write: async (data, meta) => {
+                write: async (data, meta, opts) => {
                     const space = await resolveContentSpace();
-                    const { manifest, stat } = await space.putFile(data, { name: meta.name, type: meta.type });
+                    const { manifest, stat } = await space.putFile(data, { name: meta.name, type: meta.type }, { onProgress: opts?.onProgress });
                     return { manifest, size: stat.size };
                 },
                 // Reads go through the manifest alone — no space needed. That is