DEV Community: Coffer

I Read Every Comment in My Codebase. Every Wrong One Had the Same Shape.

Coffer — Tue, 18 Aug 2026 12:00:00 +0000

I read all ~2,000 lines of comments in a codebase against the code they describe. Sixteen were wrong. Every single one of them was wrong in the same way — and it is not the way I expected.

The audit

I work on Coffer, a file store that encrypts everything in the browser before it uploads. It is a heavily commented codebase: roughly 2,000 comment lines against 19,500 lines of C# and TypeScript, about one line in ten, in around 670 distinct comment blocks across 225 files.

That is a deliberate choice, and it has an obvious failure mode. A comment can be wrong; code can't be wrong in the same way, because code is what runs. A wrong comment is worse than no comment, because a reader trusts it. So the standing worry with a codebase like this is that at any moment some unknown fraction of those 2,000 lines is quietly lying, and nobody knows which lines.

So I measured it. Every comment block, read against the code it claims to describe, in one pass. An AI coding agent did the reading — 2,000 lines of prose against 19,500 lines of code is a tedium problem more than a difficulty problem, and this is exactly the shape of tedium a model is good at. Every defect it flagged was confirmed against the referenced source before anything was edited, and two of them needed work outside the editor: one required computing a probability, one required checking the live production host.

The result, in six commits:

Outcome	How many
Comment blocks read	~670
Corrected — the comment said something the code does not do	16
Deleted — the comment said nothing the code doesn't already say	5
Verified correct, left untouched	everything else

About 2.4% wrong. Lower than I feared. But the interesting result isn't the rate.

Every defect had a remote referent

Here is the finding, and it held without a single exception across all sixteen:

Every wrong comment was describing something outside its own file. Not one comment sitting directly above the code it documents was wrong.

Four of the sixteen, to show the shape:

A deploy script's header comment described its own sync step, 240 lines below. It claimed the script deletes removed files with rsync --delete. The body of the script explains at length that rsync --delete is exactly what you must not do there — it would delete files that live on the server and not in the repository — and the script actually diffs a per-deploy manifest so it can only ever remove what it previously put there. A reader skimming the header would have come away believing the precise opposite of the rule the body exists to enforce.
A server-side Plan.cs described the client's encryption: multi-GB uploads "won't actually complete in-browser until chunked encryption lands." Chunked encryption had landed. A 4.8 GB upload was verified byte-exact months earlier.
A client-side VaultPage.tsx described the server's cleanup job as "the daily sweep." The sweeper runs hourly and reclaims sessions older than 24 hours. What's daily is how long an abandoned session survives, not how often the sweep looks — which matters at exactly that call site, since the whole reason to delete eagerly is that otherwise a part file sits on disk for a day.
A comment in Program.cs explained why database migration is wrapped in a retry, by describing a hardware fault on the production host that made the clock jump at boot. True when written. The fault had since been fixed on the machine. Nothing in the repository could have told me that; I had to go look at the host.

Three species, and all sixteen fit one of them:

Species	What it is	Example
Roadmap state that arrived	"until X lands", "the future billing webhook", "currently only the welcome email"	`SetPlan` called the billing webhook "future"; it had been live for weeks
A second case appeared	The comment names the only case that existed when it was written	Six comments said "Google" after sign-in became provider-agnostic
A number drifted	A measurement, stated once, never re-measured	A build plugin claimed it strips "roughly 1.2 KB" of HTML comments; it strips 3,202 bytes

Every one of them was true when written. Not one was sloppy. This is not a story about people writing bad comments.

Why that's the shape: the drift is invisible in the diff

Adding a second sign-in provider is a normal feature. It touched the auth controller, the startup configuration, a button component. It did not touch the account page. It did not touch the user manager's logging comment. It did not touch two test files.

And yet, the moment it merged, six comments in files it never opened became false — because each of them said "Google" where the code underneath had quietly become "any external provider." No diff showed that. No test failed. git blame on those comments still points at the commit that wrote them, correctly, months earlier.

