@muhkoo/connect 0.10.0-alpha.0 → 0.10.2-alpha.0

package/dist/connect.d.ts

@@ -1464,6 +1464,17 @@ interface ShardClientOptions {
      * block to peers. Best-effort — any failure falls through to origin.
      */
     peers?: PeerBlockSource;
+    /**
+     * When true, {@link ShardClient.putShard} returns as soon as the shard is
+     * written to {@link cache} and announced to {@link peers} — the origin PUT is
+     * fired in the BACKGROUND rather than awaited. This makes a large write's
+     * manifest available immediately (so a peer/worker can start pulling the
+     * shards over P2P right away) while origin catches up as a durable fallback.
+     * On a background-PUT failure the shard is handed to {@link deferUpload} (if
+     * present) for replay. Requires a {@link cache} so the bytes survive locally
+     * until the background upload lands. No-op without a cache.
+     */
+    backgroundUpload?: boolean;
 }
 /**
  * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
@@ -1477,6 +1488,7 @@ declare class ShardClient {
     private readonly cache?;
     private readonly deferUpload?;
     private readonly peers?;
+    private readonly backgroundUpload;
     constructor(opts: ShardClientOptions);
     /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
     urlForHash(hash: string): string;
@@ -1489,6 +1501,16 @@ declare class ShardClient {
     putShard(hash: string, bytes: Uint8Array): Promise<{
         dedup: boolean;
     }>;
+    private bgActive;
+    private readonly bgQueue;
+    private static readonly BG_CONCURRENCY;
+    /** Queue a shard's origin PUT to run in the background under a concurrency
+     *  cap. Bytes are re-read from {@link cache} at upload time (not held in the
+     *  queue) so a large file's backlog doesn't pin a second copy in memory. */
+    private enqueueBackgroundUpload;
+    /** PUT the shard bytes to origin, verifying the server accepted them.
+     *  Used by the background-upload path; throws on network/HTTP failure. */
+    private uploadToOrigin;
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
@@ -4109,6 +4131,13 @@ declare class Space {
     }>): Promise<number>;
     putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata, opts?: {
         onProgress?: (completed: number, total: number) => void;
+        /**
+         * Return the manifest as soon as shards are cached + announced to the
+         * mesh, uploading to origin in the background. Lets a peer/worker start
+         * pulling the file over P2P immediately instead of waiting out the full
+         * origin upload. Requires an offline cache (browser); ignored without.
+         */
+        backgroundUpload?: boolean;
     }): Promise<{
         manifest: FileManifest;
         stat: FileStat;

package/dist/server/index.js

@@ -2976,7 +2976,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.10.0-alpha.0";
+const VERSION = "0.10.1-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -5523,6 +5523,7 @@ class ShardClient {
     cache;
     deferUpload;
     peers;
+    backgroundUpload;
     constructor(opts) {
         if (!opts?.baseUrl)
             throw new Error("ShardClient: `baseUrl` is required");
@@ -5541,6 +5542,10 @@ class ShardClient {
         this.cache = opts.cache;
         this.deferUpload = opts.deferUpload;
         this.peers = opts.peers;
+        // Background upload needs a local cache to hold the bytes until the PUT
+        // lands; without one it would race the reader against a not-yet-uploaded
+        // origin, so we quietly ignore the flag when there's no cache.
+        this.backgroundUpload = Boolean(opts.backgroundUpload && opts.cache);
     }
     /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
     urlForHash(hash) {
@@ -5562,6 +5567,14 @@ class ShardClient {
         // Tell the swarm we now hold this block, so peers can pull it from us.
         if (this.peers)
             this.peers.announce(hash);
+        // Background mode: the bytes are cached + announced, so return now and let
+        // origin catch up asynchronously (a peer can already pull this block). The
+        // PUT is enqueued through a bounded worker pool so a big file doesn't fire
+        // hundreds of concurrent uploads at once.
+        if (this.backgroundUpload) {
+            this.enqueueBackgroundUpload(url, hash);
+            return { dedup: false };
+        }
         let response;
         try {
             response = await this.fetchFn(url, {
@@ -5594,6 +5607,56 @@ class ShardClient {
         }
         return { dedup };
     }
+    // ── bounded background-upload pool (backgroundUpload mode) ──
+    bgActive = 0;
+    bgQueue = [];
+    static BG_CONCURRENCY = 6;
+    /** Queue a shard's origin PUT to run in the background under a concurrency
+     *  cap. Bytes are re-read from {@link cache} at upload time (not held in the
+     *  queue) so a large file's backlog doesn't pin a second copy in memory. */
+    enqueueBackgroundUpload(url, hash) {
+        const run = async () => {
+            this.bgActive++;
+            try {
+                const bytes = this.cache ? await this.cache.get(hash) : null;
+                if (bytes)
+                    await this.uploadToOrigin(url, hash, bytes);
+            }
+            catch {
+                // Origin unreachable/failed — queue for replay if we can; otherwise
+                // the block is still cached + peer-served, so a later re-PUT covers it.
+                if (this.deferUpload) {
+                    try {
+                        await this.deferUpload(hash);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            finally {
+                this.bgActive--;
+                const next = this.bgQueue.shift();
+                if (next)
+                    next();
+            }
+        };
+        if (this.bgActive < ShardClient.BG_CONCURRENCY)
+            void run();
+        else
+            this.bgQueue.push(() => void run());
+    }
+    /** PUT the shard bytes to origin, verifying the server accepted them.
+     *  Used by the background-upload path; throws on network/HTTP failure. */
+    async uploadToOrigin(url, hash, bytes) {
+        const response = await this.fetchFn(url, {
+            method: "PUT",
+            headers: { "content-type": "application/octet-stream" },
+            body: bytes,
+        });
+        if (!response.ok) {
+            const text = await safeText(response);
+            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
+        }
+    }
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
@@ -7267,12 +7330,13 @@ class Space {
     }
     // -- room-scoped files (no websocket needed) -------------------------------
     async putFile(file, metadata, opts = {}) {
-        return this.fileStorage().writeFileToShards({ data: file, metadata, onProgress: opts.onProgress });
+        return this.fileStorage(opts.backgroundUpload)
+            .writeFileToShards({ data: file, metadata, onProgress: opts.onProgress });
     }
     async getFile(manifest) {
         return this.fileStorage().readFileFromShards(manifest);
     }
-    fileStorage() {
+    fileStorage(backgroundUpload = false) {
         // Global, content-addressed shard store — same store `client.storage`
         // uses, so a file shared into a channel resolves from anywhere by
         // manifest. (Shards are encrypted ciphertext; the manifest is the
@@ -7284,6 +7348,7 @@ class Space {
             cache: this.deps.shardCache,
             deferUpload: this.deps.deferShardUpload,
             peers: this.peerNet?.exchange,
+            backgroundUpload,
         });
         return new FileStorage({ shards });
     }