@coderook/cli 0.12.0 → 0.14.0

package/dist/desktop-app/src/main/upload.js

@@ -20,9 +20,56 @@ const faults_js_1 = require("./faults.js");
 const identify_js_1 = require("./identify.js");
 const worktree_js_1 = require("./worktree.js");
 const publish_name_js_1 = require("./publish_name.js");
+const compress_js_1 = require("./compress.js");
+const cbx_js_1 = require("./cbx.js");
+const profile_js_1 = require("./profile.js");
+const solid_js_1 = require("./solid.js");
+const retry_js_1 = require("./retry.js");
+const staging_js_1 = require("./staging.js");
 /** Above this the API insists on a multipart session. */
 const DIRECT_LIMIT = 95 * 1024 * 1024;
+/*
+  Above this a file is cut into content-defined chunks instead of being sent
+  whole. Below it the round trips cost more than the chunking saves — the
+  chunker's own average chunk is eight megabytes, so a smaller file would
+  usually come out as one chunk anyway.
+*/
+const CHUNK_THRESHOLD = 16 * 1024 * 1024;
+/*
+  How many files are sent at once. Six is the limit browsers settled on per
+  host for the same reason: enough to keep the link busy through the latency
+  of each request, few enough that a slow service is not buried by a client.
+*/
+const UPLOAD_LANES = 6;
+/*
+  Below this a file travels with others in one request rather than alone.
+
+  Measured rather than guessed, twice. The first number came from a source
+  folder where ninety-six percent of files were under sixty-four kilobytes.
+  A four and a half gigabyte game then showed the opposite shape: eight
+  hundred files of three hundred kilobytes per section, each just above that
+  line and so each paying its own round trip.
+
+  What the game measured is the reason for the number. Every request costs
+  about six hundred and thirty milliseconds before any bytes move, and the
+  lane carries roughly 0.79 MB/s. So a three hundred kilobyte file spends
+  sixty percent of its time on overhead and a seven megabyte file spends
+  seven. The line belongs where the overhead stops dominating, which is a few
+  megabytes and not a few kilobytes.
+
+  Four megabytes was the first attempt and it overshot. Measured on the same
+  game twice: four hundred kilobyte files went from 1.80 to 3.24 MB/s when
+  batched, while 1.3 megabyte files went from 4.43 down to 3.88 — because
+  three concurrent batches move less than six concurrent requests once a file
+  is large enough that transfer, not overhead, dominates. The crossover is
+  around a megabyte.
+*/
+const BATCH_FILE_LIMIT = 1024 * 1024;
+/** How much one batch may carry, and how many objects it may name. */
+const BATCH_BYTES = 24 * 1024 * 1024;
+const BATCH_COUNT = 256;
 const PART_SIZE = 32 * 1024 * 1024;
+/* Retrying lives in retry.ts; the downloader needs the same rule. */
 const MEDIA_TYPES = {
     ".css": "text/css",
     ".csv": "text/csv",
@@ -68,6 +115,12 @@ class Uploader {
     credentials;
     aborted = false;
     controller = new AbortController();
+    /** Null until the service has been asked; see gzipAllowed. */
+    gzipSupported = null;
+    /** Null until the service has been asked; see chunkingAllowed. */
+    chunkingSupported = null;
+    /** Null until the service has been asked; see packingAllowed. */
+    packingSupported = null;
     constructor(credentials) {
         this.credentials = credentials;
     }
@@ -79,7 +132,54 @@ class Uploader {
         if (this.aborted)
             throw new UploadCancelled();
     }
+    /**
+     * One request, repeated while repeating it might help.
+     *
+     * Everything the uploader sends passes through here, which is the only
+     * reason a single change can cover all of it. The alternative — retrying at
+     * each call site — is where the previous absence of retries came from:
+     * every site could see that its own operation was safe to repeat, and no
+     * site was responsible for repeating it.
+     */
     async call(route, init) {
+        let wait = retry_js_1.RETRY_FIRST_WAIT_MS;
+        for (let attempt = 1;; attempt += 1) {
+            // Cancellation beats a pending retry: a cancelled upload has to stop
+            // waiting rather than serve out its backoff first.
+            this.check();
+            try {
+                return await this.attempt(route, init);
+            }
+            catch (error) {
+                // Its own cancellation first: `worthRetrying` knows nothing of it.
+                if (error instanceof UploadCancelled)
+                    throw error;
+                if (attempt >= retry_js_1.RETRY_ATTEMPTS || !(0, retry_js_1.worthRetrying)(error))
+                    throw error;
+                await this.pause(wait);
+                wait *= 2;
+            }
+        }
+    }
+    /**
+     * Wait, unless the upload is cancelled while waiting.
+     *
+     * Jittered, because the lanes fail together. Six requests against a gateway
+     * that has just gone away all fail within milliseconds of each other, and
+     * six retries timed from those failures would arrive together too — which
+     * turns one outage into a second one at precisely the wrong moment.
+     */
+    async pause(ms) {
+        try {
+            await (0, retry_js_1.pauseFor)(this.controller.signal, ms);
+        }
+        catch {
+            // The signal aborted mid-wait; say so in this side's own terms.
+            throw new UploadCancelled();
+        }
+    }
+    /** A single attempt. Everything about repeating it lives in `call`. */
+    async attempt(route, init) {
         const token = await this.credentials.token();
         if (!token)
             throw new Error("Sign in again before uploading");
@@ -96,28 +196,72 @@ class Uploader {
             signal: this.controller.signal,
         });
         const text = await response.text();
-        const body = text ? JSON.parse(text) : {};
         if (!response.ok) {
-            const message = body?.error?.message ?? `${route} failed (${response.status})`;
+            /*
+              Parsed only when it looks like JSON. An edge failure serves an HTML
+              page, and parsing that unconditionally raised `Unexpected token '<'`
+              — which names the parser rather than the 502 behind it, and sends you
+              looking in entirely the wrong place.
+            */
+            let body = {};
+            if (text.trimStart().startsWith("{")) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = {};
+                }
+            }
+            const message = body.error?.message ?? `${route} failed (${response.status})`;
             /*
               The service says what kind of failure this is, and callers need that
               to say anything useful — "someone else saved first" deserves a
-              different suggestion from "the disk is full". Carrying the code on
-              the error keeps them from having to match on wording.
+              different suggestion from "the disk is full". Carrying the code on the
+              error keeps them from matching on wording, and is what lets
+              `worthRetrying` tell a refusal apart from a hiccup.
             */
             throw Object.assign(new Error(message), {
-                code: typeof body?.error?.code === "string" ? body.error.code : "",
+                code: typeof body.error?.code === "string" ? body.error.code : "",
                 status: response.status,
             });
         }