That is the whole mechanism. A comment about local code is checked constantly — by everyone who edits the line beneath it, in the diff where the change lives. A comment about remote code is checked by nobody, because the change that falsifies it happens in a file where the comment isn't visible. The referent moves; the comment stays.

The measurement species is the same failure with a longer fuse. Here's one, in full, from a recovery key generator:

// Before:
// Refill in batches so we don't call getRandomValues once per character; a few draws
// land in the rejected tail, so oversample slightly to usually finish in one batch.

// After:
// Refill in batches so we don't call getRandomValues once per character. The batch is
// exactly `length` bytes — no oversampling — and 8 of the 256 byte values (3.1%) fall in
// the rejected tail, so one batch yields all 32 characters only about a third of the
// time. The loop just draws another batch until enough survive; correctness never
// depends on a batch sufficing.

Both halves of the original were false. There was no oversampling — the batch is exactly length bytes for length characters. And "usually finish in one batch" is (248/256)^32 = 36%, which is not usually. The loop was always correct; it just draws again. But you cannot catch that by reading. You catch it by doing the arithmetic, which nobody does to a comment they're scrolling past.

So: is heavy commenting worth it?

The honest accounting, from the same audit.

The cost is real, and smaller than the argument against comments assumes. Sixteen defects in ~670 blocks, accumulated over the entire life of the project. Fixing them took one evening. That is the true maintenance bill for a decade-dense commenting habit in a codebase this size, and it is not a large number.

But the cost is not evenly distributed, and that's what makes it manageable. It is concentrated almost entirely in comments with a remote referent. If you know that, you know where to spend the evening. An audit that reads every comment equally — which is what I did, and I don't recommend repeating it — spends most of its time confirming that comments beside their own code are fine, which they reliably are.

The worst case is genuinely bad, though. The deploy script header wasn't merely stale, it was inverted: it advertised the exact practice the rest of the file exists to forbid. A reader who trusted it and "restored" rsync --delete would have wiped server-side files that exist nowhere in the repository — on the next deploy, silently. This is the strongest form of the anti-comment argument and it is correct: a wrong comment is worse than no comment, because it converts your reader's diligence into a weapon. Being 97.6% accurate is not much comfort when the 2.4% is load-bearing. This is also the one claim in the post with evidence behind it beyond my own repository: a 2024 study of code-comment inconsistency found that inconsistent changes are around 1.5x more likely to produce a bug-introducing commit than consistent ones. Wrong comments don't just mislead readers in the abstract; they show up in the defect record.

And the payoff is concentrated too — in the same place. Look at what those 654 correct blocks were doing. The most valuable one in the whole codebase is that same deploy script, which documents three specific things that were tried and broke — including why rsync --delete is forbidden. That knowledge exists nowhere else. Not in the code (the code is the fix, not the fault), not in the tests, not in a commit message anyone will find in two years. The comments carrying the highest value are almost always the ones explaining a rejected alternative or a non-obvious constraint, and those are exactly the comments most likely to name something outside their own file — the other layer, the number that was measured, the machine. The maintenance burden and the payoff live at the same address.

You can see the same distinction in what got deleted. Five blocks went, and all five were the same kind of thing: // Add services to the container. above the line adding services to the container, // Configure the HTTP request pipeline. above the pipeline configuration, a scaffolding link to the OpenAPI docs, two commented-out dead declarations. Pure restatement, generated by a project template, surviving purely because nobody ever deleted them.

Whereas these stayed, all of them one-liners:

// For EF Core.
// Hours; 0 = no expiry.
// OWASP's 2023 minimum

Delete those and you lose the only record of why. "Comments should explain why, not what" is advice everybody has heard and it is completely correct; what the audit adds is that the what comments are the harmless ones. They're useless, they dilute, they should go — but they are never what lies to you. The comments carrying real information are the same comments that can rot. There's no version of this where you get the value without the exposure.

