@muhkoo/connect 0.14.0-alpha.2 → 0.14.0-alpha.4

package/dist/connect.d.ts

@@ -1452,6 +1452,13 @@ interface ShardClientOptions {
      * just-uploaded file reads back offline. See {@link ShardByteCache}.
      */
     cache?: ShardByteCache;
+    /**
+     * Coalesce concurrent origin reads into `POST {pathPrefix}/batch`. On by
+     * default: it is what keeps opening a project from costing one request per
+     * shard. Set false to force one-at-a-time — useful against a server without
+     * the route, though that is detected and handled automatically.
+     */
+    batchShards?: boolean;
     /**
      * Called when a PUT can't reach the network (offline). Lets the caller queue
      * the upload for replay on reconnect; the bytes are already in {@link cache}
@@ -1486,6 +1493,11 @@ declare class ShardClient {
     private readonly pathPrefix;
     private readonly fetchFn;
     private readonly cache?;
+    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    private pendingShards;
+    private batchTimer;
+    /** False once the server is known not to have the batch route. */
+    private batchSupported;
     private readonly deferUpload?;
     private readonly peers?;
     private readonly backgroundUpload;
@@ -1516,9 +1528,31 @@ declare class ShardClient {
      * `null` for 404 so callers can distinguish "missing" from "errored".
      */
     getShard(hash: string): Promise<Uint8Array | null>;
+    /**
+     * Fetch from origin, COALESCING concurrent requests into one batch.
+     *
+     * A shard is not a file. A project is thousands of small source modules,
+     * each split into shards, so reading one at a time made opening a project
+     * cost thousands of requests — 2,086 for a 519-file project. Latency, not
+     * bytes, is what that spends: Chromium took 18.4s over those requests and
+     * Brave, which filters every one, took 37.5s for identical work. Batching
+     * collapses whatever is in flight at the same moment into a single POST,
+     * which is why it helps most exactly where it hurt most.
+     *
+     * Callers are unchanged: `getShard` still asks for one shard and gets one
+     * shard. The window is a few milliseconds — long enough to gather the reads
+     * a concurrent walk issues together, short enough not to be felt by a lone
+     * read.
+     *
+     * 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.
+     */
+    private fetchFromOrigin;
+    /** Send one batch of whatever has accumulated, and settle those callers. */
+    private flushShardBatch;
     /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
      *  cache is present, so RS recovery can proceed); throws otherwise. */
-    private fetchFromOrigin;
+    private fetchOneFromOrigin;
     /**
      * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
      * dedup-rewrite. The server can implement this as a HEAD or return a small

package/dist/server/index.js

@@ -3235,7 +3235,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.14.0-alpha.2";
+const VERSION = "0.14.0-alpha.4";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -7207,6 +7207,23 @@ class ReedSolomonCodec {
  *                             skip a PUT they'd otherwise dedup-rewrite. The
  *                             server can ignore the optimization if it wants.
  */
+/**
+ * How long concurrent shard reads are gathered before one batch is sent.
+ *
+ * Long enough to collect what a concurrent directory walk issues at the same
+ * moment, short enough that a single read does not feel it.
+ */
+const SHARD_BATCH_WINDOW_MS = 6;
+/** Hashes per batch. Must not exceed what the server will accept. */
+const SHARD_BATCH_MAX = 256;
+/** Decode base64 without `atob`'s per-character loop cost on large shards. */
+function bytesFromBase64(b64) {
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
 /** Peer head-start (ms) before origin joins the race in {@link ShardClient.getShard}. */
 const HEDGE_MS = 500;
 /**
@@ -7226,6 +7243,11 @@ class ShardClient {
     pathPrefix;
     fetchFn;
     cache;
+    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    pendingShards;
+    batchTimer;
+    /** False once the server is known not to have the batch route. */
+    batchSupported;
     deferUpload;
     peers;
     backgroundUpload;
@@ -7245,6 +7267,11 @@ class ShardClient {
         }
         this.fetchFn = f.bind(globalThis);
         this.cache = opts.cache;
+        // Coalescing state. `batchSupported` latches false against a deployment
+        // without the batch route, so we degrade once rather than per request.
+        this.pendingShards = new Map();
+        this.batchTimer = null;
+        this.batchSupported = opts.batchShards !== false;
         this.deferUpload = opts.deferUpload;
         this.peers = opts.peers;
         // Background upload needs a local cache to hold the bytes until the PUT
@@ -7421,9 +7448,124 @@ class ShardClient {
             }, () => startOrigin());
         });
     }