-        return body;
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            /*
+              A 200 carrying something that is not JSON is not an answer — it is
+              almost always an edge page served in place of the service. Thrown
+              without a status so it is treated as a connection that produced
+              nothing, which is what it is.
+            */
+            throw new Error(`${route} returned a malformed reply`);
+        }
     }
     async run(request, report) {
         // A version is a snapshot, not a delta, so it has to name every file in
         // the project — not merely the ones being sent this time. Anything
         // unchanged keeps the object the previous version already pointed at.
         const rules = await (0, worktree_js_1.readRules)(request.localPath);
-        const everything = await (0, worktree_js_1.changedFiles)(request.localPath, rules, null);
+        /*
+          Surveyed, not listed.
+    
+          `changedFiles` stops after twenty thousand rows, which is right for
+          something a person scrolls through and was also deciding what got
+          uploaded — so a project past that many files was silently backed up in
+          part, with nothing anywhere saying the rest existed. The survey has no
+          cap and reads nothing but sizes, which is what makes running it over
+          everything affordable.
+    
+          `onDiskNow` in particular has to be complete: it is what tells a file
+          that is still here from one this workspace deliberately removed, and a
+          truncated version of it would propose deleting everything the walk did
+          not reach.
+        */
+        const everything = await (0, profile_js_1.timed)("survey the project", () => (0, worktree_js_1.surveyFiles)(request.localPath, rules));
+        (0, profile_js_1.counted)("files surveyed", everything.length);
         const ticked = new Set(request.include);
         if (!ticked.size)
             throw new Error("Nothing is selected to upload");
@@ -194,11 +338,32 @@ class Uploader {
                 percent: Math.round((index / sending.length) * 20),
                 bytesPerSecond: 0,
             });
+            /*
+              Hashing is the first thing that opens the file, and opening is what
+              fails on a file another program holds — a database in use, a browser
+              profile's LOCK, an antivirus mid-scan. On Windows those still answer
+              stat() perfectly well, so the check three lines above lets them
+              through and the read below was the one that actually broke.
+      
+              It was unguarded, so the person got a raw "EBUSY: resource busy or
+              locked" naming a path they never chose to think about, instead of the
+              sentence this code already writes for exactly this situation. The
+              outcome was always going to be a refusal; what was missing was it
+              being legible.
+            */
+            let digest;
+            try {
+                digest = await (0, profile_js_1.timed)("hash files", () => digestOf(full));
+            }
+            catch {
+                vanished.push(file.path);
+                continue;
+            }
             declarations.push({
                 path: file.path,
                 full,
                 size,
-                sha256: await digestOf(full),
+                sha256: digest,
                 mediaType: mediaTypeOf(file.path),
             });
             totalBytes += size;
@@ -237,70 +402,430 @@ class Uploader {
                 repositoryId = existing;
             }
         }
-        // 3. Send the objects.
+        /*
+          Sent in sections, not in one attempt.
+    
+          A section is a bounded amount of work — a few hundred megabytes, or a few
+          thousand files, whichever comes first — and each one finishes before the
+          next begins. A small project is a single section and behaves exactly as
+          it did; a thirty gigabyte one is many, and holds no more at a time than
+          the small one does.
+    
+          The sections are planned from the survey rather than discovered as the
+          upload goes, so the size and shape of the work are known before a byte
+          moves, and a resumed upload plans the same sections in the same order.
+        */
+        const allDeclarations = declarations;
+        const declarationByPath = new Map(allDeclarations.map((one) => [one.path, one]));
+        const sections = (0, staging_js_1.planSections)(allDeclarations.map((one) => ({ path: one.path, size: one.size })));
+        (0, profile_js_1.counted)("sections planned", sections.length);
         const uploaded = [];
         let sentBytes = 0;
+        /*
+          Bytes that actually travelled, which is not the same as bytes accounted
+          for: a file the service already held advances the progress bar and costs
+          nothing. Reporting the rate from the second number makes a fast, mostly
+          reused save look like a stalled one.
+        */
+        let transferred = 0;
         /*
           Files whose content the service already had. Counted apart from what was
           sent, because reporting them as sent would overstate the work and hide
           the thing worth knowing: an interrupted save costs nothing to finish.
         */
         let alreadyOnAccount = 0;
-        const startedAt = Date.now();
+        /*
+          How far each lane is through the file it currently holds.
+    
+          With one worker, "everything finished plus how far I am" was simply
+          true. With six it is not: each lane added its own offset to the same
+          shared total, so the reported figure jumped between six different
+          answers and the progress bar ran backwards. Keeping the offsets apart
+          and summing them makes the total the sum of real work again.
+        */
+        const inFlight = new Map();
+        const progressBytes = () => {
+            let total = sentBytes;
+            for (const offset of inFlight.values())
+                total += offset;
+            return total;
+        };
+        /*
+          How fast the thing on screen is moving.
+    
+          Two faults, and they compounded. The rate was `transferred` over the
+          whole elapsed time, while the bar beside it showed `progressBytes()` —
+          different counters measuring different things. `transferred` only moves
+          when a file *finishes*, so a single large file reported a rate of
+          roughly nothing for its entire transfer and then jumped at the end: one
+          real upload sat at "152 MB of 1.1 GB · 10 B/s", which is not a slow
+          upload, it is a number describing something else.
+    
+          And dividing by the time since the start made it a lifetime average, so
+          a slow first minute went on dragging the figure down long after the
+          link had recovered — the opposite of what somebody watching it wants to
+          know, which is whether it is moving *now*.
+    
+          So: the same counter the bar uses, over a short trailing window.
+        */
+        const RATE_WINDOW_MS = 5000;
+        const samples = [];
         const rate = () => {
-            const seconds = (Date.now() - startedAt) / 1000;
-            return seconds > 0.2 ? Math.round(sentBytes / seconds) : 0;
+            const now = Date.now();
+            const bytes = progressBytes();
+            const last = samples[samples.length - 1];
+            // Sampled rather than recorded per call: this is asked once per report,
+            // and reports arrive per file, which for small files is thousands a
+            // second.
+            if (!last || now - last.at >= 250)
+                samples.push({ at: now, bytes });
+            while (samples.length > 2 && now - samples[0].at > RATE_WINDOW_MS) {
+                samples.shift();
+            }
+            const oldest = samples[0];
+            const seconds = (now - oldest.at) / 1000;
+            /*
+              Nothing until there is something to divide. Answering zero keeps the
+              window quiet rather than showing a figure computed from a fraction of
+              a second, which reads as a stall on an upload that has barely begun.
+            */
+            if (seconds < 0.5)
+                return 0;
+            return Math.max(0, Math.round((bytes - oldest.bytes) / seconds));
         };