The maintenance process that actually falls out of this

I would not run this audit again wholesale. It cost an evening and 94% of the reading confirmed things that were never in danger. What I'd do instead, and what the finding actually supports:

1. When writing a comment, notice when it points somewhere else. If a comment names another file, another layer, another service, a number, or a machine, it has a referent you don't control and a maintenance cost the local ones don't have. That's not a reason to avoid writing it — those are the valuable ones. It's a reason to write it so it fails loudly: name the file, name the symbol, state the number with its units and its date, so the next reader can check it in ten seconds instead of wondering.

2. Grep for time-bound language, occasionally. currently, for now, not yet, until … lands, the future, TODO. Every "roadmap state that arrived" defect announced itself with one of these words. This is a five-minute sweep with a high hit rate, and it's the highest-value habit in this entire post.

3. Review comments that make cross-file claims the way you'd review an assertion. A comment saying "the sweep runs daily" is a claim about another file's behaviour. In review, that deserves the same "is that still true?" you'd give a magic number. A comment saying "this is case-insensitive to match the server" is checkable in ten seconds, by someone who has the diff open.

4. When a feature generalizes something, grep for the old name. The single most productive five seconds of the entire audit would have been grep -ri google on the day the second provider shipped. Six of sixteen defects, all findable, all in files that feature never touched. Every time you turn one case into two — one provider into any provider, one currency into many, one region into several — the old name is sitting in comments somewhere, and it is now a lie.

5. Verify numbers by computing them, not by reading them. The two best finds in the audit were the recovery-key probability and the production host's clock. Neither was catchable by reading. One needed arithmetic, one needed leaving the editor entirely. If a comment states a measurement, it can only be checked by measuring.

What this doesn't prove

One codebase, one project, 225 files, sixteen defects. That's a small sample from a single habitat, and the habitat matters: this codebase has one primary author, which means no comment ever went stale because two people disagreed about what the code was for. In a larger team I'd expect a whole species this audit couldn't produce — comments that were never true, only believed.

And none of this is new territory, which I should be explicit about rather than let you discover in the comments. Comment rot is one of the better-studied things in software engineering research. Fluri et al. found that about 90% of comment changes happen in the same revision as the code change — the deferred remainder being exactly where inconsistency comes from. Wen et al. mined 1.3 billion AST-level changes across 1,500 systems to build a taxonomy of the inconsistencies developers actually fix. There is a whole detection subfield downstream of that.

My central category already has a name, too. Jabrayilzade et al.'s taxonomy of inline comment smells lists eleven, and one of them is non-local — comments referencing parts of the code that are not nearby. That is recognisably the thing this whole post is about, named before I got here.

What I could not find is anyone claiming what this post claims: that locality predicts drift — that the non-local ones are where essentially all of it lives, and the local ones don't drift at all. In that taxonomy "non-local" is a comprehension smell: harder to read, harder to verify. The follow-up detection work explicitly does not claim those comments go stale more often. And the large inconsistency studies categorise drift by what went stale — application logic, design, maintenance — not by where its referent lived. Two searches came up empty, which is weak evidence of novelty rather than proof.

The local/remote split is also partly definitional, and I want to be honest that I noticed it after the fact rather than predicting it. "Describes something outside its own file" is a category I drew around sixteen defects once I had them in front of me. It's a clean line and it held perfectly, but sixteen is a small number to draw a law from. So the honest positioning is narrow: they named the smell; I watched one codebase for its whole life and found the drift sitting entirely inside it. A hypothesis with a good first result, not a finding.

And a comment sitting beside its own code can absolutely still be wrong — it can misdescribe intent from the day it was written. This audit couldn't have detected that, because the check for a local comment is "does this match the code beneath it," and a comment that was born wrong matches nothing in particular. What the audit shows is that local comments don't drift. Not that they're true.

The one that got away

There's one defect I found and deliberately did not fix. A test is named:

