Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions pipelines/garage/specs/hidden-flags.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pipelines/garage/specs/octane.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pipelines/garage/specs/pqc.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pipelines/garage/specs/resample.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pipelines/garage/specs/typed-config.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pipelines/garage/specs/useragent.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion src/pages/garage/blueprint.html
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,7 @@ <h2>What I would not touch<span class="sev keep">the soul</span></h2>
</ul>

<div class="callout">
<strong>The verdict, honestly.</strong> Half of this blueprint is already the changelog:
<strong>The verdict.</strong> Half of this blueprint is already the changelog:
the Workers migration, the in-house counter DO, granular routing, the build step, the
edge-cache kit all landed incrementally, each gated by a 42-route oracle. The site
never went down for any of it. That is the actual argument against a big-bang rewrite:
Expand Down
4 changes: 2 additions & 2 deletions src/pages/garage/chunks.html
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ <h3>FastCDC <small>content-defined: min 16 · avg 40 · max 120 bytes</small></h

<h2>2 · FastCDC, briefly</h2>
<p class="note">
Here is the whole idea, with every operational concern taken back out:
Here is FastCDC with every operational concern taken back out:
</p>
<pre class="toy">function cut(bytes, avg) {
var mask = avg - 1, hash = 0, cuts = [];
Expand Down Expand Up @@ -157,7 +157,7 @@ <h2>2 · FastCDC, briefly</h2>

<h2>3 · Big files</h2>
<p class="note">
Content-addressing earns its keep on large blobs. Drop any file (it
Content-addressing pays off on large blobs. Drop any file (it
never leaves your machine) and your browser FastCDC-chunks it locally
(avg 8&nbsp;KB), then <a class="term" data-t="sha-256" href="https://en.wikipedia.org/wiki/SHA-2" title="A hash function that turns any input into a 256-bit fingerprint. Change one byte of the input and the fingerprint changes completely." rel="external">SHA-256</a>'s each chunk into a content ID. The blocks
run proportional to size so you can see the variable-length cuts; the
Expand Down
6 changes: 3 additions & 3 deletions src/pages/garage/cloudflare.html
Original file line number Diff line number Diff line change
Expand Up @@ -53,13 +53,13 @@
<main id="main" class="content prose">
<h1>Four free Cloudflare features, live</h1>
<p class="lede">
The free Workers plan quietly bundles things that used to cost money or
The free Workers plan bundles things that used to cost money or
a separate service. I wired four of them to live demos here
(<b><a class="term" data-t="durable-object" href="https://developers.cloudflare.com/durable-objects/" title="A Cloudflare Workers object with its own built-in storage, where each named instance lives in one place so every request to it is coordinated." rel="external">Durable Objects</a></b>, <b><a class="term" data-t="workers-ai" href="https://developers.cloudflare.com/workers-ai/" title="Cloudflare's service for running machine-learning models, such as language and vision models, on its own GPUs, called directly from a Worker." rel="external">Workers&nbsp;AI</a></b>, <b><a class="term" data-t="workers-logs" href="https://developers.cloudflare.com/workers/observability/logs/workers-logs/" title="Cloudflare's built-in log store for Workers. It collects each request's log lines so you can search and filter them in the dashboard." rel="external">Workers&nbsp;Logs</a></b>, and <b><a class="term" data-t="trace-span" href="https://opentelemetry.io/docs/concepts/signals/traces/" title="One timed step inside a traced request, with a name, a start time, a duration and attributes. Nested spans show where the time went." rel="external">custom trace spans</a></b>),
behind a tiny worker (<code class="m">cf-garage</code>) routed at
<code class="m">/garage/cf/*</code>. The buttons hit real endpoints; nothing is faked.
A fifth, <b><a class="term" data-t="browser-run" href="https://developers.cloudflare.com/browser-run/" title="Cloudflare's service for controlling a headless browser from a Worker, to render pages, take screenshots or make PDFs." rel="external">Browser&nbsp;Rendering</a></b>, I bound and deployed, then parked on the free
tier&apos;s daily cap. <a href="#parked">Noted honestly below.</a>
tier&apos;s daily cap. <a href="#parked">The note below says why.</a>
</p>

<div class="cf-feat">
Expand Down Expand Up @@ -124,7 +124,7 @@ <h2>The honest scorecard</h2>
request shows its own spans in the trace waterfall.</p>

<div class="callout" id="parked">
<b>The fifth, parked honestly: Browser Run.</b> <a class="term" data-t="headless-browser" href="https://en.wikipedia.org/wiki/Headless_browser" title="A web browser that runs with no window on screen, driven by code, so a program can load pages, run their scripts and capture the result." rel="external">Headless Chromium</a> in a Worker
<b>The fifth, parked: Browser Run.</b> <a class="term" data-t="headless-browser" href="https://en.wikipedia.org/wiki/Headless_browser" title="A web browser that runs with no window on screen, driven by code, so a program can load pages, run their scripts and capture the result." rel="external">Headless Chromium</a> in a Worker
via <code class="m">env.BROWSER.quickAction("screenshot", options)</code>, the basis for
on-the-fly <code class="m">og:image</code> cards. I bind
it and the worker deploys; no enable toggle exists (the binding
Expand Down
2 changes: 1 addition & 1 deletion src/pages/garage/compression.html
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ <h2>Deltas, and why they ship as dcz</h2>
because decode scales with the CPU while 44 bytes stays 44 bytes.
</p>
<p>
Worth saying plainly: on the old numbers this was a coin flip, and on these it's lopsided. The
On the old numbers this was a coin flip, and on these it's lopsided. The
size table now favours brotli by more than it ever did, and that table is the wrong axis to
decide on.
</p>
Expand Down
6 changes: 3 additions & 3 deletions src/pages/garage/encoding.html
Original file line number Diff line number Diff line change
Expand Up @@ -335,14 +335,14 @@ <h3>Chrome paints nothing until every channel has started <span class="badge rev
<p class="note"><b>On a thumbnail that barely matters.</b> The JPG tile is the fallback most
browsers never fetch, and it is small: a median 48.7&nbsp;KB, with the gate at a median
19.3&nbsp;KB. A 10-packet initial <a class="term" data-t="congestion-window" href="https://en.wikipedia.org/wiki/TCP_congestion_control#Congestion_window" title="How much data a TCP sender may have in flight before it hears back. Connections usually start at 10 packets and grow as replies arrive." rel="external">congestion window</a> carries about 14&nbsp;KB, so 116 of the 255
reach their gate in the opening flight and the rest one round trip later. The scan search still earns its place
reach their gate in the opening flight and the rest one round trip later. The scan search is still worth running
at this size, purely for the bytes it saves.</p>

<p class="note">It matters at <a href="/photos">the full-size archive</a>. <code>/images/full/</code>
is the one image surface here with no AVIF tier and no <code>&lt;picture&gt;</code> around it:
the worker streams a median 21.6&nbsp;MB progressive JPEG from R2 (since October 2026 as its
lossless JPEG XL copy, about 8% smaller), and that single file is the whole payload. That is also the awkward part of the format story, because <b>AVIF
structurally cannot do this</b>. Its layered mode caps at four stages, paints early only in
can&apos;t do this</b>. Its layered mode caps at four stages, paints early only in
Chromium, and is staged rather than incremental the way a JPEG scan script is. On the tiles it
costs 6 to 10% more bytes (<a href="#layered-avif">measured below</a>), so nothing here emits
it. So the format that wins every byte comparison on this page
Expand Down Expand Up @@ -406,7 +406,7 @@ <h3>What the archive tier actually costs</h3>
Re-encoding at 4:4:4 instead of 4:2:2 scores 88.28 against 88.15, so the chroma round-trip is
not the limit and 4:2:2 keeps its ~13% byte saving for free. Flattening the reference to 8-bit
first scores 88.08 against 88.15, so the 10-bit&rarr;8-bit step is not the limit either: JPEG is
8-bit, and a HIF&apos;s extra depth earns its keep in the edit.</p>
8-bit, and a HIF&apos;s extra depth pays off in the edit.</p>
<p class="note">That generation also costs far less than it looks once an image is resized for
anywhere else. Comparing a direct downscale of the HIF against a downscale of the archive JPEG,
the same pair that reads 88.15 at full resolution reads <b>94.62 at 1080px</b>: averaging ~50
Expand Down
10 changes: 5 additions & 5 deletions src/pages/garage/hidden-flags.html
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ <h2>The inventory</h2>
<h2>Two questions, and only one of them is free</h2>
<p>When you find an undocumented option, there are two separate things to establish, and reading the docs answers neither.</p>
<p><b>Is it accepted?</b> Does the tool recognise the key at all, or is it dropping an unknown name on the floor? <b>Does it work?</b> Does accepting the key change the behaviour the flag claims to change.</p>
<p>The first question is usually free, and that is the part people skip. A tool with strict argument parsing answers it through its exit code alone, with no work performed and nothing deployed:</p>
<p>The first question is usually free, and people skip it. A tool with strict argument parsing answers it through its exit code alone, with no work performed and nothing deployed:</p>
<pre class="hf-code"><code>$ wrangler deploy --x-bogus-flag ; echo $?
1
$ wrangler deploy --x-provision=false --dry-run ; echo $?
Expand All @@ -230,8 +230,8 @@ <h2>When silence is the failure mode</h2>
<h3>A payload schema that refuses unknown keys</h3>
<p>Cloudflare's <a class="term" data-t="browser-run" href="https://developers.cloudflare.com/browser-run/" title="Cloudflare's service for controlling a headless browser from a Worker, to render pages, take screenshots or make PDFs." rel="external">Browser Run</a> binding takes a JSON payload. A launch post described selecting a rendering engine with one extra key; the Quick Actions reference did not list it. Sending it answered:</p>
<pre class="hf-code"><code>{"code":"unrecognized_keys","keys":["browser"]}</code></pre>
<p>An invented engine name returned the byte-identical error, which is the useful half of the result. The schema is closed, so it refuses the option rather than failing on the value, and a closed schema is a gift: it answers "is this accepted" for free, every time, with no render performed and no browser minutes spent.</p>
<p>The same feature then produced the opposite trap through the <a class="term" data-t="rest-api" href="https://en.wikipedia.org/wiki/REST" title="A common style of web API where each URL names a resource and standard HTTP methods such as GET and POST act on it." rel="external">REST</a> door, where the parameter is merely ignored. A 200 came back either way, so the code labelled the render with the engine it had asked for. On a page whose entire premise is showing what a machine actually saw, that label was a claim nobody had checked. It reads <code>kitesurf-requested</code> now.</p>
<p>An invented engine name returned the byte-identical error. The schema is closed, so it refuses the option rather than failing on the value, and a closed schema is a gift: it answers "is this accepted" for free, every time, with no render performed and no browser minutes spent.</p>
<p>The same feature then produced the opposite trap through the <a class="term" data-t="rest-api" href="https://en.wikipedia.org/wiki/REST" title="A common style of web API where each URL names a resource and standard HTTP methods such as GET and POST act on it." rel="external">REST</a> door, where the parameter is merely ignored. A 200 came back either way, so the code labelled the render with the engine it had asked for. On a page whose premise is showing what a machine actually saw, that label was a claim the code never checked. It reads <code>kitesurf-requested</code> now.</p>

<h3>A compression option three runtimes disagree about</h3>
<p><a class="term" data-t="compression-dictionaries" href="https://www.rfc-editor.org/rfc/rfc9842.html" title="A scheme where the browser keeps an earlier copy of a file and the server sends only a compressed difference against it." rel="external">Dictionary compression</a> takes a <code>dictionary</code> option. <a class="term" data-t="nodejs" href="https://en.wikipedia.org/wiki/Node.js" title="A program that runs JavaScript outside the browser, widely used for servers and build tools." rel="external">Node 26</a> honours it. <a class="term" data-t="cloudflare-workers" href="https://developers.cloudflare.com/workers/" title="Code that runs on Cloudflare's servers around the world and answers each request directly, with no server of the site's own." rel="external">Workers</a> ignore it for <a class="term" data-t="zstd" href="https://en.wikipedia.org/wiki/Zstd" title="Zstandard, a compression algorithm from Meta built for very fast decompression. Browsers accept it as a way to shrink web pages in transit." rel="external">zstd</a> and say nothing. <a class="term" data-t="bun" href="https://en.wikipedia.org/wiki/Bun_(software)" title="A JavaScript runtime that also bundles a package manager, bundler and test runner, built to work as a replacement for Node.js." rel="external">Bun</a> ignored it through 1.3.14 and fixed it in <a href="https://github.com/oven-sh/bun/pull/34427" rel="external">oven-sh/bun#34427</a>. Every one of those failures is silent, because a frame compressed <em>without</em> a dictionary still decodes perfectly <em>with</em> one. Nothing throws. The only symptom is a byte count that never got smaller.</p>
Expand Down Expand Up @@ -394,7 +394,7 @@ <h2>The rule this leaves</h2>
<p>And prefer reading the definition to running the experiment when the definition is in your <code>node_modules</code>. Two of the four cases here were settled by a source comment and a call site, in less time than a deploy takes, and neither answer could have been reached by watching the tool succeed.</p>

<h2>What would change this</h2>
<p>A tool that accepts unknown flags silently would break the free half outright, and the check for that is the bogus-flag control itself: an exit code of 0 on an invented name means every conclusion on this page has to be re-earned with real runs. A hidden flag becoming documented would move its row from this list to an ordinary reference, which is the outcome to hope for. And a measurement showing the capture does honour <code>waitForTimeout</code> would close the one case here that is deliberately still open.</p>
<p>A tool that accepts unknown flags silently would break the free half, and the check for that is the bogus-flag control itself: an exit code of 0 on an invented name means every conclusion on this page has to be re-earned with real runs. A hidden flag becoming documented would move its row from this list to an ordinary reference, which is the outcome to hope for. And a measurement showing the capture does honour <code>waitForTimeout</code> would close the one case here that is deliberately still open.</p>
<section id="luq" aria-label="understanding check"></section>
</main>
<div class="xp-statusbar"><span>garage</span><span>shipped</span><span>2026-08-24</span></div>
Expand Down Expand Up @@ -442,7 +442,7 @@ <h2>What would change this</h2>
]
},
{
"q": "The dictionary control runs three times: no option, the right value, a wrong value. Why does the wrong value earn its place?",
"q": "The dictionary control runs three times: no option, the right value, a wrong value. Why run the wrong value at all?",
"options": [
{
"t": "It ties the smaller output to the value you passed rather than to some other cause.",
Expand Down
Loading
Loading