-        for (const [index, declaration] of declarations.entries()) {
-            this.check();
+        /*
+          Two pipelines, not one queue.
+    
+          The sections were run one after another, and they do not compete for the
+          same thing: a section of small files spends about three seconds per batch
+          waiting on the service — measured, and independent of how many objects
+          the batch holds — while a section of large files is limited by the link.
+          One leaves bandwidth idle; the other cannot use any more.
+    
+          So they run together. Each pipeline takes the next section of its own
+          kind, and when one runs out it stops rather than stealing from the other,
+          because that would put two bandwidth-bound pipelines against a link that
+          is already saturated by one.
+        */
+        /*
+          Classified by where the bytes are, not by whether every file qualifies.
+    
+          Requiring every file to be small put one large file in charge of a whole
+          section: on a four gigabyte game it left three sections in one pipeline
+          and eighteen in the other, which is not two pipelines. Judging by the
+          share of bytes that will be batched splits the same game nine and twelve.
+        */
+        const smallShare = (one) => one.files
+            .filter((file) => file.size <= BATCH_FILE_LIMIT)
+            .reduce((sum, file) => sum + file.size, 0) / Math.max(one.bytes, 1);
+        const batchy = sections.filter((one) => smallShare(one) >= 0.5);
+        const heavy = sections.filter((one) => smallShare(one) < 0.5);
+        (0, profile_js_1.counted)("sections batched", batchy.length);
+        (0, profile_js_1.counted)("sections heavy", heavy.length);
+        const runSection = async (section) => {
+            const declarations = section.files.map((file) => declarationByPath.get(file.path));
             report({
                 stage: "upload",
-                files: index,
-                totalFiles: declarations.length,
-                bytes: sentBytes,
+                files: 0,
+                totalFiles: allDeclarations.length,
+                bytes: progressBytes(),
                 totalBytes,
-                path: declaration.path,
-                percent: 20 + Math.round((sentBytes / Math.max(totalBytes, 1)) * 72),
+                path: `Section ${section.index + 1} of ${sections.length}`,
+                percent: 20 + Math.round((progressBytes() / Math.max(totalBytes, 1)) * 72),
                 bytesPerSecond: rate(),
             });
             /*
-              Content the service already holds does not need sending. Asking costs
-              one round trip and saves the whole file — which after an interrupted
-              save is the difference between re-uploading a project and re-uploading
-              nothing.
+            Ask once what the account already holds.
+      
+            This used to be one request per file, immediately before deciding
+            whether to send it — nine thousand files meant nine thousand serial
+            round trips before a single byte moved, and on a folder of that size the
+            asking took longer than the transfer. The answer per digest is a boolean
+            and an identifier, so the whole question fits in one request.
+          */
+            const alreadyHeld = await (0, profile_js_1.timed)("ask what is already held", () => this.storedInBulk(repositoryId, declarations.map((one) => one.sha256)));
+            /*
+              The small files go first, packed together.
+        
+              They are the overwhelming majority by count and almost nothing by size,
+              so sending them one per request is where an upload spends its time. What
+              is left after this — the large files — is where bandwidth actually
+              matters, and those still go one per request through the lanes below.
+            */
+            const missing = declarations.filter((one) => !alreadyHeld.has(one.sha256));
+            const smallOnes = missing.filter((one) => one.size <= BATCH_FILE_LIMIT);
+            // 3. Send the objects.
+            /*
+              What was sent, in whichever shape it was sent. A small file is one
+              object; a large one is an ordered list of chunks and the digest of the
+              whole, which is what gives it an identity when no single object holds it.
             */
-            const alreadyStored = await this.findStored(repositoryId, declaration);
-            if (alreadyStored)
-                alreadyOnAccount += 1;
-            const result = alreadyStored ??
-                (declaration.size <= DIRECT_LIMIT
-                    ? await this.putDirect(repositoryId, declaration).catch((error) => {
-                        // Naming the file turns "it failed" into something actionable.
-                        const reason = error instanceof Error ? error.message : String(error);
-                        throw new Error(`${declaration.path}: ${reason}`);
-                    })
-                    : await this.putMultipart(repositoryId, declaration, (offset) => {
+            const batched = new Map();
+            /*
+              Files that went up inside a solid pack. Kept apart from `batched` because
+              they are named differently in the version: a slice of a pack rather than
+              an object of their own.
+            */
+            const packedInto = new Map();
+            if (smallOnes.length > 1) {
+                let pack = [];
+                let packBytes = 0;
+                /*
+                  Batches overlap rather than queue.
+          
+                  Each one was sent and awaited before the next was built, so the link
+                  sat idle while the client read and packed the following batch, and
+                  again while the service stored it. Measured on four hundred kilobyte
+                  files, one batch at a time managed 2.52 MB/s and four at once 3.26 —
+                  against a line that can do 5.58.
+          
+                  Bounded low: a batch holds its whole body in memory on both ends, so
+                  three in flight of up to twenty four megabytes is already the most
+                  that is reasonable to have outstanding.
+                */
+                const BATCH_LANES = 3;
+                const flying = new Set();
+                const flush = async () => {
+                    if (!pack.length)
+                        return;
+                    const taking = pack;
+                    pack = [];
+                    packBytes = 0;
+                    const task = (async () => {
+                        try {
+                            /*
+                              Compressed together first. This is what the .cbx format is for and
+                              what the upload path was not using: measured on a real project,
+                              small files came to 42.9% of their size compressed one at a time
+                              and 30.2% compressed together, because a two-kilobyte file gives a
+                              compressor no dictionary worth having.
+                            */
+                            const placed = (await this.packingAllowed())
+                                ? await (0, profile_js_1.timed)("send packs", () => this.putPack(repositoryId, taking.map((item) => ({
+                                    declaration: item.declaration,
+                                    body: item.body,
+                                }))))
+                                : null;
+                            if (placed) {
+                                (0, profile_js_1.counted)("files sent in packs", taking.length);
+                                for (const [digest, one] of placed)
+                                    packedInto.set(digest, one);
+                            }
+                            else {
+                                /*
+                                  Not worth packing — already-compressed content, or too few files.
+                                  They still travel together, just as separate objects.
+                                */
+                                const answer = await (0, profile_js_1.timed)("send batches", () => this.putBatch(repositoryId, taking));
+                                (0, profile_js_1.counted)("files sent in batches", taking.length);
+                                for (const [digest, one] of answer)
+                                    batched.set(digest, one);
+                            }
+                        }
+                        catch {
+                            /*
+                              A refusal here is never fatal: everything in the pack is simply
+                              left for the ordinary path below, which sends it one at a time.
+                              An older deployment without this route lands here every time.
+                            */
+                        }
+                        /*
+                          Only what actually landed. Counting the whole pack meant a batch the
+                          service refused was counted here and then sent again by the lanes
+                          below and counted a second time — which is how the progress bar came
+                          to report a hundred and twenty percent of a forty megabyte upload.
+                        */
+                        for (const item of taking) {
+                            const digest = item.declaration.sha256;
+                            if (!batched.has(digest) && !packedInto.has(digest))
+                                continue;
+                            sentBytes += item.declaration.size;
+                            transferred += item.encoded.body.byteLength;
+                        }
                         report({
                             stage: "upload",
-                            files: index,
+                            files: 0,
                             totalFiles: declarations.length,
-                            bytes: sentBytes + offset,
+                            bytes: progressBytes(),
                             totalBytes,
-                            path: declaration.path,
-                            percent: 20 +
-                                Math.round(((sentBytes + offset) / Math.max(totalBytes, 1)) * 72),
+                            path: taking[taking.length - 1].declaration.path,
+                            percent: 20 + Math.round((progressBytes() / Math.max(totalBytes, 1)) * 72),
                             bytesPerSecond: rate(),
                         });
-                    }));
-            uploaded.push({
-                path: declaration.path,
-                objectId: result.objectId,
-                sourceSize: declaration.size,
-                storedSize: result.size,
-                mediaType: declaration.mediaType,
-            });
-            sentBytes += declaration.size;
-        }
+                    })().finally(() => flying.delete(task));
+                    flying.add(task);
+                    if (flying.size >= BATCH_LANES)
+                        await Promise.race(flying);
+                };
+                for (const declaration of smallOnes) {
+                    this.check();
+                    let body;
+                    try {
+                        body = await (0, profile_js_1.timed)("read small files", async () => new Uint8Array(await (0, promises_1.readFile)(declaration.full)));
+                    }
+                    catch {
+                        /* Unreadable now; the ordinary path reports it properly. */
+                        continue;
+                    }
+                    const allowGzip = await this.gzipAllowed();
+                    const encoded = await (0, profile_js_1.timed)("compress small files", () => (0, compress_js_1.encodeForUpload)(body, declaration.path, allowGzip));
+                    if (pack.length >= BATCH_COUNT ||
+                        packBytes + encoded.body.byteLength > BATCH_BYTES) {
+                        await flush();
+                    }
+                    pack.push({ declaration, body, encoded });
+                    packBytes += encoded.body.byteLength;
+                }
+                await flush();
+                await Promise.all(flying);
+            }
+            /*
+              Several files at once, rather than one at a time.
+        
+              Every file costs at least one round trip, and they were taken strictly
+              in order — so the transfer ran at one file per latency, no matter how
+              much bandwidth was free. On a folder of thousands of small files that is
+              the whole cost of the upload: the network is idle between each one.
+        
+              Bounded, because the opposite mistake is worse. Thousands of concurrent
+              requests would exhaust sockets, defeat the service's own rate limits and
+              make a failure impossible to attribute.
+            */
+            const queue = declarations.entries();
+            const runWorker = async () => {
+                for (const [index, declaration] of queue) {
+                    this.check();
+                    report({
+                        stage: "upload",
+                        files: index,
+                        totalFiles: declarations.length,
+                        bytes: sentBytes,
+                        totalBytes,
+                        path: declaration.path,
+                        percent: 20 + Math.round((sentBytes / Math.max(totalBytes, 1)) * 72),
+                        bytesPerSecond: rate(),
+                    });
+                    /*
+                      Content the service already holds does not need sending. Asking costs
+                      one round trip and saves the whole file — which after an interrupted
+                      save is the difference between re-uploading a project and re-uploading
+                      nothing.
+                    */
+                    /*
+                      A large file goes up in pieces, cut where its own content says.
+              
+                      This is what CBX is for and what it was never doing on the wire. The
+                      boundaries come from the same chunker the .cbx bundle uses, so an
+                      edit in the middle of a large file leaves the chunks either side of it
+                      untouched — and an untouched chunk is one the service already holds,
+                      which costs a question rather than a transfer. A small file is left
+                      whole: cutting it up would trade one request for several and save
+                      nothing.
+                    */
+                    if (declaration.size > CHUNK_THRESHOLD && (await this.chunkingAllowed())) {
+                        const pieces = await this.putChunked(repositoryId, declaration, (offset) => {
+                            inFlight.set(index, offset);
+                            report({
+                                stage: "upload",
+                                files: index,
+                                totalFiles: declarations.length,
+                                bytes: progressBytes(),
+                                totalBytes,
+                                path: declaration.path,
+                                percent: 20 +
+                                    Math.round(((sentBytes + offset) / Math.max(totalBytes, 1)) * 72),
+                                bytesPerSecond: rate(),
+                            });
+                        });
+                        inFlight.delete(index);
+                        alreadyOnAccount += pieces.reused;
+                        uploaded.push({
+                            path: declaration.path,
+                            sha256: declaration.sha256,
+                            chunks: pieces.chunks,
+                            sourceSize: declaration.size,
+                            storedSize: pieces.chunks.reduce((sum, one) => sum + one.storedSize, 0),
+                            mediaType: declaration.mediaType,
+                        });
+                        sentBytes += declaration.size;
+                        transferred += pieces.sentBytes;
+                        continue;
+                    }
+                    const fromPack = packedInto.get(declaration.sha256);
+                    if (fromPack) {
+                        uploaded.push({
+                            path: declaration.path,
+                            sha256: declaration.sha256,
+                            pack: fromPack,
+                            sourceSize: declaration.size,
+                            /* Its share of the pack, so the version's totals stay honest. */
+                            storedSize: fromPack.storedSize,
+                            mediaType: declaration.mediaType,
+                        });
+                        continue;
+                    }
+                    const fromBatch = batched.get(declaration.sha256);
+                    if (fromBatch) {
+                        uploaded.push({
+                            path: declaration.path,
+                            objectId: fromBatch.objectId,
+                            sourceSize: declaration.size,
+                            storedSize: fromBatch.size,
+                            mediaType: declaration.mediaType,
+                        });
+                        continue;
+                    }
+                    const alreadyStored = alreadyHeld.get(declaration.sha256) ??
+                        /*
+                          Only asked individually when the batch did not cover it — a digest
+                          that changed after the bulk question, because the file was rewritten
+                          while this upload was running.
+                        */
+                        (await this.findStored(repositoryId, declaration));
+                    if (alreadyStored)
+                        alreadyOnAccount += 1;
+                    const result = alreadyStored ??
+                        (declaration.size <= DIRECT_LIMIT
+                            ? await (0, profile_js_1.timed)("send files one at a time", () => this.putDirect(repositoryId, declaration)).catch((error) => {
+                                // Naming the file turns "it failed" into something actionable.
+                                const reason = error instanceof Error ? error.message : String(error);
+                                throw new Error(`${declaration.path}: ${reason}`);
+                            })
+                            : await this.putMultipart(repositoryId, declaration, (offset) => {
+                                report({
+                                    stage: "upload",
+                                    files: index,
+                                    totalFiles: declarations.length,
+                                    bytes: progressBytes(),
+                                    totalBytes,
+                                    path: declaration.path,
+                                    percent: 20 +
+                                        Math.round(((sentBytes + offset) / Math.max(totalBytes, 1)) * 72),
+                                    bytesPerSecond: rate(),
+                                });
+                            }));
+                    inFlight.delete(index);
+                    uploaded.push({
+                        path: declaration.path,
+                        objectId: result.objectId,
+                        sourceSize: declaration.size,
+                        storedSize: result.size,
+                        mediaType: declaration.mediaType,
+                    });
+                    sentBytes += declaration.size;
+                    if (!alreadyStored)
+                        transferred += declaration.size;
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(UPLOAD_LANES, declarations.length) }, () => runWorker()));
+        };
+        const pipeline = async (queue) => {
+            for (const section of queue) {
+                this.check();
+                await runSection(section);
+            }
+        };
+        await Promise.all([pipeline(batchy), pipeline(heavy)]);
         // 4. Name the version, which is what makes the upload visible.
         this.check();
         report({
@@ -319,9 +844,38 @@ class Uploader {
             ...uploaded,
             ...reused.map((file) => {
                 const held = prior.get(file.path);
+                /*
+                  Republished in the shape it was already stored in. A file kept in
+                  pieces names the same pieces; flattening it to one object here would
+                  name an object that was never created.
+                */
                 return {
                     path: file.path,
-                    objectId: held.objectId,
+                    /*
+                      Republished in the shape it is stored in — all three of them. The
+                      packed case was missing, so an unchanged small file was declared
+                      with an empty object id instead of the slice it actually is.
+                    */
+                    ...(held.pack
+                        ? {
+                            /*
+                              The uploader's own shape for a pack slice, which is what
+                              the publish step converts to the wire. A file that came
+                              back from the service is described the same way as one this
+                              run packed, so the two paths converge before publishing
+                              rather than at it.
+                            */
+                            pack: {
+                                packObjectId: held.pack.objectId,
+                                offset: held.pack.offset,
+                                length: held.pack.length,
+                                storedSize: held.storedSize,
+                            },
+                            sha256: held.sha256,
+                        }
+                        : held.chunks?.length
+                            ? { chunks: held.chunks, sha256: held.sha256 }
+                            : { objectId: held.objectId }),
                     sourceSize: held.sourceSize,
                     storedSize: held.storedSize,
                     mediaType: held.mediaType,
@@ -339,8 +893,18 @@ class Uploader {
         if (dropped.length) {
             const shown = dropped.slice(0, 5).join(", ");
             const rest = dropped.length > 5 ? ` and ${dropped.length - 5} more` : "";
+            /*
+              Say what to do about it. Refusing is right — a version quietly missing
+              a file somebody chose is the one failure a backup tool must never have
+              — but the message stopped at the refusal, and the person is left with
+              a list of paths and no idea that the fix is either closing whatever
+              holds them or unticking them. Almost every case is a file another
+              program has open, so that is what it says.
+            */
             throw new Error(`${dropped.length} selected file${dropped.length === 1 ? "" : "s"} could not be read, ` +
-                `so nothing was saved: ${shown}${rest}. Nothing was changed on your account.`);
+                `so nothing was saved: ${shown}${rest}. This usually means another program ` +
+                `has them open. Close it and try again, or untick them in the file list. ` +
+                `Nothing was changed on your account.`);
         }
         const sourceBytes = contents.reduce((total, item) => total + item.sourceSize, 0);
         const storedBytes = contents.reduce((total, item) => total + item.storedSize, 0);
@@ -358,6 +922,7 @@ class Uploader {
                 ...(request.expectedHeadVersionId === undefined
                     ? {}
                     : { expectedHeadVersionId: request.expectedHeadVersionId }),
+                ...(request.track ? { track: request.track } : {}),
                 /*
                   Names this attempt so a retry after a lost connection is answered
                   with the version already made, rather than making a second one.
@@ -366,13 +931,36 @@ class Uploader {
                     repositoryId,
                     expectedHeadVersionId: request.expectedHeadVersionId,
                     message: request.message,
-                    files: contents,
+                    /*
+                      Named by what each file is. A whole file is its object; a chunked
+                      one is the digest of its contents — so retrying the same publish
+                      produces the same key either way, which is the point of it.
+                    */
+                    files: contents.map((item) => ({
+                        path: item.path,
+                        objectId: item.objectId ?? item.sha256 ?? "",
+                    })),
                 }),
                 sourceSize: sourceBytes,
                 storedSize: storedBytes,
+                /*
+                  One shape or the other, never both — the service refuses a file that
+                  names an object and a chunk list, and so does its database.
+                */
                 files: contents.map((item) => ({
                     path: item.path,
-                    objectId: item.objectId,
+                    ...(item.pack
+                        ? {
+                            pack: {
+                                objectId: item.pack.packObjectId,
+                                offset: item.pack.offset,
+                                length: item.pack.length,
+                            },
+                            sha256: item.sha256,
+                        }
+                        : item.chunks
+                            ? { chunks: item.chunks, sha256: item.sha256 }
+                            : { objectId: item.objectId }),
                     sourceSize: item.sourceSize,
                     storedSize: item.storedSize,
                     mediaType: item.mediaType,
@@ -439,8 +1027,26 @@ class Uploader {
                 method: "GET",
             });
             for (const row of body.files ?? []) {
+                const pieces = Array.isArray(row.chunks)
+                    ? row.chunks.map((chunk) => ({
+                        objectId: String(chunk.objectId ?? ""),
+                        sourceSize: Number(chunk.sourceSize ?? 0),
+                        storedSize: Number(chunk.storedSize ?? 0),
+                    }))
+                    : undefined;
+                const packed = row.pack;
                 held.set(String(row.path ?? ""), {
                     objectId: String(row.objectId ?? ""),
+                    ...(packed?.objectId
+                        ? {
+                            pack: {
+                                objectId: String(packed.objectId),
+                                offset: Number(packed.offset ?? 0),
+                                length: Number(packed.length ?? 0),
+                            },
+                        }
+                        : {}),
+                    ...(pieces?.length ? { chunks: pieces } : {}),
                     sha256: String(row.sha256 ?? ""),
                     sourceSize: Number(row.sourceSize ?? 0),
                     storedSize: Number(row.storedSize ?? 0),
@@ -498,6 +1104,298 @@ class Uploader {
             return null;
         }
     }
+    /**
+     * Send many small files compressed together as one pack.
+     *
+     * Returns where each file ended up inside the stored pack, or null if the
+     * service would not take it — in which case the caller falls back to sending
+     * them separately, which is slower and larger but always works.
+     */
+    async putPack(repositoryId, items) {
+        const built = await (0, solid_js_1.buildSolidPack)(items.map((item) => ({
+            sha256: item.declaration.sha256,
+            body: item.body,
+        })));
+        if (!built)
+            return null;
+        const manifest = JSON.stringify({
+            sha256: built.sha256,
+            storedSha256: built.storedSha256,
+            size: built.size,
+            members: built.members,
+        });
+        const manifestBytes = new TextEncoder().encode(manifest);
+        const packed = new Uint8Array(4 + manifestBytes.byteLength + built.body.byteLength);
+        new DataView(packed.buffer).setUint32(0, manifestBytes.byteLength, false);
+        packed.set(manifestBytes, 4);
+        packed.set(built.body, 4 + manifestBytes.byteLength);
+        const answer = await this.call(`/v1/repositories/${repositoryId}/objects/pack`, {
+            method: "POST",
+            contentType: "application/octet-stream",
+            body: packed,
+        });
+        const placed = new Map();
+        /*
+          Each file's share of what the pack actually costs.
+    
+          A packed file has no stored size of its own — the pack was charged once
+          for all of them — but a version still has to say what it costs, and
+          reporting each file's uncompressed length made a pack that halved the
+          storage look like it had saved nothing. Apportioned by length, so the
+          shares add up to the pack and the totals stay true.
+        */
+        const compressed = Number(answer.storedSize) || built.body.byteLength;
+        for (const member of built.members) {
+            placed.set(member.sha256, {
+                packObjectId: answer.packObjectId,
+                offset: member.offset,
+                length: member.length,
+                storedSize: built.size
+                    ? Math.round((member.length / built.size) * compressed)
+                    : 0,
+            });
+        }
+        return placed;
+    }
+    /**
+     * Send many small objects in one request.
+     *
+     * Returns what landed, keyed by digest. Anything the service could not take
+     * is simply absent, and the caller sends those the ordinary way — these are
+     * content-addressed, so a retry is free and a partial batch costs nothing
+     * but the objects it missed.
+     */
+    async putBatch(repositoryId, items) {
+        const landed = new Map();
+        if (!items.length)
+            return landed;
+        const manifest = JSON.stringify({
+            objects: items.map((item) => ({
+                sha256: item.declaration.sha256,
+                size: item.body.byteLength,
+                storedSize: item.encoded.body.byteLength,
+                mediaType: item.declaration.mediaType,
+                encoding: item.encoded.encoding,
+                ...(item.encoded.encoding === "gzip"
+                    ? { storedSha256: item.encoded.storedSha256 }
+                    : {}),
+            })),
+        });
+        const manifestBytes = new TextEncoder().encode(manifest);
+        const total = 4 +
+            manifestBytes.byteLength +
+            items.reduce((sum, item) => sum + item.encoded.body.byteLength, 0);
+        const packed = new Uint8Array(total);
+        new DataView(packed.buffer).setUint32(0, manifestBytes.byteLength, false);
+        packed.set(manifestBytes, 4);
+        let at = 4 + manifestBytes.byteLength;
+        for (const item of items) {
+            packed.set(item.encoded.body, at);
+            at += item.encoded.body.byteLength;
+        }
+        const answer = await this.call(`/v1/repositories/${repositoryId}/objects/batch`, {
+            method: "POST",
+            contentType: "application/octet-stream",
+            body: packed,
+        });
+        for (const one of answer.objects ?? []) {
+            landed.set(one.sha256, {
+                objectId: one.objectId,
+                size: one.storedSize,
+            });
+        }
+        return landed;
+    }
+    /**
+     * Which of these digests the account already holds, in one request.
+     *
+     * Falls back to an empty answer rather than an error: an older deployment
+     * has no such route, and the per-file lookup below still works, so the
+     * upload is slower and never broken.
+     */
+    async storedInBulk(repositoryId, digests) {
+        const held = new Map();
+        if (!digests.length)
+            return held;
+        try {
+            /*
+              Split so one request stays a reasonable size on both ends. Five
+              thousand digests is roughly a third of a megabyte of JSON, which is
+              nothing beside the transfer it is replacing.
+            */
+            for (let at = 0; at < digests.length; at += 5000) {
+                this.check();
+                const batch = [...new Set(digests.slice(at, at + 5000))];
+                const answer = await this.call(`/v1/repositories/${repositoryId}/stored`, {
+                    method: "POST",
+                    contentType: "application/json",
+                    body: JSON.stringify({ sha256: batch }),
+                });
+                for (const [digest, one] of Object.entries(answer.stored ?? {})) {
+                    held.set(digest, { objectId: one.objectId, size: one.storedSize });
+                }
+            }
+        }
+        catch {
+            /*
+              Unknown route, or a refusal. Answering "nothing is held" is always
+              safe: every file is then asked about individually, exactly as before.
+            */
+            return new Map();
+        }
+        return held;
+    }
+    /**
+     * Send one file as content-defined chunks, reusing whatever is already held.
+     *
+     * The boundaries come from CBX's chunker, so they depend on the bytes rather
+     * than on offsets: inserting a line near the top of a large file shifts one
+     * chunk instead of every chunk after it. Each piece is an ordinary
+     * content-addressed object, which is what makes "the service already has
+     * this one" a question the existing protocol can already answer.
+     */
+    async putChunked(repositoryId, declaration, onOffset) {
+        /*
+          Read in windows, not all at once.
+    
+          This used to load the whole file to chunk it, which for the files that
+          reach this path — everything past sixteen megabytes — meant an allocation
+          the size of the file. A three gigabyte video was a three gigabyte buffer
+          and an out-of-memory crash partway through an upload, which is the one
+          failure worse than a slow one: it happens after the work.
+    
+          The window holds at most one read plus one maximum chunk, whatever the
+          file is. Exactly how cbx.ts packs a bundle, and for the same reason.
+        */
+        const chunks = [];
+        let reused = 0;
+        let sent = 0;
+        let done = 0;
+        const note = (kind, bytes) => {
+            if (kind === "reused")
+                reused += 1;
+            else
+                sent += bytes;
+        };
+        /*
+          A file's chunks go up several at a time.
+    
+          They were sent strictly one after another, which meant one large file
+          used exactly one lane however many were free. Measured on a gigabyte
+          folder, throughput fell from 4 MB/s to 0.97 MB/s as the small files ran
+          out and only the big one was left — five lanes idle while one crawled.
+          For a folder that is *one* large file, that was the whole upload.
+    
+          Bounded tighter than the file lanes because each one holds a piece in
+          memory: four in flight of at most a maximum chunk each, rather than six.
+        */
+        const CHUNK_LANES = 4;
+        const active = new Set();
+        const dispatch = async (piece, at) => {
+            const task = this.sendChunk(repositoryId, declaration, piece, chunks, at, note).finally(() => {
+                active.delete(task);
+                done += piece.length;
+                onOffset(done);
+            });
+            active.add(task);
+            if (active.size >= CHUNK_LANES)
+                await Promise.race(active);
+        };
+        let ordinal = 0;
+        let pending = Buffer.alloc(0);
+        for await (const block of (0, node_fs_1.createReadStream)(declaration.full, {
+            highWaterMark: 8 * 1024 * 1024,
+        })) {
+            this.check();
+            const incoming = Buffer.from(block);
+            pending = pending.length ? Buffer.concat([pending, incoming]) : incoming;
+            let from = 0;
+            for (const cut of (0, cbx_js_1.cutPoints)(pending)) {
+                await dispatch(Buffer.from(pending.subarray(from, cut)), ordinal++);
+                from = cut;
+            }
+            pending = Buffer.from(pending.subarray(from));
+        }
+        /*
+          cutPoints returns the boundaries *inside* what it was given and never the
+          end, so whatever is left after the last cut is a chunk it does not
+          mention — the packer in cbx.ts emits that tail itself, after its loop.
+          Dropping it truncates every chunked file by exactly its last piece.
+        */
+        if (pending.length)
+            await dispatch(pending, ordinal++);
+        await Promise.all(active);
+        /*
+          Order is the file. Every position must be filled: a hole would mean a
+          chunk that never landed, and publishing around it would produce a version
+          whose bytes are individually verified and collectively wrong.
+        */
+        const ordered = chunks.slice(0, ordinal);
+        if (ordered.some((one) => !one)) {
+            throw new Error(`${declaration.path}: a chunk did not finish uploading`);
+        }
+        return {
+            chunks: ordered,
+            reused,
+            sentBytes: sent,
+        };
+    }
+    /** Send one chunk, reusing it if the account already holds those bytes. */
+    async sendChunk(repositoryId, declaration, piece, 
+    /*
+      Written at a known position rather than appended. The chunks are sent
+      several at a time and finish in whatever order the network decides, but
+      their order *is* the file — appending as they land would reassemble a
+      large file out of sequence, which produces bytes that are all present,
+      all verified individually, and wrong.
+    */
+    chunks, at, note) {
+        {
+            this.check();
+            const digest = (0, node_crypto_1.createHash)("sha256").update(piece).digest("hex");
+            /*
+              Asked per chunk rather than per file. This is the whole saving: the
+              parts of a large file that did not change answer "already held" and
+              never travel.
+            */
+            const held = await this.findStored(repositoryId, {
+                ...declaration,
+                sha256: digest,
+                size: piece.length,
+            });
+            if (held) {
+                note("reused", 0);
+                chunks[at] = {
+                    objectId: held.objectId,
+                    sourceSize: piece.length,
+                    storedSize: held.size,
+                };
+            }
+            else {
+                const encoded = await (0, compress_js_1.encodeForUpload)(new Uint8Array(piece), declaration.path, await this.gzipAllowed());
+                const query = encoded.encoding === "gzip"
+                    ? `?kind=chunk&role=chunk&encoding=gzip` +
+                        `&logicalSize=${piece.length}` +
+                        `&storedSha256=${encoded.storedSha256}`
+                    : `?kind=chunk&role=chunk`;
+                const stored = await this.call(`/v1/repositories/${repositoryId}/objects/${digest}${query}`, {
+                    method: "PUT",
+                    contentType: "application/octet-stream",
+                    body: encoded.body,
+                }).catch((error) => {
+                    const reason = error instanceof Error ? error.message : String(error);
+                    throw new Error(`${declaration.path}: ${reason}`);
+                });
+                note("sent", encoded.body.byteLength);
+                chunks[at] = {
+                    objectId: stored.objectId,
+                    sourceSize: piece.length,
+                    /* What the service keeps, which is smaller when the piece gzipped. */
+                    storedSize: stored.storedSize ?? stored.size,
+                };
+            }
+        }
+    }
     async putDirect(repositoryId, declaration) {
         const body = await (0, promises_1.readFile)(declaration.full);
         // The file was hashed earlier, and a live file — a database, a log — can
@@ -508,11 +1406,97 @@ class Uploader {
             declaration.sha256 = digest;
             declaration.size = body.length;
         }
-        return this.call(`/v1/repositories/${repositoryId}/objects/${digest}?kind=chunk&role=chunk`, {
+        /*
+          The digest in the path stays the original file's, whatever travels.
+    
+          That is the whole reason an object can be sent compressed at all: its
+          identity is what it *is*, not how it was packed, so a file the service
+          already holds is recognised as held even if the two clients that sent it
+          made different choices about compression.
+        */
+        const encoded = await (0, compress_js_1.encodeForUpload)(new Uint8Array(body), declaration.path, await this.gzipAllowed());
+        const query = encoded.encoding === "gzip"
+            ? `?kind=chunk&role=chunk&encoding=gzip` +
+                `&logicalSize=${body.length}` +
+                `&storedSha256=${encoded.storedSha256}`
+            : `?kind=chunk&role=chunk`;
+        /*
+          The answer carries both sizes and they are not the same thing: `size` is
+          the file's own length, `storedSize` is what the service actually keeps.
+          They agree only while nothing is compressed, which is why recording the
+          wrong one went unnoticed until a compressed object was sent — and then
+          the version is refused for declaring a size the object does not have.
+        */
+        const stored = await this.call(`/v1/repositories/${repositoryId}/objects/${digest}${query}`, {
             method: "PUT",
             contentType: declaration.mediaType,
-            body: new Uint8Array(body),
+            body: encoded.body,
         });
+        return {
+            objectId: stored.objectId,
+            size: stored.storedSize ?? stored.size,
+        };
+    }
+    /**
+     * Whether this deployment records gzipped objects.
+     *
+     * Asked once and remembered. Sending an encoding the service cannot record
+     * is refused outright, so this is not an optimisation to guess at — an older
+     * deployment answers without gzip and every upload simply goes as it always
+     * did.
+     */
+    /**
+     * Whether this deployment can store a file as chunks.
+     *
+     * Asked rather than assumed, because the app updates on its own schedule and
+     * the service updates on another: a build that started chunking against a
+     * deployment without the table behind it would fail every large upload, and
+     * fail it after doing all the work. An older service answers no and files go
+     * up whole exactly as they always did.
+     */
+    async packingAllowed() {
+        if (this.packingSupported !== null)
+            return this.packingSupported;
+        this.packingSupported = (await this.serviceFeatures()).includes("solid-packs");
+        return this.packingSupported;
+    }
+    async chunkingAllowed() {
+        if (this.chunkingSupported !== null)
+            return this.chunkingSupported;
+        this.chunkingSupported = (await this.serviceFeatures()).includes("chunked-files");
+        return this.chunkingSupported;
+    }
+    /** What /health says this deployment accepts. Fetched once. */
+    async serviceFeatures() {
+        try {
+            const response = await fetch(`${this.credentials.origin()}/health`, {
+                headers: { accept: "application/json", ...(0, identify_js_1.clientHeaders)() },
+                signal: AbortSignal.timeout(8000),
+            });
+            const body = (await response.json());
+            return body.features ?? [];
+        }
+        catch {
+            /* Unknown is treated as unsupported: never risk a refused upload. */
+            return [];
+        }
+    }
+    async gzipAllowed() {
+        if (this.gzipSupported !== null)
+            return this.gzipSupported;
+        try {
+            const response = await fetch(`${this.credentials.origin()}/health`, {
+                headers: { accept: "application/json", ...(0, identify_js_1.clientHeaders)() },
+                signal: AbortSignal.timeout(8000),
+            });
+            const body = (await response.json());
+            this.gzipSupported = Boolean(body.contentEncodings?.includes("gzip"));
+        }
+        catch {
+            /* Unknown is treated as unsupported: never risk a refused upload. */
+            this.gzipSupported = false;
+        }
+        return this.gzipSupported;
     }
     /** Files past the direct limit go up in parts under an upload session. */
     async putMultipart(repositoryId, declaration, onOffset) {