Delete_ShouldDeleteAccount_WhenGoogleOnlyUserTypesTheirOwnEmail

Same stale assumption as the six comments — it is not a Google-only path, it's the path every external provider takes. But it's in the name. Renaming it is a code change, not a comment fix, and it didn't belong in a commit series that touched nothing executable.

It's the better illustration of the whole point, though. Comment drift is at least confined to comments, where the fix is free and the blast radius is a confused reader. The same drift in an identifier is a refactor, and it's the reason people who identify their symbols after a single case end up living with the wrong word forever. Your comments and your names go stale by exactly the same mechanism — a second case appears somewhere else — and only one of them is cheap to correct afterwards.

Coffer is at getcoffer.org. The comments are, as of this week, accurate — a claim with a known shelf life, which is roughly the point of the article.

The Bug Was in My Benchmark: Attaching a Debugger to Chromium Throttles fetch() Uploads 20x

Coffer — Thu, 06 Aug 2026 11:07:41 +0000

We chased an upload running 8x below what the link could do, shipped three fixes that turned out to fix nothing, and found a real one that turned out to be far smaller than it looked — because the thing measuring the bug was also causing it.

The crime

I work on Coffer, a file store that encrypts everything in the browser before it uploads. Files go up in chunks: at the time of this investigation, a 4.8 GB file became about 300 sequential PUTs of 16 MiB, each one AES-256-GCM encrypted client-side before it leaves the tab. The server is ASP.NET Core, sitting on the same gigabit switch as the machine doing the testing, with the CDN entirely out of the path. Exact versions for everything below are in an appendix at the end.

Direction	Throughput
Download — one streamed GET	~74 MB/s (~980 Mbps)
Upload — sequential chunk PUTs	~14.6 MB/s (~117 Mbps)

Same machine, same wire, same server process. Downloads essentially saturated the gigabit link; uploads used an eighth of it. Something was eating most of our upload time and leaving no fingerprint on any component we could name — which is the story of a day spent disbelieving three answers we'd already shipped, and a fourth one that turned out to be right for the wrong reason.

Three suspects, three alibis

Too many round trips. ~300 requests instead of 1 — so double the chunk size, 16 MiB → 32 MiB, and halve the count. Shipped it, re-measured the identical file: ~350s, against a ~328s baseline. Slightly worse, not better. A 100 MB file dropping from ~6 chunks to 3 confirmed the change had actually taken effect; it just didn't move the needle. Chunk size wasn't the cost.

Encryption and transfer never overlapping. The upload loop pulled each chunk from an async generator only after the previous PUT resolved, so CPU and network alternated instead of running together — and Windows' network graph showed a clean sawtooth to match: burst, trough, burst. We pipelined it (encrypt N+1 while PUT(N) is in flight) and measured ~305s, a 13% gain. Wrote it up as a win.

That number didn't survive what came next. Direct component measurement — disk read, AES-GCM encrypt, both against a real disk-backed file read at 8 distinct offsets so the OS page cache couldn't flatter it — put the client's entire per-chunk workload at 70ms out of a ~3000ms chunk: a hard ceiling of ~2% on anything overlapping could buy. We'd reported 13% from a single run per configuration on a ~5-minute test, where run-to-run spread is comfortably larger than the effect. The pipelining code stayed (harmless, correct in principle); the number was noise wearing a result's clothing, and got retracted.

(Hold on to that ~3000ms. It is going to turn out not to mean what it says either — and unlike the retraction you just read, I did not catch that one until publication was already being planned.)

The sawtooth wasn't encryption gaps either — a 70ms dip inside a 3000ms chunk is a ~2% notch, invisible at that scale, categorically not a trough falling to near zero. We'd taken a picture, matched it to a theory we already liked, and promoted a correlation to a mechanism. (What actually draws that graph is still the one genuinely open question from this whole investigation.)