+    /**
+     * Fetch from origin, COALESCING concurrent requests into one batch.
+     *
+     * A shard is not a file. A project is thousands of small source modules,
+     * each split into shards, so reading one at a time made opening a project
+     * cost thousands of requests — 2,086 for a 519-file project. Latency, not
+     * bytes, is what that spends: Chromium took 18.4s over those requests and
+     * Brave, which filters every one, took 37.5s for identical work. Batching
+     * collapses whatever is in flight at the same moment into a single POST,
+     * which is why it helps most exactly where it hurt most.
+     *
+     * Callers are unchanged: `getShard` still asks for one shard and gets one
+     * shard. The window is a few milliseconds — long enough to gather the reads
+     * a concurrent walk issues together, short enough not to be felt by a lone
+     * read.
+     *
+     * 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) {
+        if (!this.batchSupported)
+            return this.fetchOneFromOrigin(hash);
+        return new Promise((resolve, reject) => {
+            const waiting = this.pendingShards.get(hash);
+            if (waiting) {
+                waiting.push({ resolve, reject });
+                return;
+            }
+            this.pendingShards.set(hash, [{ resolve, reject }]);
+            if (this.batchTimer === null) {
+                this.batchTimer = setTimeout(() => { void this.flushShardBatch(); }, SHARD_BATCH_WINDOW_MS);
+            }
+        });
+    }
+    /** Send one batch of whatever has accumulated, and settle those callers. */
+    async flushShardBatch() {
+        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);
+            this.pendingShards.delete(h);
+            return [h, w];
+        });
+        // Anything over the cap 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);
+        }
+        let shards;
+        try {
+            const res = await this.fetchFn(`${this.baseUrl}${this.pathPrefix}/batch`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ hashes }),
+            });
+            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.
+                this.batchSupported = false;
+                for (const [h, ws] of waiters) {
+                    this.fetchOneFromOrigin(h).then((b) => ws.forEach((w) => w.resolve(b)), (e) => ws.forEach((w) => w.reject(e)));
+                }
+                return;
+            }
+            if (!res.ok)
+                throw new Error(`ShardClient batch failed (${res.status}): ${await safeText(res)}`);
+            const parsed = await res.json().catch(() => null);
+            // A 200 is not proof the batch route exists. A catch-all handler, a
+            // proxy, or an older deployment can answer this POST with something
+            // else entirely, and trusting the shape would resolve every hash to
+            // `null` — reads silently returning "missing" for shards that are
+            // right there. Anything not shaped like a batch reply is treated as
+            // "no batch route", exactly like a 404.
+            const candidate = parsed?.shards;
+            if (!candidate || typeof candidate !== "object") {
+                this.batchSupported = false;
+                for (const [h, ws] of waiters) {
+                    this.fetchOneFromOrigin(h).then((b) => ws.forEach((w) => w.resolve(b)), (e) => ws.forEach((w) => w.reject(e)));
+                }
+                return;
+            }
+            shards = candidate;
+        }
+        catch (err) {
+            // Offline with a cache behaves as it does for a single fetch: report
+            // absence so Reed-Solomon recovery can still be attempted.
+            for (const [, ws] of waiters) {
+                if (this.cache)
+                    ws.forEach((w) => w.resolve(null));
+                else
+                    ws.forEach((w) => w.reject(err));
+            }
+            return;
+        }
+        for (const [hash, ws] of waiters) {
+            const b64 = shards[hash];
+            if (typeof b64 !== "string") {
+                ws.forEach((w) => w.resolve(null));
+                continue;
+            }
+            let bytes;
+            try {
+                bytes = bytesFromBase64(b64);
+            }
+            catch (e) {
+                ws.forEach((w) => w.reject(e));
+                continue;
+            }
+            if (this.cache)
+                void this.cache.put(hash, bytes);
+            ws.forEach((w) => w.resolve(bytes));
+        }
+    }
     /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
      *  cache is present, so RS recovery can proceed); throws otherwise. */
-    async fetchFromOrigin(hash) {
+    async fetchOneFromOrigin(hash) {
         const url = this.urlForHash(hash);
         let response;
         try {