No concurrency. Our server enforces strictly sequential chunk indices, so testing this for real would have meant reworking the domain, service and storage layers before writing a single benchmark. Instead: separate upload sessions each restart their chunk index at 0, so parallel sessions don't violate the sequential invariant at all — meaning aggregate throughput could be measured with zero server changes.

Parallel streams	1	2	4	8
Aggregate throughput	143 Mbps	137 Mbps	134 Mbps	135 Mbps

Eight concurrent uploads moved exactly as much total data as one. Not "less than 8x" — the same. A multi-day rework, cancelled by an afternoon of measurement, and easily the highest-value negative result of the day. Whatever the ceiling was, it was global, not per-request.

Three suspects, three alibis, and still no idea where the time went.

The lineup, and the thing nobody had varied

So we stopped varying our code and started varying the thing doing the sending. Same 16 MiB PUT, same LAN-direct endpoint, CDN out of the picture — only the client changes:

Client	Protocol	Throughput
.NET `HttpClient`	HTTP/1.1	626–725 Mbps
.NET `HttpClient`	HTTP/2	488–717 Mbps
Windows `curl` (Schannel)	HTTP/1.1	435–453 Mbps
Chromium `fetch()`	HTTP/2	131–143 Mbps

The server handed ~700 Mbps to a .NET client over both protocols and ~140 to a browser. That also quietly executed a suspect I'd been nursing — Kestrel's HTTP/2 flow-control window defaults. The .NET HTTP/2 row falsifies it outright: same server, same untouched defaults, five times the throughput.

The obvious read was "the browser's network stack is the ceiling, there's no client-side lever left, go measure your WAN uplink." It's a very comfortable conclusion — it's someone else's bug, and it has a table behind it. It was also wrong, and the correction was one sentence: every number above was LAN-local, across a gigabit switch, CDN out of the path. The WAN cannot explain a LAN measurement. That wasn't an answer to the question; it was a change of subject dressed as a finding.

So: what had never actually been varied, across a full day of varying chunk size, encryption schedule, stream count, client and protocol? The kind of object handed to fetch() as the request body. It had been a Uint8Array since the line was first written, because obviously — it's a buffer of bytes, that's what it is. Nobody audits the obvious thing.

Same 32 MiB chunk, same endpoint, same request, runs interleaved to rule out drift or thermal effects:

Body handed to `fetch()`	Throughput
`Uint8Array` (what we'd been sending)	134–144 Mbps
`ArrayBuffer`	122–141 Mbps
`Blob`	678–740 Mbps
`ReadableStream` + `duplex: 'half'`	683–705 Mbps

Wrap the identical bytes in a Blob and the number lands within noise of native .NET against the same endpoint. One-line fix, shipped — with one production detail that matters: build the Blob outside any retry closure. Blobs are re-readable, so a 429 retry re-sends the same object safely, whereas a ReadableStream body scores just as well on throughput and is consumed on the first attempt. Fast until the first retry, then broken.

At the time, this read as the ending: a 5x browser-only bottleneck, invisible to every non-browser client, fixed by changing one word. It shipped. It is also not what was actually happening.

The bug was in the thing doing the measuring

Every number in the two tables above — the client comparison, the body-type sweep, the original ~140 Mbps browser baseline — was collected with a debugger attached to the browser: first an AI coding agent driving Chromium through the Playwright MCP servers, later a standalone Playwright/Puppeteer harness built to isolate the effect further. Re-running the body-type sweep hand-driven, in an ordinary Edge window with nothing attached, LAN-direct against the same server:

Body	Median	Range
`Uint8Array`	609 Mbps	446–651
`Blob`	802 Mbps	588–835

Uint8Array alone was 609 Mbps — over 4x what every automated run had shown, and most of the way to what Blob was supposedly worth. The "gigabit link, using an eighth of it" premise was simply false in an ordinary browser.

Two falsification passes before believing the instrument itself. Was it a browser version fix? No: Chromium 149.0.7827.55 and 151.0.7922.34 (Playwright 1.61.0 and 1.62.1), same harness, same endpoint, measured identically under automation — 125 and 116 Mbps. Was it DevTools? No: a controlled A/B/C on Edge — Network panel recording, Console only, and DevTools fully closed with results painted into the page so no console was needed to read them — came back at 609, 633 and 656 Mbps. Three configurations agreeing within noise is a controlled null, not an eyeballed resemblance.

That left one variable nobody had isolated on purpose: automation itself. A minimal test settled it — same browser process, same page, same sink, same flags, the only variable whether a CDP debugger is attached while the bytes move.

This test runs over loopback, against a small Node sink — no network, no TLS, no real server. That is deliberate: if the ceiling still appears with the network deleted entirely, the network cannot be what causes it. It also means the numbers below are memory-to-memory and are not comparable with the gigabit-LAN figures above — multi-Gbps here is expected, not a typo.

Phase	`Uint8Array`	`Blob`	Ratio
CDP attached	113 (108–116)	2835 (2412–3226)	25.1x
CDP detached	2351 (2182–2799)	3125 (2616–3330)	1.33x

Detaching mid-session — same tab, same in-flight code — took the typed-array path from 113 to 2351 Mbps. More than 20x, from nothing but letting go of the debugger.

The effect is specific to typed-array request bodies — but read the Blob column carefully, because it is doing less work than it appears to. This sink's own ceiling is ~3 Gbps, and both Blob figures sit on it. So the 1.33x in the detached row is a lower bound on the remaining gap, measured with its numerator saturated, not a clean measurement of one. The load-bearing column is the typed-array one, where 113 Mbps is nowhere near any ceiling in this rig.

It is not a Playwright bug. Puppeteer (puppeteer-core 25.4.0) reproduces it at 113 Mbps against Playwright's 116–125, so it belongs to CDP/Chromium, and any upstream report goes there rather than to a test framework.

Every earlier result falls out of that one fact. The original ~140 Mbps: measured through the Playwright MCP servers, debugger attached. Chromium 149 and 151 measuring identically: both had a debugger attached — the version was never the variable. Hand-driven Edge and Firefox at 609–656: no debugger, because a human doesn't attach one to browse. The "browser is 5x slower than .NET" finding: an artifact of the one client in the comparison that happened to be under a debugger. And DevTools making no difference means its frontend evidently doesn't take the same path an external CDP client does — noted, not explained.

No mechanism is claimed. Three were proposed in one day and all three were wrong (browser version, DevTools, and an earlier loopback "ceiling" that turned out to be a slow toy sink coincidentally landing near the real figure). What's established is the conditional — debugger attached, typed-array upload bodies crawl. Why, is for someone who can read the Chromium source.

Reproduce it

Self-contained — the sink, the page and the attach/detach test in one file. npm i puppeteer-core, point CHROME_EXE at a Chrome or Edge binary, run it:

// Does an attached CDP debugger throttle typed-array fetch() upload bodies?
// npm i puppeteer-core  &&  CHROME_EXE=/path/to/chrome node repro.mjs
import http from 'node:http';
import puppeteer from 'puppeteer-core';

const PORT = 8099, MIB = 32, REPS = 6;

const PAGE = `<!doctype html><meta charset="utf-8"><pre id="out">ready</pre><script>
window.bodyTypeTest = async (sizeMiB, reps) => {
  const bytes = sizeMiB * 1024 * 1024;
  const chunk = new Uint8Array(bytes);
  // randomise a slice per MiB - content doesn't matter, just don't ship compressible zeros
  for (let o = 0; o < bytes; o += 1 << 20)
    crypto.getRandomValues(chunk.subarray(o, Math.min(o + 4096, bytes)));

  const makeBody = k => k === 'Uint8Array' ? chunk : new Blob([chunk]);
  const results = { Uint8Array: [], Blob: [] };

  // interleaved, so thermal drift can't favour whichever kind ran first
  for (let r = 0; r < reps; r++) {
    for (const kind of ['Uint8Array', 'Blob']) {
      const t0 = performance.now();
      await (await fetch('/sink', { method: 'PUT', body: makeBody(kind) })).json();
      const ms = performance.now() - t0;
      results[kind].push(Math.round(bytes * 8 / (ms / 1000) / 1e6));  // Mbps
      out.textContent = JSON.stringify(results);
    }
  }
  return results;
};
</script>`;

// The sink replies only once it has the whole body, so the in-page timing covers the upload.
const server = http.createServer((req, res) => {
  if (req.method === 'PUT') {
    let n = 0;
    req.on('data', c => { n += c.length; });
    req.on('end', () => res.end(JSON.stringify({ received: n })));
    return;
  }
  res.writeHead(200, { 'content-type': 'text/html' });
  res.end(PAGE);
}).listen(PORT, '127.0.0.1');

const med = a => [...a].sort((x, y) => x - y)[a.length >> 1];
const summarise = r => r && { Uint8Array: med(r.Uint8Array), Blob: med(r.Blob) };

const browser = await puppeteer.launch({
  executablePath: process.env.CHROME_EXE,
  headless: false
});
const ws = browser.wsEndpoint();
const page = (await browser.pages())[0];
await page.goto(`http://127.0.0.1:${PORT}/`);

// Phase A - debugger attached the whole time.
const attached = await page.evaluate((m, r) => window.bodyTypeTest(m, r), MIB, REPS);

// Phase B - same browser, nothing attached. Schedule the run for 15s out, disconnect
// (which leaves the browser alive), let it happen unobserved, reconnect and read it back.
await page.evaluate((m, r) => {
  localStorage.removeItem('res');
  setTimeout(async () => {
    localStorage.setItem('res', JSON.stringify(await window.bodyTypeTest(m, r)));
  }, 15000);
}, MIB, REPS);

await browser.disconnect();
await new Promise(r => setTimeout(r, 120000));

const again = await puppeteer.connect({ browserWSEndpoint: ws });
const detached = await (await again.pages())[0]
  .evaluate(() => JSON.parse(localStorage.getItem('res') || 'null'));

console.log({ attached: summarise(attached), detached: summarise(detached) });
await again.close();
server.close();

Two runs of exactly the file above, unmodified, on Edge 151 while preparing this post:

{ attached: { Uint8Array:  89, Blob: 1797 }, detached: { Uint8Array: 1791, Blob: 2279 } }
{ attached: { Uint8Array: 104, Blob: 1863 }, detached: { Uint8Array: 1748, Blob: 2532 } }

20.1x and 16.8x on the typed-array arm. Worth saying plainly: the multiplier moves between runs. Across every run I have, including the table above, it lands somewhere between about 17x and 21x — so read the "20x" in the title as a round number, not a constant. What doesn't move is the direction and the order of magnitude: the attached arm is always around 100 Mbps and the detached arm is always well past 1500, on the same machine, minutes apart.

About three minutes per run, nearly all of it waiting out the detached measurement. Two things to know before you read your own output: this sink tops out around 3 Gbps on a typical desktop, so an arm sitting near that is limited by the harness rather than the browser — which is exactly what happens to the Blob column. And run a positive control first: a rig that can't reproduce a known effect can't be trusted to rule one out.

What's actually true

Blob is a genuine, free, one-line win in Chromium: ~1.3x — 609→802 Mbps, measured by hand against the real server and reproduced. The detached loopback harness lands at 1.33x too, but that agreement is worth less than it looks, since its Blob arm is pinned at the sink's own ceiling; the hand-driven LAN number is the one carrying this claim.

It's also the only body type in the sweep that is both fast and functional in every engine: hand Firefox a ReadableStream body and it doesn't throw, it stringifies the object and uploads the literal 23-byte text [object ReadableStream] with a 200 response. Silent upload corruption. In Firefox, Blob vs Uint8Array makes no measurable difference at all (655 vs 656).

The shipped fix is still correct. It is not the finding. Not 5x. Not even close to the biggest number in this post. The biggest number here is what a debugger did to the measurement while nobody was watching it happen.

And now that ~3000ms chunk from the pipelining section comes due, because it was measured under the same debugger — which makes the per-chunk time about 9x longer than the same chunk takes unobserved. Redone at each throughput that actually occurs, against the same 70ms of client work:

Per-chunk PUT	Ceiling on what pipelining could save
~3000ms — what we originally measured, debugger attached	~2%
~4.5s — a real user over the CDN tunnel, WAN-capped 37–97 Mbps	~1.5%
~335ms — gigabit LAN, `Blob` body, nothing attached	~17%

So "~2%" was right about real users and wrong about why: they are WAN-bound, which the original arithmetic never established. On a genuinely fast link, overlapping encryption with transfer is worth something — not the 13% we retracted, but not nothing either. The retraction stands (that 13% was single-run variance regardless) and the code stays. What changes is that I no longer get to call it pointless; only that it does nothing for the link our users actually have.

Worth adding, since the obvious guess is wrong: none of this is about JavaScript being single-threaded. crypto.subtle and fetch() both do their work off the main thread, so the overlap is real. The original loop was serial because an async generator is pull-based — it only started encrypting chunk N+1 once the await on chunk N's PUT had resolved. A structural problem wearing a performance problem's clothes.

The actual lesson

None of the three suspects was bad reasoning. Chunk count, overlap and concurrency are the correct first things to check on a slow upload, and ruling them out by measurement rather than by shipping-and-hoping is exactly right. Each theory explained the evidence available at the time, and one of them even predicted the previous null result — which is supposed to be the sign you're onto something.

The failure was narrower and easier to miss: every measurement across a full day shared one silent, unvaried input — the tool doing the measuring — and it never occurred to anyone to put that tool in the suspect lineup until a human ran the same test by hand and got a different universe. Twice this investigation produced a number that was really a property of the harness. The second time, it was the headline.

Two habits are the only reason it broke at all: a null result got chased instead of shrugged off (350 vs 328 looked like nothing), and a confident conclusion got challenged instead of accepted ("it's the browser stack, go measure your WAN" was wrong in the specific way that feels like rigour — plenty of evidence, aimed at the wrong question).

So: if you benchmark browser fetch() uploads — a CI perf gate, a load test, anything driven by Playwright, Puppeteer or raw CDP — and the numbers look like they're leaving most of a fast link on the table, check whether that link is actually your code before you believe it. The fix that took ten minutes was detaching the debugger, not touching the app.

Versions

Everything above is one machine, one LAN, over two days. Pin your own setup against it:


Client OS	Windows 11 Pro, build 26200
Hand-driven browsers	Edge 151.0.4129.59, Firefox 153.0.1 — ordinary installs, nothing attached
Automated Chromium	151.0.7922.34 (Playwright 1.62.1) and 149.0.7827.55 (Playwright 1.61.0)
CDP attach/detach test	`puppeteer-core` 25.4.0, driving Chromium 151.0.7922.34
Loopback sink	Node v24.5.0, plain HTTP/1.1, no dependencies
Server	ASP.NET Core net10.0 (SDK 10.0.302), Kestrel, HTTP/2 over TLS, Linux
Link	gigabit switch, LAN-direct, CDN out of the path

One trap worth naming: Edge 151 and Chromium 151 are not the same binary. Edge carries its own version line, so the "151" in the hand-driven rows and the "151" in the Playwright rows are different builds that happen to share a major number. That mattered here — the hand-driven and automated numbers differ by 5x, and it would be easy to misread that as a build difference rather than the debugger.

The one-line Blob change is live in Coffer — though, as the numbers above say, it is worth about 30% in one engine rather than the 5x we thought we'd found.