We’re building a GPU flood solver for unstructured 2D meshes. On every step, each cell reads its neighbors’ state and turns those values into fluxes across its edges. Before optimizing the solver, we wanted to answer one question: how much does the order of cells in memory affect the speed of those neighbor reads?

To find out, we swapped the solver for Game of Life on the same kind of mesh. The memory access pattern is the same (read your neighbors, write yourself), but there’s almost no math, so the result mostly measures memory performance.

Storing cells along a space-filling curve instead of in random order made the benchmark 1.9–3x faster. We didn’t change the kernel or the mesh. The simulation computes the same result, only the cell numbering changed.

Cell reordering assigns nearby mesh cells nearby positions in memory so GPU neighbor reads can reuse cache lines more effectively.

Why Cell Ordering Affects GPU Performance

A GPU memory system fetches data in cache-line-sized transactions. If a cell’s neighbors live next to it in memory, one fetch can cover many of them. If they’re scattered, neighbor reads can require separate trips to device memory.

Meshes don’t always come with a useful order. Our Voronoi mesh numbers its cells in the order the random sites were generated, so random order is our baseline: it’s what you get if you do nothing. The hex grids naturally come out row by row, which already has decent locality, so we shuffled them to create the same baseline.

A space-filling curve — Hilbert, Morton, or Peano — snakes through the 2D domain. Cells that are near each other in space then tend to be near each other in memory.

Each dot is colored by the cell’s position in memory. With random order (left), you get noise. With Hilbert order (right), memory sweeps through the domain in compact blocks.

Benchmark Setup

• Hardware: an M1 Pro running Taichi 1.7.4, a Python framework that compiles kernels to the GPU, on the Vulkan backend. On a Mac, MoltenVK translates Vulkan to Metal. Every timed run reported backend: vulkan, so nothing quietly fell back to the CPU.
• Meshes: stored as CSR adjacency graphs. A 768x768 hex grid (589,824 cells, 3.53M directed edges), a 512x512 hex grid (262,144 cells), and a Voronoi mesh built from 200,000 random sites with scipy.
• Orderings: each one is a permutation applied to the cells before the run. Random uses rng.permutation. For the curves, we snap cell centers to a grid, compute each cell's position along the curve, and sort with argsort. Neighbor indices get remapped to match. Geometry, initial state, and rules stay the same.
• Kernel: two i32 buffers, one for the current state and one for the next. One kernel counts live neighbors along each CSR row and looks up birth/survive tables, then a second one copies the new state back. Standard B3/S23 rules.
• Timing: an untimed warmup for each ordering, ti.sync() on both sides of the timed region, and no reads back to the host inside that region. Each number is the median of 5 runs.

GPU Performance Results

Hex 768x768, 1000 steps, 100 warmup steps:

Smaller meshes, 500 steps, 50 warmup steps:

The choice of curve has little effect

Peano came out on top for both hex meshes in this run, while Hilbert won on Voronoi. In a repeat run, Morton took first place on the 512-cell hex mesh. The curves stayed within 9% of one another, and each beat random order by about 1.9–3x. All three were effective. Our solver uses Hilbert, but Morton is the simplest to implement, so the example below uses it.

Random ordering limits throughput

Under random order, every mesh runs at about 0.9 billion cell updates per second, whatever its size or shape. Random ordering causes poor cache reuse, so mesh layout has little effect. With a curve, the same meshes reach 1.8–2.5 billion updates per second because neighbors are stored closer together.

Memory is the bottleneck

If you count only the bytes each step has to move (edge list, row offsets, state reads, and writes), the curve orders move about 105–111 GB/s on the big hex mesh. That’s more than half of the M1 Pro’s 200 GB/s spec. Random order manages 37 GB/s of useful traffic and spends the rest of its time waiting on cache misses.

How to Reorder Cells in Your Own Mesh

You need two NumPy functions. morton_order takes cell centers and returns a permutation, and reorder_csrrenumbers a CSR adjacency graph to match it. Here, order maps each new cell position to its old cell ID; new_id is the inverse mapping used to rewrite neighbor indices. Apply the same permutation to every other per-cell array you have (state, geometry, boundary flags).

import numpy as np

def morton_order(xy, bits=10):
    """Permutation that sorts cells along a Z-order (Morton) curve."""
    lo, hi = xy.min(0), xy.max(0)
    g = ((xy - lo) / np.where(hi > lo, hi - lo, 1) * (2**bits - 1)).astype(np.uint64)
    key = np.zeros(len(xy), np.uint64)
    for b in range(bits):
        key |= ((g[:, 0] >> b) & 1) << (2 * b)
        key |= ((g[:, 1] >> b) & 1) << (2 * b + 1)
    return np.argsort(key, kind="stable")
def reorder_csr(indptr, indices, order):
    """Renumber cells so that new cell k is old cell order[k]."""
    new_id = np.empty_like(order)
    new_id[order] = np.arange(len(order))
    deg = np.diff(indptr)[order]
    new_indptr = np.concatenate([[0], np.cumsum(deg)])
    src = np.repeat(indptr[order] - new_indptr[:-1], deg) + np.arange(new_indptr[-1])
    return new_indptr, new_id[indices[src]]
order = morton_order(positions)
indptr, indices = reorder_csr(indptr, indices, order)  # int64; cast with .astype(np.int32) for i32 GPU buffers
state = state[order]

With bits=10, the domain is split into a 1024x1024 grid. Cells that land in the same grid square keep their original relative order, so if your mesh is much finer than that, increase bits.

What it costs

Reordering is a one-time cost. On the 768 hex mesh, the code above runs in about 110 ms: 74 ms to compute the keys and sort, 33 ms to rebuild the CSR graph. Each step saves about 450 µs, so it pays for itself after roughly 240 steps. You only do it when you load the mesh.

Reading state back to the CPU is slow. If we copy the full state to the host after every step, the 768 hex mesh with Hilbert order drops from 4033 to 565 steps/s (median of 5 runs of 1000 steps, ranging from 510 to 826). Each readback costs about 1.5 ms, six times the step time. A flood run still needs periodic output, so how often you read back matters about as much as how you order the cells.

Caveats

All of these numbers come from a single M1 Pro going through MoltenVK. A discrete GPU with a different cache setup will give different ratios. Game of Life also does almost no math per neighbor, while a real flux kernel does plenty, so the gap should shrink. Treat 2–3x as the most you can expect from reordering on this hardware. Your own kernel will probably gain less.

Conclusion

If your GPU code gathers neighbor data on an unstructured mesh, check the order of your cells. If the mesher or loader hands them over in arbitrary order, you’re probably leaving speed on the table. Sorting them along a Morton curve takes about 20 lines of NumPy and a tenth of a second when the mesh loads, and on this benchmark it made every step 2–3x faster.

For us, the real test is the flood solver itself. It already orders its cells along a Hilbert curve, and next we’ll time its flux kernel the same way to see how much of that speedup survives once the kernel does real math.

Boosting GPU Performance by Reordering Unstructured Mesh Cells was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

You have probably already tried the obvious thing. You wrote the rules down — in AGENTS.md, CLAUDE.md, .cursor/rules, or whatever file your agent reads first. Do not commit without tests. Do not leave a component without a story. Run the type checker before you say you are done. The agent agreed, enthusiastically, and then went ahead and did something else anyway.

This is not a prompt-quality problem, and it is not specific to any one model. Large language models optimize for the next plausible token, not for your repository’s conventions. In a small codebase you can review every diff and catch the drift by hand. In a large one you cannot: the agent touches a dozen files across a monorepo, the formatting is off, a component is missing its story, a test that used to pass now does not, and the commit lands anyway because nobody is running the checks at the moment the change is written.

The fix is not a better prompt; it is a gate. A Git hook runs your checks on every change, at git commit and git push, whoever - or whatever - wrote it. The tool I use to manage them is Lefthook: a single, dependency-free Go binary, driven by one YAML file, able to run jobs in parallel and re-stage the files it fixes. It reaches past Git, too: an ai: block (currently beta) lets Claude Code, Cursor, Codex, and Copilot run Lefthook hooks on their own events, so your checks fire when the agent stops working - before anything is ever committed. What follows is a working setup: the Git hooks first, then the same checks wired into the agent.

Quick Reference

If you want the short answer before the walkthrough, this is the whole tool at a glance:

The config we build in the next sections wires up five checks on commit and two on push; later, the same checks are attached to your coding agent’s events.

Why Instructions Are Not Enforcement

A written rule is advisory. The agent may follow it, may partially follow it, or may follow it for the first three files and forget by the fourth — and you will not know which until you read the diff. A hook is deterministic. It runs the same command on the same files every single time, it fails closed, and it does not care who authored the change. If the check fails, the commit does not happen.

That difference matters more, not less, as codebases grow. Instructions have to be read, remembered, and applied; enforcement is automatic. It also gives you a single place to put the rules that are specific to your project — the ones no linter ships with, like “every component must have a story” — instead of repeating them across agent instruction files and hoping.

Lefthook fits here because it is small. It is a Go binary with no runtime to install, and it reads lefthook.yml on every hook run, so you never reinstall after editing the config - for Git hooks or for the agent hooks we add later.

Install Lefthook

The most common route is the package manager you already use. For a Node project that is the lefthook npm package:

pnpm add -D lefthook     # or: npm install --save-dev lefthook / yarn add --dev lefthook

There are equivalents for almost every ecosystem, all documented in the installation guide: brew install lefthook on macOS and Linux, go install github.com/evilmartians/lefthook/v2@v2.1.17, pipx install lefthook, gem install lefthook, plus apt, rpm, apk, winget, scoop, snap, and mise. If you would rather not use a package manager at all, download the binary from the latest release and put it on your PATH; lefthook self-update keeps it current.

For CI the mechanics are slightly different, because Git hooks are a local, client-side feature. Nothing runs your pre-commit hook in a container that just cloned the repo - there is no .git/hooks/pre-commit doing work unless you install it. So the CI job installs Lefthook and then calls the hook explicitly:

pnpm add -D lefthook
pnpm exec lefthook run pre-commit --all-files

--all-files replaces {staged_files} with every tracked file, which is what you want when there is no index to speak of. There is no official Lefthook GitHub Action and no official Docker image, so in CI you install the binary yourself - brew, curl, npm, or your base image's package manager - and call the hook explicitly. One detail to know: when the npm package is installed with CI=true set, its postinstall script deliberately skips hook installation, so a CI run will not try to wire up .git/hooks that nothing will execute. Your CI step calling lefthook run is what does the work.

Step 1: Write the Config

The whole configuration is one file at the repository root. This is the shape I use on a TypeScript/React project, and it is the config the runs below use:

# lefthook.yml
min_version: 2.1.10
lefthook: pnpm exec lefthook
glob_matcher: doublestar

pre-commit:
  jobs:
    - name: format staged files
      glob: "**/*.{js,jsx,ts,tsx,json,md,yml,yaml,css}"
      run: pnpm format {staged_files}
      stage_fixed: true

    - name: lint staged files
      glob: "**/*.{js,jsx,ts,tsx}"
      run: pnpm lint {staged_files}
      stage_fixed: true

    - name: typecheck
      run: pnpm check:types

    - name: stories-present
      glob: "src/components/**/*.{ts,tsx}"
      exclude: "**/*.stories.{ts,tsx}"
      run: pnpm check:stories {staged_files}

    - name: unit tests
      run: pnpm test:unit

pre-push:
  parallel: true
  jobs:
    - name: full verification
      run: pnpm verify

    - name: storybook tests
      run: pnpm test:storybook

Seven jobs in total, split across the two hooks:

A few keys carry most of the weight. The format, lint, check:*, and test:* targets are your own package.json scripts, so the config stays tool-agnostic: replacing Prettier with Biome is a change to one script body, not to seven hook entries. jobs is the modern list form (the older commands: map still works, but jobs also support scripts and groups). glob filters the file list a job receives, and exclude removes files from that filtered list. run is the command, executed with sh. The {staged_files} template expands to the files staged for the current commit - for a pre-push job you would use {push_files}, and {all_files} gives you everything tracked.

stage_fixed: true is the one that changes how it feels to use. When a job rewrites its files - Prettier reformatting, ESLint applying an autofix - Lefthook runs git add on them afterward, so the fixes land in the same commit instead of leaving a dirty working tree behind. It only works on pre-commit, and because each of those jobs mutates the index, I keep the auto-fixing jobs sequential by leaving parallel at its default (false). If the git add fails, Lefthook fails the hook rather than let the commit go through with unfixed content. If you would rather fail than let a hook rewrite files, invert the two auto-fixing jobs: run prettier --check and eslint without --fix, drop stage_fixed, and the pre-commit hook becomes a pure, parallel-safe gate.

The typecheck, stories-present, and unit tests jobs do not use {staged_files}; they run against the whole project, because a change in one file can break a type or a test somewhere else. The stories-present job is the interesting one for the agent narrative: it is a rule that exists only in this repository. Its glob is the part that matters, and it is also the part that is easy to get wrong - see The Glob That Silently Disables Your Hook.

The pre-push hook is deliberately broader and parallel. It runs pnpm verify (types, unit tests, and the custom story check) alongside the component tests. This is the layer that catches what a distracted --no-verify commit slipped past, and it is the right place for the slower checks you do not want on every keystroke.

Step 2: Install and Run the Hooks

Install the hooks once per clone:

pnpm exec lefthook install

sync hooks: ✔️(pre-push, pre-commit)

That command writes small shell scripts into .git/hooks/ for each configured hook; each script simply calls lefthook run <hook>. Because the config is read fresh every time a hook runs, editing lefthook.yml never requires reinstalling. You can confirm the hooks are present and synchronized with:

pnpm exec lefthook validate     # config is well-formed
pnpm exec lefthook check-install # exit 0 if hooks are installed and in sync

To run a hook without committing, lefthook run is the entry point. lefthook run pre-commit runs the hook as-is, lefthook run pre-commit --all-files forces every tracked file through it, --file path/to/file forces a specific list, and --job or --tag narrows it to specific jobs. Any hook name is a valid target, so a custom block such as verify: becomes lefthook run verify.

Two escape hatches are worth knowing. LEFTHOOK=0 git commit disables hooks for a single command, and git commit --no-verify bypasses hooks at the Git level. I mention them because they are necessary - but they are also exactly why the push hook and CI matter: a rule enforced only at commit time is a rule that a tired developer or a confident agent can skip.

Finally, teams rarely want identical hooks on every machine. A lefthook-local.yml file (git-ignored) merges over lefthook.yml, so an individual can set skip: true on a slow job or re-tag a command without touching the shared config.

What It Looks Like When a Commit Is Blocked

Here is a real run, on a small demo repository, of an agent finishing a change and committing it. The change adds a greet helper written in double quotes with a let that is never reassigned, and a Modal component with no story file. The first attempt:

$ git commit -m "feat: add greeting helper and modal component"
╭───────────────────────────────────────╮
│ lefthook  v2.1.17   hook:  pre-commit │
╰───────────────────────────────────────╯
┃  format staged files ❯ 
$ prettier --write lefthook.yml src/components/Modal.ts src/greeting.ts
lefthook.yml 12ms
src/components/Modal.ts 18ms (unchanged)
src/greeting.ts 3ms

┃  lint staged files ❯ 
$ eslint --fix src/components/Modal.ts src/greeting.ts

┃  typecheck ❯ 
$ tsc --noEmit

┃  stories-present ❯ 
$ node scripts/check-stories.mjs src/components/Modal.ts
Missing story files for:
  src/components/Modal.ts
[ELIFECYCLE] Command failed with exit code 1.

exit status 1
...

  ────────────────────────────────────
summary: (done in 1.24 seconds)
✓ format staged files (0.26 seconds)
✓ lint staged files (0.44 seconds)
✓ typecheck (0.37 seconds)
✓ unit tests (0.11 seconds)
✗ stories-present (0.05 seconds)

The commit does not happen. Two different things occurred in that run, and they are the two halves of why this works. First, format and lint silently fixed the sloppy code: Prettier rewrote the quotes and style, ESLint turned the let into a const, and stage_fixed re-staged both. You can prove the fixed content is what is staged, not just present in the working tree:

$ git show :src/greeting.ts
export function greet(name: string) {
  const message = 'Hello, ' + name + '!'
  return message
}

Second, stories-present refused the change. The component exists, the story does not, and no amount of instruction-following on the agent's part makes the commit land. Add the missing story and the same commit passes, every job green:

$ git add src/components/Modal.stories.ts
$ git commit -m "feat: add greeting helper and modal component"
...

  ────────────────────────────────────
summary: (done in 1.17 seconds)
✓ format staged files (0.14 seconds)
✓ lint staged files (0.47 seconds)
✓ typecheck (0.38 seconds)
✓ stories-present (0.05 seconds)
✓ unit tests (0.12 seconds)
[main de227fe] feat: add greeting helper and modal component
 4 files changed, 17 insertions(+), 4 deletions(-)

git push runs the second gate. Both jobs run in parallel:

$ git push origin main
╭─────────────────────────────────────╮
│ lefthook  v2.1.17   hook:  pre-push │
╰─────────────────────────────────────╯
┃  storybook tests ❯ 
$ node scripts/check-stories.mjs
Story check passed for 2 component file(s).

┃  full verification ❯ 
$ pnpm check:types && pnpm test:unit && pnpm check:stories
$ tsc --noEmit
$ node --test "src/**/*.test.ts"
✔ adds two numbers (0.467667ms)
ℹ pass 1
ℹ fail 0
$ node scripts/check-stories.mjs
Story check passed for 2 component file(s).

  ────────────────────────────────────
summary: (done in 0.65 seconds)
✓ storybook tests (0.06 seconds)
✓ full verification (0.55 seconds)

The Glob That Silently Disables Your Hook

The config above includes glob_matcher: doublestar, and that one line is doing more than it looks. A pattern like src/components/**/*.{ts,tsx} reads as correct, but without doublestar it never matches a file sitting directly in src/components/. Here is what that looks like on a commit that adds src/components/Modal.ts with no story:

$ git commit -m "feat: add modal component"
...
│  stories-present (skip) no files for inspection
  ────────────────────────────────────
summary: (done in 1.10 seconds)
✓ format staged files (0.11 seconds)
✓ lint staged files (0.49 seconds)
✓ typecheck (0.38 seconds)
✓ unit tests (0.12 seconds)
[main 511f599] feat: add modal component
 1 file changed, 3 insertions(+)

The check did not fail. It did not run at all. In Lefthook’s default matcher (gobwas), ** matches one or more directories, not zero or more, so src/components/**/*.ts requires at least one directory between src/components/ and the file - it matches src/components/Button/Button.ts but not src/components/Modal.ts. With no matching files, Lefthook prints (skip) no files for inspection and moves on, and the commit succeeds. A guard you believe is watching is worse than no guard, because you stop checking by hand.

There are two ways out. The recommended one is to switch to standard glob semantics for the whole config:

glob_matcher: doublestar

With doublestar, **/ matches zero or more directories, so src/components/**/*.{ts,tsx} matches Modal.ts as expected - this is the reason the setting appears at the top of the config above. The catch is that the same setting also makes * separator-aware: a bare *.ts now matches only files in the repository root, where the default matcher had let * cross /. That is why every file glob in the config above uses **/*.{...}: with doublestar, that is how you say "at any depth".

The second option is to keep the default matcher and write the pattern for its rules: because * crosses / there, src/components/*.{ts,tsx} already matches at any depth. That works, but it depends on a matcher behavior most people do not expect, so I prefer the explicit switch. Either way, the lesson generalizes: after you add a file-filtering rule, verify it actually fires. Lefthook's (skip) no files for inspection line in the output is the tell.

Make the Agent Run the Checks Too

The hooks above fire on git commit and git push. An agent that edits twenty files and stops - without committing - never triggers them. Lefthook has a beta feature for exactly this: an ai: block that declares which of your hooks an agent should call on which of its own events. During lefthook install, Lefthook generates the provider's settings file for you.

ai:
  claude:
    Stop: verify
  cursor:
    stop: verify

verify:
  jobs:
    - name: typecheck
      run: pnpm check:types
    - name: unit tests
      run: pnpm test:unit

Stop is Claude Code's event for "the agent finished responding", and stop is the Cursor equivalent; both map to the verify hook that Lefthook then runs. Supported providers are claude, codex, cursor, and copilot. Running lefthook install with the config above updates .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "pnpm exec lefthook run verify" }]
      }
    ]
  }
}

Note the command. Generated hook commands use the top-level lefthook: value when it is set - here pnpm exec lefthook - and otherwise fall back to the absolute path of the binary that ran install. Since that absolute path is machine-specific and would poison a committed settings file, setting lefthook: to a portable command is the difference between a file your teammates can share and a file that only works on your laptop. This feature is marked beta, so treat the generated output as version-sensitive and keep an eye on it when you upgrade.

Lefthook vs. pre-commit vs. Husky

There is no objective winner here; pick the one that fits how your repository already works. If you rely on pre-commit’s managed, per-language hook environments, stay there — that isolation is real value. If your repo is Node-based, Husky is familiar and perfectly capable. I reach for Lefthook for three reasons: it is one binary so nothing new has to be installed at runtime, its jobs run in parallel so the hook stays fast, and {staged_files}, stage_fixed, and glob filtering are built into the config rather than pushed into scripts. As always with tools, the right answer is the one your team will actually keep running.

Troubleshooting & Gotchas

A glob that matches nothing silently skips the job. This is the failure from the section above, and it is the most dangerous one because the hook reports success. ** in the default gobwas matcher means one or more directories; (skip) no files for inspection in the output means your filter is excluding everything. Set glob_matcher: doublestar and use **/ where you mean any depth.

stage_fixed only works on pre-commit, and it needs the index. It calls git add after the job rewrites files, so it cannot fix anything on pre-push or a custom hook. Keep auto-fixing jobs on pre-commit and sequential: if several jobs run in parallel and rewrite the index at the same time, keep them out of that batch.

--no-verify and LEFTHOOK=0 bypass everything. Hooks are a convenience gate, not a security boundary. For rules that must hold, run the same checks in CI (lefthook run pre-commit --all-files) and make that job required. Do not rely on the client-side hook as your only enforcement.

pnpm gates the postinstall script. The lefthook npm package installs hooks from a postinstall script, but pnpm blocks dependency build scripts by default. In pnpm 11/12 the setting moved from pnpm.onlyBuiltDependencies in package.json to an allowBuilds map in pnpm-workspace.yaml; approve it and the postinstall runs. Failing that, lefthook install explicitly does the same thing.

Fresh releases can be held back by supply-chain policies. pnpm refused to install the just-published lefthook@2.1.17 because it was inside the default minimumReleaseAge window; minimumReleaseAge: 0 (or waiting out the window) is the adjustment. Useful to know when a version you just saw released will not install yet.

A long file list is split into several commands. Command-line length is capped on every OS, so Lefthook runs your command in batches when {staged_files} is large. A linter that prints per-run summaries will print one per batch.

Check that the hooks are actually installed. A fresh clone has no hooks until lefthook install runs - the npm postinstall usually handles it, but clones that skip install scripts will not, and CI=true makes the postinstall skip on purpose. lefthook check-install returns exit code 0 only when the hooks are present and in sync, which makes it a cheap guard in a setup script.

Conclusion

Agentic coding has not changed the need for quality gates; it has made them more valuable, because the volume of change goes up while the attention per change goes down. Writing the rules in an instruction file is still worth doing, but it is not enforcement. A Lefthook config is a few dozen lines of YAML that makes the same checks run on every commit and push, whoever — or whatever — wrote the code, and the beta ai: block extends the same jobs to the agent's own events. Start with one hook: format and lint the staged files, re-stage the fixes, and refuse the commit if the tests fail. In a large codebase, that one gate prevents more bad diffs than any prompt.

Resources

• Lefthook documentation
• Configuration reference
• Installation guide
• glob_matcher
• stage_fixed
• ai - agent hooks (beta)
• GitHub repository
• pre-commit

FAQ

My AI coding agent keeps committing code that fails lint and tests. How do I stop it?

Install Git hooks with Lefthook so the checks run before the commit is created. Add a lefthook.yml with a pre-commit hook whose jobs run your formatter, linter, type checker, and tests, then run lefthook install once per clone. If any Lefthook job exits non-zero, the commit is aborted, so code that fails your checks cannot be committed even if an agent ignored the same rules written in an instruction file.

How do I make Git hooks run automatically after every clone without asking each developer to install them?

Add Lefthook to your project’s dependencies — for example pnpm add -D lefthook or npm install --save-dev lefthook. The package's postinstall script runs lefthook install, which writes the hooks into .git/hooks for each developer automatically. Note that pnpm blocks dependency build scripts by default, so you must approve Lefthook's build in pnpm-workspace.yaml, and a fresh clone can always run lefthook install manually.

Why did my Lefthook job not run and print “no files for inspection”?

Lefthook’s default glob matcher treats ** as one or more directories, so a pattern like src/components/**/*.ts does not match src/components/Modal.ts - it matches nothing, and the job is skipped instead of failing. Set glob_matcher: doublestar in lefthook.yml so **/ matches zero or more directories, and remember that with doublestar a bare *.ts only matches the repository root, so use **/*.ts for files at any depth.

How do I make Lefthook commit the files that a formatter fixed?

Set stage_fixed: true on the Lefthook job. After the job's command rewrites the staged files, Lefthook runs git add on them, so the corrected content is included in the same commit. stage_fixed works only on the pre-commit hook, and jobs that use it should run sequentially rather than in parallel because they modify the Git index.

Can I skip Git hooks for a single commit?

Yes. Run LEFTHOOK=0 git commit to disable Lefthook for that one command, or git commit --no-verify to skip Git hooks entirely. Both are intentional escape hatches; because either can bypass a pre-commit hook, rules that must always hold should also be enforced in CI by running lefthook run pre-commit --all-files.

How do I run Lefthook hooks in CI when hooks are a local Git feature?

Install the Lefthook binary in your CI job, then invoke the hook explicitly instead of relying on .git/hooks: pnpm exec lefthook run pre-commit --all-files. The --all-files flag replaces {staged_files} with every tracked file, since there is no staging area to speak of. Setting CI=true makes the Lefthook npm package skip its postinstall hook installation, which is the desired behavior in CI.

Does Lefthook work with Claude Code, Cursor, Codex, and GitHub Copilot?

Yes, through the beta ai: block in lefthook.yml. You map a provider's event names - for example Claude Code's Stop or Cursor's stop - to a Lefthook hook, and lefthook install generates the provider's settings file so the agent calls lefthook run <hook> when that event fires. The feature supports claude, codex, cursor, and copilot, and because it is beta its generated files are worth re-checking after a Lefthook upgrade.

Is Lefthook faster than pre-commit or Husky?

Lefthook is distributed as a single Go binary with no runtime to load, and it can run a hook’s jobs in parallel, so it does not pay the startup cost of a Python framework or a Node process. pre-commit’s advantage is its isolated per-language hook environments, and Husky’s is familiarity in Node projects, so the choice usually comes down to which model fits your repository rather than raw speed.

Beyond Prompts: Enforcing Repository Rules With Git Hooks was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

If your origin needs data the cache key shouldn’t include, an origin request policy is the right tool. It controls what CloudFront forwards to your backend on a cache miss, separately from what makes a request “unique” for caching. Use a managed policy unless you have a specific reason not to — AWS ships eight of them, and most distributions can pick one off the shelf.

The short version, before the rest of the article:

The rest of this article covers what these policies actually do, how they interact with the cache key (where most bugs live), and when to skip the managed list and write a custom one.

This is a follow-up to an earlier post that covered cache, origin request, and response policies as a trio — read that first if you want the broader context.

What an origin request policy actually does

CloudFront builds the request it sends to your origin from two sources. The first is everything in the cache key, controlled by your cache policy. The second is whatever your origin request policy adds on top. Without an origin request policy attached, the only headers your origin sees are the ones already in the cache key, plus a small set CloudFront automatically adds (Host, User-Agent, X-Amz-Cf-Id, and a few others).

That default is intentional. If a value isn’t in the cache key, CloudFront treats requests with different versions of that value as the same cached object. Forwarding the value to the origin would make the response depend on something the cache doesn’t see — and you’d get inconsistent results because the first response wins and gets served to everyone else. Origin request policies let you forward extra data to the origin while keeping the cache blind to it. That’s only safe when the origin uses that data for things that don’t change the response body: logging, analytics, downstream auth, or branching that returns the same content regardless.

I’ve seen teams reach for an origin request policy when what they actually needed was to add a value to the cache key. If your application reads User-Agent to decide between a mobile and a desktop response, forwarding it via an origin request policy isn't enough — the cached response is shared across both. The fix is to put User-Agent in the cache key, or to use a CloudFront-supplied header like CloudFront-Is-Mobile-Viewer, which is designed exactly for that case.

How it interacts with the cache policy

Anything in the cache key is automatically forwarded to the origin. The origin request policy can only add to that — it can’t subtract. If your cache policy includes Authorization in the cache key, the origin will see it on a cache miss whether or not your origin request policy mentions it. This often surprises people debugging "why is this header reaching my origin when I didn't list it?"

There’s also a hard requirement worth knowing up front: a cache behavior cannot have an origin request policy attached without also having a cache policy. AWS rejects the configuration. So in practice, every distribution that uses origin request policies pairs each one with a cache policy on the same behavior.

The working rule: put values in the cache key when the response actually varies on them. Put values in the origin request policy when the origin needs them but the response is the same regardless.

What’s inside an origin request policy

Three knobs: headers, cookies, and query strings. Each one accepts a behavior, plus an optional list when the behavior calls for one.

For headers, the available behaviors are:

• none — no viewer headers forwarded (cache-key headers still go through, plus the small CloudFront-added set)
• whitelist — only the listed headers
• allViewer — every viewer header
• allViewerAndWhitelistCloudFront — every viewer header plus specific CloudFront headers (geolocation, device-type, TLS info)
• allExcept — every viewer header except a listed set

Cookies and query strings have a similar shape but a smaller set: none, all, whitelist, or allExcept. There's no allViewerAndWhitelistCloudFront equivalent because CloudFront doesn't add its own cookies or query strings.

A subtlety worth knowing before you read the managed policies below: when a policy uses allExcept to remove the viewer's Host header, CloudFront automatically replaces it with a new Host header containing the origin's domain name. That's exactly what makes AllViewerExceptHostHeader work for API Gateway — the gateway sees its own domain in the Host header and routes correctly, instead of seeing the CloudFront distribution's domain and rejecting the request.

The eight managed policies

Each managed policy has a stable ID that you reference from CloudFormation, the AWS CLI, the SDKs, or your IaC tool of choice. The IDs don’t change, so it’s safe to hardcode them.

AllViewer

Forwards every header, cookie, and query string from the viewer request to the origin.

ID: 216adef6-5c7f-47e4-b989-5492eafa07d3

Use this when your backend genuinely needs the full request — typically for legacy applications, complex authenticated apps, or anything where you can’t easily enumerate which headers and cookies matter. The trade-off is that it forwards the viewer’s Host header too, which means it doesn't work with API Gateway or Lambda function URLs (use AllViewerExceptHostHeader for those). It also forwards anything sensitive that the client happens to send, so think about whether your origin should see, for instance, a long-lived authentication cookie that some unrelated part of your app sets.

AllViewerAndCloudFrontHeaders-2022–06

Same as AllViewer plus a fixed set of CloudFront-added headers: CloudFront-Forwarded-Proto, the device-type series (-Is-Android-Viewer, -Is-Mobile-Viewer, -Is-Tablet-Viewer, etc.), the geolocation series (-Viewer-Country, -Viewer-City, -Viewer-Latitude, -Viewer-Longitude, -Viewer-Time-Zone, -Viewer-Postal-Code, -Viewer-ASN, and a few more), CloudFront-Viewer-Http-Version, and CloudFront-Viewer-TLS.

ID: 33f36d7e-f396-46d9-90e0-52428a34d9dc

The -2022-06 suffix is significant. The set of headers this policy forwards is frozen as of June 2022 — any CloudFront viewer header added after that date isn't included. AWS does this so existing distributions don't change behavior when new headers ship. If you want a newer CloudFront header in your origin requests, write a custom policy.

Use this when your origin uses CloudFront’s enriched headers for personalization, analytics, or routing. Geolocation-based content selection is the common case: your backend reads CloudFront-Viewer-Country and serves a localized response, without doing GeoIP lookups itself.

AllViewerExceptHostHeader

Forwards everything except the Host header. CloudFront then injects the origin's domain name as the new Host.

ID: b689b0a8-53d0-40ab-baf2-68738e2966ac

This is the policy you almost certainly want when your origin is API Gateway, a Lambda function URL, or any AWS-managed endpoint that does virtual hosting based on the Host header. These services check Host against their own domain. If CloudFront forwards the viewer's Host (which is your CloudFront distribution's domain or your custom domain), they don't recognize it and respond with a 403.

It also includes the same set of CloudFront viewer headers as AllViewerAndCloudFrontHeaders-2022-06, which means you get geolocation and device-type metadata for free. For most API Gateway-backed CloudFront distributions, this is a one-line answer to a problem that used to require fiddling with cache behaviors and Lambda@Edge.

CORS-CustomOrigin

Forwards only the Origin header. No cookies, no query strings.

ID: 59781a5b-3903-41f3-afcb-af62929ccde1

Use this when your origin is anything other than S3 — an ALB, an EC2 instance, a containerized service, or a third-party HTTP server — and it serves cross-origin requests. The Origin header is what the server inspects to decide whether to return CORS-allowing response headers. Anything more just bloats the origin request without any CORS benefit, and risks forwarding data the origin doesn't need to see.

This policy pairs naturally with the CORS-with-preflight-and-SecurityHeadersPolicy response headers policy when your backend doesn't reliably set CORS headers itself.

CORS-S3Origin

Forwards Origin, Access-Control-Request-Headers, and Access-Control-Request-Method. No cookies, no query strings.

ID: 88a5eaf4-2fd4-4709-b370-b4c650ea3fcf

S3 is fussier about CORS than a custom server. To return the right CORS response headers, S3 needs to see all three of these request headers — not just Origin. The standard CORS forwarding policy (CORS-CustomOrigin) doesn't work because it omits the other two. If you've ever spent time debugging "CORS works locally but not through CloudFront" with an S3 origin, this is almost certainly the missing piece.

Note that this policy is for S3-as-origin scenarios where you’ve also configured a CORS rule on the bucket itself. Without the bucket-side CORS configuration, S3 won’t return the Access-Control-Allow-* headers regardless of what gets forwarded.

HostHeaderOnly

Forwards just the Host header. Nothing else.

ID: bf0718e1-ba1e-49d1-88b1-f726733018ae

A narrow policy with a specific use case: multi-tenant origins that route based on the original viewer Host. If your backend serves multiple custom domains and uses the Host header to figure out which tenant a request belongs to, you need that header to come through unchanged. Most other managed policies either rewrite Host or don't forward enough information to make it useful.

If you’re using this with anything other than a multi-tenant routing scenario, double-check whether you actually want it. For API Gateway origins, HostHeaderOnly will not work — API Gateway needs the rewritten Host, which is what AllViewerExceptHostHeader gives you instead.

UserAgentRefererHeaders

Forwards only User-Agent and Referer.

ID: acba4595-bd28-49b8-b9fe-13317c0390fa

This is the policy for cases where the origin needs to know “what kind of client is this?” or “where did the request come from?” without seeing the rest of the headers, cookies, or query strings. Two common uses: hotlink protection (block requests where Referer doesn't match an allowed list) and analytics that bucket traffic by browser or operating system.

It pairs well with a tight cache policy — typically CachingOptimized — because neither header is in the cache key. The cache stays efficient and the origin still gets enough data to do its filtering or counting.

Elemental-MediaTailor-PersonalizedManifests

Forwards Origin, Access-Control-Request-Headers, Access-Control-Request-Method, User-Agent, X-Forwarded-For, and all query strings.

ID: 775133bc-15f2-49f9-abea-afb2e0bf67d2

A specialized policy for AWS Elemental MediaTailor, which serves personalized HLS/DASH manifests for ad insertion in video streaming. MediaTailor needs the CORS triplet for browser playback, User-Agent and X-Forwarded-For for ad-decisioning logic, and the full query string because session and personalization tokens are encoded there. If you're not using MediaTailor, you don't need this policy — but if you are, it's the difference between manifests that work and manifests that don't.

Comparison: what each managed policy forwards

When to write a custom origin request policy

The managed policies cover most cases. A custom policy is needed when:

• Your origin needs a specific application header (like X-Tenant-ID or X-Request-Trace) that isn't in any managed policy
• You want CloudFront viewer headers added after June 2022 — the managed AllViewerAndCloudFrontHeaders-2022-06 is frozen at that date
• A specific cookie or query string needs to pass through while others stay blocked (no managed policy uses the whitelist behavior for cookies or query strings)
• The requirements get oddly mixed — e.g., “everything except Authorization, plus a few CloudFront geolocation headers"

Here’s a Terraform example for a custom policy that forwards a tenant header, geolocation, and a session cookie, while excluding everything else:

resource "aws_cloudfront_origin_request_policy" "tenant_api" {
  name    = "tenant-api-policy"
  comment = "Forwards tenant routing data and CF geolocation"

  headers_config {
    header_behavior = "whitelist"
    headers {
      items = [
        "X-Tenant-ID",
        "CloudFront-Viewer-Country",
        "CloudFront-Viewer-City",
      ]
    }
  }
  cookies_config {
    cookie_behavior = "whitelist"
    cookies {
      items = ["session_id"]
    }
  }
  query_strings_config {
    query_string_behavior = "none"
  }
}

A subtle gotcha worth knowing: under allViewerAndWhitelistCloudFront, the headers.items list isn't the only set of headers forwarded — every viewer header is forwarded too, and the list just adds CloudFront-specific headers on top. The behavior name is more literal than it looks. To restrict to a specific allowlist, use whitelist (as in the example above) and list both the viewer headers and any CloudFront headers you want.

To list all available origin request policies (managed and custom) from the AWS CLI:

# Returns the 8 managed policies with their IDs
aws cloudfront list-origin-request-policies --type managed

# Or list only your custom policies
aws cloudfront list-origin-request-policies --type custom

To attach a managed policy by ID, set OriginRequestPolicyId on the relevant cache behavior in your distribution config:

aws cloudfront update-distribution \
  --id E1A2B3C4D5E6F7 \
  --distribution-config file://config.json

Common pitfalls

A header isn’t reaching the origin in the form you expect

Check whether the same header is configured under Origin Custom Headers on the distribution. AWS specifically warns against setting the same header in both places. Origin custom headers are applied before CloudFront forwards the request, and if the header is already present in the viewer request, CloudFront overwrites the value. The origin sees one deterministic value, but it may not be the one you set in the origin request policy. Pick one mechanism per header and you avoid the ambiguity.

API Gateway returns 403 even though Host isn't in the allowlist

If you wrote a custom policy and used whitelist for headers without including Host in the allowlist, the viewer's Host header isn't forwarded — but it also isn't replaced. CloudFront's automatic Host rewrite only kicks in with the allExcept behavior when Host is in the excluded list. For API Gateway, either use AllViewerExceptHostHeader (the easiest path), or use allExcept with Host in the exclusion list.

Authorization reaches the origin even though it's not in the policy

Your cache policy is including it. Cache-key headers are automatically forwarded; the origin request policy can only add to that. Open the cache policy attached to the same cache behavior and check whether Authorization is listed under headers there. If you actually want the header to stay out of the origin requests, you'll need to remove it from the cache key — and accept the implications for cache hit ratio, since responses will no longer be keyed on it.

A CloudFront-added header isn’t arriving

Two different causes look the same from the origin side. First, the header may simply not be in your policy: a bare AllViewer doesn't include any CloudFront-added headers, and AllViewerAndCloudFrontHeaders-2022-06 is frozen at the set of headers AWS released through June 2022. Anything added later — CloudFront-Viewer-JA3-Fingerprint and CloudFront-Viewer-JA4-Fingerprint for TLS fingerprinting, CloudFront-Viewer-Header-Order and CloudFront-Viewer-Header-Count for bot detection, CloudFront-Error-Uri and CloudFront-Error-Args for error-handling flows — is not in the managed -2022-06 policy. To get those, write a custom origin request policy and list them explicitly.

Second, even when the header is included, AWS notes that CloudFront-Viewer-City, CloudFront-Viewer-Metro-Code, and CloudFront-Viewer-Postal-Code may not be available for every IP address — some addresses don't geolocate with enough precision. If those fields are blank for some traffic but populated for others, the policy is fine; the geolocation data just isn't there.

Cookies aren’t reaching a Lambda function URL even with AllViewerExceptHostHeader

Three things to check, in order. First, confirm the browser actually sent the cookie to your CloudFront domain — Secure, HttpOnly, SameSite=Strict, and Domain mismatches all stop browsers from including the cookie in the first place, and no policy can rescue you if the cookie never crossed the wire. Second, confirm the policy you chose includes cookies: AllViewerExceptHostHeader does forward all cookies, but if you wrote a custom policy and set cookie_behavior = "none", you'll see no cookies at the origin regardless of what was in the request. Third, when you do receive the request at the function, remember that Lambda function URLs use the API Gateway v2.0 payload format — cookies arrive in the event's cookies array, not in headers["Cookie"]. Code that reads the Cookie header directly will appear to receive nothing even when the cookies are present in the event.

If the issue is specific to cross-origin browser requests, the function URL’s CORS configuration matters too — specifically the AllowCredentials setting, which has to be true for credentialed requests to be allowed at all. But that's only one of three things that need to align: the cookie has to permit cross-origin sending (typically SameSite=None; Secure), the client-side fetch has to opt into credentials (credentials: 'include'), and the function URL has to allow credentials. Miss any one and the cookie won't reach the function — and none of that is something CloudFront can fix from the edge.

Picking the right policy

A short decision tree:

1. Is your origin API Gateway or a Lambda function URL? → AllViewerExceptHostHeader
2. Is your origin S3 and you need CORS? → CORS-S3Origin
3. Is your origin a custom server (ALB, EC2, ECS) with CORS? → CORS-CustomOrigin
4. Are you using AWS Elemental MediaTailor? → Elemental-MediaTailor-PersonalizedManifests
5. Do you only need to identify the client? → UserAgentRefererHeaders
6. Are you running multi-tenant routing on Host? → HostHeaderOnly
7. Does your origin need everything? → AllViewer, or AllViewerAndCloudFrontHeaders-2022-06 if you want geolocation too
8. None of the above? → Write a custom policy

If none of the managed policies match exactly but you’re close, custom policies are cheap to create and easy to version. There’s no API quota concern for normal use, and you can test changes by attaching the new policy to a non-production cache behavior first.

The next post in this series will go through CloudFront response headers policies in the same depth — what each managed policy adds, when the browser actually honors it, and where custom policies are worth the maintenance cost.

Need help optimizing your CDN?

If you are struggling with complex CloudFront configurations or cache behavior, reach out to u11d for expert engineering guidance.

Originally published at https://u11d.com on September 30, 2026.

A Complete Guide to AWS CloudFront Origin Request Policies | u11d was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Server Components can reduce client-side JavaScript, keep sensitive logic on the server, and prevent data-fetching waterfalls. But they also introduced a frustrating user experience in many dynamic applications: after clicking a link, the user sometimes had to wait for the server before seeing the next screen.

Next.js 16.3 addresses this problem with Instant Navigations, an opt-in set of rendering, prefetching, development, and testing tools. The goal is not to make every data request finish immediately. It is to make sure the application always has meaningful UI ready when navigation begins.

This is particularly useful for e-commerce platforms, dashboards, and account areas. These applications cannot prerender every personalized state at build time, but they should still respond to clicks without a visible pause.

In this guide, I will explain how Instant Navigations work, how to choose between streaming and caching, and how to protect navigation performance with Playwright tests.

Why Dynamic Next.js Navigations Can Feel Slow

In a traditional server-driven navigation, the sequence often looks like this:

1. The user clicks a link.
2. The browser requests the target route from the server.
3. The server reads data and renders the route.
4. The browser finally displays the next UI.

The architecture can be efficient, but the delay between the first and fourth steps is visible. A client-driven SPA usually feels more responsive because it already has enough code in the browser to display the next screen or its loading state immediately.

Before Next.js 16.3, teams had two common ways to reduce this delay:

• prerender the full page at build time, which does not work for every dynamic or personalized route
• fully prefetch each destination with <Link prefetch={true}>, which can generate unnecessary requests and increase server load

A loading.tsx file could provide an immediate loading state, but it was easy to forget and applied at the route-segment level rather than around the exact data dependency.

Instant Navigations provide a more precise model. Instead of asking whether the whole route is static or dynamic, you decide which parts can be ready before the click and which parts should arrive later.

Enabling Instant Navigations in Next.js 16.3

Instant Navigations are opt-in in Next.js 16.3. Enable Cache Components and Partial Prefetching in next.config.ts:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

cacheComponents enables the explicit caching model built around 'use cache', cacheLife, and cacheTag. It also allows routes to combine prerendered UI with dynamic content behind Suspense boundaries.

partialPrefetching changes how Next.js prepares routes on the client. Instead of treating prefetching as an all-or-nothing decision, Next.js can prefetch only the reusable UI needed to start a navigation.

Enabling cacheComponents is a migration step, not just a performance flag. During production builds, Next.js attempts to prerender as much of a route as possible and can report an error when runtime or uncached data is accessed outside a Suspense boundary. Each case must be streamed behind Suspense, cached with 'use cache' when appropriate, or explicitly allowed to block with export const instant = false. Existing applications may also need to remove incompatible route segment configuration such as dynamic, revalidate, or fetchCache.

These behaviors are planned to become defaults in a future major version. In 16.3, enabling them explicitly gives teams time to review their asynchronous boundaries and migration requirements.

The Core Model: Stream, Cache, or Block

When a route depends on asynchronous data, Next.js 16.3 asks you to make the intended behavior explicit. There are three useful choices.

1. Stream dynamic content with Suspense

Use <Suspense> when the data must stay fresh or depends on the active request. The fallback becomes part of the route shell, so it can appear immediately while the server renders the final content.

This is a good fit for:

• inventory and delivery estimates
• cart state
• account-specific data
• live analytics
• personalized recommendations

The navigation is instant because the user sees the fallback without waiting for the dynamic operation. The final data still arrives from the server later.

2. Cache reusable content with 'use cache'

Use 'use cache' when the result can be safely reused. Cached UI can be included in the prefetched response and displayed immediately during navigation.

This works well for:

• product descriptions
• category content
• CMS blocks
• public pricing shared by a region
• configuration that changes infrequently

The cache boundary should follow the business meaning of the data. Content that is safe to share globally should not be mixed with customer-specific prices or session state.

3. Allow the route to block

Not every route needs to navigate instantly. If displaying a loading state would be misleading and the route should wait for complete server output, mark that decision explicitly:

export const instant = false

This can be appropriate for a simple content page where the team prefers to show the complete article at once, or for a flow where a partial state would create confusion.

The important change is that blocking becomes an intentional route decision rather than an accidental result of one unresolved data dependency.

How Partial Prefetching Changes the Network Cost

The previous prefetching model could issue a request for every visible link. Consider an account sidebar with twenty links to /orders/[id]. Even though all links share the same route structure, the browser could prefetch each destination separately.

With Partial Prefetching, Next.js can generate one reusable shell for /orders/[id], store it in the browser, and use it for multiple links during the session. This is closer to route-level code splitting in a SPA: the browser receives enough UI to react immediately, but it does not need the complete data for every possible destination.

If a particular link deserves a deeper prefetch, you can still opt in:

<Link href={`/products/${product.slug}`} prefetch={true}>
  {product.title}
</Link>

Next.js then prerenders as much of that destination as it safely can. Synchronous values from the URL and content marked with 'use cache' can be included, while request-bound work remains behind its Suspense boundary.

This avoids a common tradeoff in dynamic applications: either prefetch nothing and make the user wait, or prefetch complete pages and make the server do work that may never be used.

A Practical E-Commerce Example

A product page usually combines data with very different freshness requirements:

• product copy and media are broadly reusable
• inventory changes often
• customer pricing may depend on identity, region, or sales channel
• the cart belongs to the current session

Making the whole page dynamic means one slow operation can block navigation. Caching the whole page is more dangerous because it can expose stale or private data.

A better boundary looks like this:

import { Suspense } from 'react'
import { cacheLife, cacheTag } from 'next/cache'

async function ProductSummary({ slug }: { slug: string }) {
  'use cache'

cacheTag(`product:${slug}`)
  cacheLife('hours')
  const product = await getProduct(slug)
  return (
    <section>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
    </section>
  )
}
async function Inventory({ slug }: { slug: string }) {
  const inventory = await getLiveInventory(slug)
  return <p>{inventory.available} items available</p>
}
export default async function ProductPage({
  params,
}: PageProps<'/products/[slug]'>) {
  const { slug } = await params
  return (
    <main>
      <ProductSummary slug={slug} />
      <Suspense fallback={<p>Checking availability...</p>}>
        <Inventory slug={slug} />
      </Suspense>
    </main>
  )
}

The product summary can be cached and reused. Live inventory remains dynamic, but it no longer prevents the route from showing useful content. During navigation, the browser can display the product UI or its prepared shell first and fill in availability when the server responds.

For a real storefront, customer-specific pricing should follow the same principle as inventory: isolate it in a private or request-time boundary instead of adding cookies or session access to the entire page.

Finding Slow Routes with Instant Insights

Performance problems are difficult to fix when they only appear as a vague feeling that the application is slow. Next.js 16.3 adds Instant Insights to the development tools to make the problem visible.

When you encounter a non-instant navigation during development, Instant Insights identifies the route and points to the asynchronous work that blocks its shell. In most cases, the fix is one of the following:

• move request-specific work below a Suspense boundary
• mark reusable work with 'use cache'
• move a blocking dependency out of a shared layout
• explicitly accept blocking with export const instant = false

The Navigation Inspector complements this by pausing navigation at the prefetched shell. This lets you inspect exactly what the user can see before dynamic content arrives. It is useful because production prefetching is normally disabled in development, where loading behavior can otherwise be difficult to reproduce accurately.

Testing Instant Navigations with Playwright

A route that feels instant today can become blocking after a small refactor. A new cookies() call in a shared component or a moved Suspense boundary may be enough to change the result.

Next.js 16.3 includes the instant() helper in @next/playwright. It temporarily holds back dynamic content, allowing the test to assert which UI is available without waiting for the network:

import { expect, test } from '@playwright/test'
import { instant } from '@next/playwright'

test('product navigation shows useful UI instantly', async ({ page }) => {
  await page.goto('/products/shoes')
  await instant(page, async () => {
    await page.click('a[href="/products/hats"]')
    await page.waitForURL((url) => url.pathname === '/products/hats')
    await expect(page.locator('h1')).toContainText('Baseball Cap')
    await expect(page.getByText('Checking availability...')).toBeVisible()
  })
  await expect(page.getByText(/items available/)).toBeVisible()
})

The test describes a user-facing contract:

• the product title must be available immediately
• the inventory fallback must be visible while live data is pending
• the final inventory must appear after the dynamic work completes

This is more useful than testing an arbitrary duration such as 100 milliseconds. Network and CI timing can vary, but the boundary between prefetched UI and network-dependent UI is deterministic.

The v0 team used this property to improve real routes with a coding agent. The agent wrote a failing instant() test, moved or cached the blocking work, rebuilt the application, and repeated the process until the test passed. The resulting 16 tests were kept in CI to prevent future regressions.

Where Teams Usually Get It Wrong

Mistake 1: Treating “instant” as “fully loaded”

Instant Navigations do not make databases or APIs respond with zero latency. They guarantee that useful UI can respond to the click without waiting for those systems.

The distinction matters. A complete page may still stream in over time, but the application should never look unresponsive.

Mistake 2: Placing Suspense too high in the tree

Wrapping an entire page in one Suspense boundary may technically make navigation instant, but the user will see a generic full-page skeleton. Place boundaries close to the data that actually needs to wait so stable navigation, headings, and controls remain visible.

Mistake 3: Reading dynamic data in a shared layout

A session or request-dependent operation near the root can block many routes at once. Keep shared layouts focused on reusable UI and move dynamic reads into the components that need them.

Mistake 4: Enabling full prefetching on every link

prefetch={true} is still useful, but it should represent a deliberate choice to prepare more than the route shell. Applying it everywhere can recreate the server and network cost that Partial Prefetching is designed to avoid.

Mistake 5: Using meaningless loading states

An instant blank rectangle is not a good user experience. The shell should preserve the layout and provide enough context for the user to understand where the navigation is going.

For a product page, that may include the title, gallery frame, price area, and an inventory placeholder. For an account page, it may include the navigation, page heading, and form structure.

A Practical Adoption Strategy

For an existing Next.js application, avoid changing every route at once. Start with the journeys where a delay has the largest user or business impact.

1. Enable cacheComponents and partialPrefetching in a branch.
2. Use Instant Insights to identify blocking navigations.
3. Choose one important journey, such as category to product or cart to checkout.
4. Write a failing test with instant() that describes the minimum UI required after the click.
5. Stream request-bound data and cache only content that is safe to reuse.
6. Inspect the shell with Navigation Inspector.
7. Keep the test in CI after the route passes.

This process turns perceived performance into an architectural requirement that can be reviewed and tested. It also creates a clear stopping point: the work is complete when the intended shell is visible without network-dependent content.

Final Thoughts

The most important part of Instant Navigations is not another prefetch option. It is the clearer boundary between UI that must be ready for a click and data that is allowed to arrive later.

For dynamic applications, this removes the need to choose between a server-driven architecture and SPA-like responsiveness. Server Components can continue to handle rendering and sensitive data, while Suspense, Cache Components, and reusable route shells keep navigation responsive.

The best result comes from combining three decisions:

• stream data that must remain dynamic
• cache content that is genuinely reusable
• block only when waiting is an intentional product choice

Once those decisions are protected by instant() tests, navigation performance stops being something that can disappear unnoticed during the next refactor.

Achieving Instant Navigations in Next.js 16.3 was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

A bullion dealer’s product catalog doesn’t have prices. It has formulas. A 1 oz gold coin isn’t “2,100” the way a t-shirt is “25” — it’s weight × today's spot price × your spread, plus whatever fixed minting or handling premium you charge on top. Spot prices for gold and silver move throughout the trading day, sometimes several times a minute, which means the "correct" price for every SKU in the catalog is technically wrong again a few seconds after you last calculated it.

Most e-commerce platforms were not built around that assumption. They were built around the idea that a product has a price, someone sets it, and it stays put until someone changes it again. That’s a completely reasonable default for almost every category of goods sold online — until the goods themselves are priced off a market that never stops moving.

This creates a specific set of requirements that a general-purpose store doesn’t have to think about:

• Live pricing tied to a market feed, not a value someone typed into an admin panel.
• A pricing formula per product or product line — spread, fixed premiums, percentage premiums — layered on top of that feed.
• Frequent updates, ideally continuous during market hours, not a batch job that runs once an hour.
• Checkout price locking — the price a customer sees when they start checkout has to hold for a defined window, or the order has to be rejected, otherwise either the dealer or the customer eats the difference.
• Reliability when the feed itself fails — a stale or missing spot price can’t silently turn into a wrong price or a broken checkout.
• Integrations with ERP systems, inventory/vaulting software, and payment processors that are comfortable underwriting a high-value, high-risk category.
• Room to customize the pricing logic as the business’s spreads, premium structure, or product mix changes.

WooCommerce, Shopify, and Medusa can all run a bullion store. The difference is how much of the above you get by default, how much you build yourself, and how much friction you hit doing it. This article compares all three specifically against that list — not as a generic “which platform is better” question, but as the specific decision a bullion or precious-metals dealer is actually facing.

Quick Reference

Why Bullion E-Commerce Doesn’t Behave Like a Normal Store

Before comparing platforms, it’s worth being precise about what’s actually different, because it’s easy to under-scope this as “just update the price more often.”

The price is derived, not entered. A normal product’s price is a fact you record. A bullion product’s price is the output of a calculation: current spot price for that metal, times the product’s weight, times a spread factor, plus any fixed or percentage premium (minting costs, rarity, packaging). Change the spot price and every affected SKU’s correct price changes with it — instantly, in principle.

Update frequency is high and continuous. Gold and silver spot prices move throughout market hours. A store that only updates prices a few times a day is either giving away margin between updates (selling below the current market) or overcharging (selling above it) — and both outcomes cost the dealer customers over time, just in different ways.

Checkout needs a quote, not a live price. A customer needs the price to hold still for the few minutes it takes to fill in an address and pay. If the price is still tied to a live feed while payment is being processed, the amount charged can differ from the amount the customer agreed to. The standard fix is a “lock”: freeze the computed price the moment checkout starts, attach an expiry to it, and refuse to complete the order if that lock has expired by the time payment is submitted.

A feed outage can’t become a wrong price. If the spot-price provider goes down for ten minutes, the store has to keep functioning — showing the last known good price and continuing to accept orders — rather than either breaking checkout or, worse, silently pricing products at $0 or a stale multi-day-old value.

The integration surface is wider than checkout. Bullion dealers commonly need to sync with an ERP or inventory/vaulting system, and payment processing for precious metals is frequently treated as a reviewed or higher-risk category by processors — worth confirming with your payment provider early, regardless of which platform you choose.

None of this is exotic engineering. But it’s also not something any of the three platforms below solves out of the box.

WooCommerce for Bullion Dealers

WooCommerce’s strength here is exactly its strength everywhere else: it’s open PHP, self-hosted, and has an enormous plugin ecosystem, so there’s a real, mature market of niche plugins for this exact use case. Plugins like Precious Metals Product Prices for WooCommerce advertise real-time precious-metals pricing, product sync, and wholesale drop-ship order automation specifically for bullion and coin stores, and simpler options like Gold Price Based on Weight calculate a product’s price from a global price-per-gram figure and the product’s weight. These plugins genuinely solve the “pull a live price and multiply it out” problem.

Where WooCommerce runs into friction is checkout behavior. WooCommerce recalculates the cart and checkout totals from each product’s currently stored price every time the cart is loaded — there’s no built-in concept of “hold this exact quoted price for the next 10 minutes, then reject the order if it expires.” A dealer who wants that has to build it as custom logic on top of one of the pricing plugins: snapshotting the computed price into cart or session data, and validating it again before the order is allowed to complete.

Real-time storefront updates (a price that visibly ticks upward or downward while a customer is looking at the cart, without a page reload) also aren’t native. Even with WooCommerce’s newer Cart and Checkout blocks, the built-in reactivity is around cart operations like changing a quantity — it won’t push an externally changing spot price into an already-open page without custom JavaScript polling a price endpoint yourself.

WooCommerce is a good fit for a smaller dealer already running WordPress, with a catalog that doesn’t need sub-minute pricing precision, and a technical budget that can stretch to some custom development for checkout locking.

Shopify for Bullion Dealers

Shopify’s case is speed and operational simplicity: managed hosting, PCI compliance handled for you, a fast path to launch, and by far the largest app ecosystem of the three. For a dealer who wants to be selling quickly and isn’t chasing sub-minute pricing precision, that’s a legitimate, low-friction starting point.

The friction shows up in how Shopify models price and checkout. A product variant’s price is a stored field, not a computed value — a pricing app updates it by calling the Admin API on a schedule or in response to a webhook, which is fundamentally a batch update loop, not a live per-request formula tied to a streaming feed. Checkout customization today runs through Shopify Functions: discount functions, cart/checkout validation functions, delivery and payment-method customization functions, and similar. Every documented Function category is scoped to adjusting discounts, validation, or checkout behavior around an existing price — none of them is designed to recompute a commodity-linked unit price from a live formula on the fly.

There’s also a plan gate to be aware of: per Shopify’s own documentation, stores on any plan can install a public app from the Shopify App Store that happens to contain Functions, but building and running a custom app with Shopify Function APIs requires a Shopify Plus plan. That matters for a dealer planning to build bespoke pricing logic in-house rather than relying entirely on a third-party app.

Shopify is a good fit for a dealer prioritizing managed infrastructure and fast launch, where pricing updates on the order of minutes-via-API (rather than a continuous live feed) and standard discount/checkout customization are acceptable trade-offs.

Medusa’s Extensibility: Building Only the Part That’s Actually Custom

Medusa doesn’t ship dynamic commodity pricing, ERP connectors, or a high-risk-friendly payment processor out of the box — no platform in this comparison does. The difference is what it costs to add them. Medusa’s core is organized as modules (self-contained data and logic for one domain — pricing, tax, payments, inventory), workflows (business logic composed of retryable, rollback-safe steps), and module links (which connect data across modules without collapsing everything into one table). That structure means a dealer-specific requirement gets built as an addition that plugs into Medusa’s existing provider interfaces and event system, not as a fork of the platform or a rebuild of checkout, promotions, multi-region support, or order management.

This isn’t a theoretical benefit. u11d’s own @u11d/medusa-avalara plugin is a working example of the same pattern applied to tax instead of pricing. It installs into an existing Medusa store, registers itself through Medusa’s tax-provider interface, and takes over the full transaction lifecycle: it creates a sales invoice in Avalara when an order is placed, commits it when the order completes, and voids it if the order is canceled — all without any change to Medusa’s own cart, checkout, or order code. A dealer picks Avalara as their tax provider in the Medusa admin the same way they’d pick any other provider, and everything else in the store keeps working exactly as it did before.

The same pattern generalizes to the other systems a bullion dealer actually needs to connect:

• ERP and vaulting/inventory sync. Medusa emits events for order placement, fulfillment, and inventory changes. A module can subscribe to those events, and a workflow can push the relevant data out to an ERP or a vaulting/inventory system — the integration lives in its own module, not scattered across checkout code.
• Payment processors. Medusa’s payment system is provider-based, with Stripe, PayPal, Klarna, and Adyen supported out of the box. Bullion dealers often need a processor comfortable underwriting a high-value, high-risk category rather than a default consumer gateway — adding one means implementing Medusa’s payment provider interface, not replacing the checkout flow.
• Tiered and wholesale pricing. This one doesn’t even require an add-on: Medusa’s core Pricing Module natively supports quantity-based tiers (a lower unit price once a customer buys 10+ or 50+ ounces) and rule-based pricing by customer group, region, or cart total — genuinely useful for a dealer serving both retail customers and wholesale/dealer accounts from the same catalog.
• Market-driven pricing. The same module pattern is what lets a plugin compute a product’s final price at read time from a live spot price plus a merchant-configured formula, without ever writing that value into Medusa’s own price records — covered in detail below with Fluctum.

None of this requires forking Medusa or building a bullion-specific commerce platform from zero. It’s the difference between building the tax logic, the ERP sync, the payment integration, and the pricing engine all from scratch, and building only the one piece that’s actually specific to the business on top of a platform that already handles everything else.

The Checkout Price-Locking Problem

Across all three platforms, this is the piece that consistently doesn’t come for free: freezing a computed price at the moment a customer starts checkout, and refusing to let the order complete if that lock has expired. It’s not a hard problem conceptually, but getting it right requires the platform to support:

1. Recording the exact price, and the inputs that produced it (spot price, spread, premium), at the moment checkout begins.
2. An expiry window on that record.
3. A hard check, at order completion, that rejects the order if the lock is missing or expired — not just a soft warning.

WooCommerce and Shopify both leave this entirely to custom development or a third-party app’s own implementation of it. Neither has a first-class “price lock” primitive in its core commerce model. This is precisely the gap Fluctum was built to close on Medusa.

Fluctum: Market-Driven Dynamic Pricing for Medusa

Fluctum is an open-source, MIT-licensed Medusa plugin built by u11d that implements the full pricing pipeline described above, so a Medusa store doesn’t need a custom-built pricing engine to sell spot-priced goods.

It fetches live spot prices on a schedule, and computes each product’s final price from the current spot price, the product’s weight, and a merchant-configured formula — a spread factor, a fixed spread fee, a percentage premium, and a fixed premium (for minting or handling costs, for example) — without ever writing that computed value back into a Medusa product’s own price fields. The storefront reflects price changes in real time via Server-Sent Events, so a customer watching the cart sees the price move without a page reload.

At checkout, Fluctum locks the computed price into an auditable record and gives it an expiry. If a customer completes payment before that lock expires, the order proceeds at the locked price. If the lock has expired — because checkout took too long, or the price moved and wasn’t refreshed — order completion is rejected rather than silently charging a stale amount. If the spot-price feed itself goes down, the storefront and checkout keep working off the last known good price instead of breaking.

Because it’s a Medusa plugin rather than a separate system, installing Fluctum on an existing Medusa store keeps everything else Medusa already provides — multi-region and multi-currency support, promotions, customer accounts, taxes, shipping, and payments — and adds market-driven pricing on top of it. It’s free to use and, being open-source, can be extended by any developer to sync with an ERP, add payment providers, or add business logic specific to a given dealer.

We’ve written about Fluctum from two angles: a business-facing overview of the build-vs-buy decision for store owners deciding whether to build this themselves, and a developer guide covering the pricing formula, the price-lock lifecycle, and a full local setup walkthrough. A live demo is available at fluctum.medusajs.site.

Cost Comparison

A full cost-of-ownership model for a bullion dealer is more than just the monthly subscription fee. It’s a mix of platform fees, transaction fees as a percentage of gross merchandise value (GMV), app/plugin costs, and hosting or infrastructure overhead.

WooCommerce: The core software is free, so there’s no monthly platform fee. Costs are a combination of:

• Hosting: A reliable WordPress host capable of handling e-commerce can range from 25 to 100+ per month.
• Transaction Fees: These are charged by your payment gateway (e.g., WooCommerce Payments, Stripe, PayPal) and are typically around 2.9% + $0.30 per transaction for US cards. These are often negotiable for high-volume merchants.
• Plugin Costs: A robust “Pro” version of a precious metals pricing plugin is essential and can cost 100–300 per year.
• Operational Overhead: You are responsible for all maintenance, security, and updates.

Shopify: Pricing is based on a monthly subscription, but the need for custom checkout logic creates a significant cost hurdle.

• Monthly Subscription: To implement the required checkout customizations for live pricing, a dealer must use the Shopify Plus plan, which starts at $2,000/month.
• Transaction Fees: If you don’t use Shopify Payments, Shopify adds its own fee on top of your payment gateway’s charge. This fee is 0.15% on Shopify Plus-a direct tax on your GMV.
• App Costs: You’ll need a third-party app for the pricing logic itself, which is an additional monthly cost.
• Development Costs: You’ll need to hire developers to build a custom app using Shopify Functions to handle the live pricing at checkout.

Medusa: As an open-source framework, Medusa has no platform or transaction fees, offering the most control over your cost structure.

• Hosting: You can self-host on services like AWS or Vercel (typically 50–200+ per month depending on scale) or use Medusa Cloud (plans start from $29/month and scale up).
• Transaction Fees: You only pay the fees from your chosen payment processor (e.g., Stripe), with no additional platform tax on GMV.
• Development Costs: This is the primary investment. You need development resources to build and maintain the live pricing logic, integrations, and storefront. However, you only build the parts that are unique to your business, leveraging Medusa’s core commerce features for the rest. Fluctum can significantly reduce this initial development cost.

Which Platform Should You Choose?

If your catalog is small and your pricing updates a handful of times a day is acceptable, WooCommerce or Shopify are both legitimate, lower-friction choices — pick based on whether you’d rather own a WordPress-based stack (WooCommerce) or hand hosting and PCI compliance to a managed platform (Shopify).

If you need pricing that genuinely tracks the live market, or you know you’ll need to connect a specific ERP, tax provider, payment processor, or wholesale pricing model beyond what a plugin already covers, that combination pushes hard against how WooCommerce and Shopify are built, and it’s the situation Medusa’s modular architecture was built to accommodate. The same module/workflow/provider pattern that lets Fluctum add live pricing and u11d’s own Avalara plugin handle tax automation is available for whatever a dealer needs to connect next — a dealer in that situation doesn’t have to build each of those pieces from scratch.

Conclusion

For a bullion dealer, the choice between WooCommerce, Shopify, and Medusa is a decision about where you want to spend your money and how much control you need.

• Shopify is the highest-cost option due to the non-negotiable requirement of the Shopify Plus plan ($2,000+/month) to achieve true dynamic pricing at checkout. You’re paying a premium for managed infrastructure, but also a platform tax on every transaction.
• WooCommerce offers a much lower entry cost, with no monthly platform fees. It’s a viable option if your pricing logic is relatively simple and you have the technical resources to manage a WordPress/WooCommerce stack securely.
• Medusa presents the lowest long-term platform cost, with zero platform fees on your GMV. The investment is in development, giving you complete ownership and control over the critical pricing and checkout logic that defines your business. For a serious dealer planning for scale, avoiding a platform tax on a high-GMV business is a significant financial advantage.

Medusa’s modular architecture is what makes this control possible and cost-effective. The same pattern that lets Fluctum add live spot pricing is what lets u11d’s own Avalara plugin automate tax, and it’s the same pattern available for any other integration a dealer needs. u11d builds and maintains these open-source tools and works with bullion dealers on their Medusa storefronts precisely because of this flexibility. If live market pricing and long-term cost of ownership are your primary concerns, that’s the problem Medusa, and by extension Fluctum, is built to solve.

Originally published at https://u11d.com on September 9, 2026.

WooCommerce, Shopify, or Medusa: Choosing an E-Commerce Platform for Bullion Dealers was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

For years, MinIO was the obvious answer whenever an engineering team needed S3-compatible object storage outside AWS. You wanted an S3-compatible API on Kubernetes? You needed object storage for backups? You wanted something you could run locally with Docker Compose? The answer was the same — MinIO.

That recommendation has changed.

In 2026, the open-source MinIO project is no longer a maintained project in the way engineers historically expected it to be. The upstream GitHub repository was archived on April 25, 2026, and its README explicitly states that the repository is no longer maintained.

That raises an obvious question:

What should replace MinIO?

There isn’t a single answer. Three projects are particularly worth looking at: Garage, RustFS, and SeaweedFS. All three provide S3-compatible storage, but they are built around quite different ideas. Garage focuses heavily on decentralized and geographically distributed object storage, RustFS is particularly interesting for engineers looking for something close to the MinIO model, while SeaweedFS takes a much broader approach and combines object storage with distributed file storage and other storage interfaces.

The important thing is therefore not simply to find “the next MinIO”, but to understand what each project is actually designed to do.

What actually happened to MinIO?

The MinIO repository on GitHub is now archived and read-only. Its current README states:

“THIS REPOSITORY IS NO LONGER MAINTAINED.”

For any production engineer, this should immediately raise a question: what are the alternatives? But let’s be realistic. Thousands of projects are still running MinIO, and many of them are running perfectly fine on the latest version they deployed. A running MinIO cluster does not magically stop serving objects because the GitHub repository was archived. If your cluster is healthy and you already have the required binaries or container images, it can continue operating. The bigger problem is the future lifecycle of the installation.

In September 2026, the minio/minio repository on Docker Hub was archived, and users started reporting that both minio/minio and minio/mc could no longer be pulled from Docker Hub. This is exactly the kind of failure that makes infrastructure engineers nervous. Imagine that your application hasn't changed at all. Your Kubernetes manifests are still valid, your infrastructure code is still valid, and your production cluster is still running. Then a node fails. You need to recreate the workload, and Kubernetes tries to pull:

image: minio/minio:latest

But the image is no longer available.

If you haven’t mirrored the image to your own registry, your deployment is blocked. You may end up relying on a colleague who still has the image locally, or trying to recover an old image from somewhere else.

Alternative #1: Garage

Garage is a distributed object storage system written in Rust that implements the S3 API.

Its philosophy is somewhat different from MinIO. Garage is particularly interesting if your goal isn’t simply “I want a server that looks like MinIO”, but rather “I want distributed object storage that can operate across multiple locations.”

Garage uses a decentralized architecture where nodes participate in the distributed storage system. This makes it particularly interesting for deployments where you might have several relatively small nodes spread across different locations instead of one large storage cluster.

For example, you could have infrastructure distributed across several sites:

This is one of the areas where Garage differs significantly from the traditional MinIO mental model.

Alternative #2: RustFS

RustFS takes a different approach from Garage, although it shares some important characteristics. It is also written in Rust and provides an AWS S3-compatible API.

For MinIO users, the interesting part is its design philosophy. RustFS explicitly describes its architecture as being inspired by MinIO’s design philosophy, which makes it particularly interesting when your starting point is: “I already know MinIO, and I want something that feels familiar.”

RustFS uses a distributed model consisting of nodes and drives. Conceptually, it looks like:

That doesn’t mean that migration is completely transparent. S3 compatibility needs to be tested against the actual application workload, and the operational model of the new cluster still needs to be understood.

Alternative #3: SeaweedFS

SeaweedFS takes a broader approach than Garage and RustFS. While both are primarily distributed object-storage systems, SeaweedFS is designed as a distributed storage platform supporting S3, FUSE, HDFS, WebDAV, SFTP, and other interfaces.

For MinIO users, this makes SeaweedFS interesting when S3 is only part of the requirement. If you simply need an S3-compatible API, SeaweedFS may provide more infrastructure than necessary. But if you need multiple storage interfaces or have workloads involving very large numbers of small objects, its architecture becomes more compelling.

Conceptually, it looks like:

SeaweedFS separates storage into master servers, volume servers, and the Filer. The master manages cluster metadata, volume servers store the data, and the Filer provides a filesystem-like namespace. The S3 gateway sits on top of this architecture and can be scaled independently.

Another notable feature is its support for both replication and erasure coding, together with a volume-based design that works well with large numbers of small objects. This makes SeaweedFS worth considering for datasets, thumbnails, generated files, and other high-object-count workloads.

The trade-off is complexity. SeaweedFS offers considerably more functionality than a simple S3-compatible object store, so the additional flexibility needs to be weighed against the operational overhead.

Garage vs RustFS vs SeaweedFS

At this point, it should be clear that these three projects aren’t simply three interchangeable MinIO clones.

They all provide S3-compatible storage, but they target somewhat different requirements.

Garage is focused on decentralized object storage and is particularly interesting for geographically distributed or multi-site deployments.

RustFS is the most natural project to investigate when your primary requirement is replacing MinIO with another distributed S3-compatible object store while retaining a relatively familiar architecture.

SeaweedFS takes a broader approach and makes sense when object storage is only one part of the problem. Its ability to expose the same underlying storage through S3, filesystem, HDFS, and other interfaces can be valuable for larger or more diverse storage environments.

The important distinction is therefore not simply performance or feature count. It is the architecture you want to operate.

This table is not intended to declare a winner. The projects solve different problems, and the right choice depends on the workload and architecture you need to support.

If you have multiple locations and want decentralized storage that treats geographic distribution as a fundamental part of the architecture, Garage is worth investigating.

If your main requirement is replacing MinIO with a modern, Rust-based, distributed S3-compatible object store that follows a relatively familiar model, RustFS is an obvious candidate.

If you need more than S3 — for example, filesystem access, HDFS, huge numbers of small objects, or multiple storage interfaces — SeaweedFS deserves serious consideration.

The important thing is that you don’t have to choose the project with the longest feature list. You have to choose the architecture that matches your workload.

Conclusion

MinIO may no longer be the default choice it once was, but that doesn’t mean there is a single project waiting to take its place. Garage, RustFS, and SeaweedFS represent three different directions for self-hosted object storage. Garage focuses on decentralized, multi-site storage. RustFS is the closest fit for teams looking for a familiar distributed S3 model. SeaweedFS goes beyond object storage and provides a broader storage platform with multiple interfaces and a design particularly suited to large numbers of objects. The era of treating MinIO as the automatic default for self-hosted S3 is over. The right replacement depends on the operational model, workload, and architecture you want to maintain long after the migration is complete.

For an existing MinIO deployment, the decision should not start with “Which project is the best?”. It should start with “What do we actually need from our storage layer?”

Once you answer that question, choosing between Garage, RustFS, and SeaweedFS becomes much less about finding the next MinIO and much more about choosing the storage architecture that actually fits your infrastructure.

MinIO Is Deprecated: Best Alternatives for S3-Compatible Storage was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

TypeSafe AI Jev explained: examples, use cases, and LLM comparisons

TypeSafe AI Jev is a model for making bounded decisions inside software. You give it text or structured state plus questions whose valid answers you define. It returns typed choices, scores, probabilities, and confidence values instead of generating prose.

That makes Jev useful for classification, routing, scoring, and review gates. It does not replace GPT, Claude, or another generative model when you need writing, code, explanations, or open-ended reasoning. Think of it as a fuzzy decision function, not a chatbot wearing a smaller hat.

Quick answer

Use Jev when:

• Every valid answer can be defined before the call.
• The hard part is semantic judgment, not arithmetic or deterministic policy.
• Software needs probabilities or confidence to decide whether to act, retry, or escalate.
• The workload repeats often enough for latency and per-call cost to matter.

Use something else when:

• The output must contain newly written text, code, or an explanation.
• Correctness depends on exact math, dates, permissions, or database state.
• The task requires long, multi-step reasoning.
• The model would be the only security or authorization boundary.

What is TypeSafe AI Jev?

TypeSafe calls Jev its first System One model. That is the company’s product category for models built to make fast, structured decisions that software can consume directly. It is not a new chat interface and it is not an industry-standard model category.

The contract is simple:

state + typed questions -> Jev -> typed answers + probabilities -> application code

The state can be a string, JSON object, or array containing text. Each question defines its answer space. Jev evaluates independent questions against the same state in parallel, then your code decides what happens next.

At the time of writing, jev-latest resolves to jev-1.13.0. TypeSafe's model documentation lists it at $0.042 per million input tokens with free output tokens. The documented context limit is 64,000 tokens per request, with a separate 32,000-token limit for the state plus the longest question. Input is text only, so images, audio, and video must be converted before they reach Jev.

Pin a version when tuning thresholds and rerun evaluation before upgrading. A moving alias is convenient until it changes a production route at 02:00.

TypeSafe’s launch material describes Jev as unable to hallucinate because it cannot emit a value outside the schema. That claim needs a narrower reading. Jev cannot invent a fourth result when your Choice defines three, but it can choose the wrong one. Type safety protects the shape of an answer. It does not make the judgment correct. Independent analysis from Arize makes the same distinction.

How Choice, Score, and Noul work

Jev exposes three question types:

A Choice can contain up to 255 options. A Score accepts between two and ten ordered levels. Choice and Score return a confidence value derived from their probability distributions; Noul returns the probability of yes without a separate confidence field.

Questions in one request are independent. If question B depends on question A, use another call or express the dependency in code. Do not assume that two differently phrased questions will obey arithmetic identities either. TypeSafe documents cases where a Noul and an equivalent-looking Choice produce different numbers because they ask different statistical questions.

Keep questions atomic. Ask separately whether a refund was requested, score impact, classify intent, then let code apply policy. Models judge fuzzy meaning; code does not reinterpret accounting rules overnight.

Run a Jev decision in Python

Install the SDK

The Python SDK requires an API key in TYPESAFE_API_KEY:

python3 -m pip install typesafe-sdk
export TYPESAFE_API_KEY='replace-with-a-key-from-console.typesafe.ai'

Use your normal secret manager in CI and production. Committing the key beside the example would turn a quick start into an incident report.

Classify and route a support ticket

This example asks one Choice, one Score, and one Noul in a single call. It then applies routing thresholds in ordinary Python.

import os
import time

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

if "TYPESAFE_API_KEY" not in os.environ:
    raise SystemExit("Set TYPESAFE_API_KEY before running this example")

INPUT_USD_PER_MTOK = 0.042  # TypeSafe list price at the time of writing

ticket = {
    "subject": "Checkout fails after payment",
    "message": (
        "Our card was charged twice and checkout still shows an error. "
        "We need this fixed today because customers cannot place orders."
    ),
    "plan": "business",
}

started = time.perf_counter()

with TypeSafeClient(model="jev-1.13.0") as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should own this ticket first?",
                criteria={
                    "billing": "Charges, invoices, refunds, or subscriptions",
                    "technical": "Bugs, outages, failed integrations, or broken product behavior",
                    "account": "Login, identity, permissions, or account access",
                    "other": "The ticket does not fit the other categories",
                },
            ),
            "severity": Score(
                instructions="How severely does this issue block the customer's work?",
                criteria=[
                    "Minor inconvenience with a clear workaround",
                    "Important feature is degraded but work can continue",
                    "Critical workflow is blocked or customers are losing money",
                ],
            ),
            "requests_refund": Noul(
                instructions="Does the customer explicitly ask for a refund?",
                criteria={
                    "true": "The customer directly requests money back",
                    "false": "The customer reports a charge but does not request a refund",
                },
            ),
        },
    )

elapsed = time.perf_counter() - started

department = response.choices["department"]
severity = response.scores["severity"]
refund_probability = response.nouls["requests_refund"].noul

if department.confidence < 0.65 or severity.confidence < 0.55:
    destination = "human-review"
elif severity.score > 1.5:
    destination = "incident-response"
else:
    destination = department.choice

input_tokens = response.usage.input_tokens or 0
estimated_cost = input_tokens / 1_000_000 * INPUT_USD_PER_MTOK

print(f"model={response.model}")
print(f"destination={destination}")
print(f"department_confidence={department.confidence:.2f}")
print(f"severity={severity.score:.2f}")
print(f"refund_probability={refund_probability:.2f}")
print(f"input_tokens={input_tokens}")
print(f"output_tokens={response.usage.output_tokens}")
print(f"elapsed_seconds={elapsed:.2f}")
print(f"estimated_cost_usd={estimated_cost:.8f}")

The SDK exposes separate collections for Choice, Score, and Noul answers. The thresholds are examples, not TypeSafe defaults. Set them from errors and review costs measured on your own data.

Pinning jev-1.13.0 prevents alias drift. In production, log the criteria version, probability distributions, chosen route, and human outcome.

Sample output and cost

A real run of the example above against jev-1.13.0 printed this:

model=jev-1.13.0
destination=incident-response
department_confidence=0.95
severity=2.00
refund_probability=0.06
input_tokens=528
output_tokens=77
elapsed_seconds=0.64
estimated_cost_usd=0.00002218

The usage block in the response is what makes the cost measurable without opening a billing dashboard. That call moved 528 input tokens. TypeSafe bills 0.042 per million input tokens and does not bill output tokens, so the run cost 528 / 1,000,000 * 0.042, or roughly 0.000022 at current list prices. A thousand calls of this size cost about two cents, and one dollar buys roughly 45,000 of them.

elapsed_seconds covers client setup plus the round trip, not just server time. Values move with the input, criteria, and model version, so treat the transcript as a real example rather than a fixed contract.

Practical Jev use cases

Route support requests

Support routing is the natural first pilot. Put the ticket text and relevant account context in state. Use Choice for the owning queue, Score for impact, and Noul for independent conditions such as an explicit refund request:

{
  "state": {
    "channel": "email",
    "subject": "Wrong item delivered, replacement needed before Friday",
    "message": "Order 48213 arrived with two left boots. I need the replacement before the conference on Friday or I want to cancel.",
    "account_tier": "enterprise",
    "earlier_tickets": 2
  },
  "model": "jev-1.13.0",
  "questions": {
    "queue": {
      "type": "choice",
      "instructions": "Which queue should own this ticket first?",
      "criteria": {
        "returns": "Wrong, damaged, or missing items, replacements, and shipping problems",
        "billing": "Charges, invoices, refunds, and subscriptions",
        "technical": "Product failures, errors, and defects",
        "account": "Access, identity, and permissions",
        "other": "None of the other queues fit"
      }
    },
    "impact": {
      "type": "score",
      "instructions": "How much does the problem block the customer?",
      "criteria": [
        "Minor inconvenience with a workaround",
        "The item or order cannot be used as delivered",
        "Time-critical situation or total loss of the purchase"
      ]
    },
    "wants_cancel": {
      "type": "noul",
      "instructions": "Is the customer asking to cancel an order or close the account?"
    }
  }
}

Code can accept a confident route, send uncertain tickets to a person, and apply exact entitlement rules from the account database.

Review agent actions

An agent can propose a tool call while Jev supplies a bounded semantic risk signal:

{
  "state": {
    "user_goal": "Remove generated build artifacts",
    "tool": "shell",
    "command": "rm -rf dist"
  },
  "model": "jev-1.13.0",
  "questions": {
    "risk": {
      "type": "choice",
      "instructions": "Classify the operational risk of the proposed action",
      "criteria": {
        "read_only": "Does not modify state",
        "reversible_write": "Changes state but has a reliable rollback",
        "irreversible_write": "Deletes or overwrites state without a reliable rollback",
        "unclear": "The available state is insufficient"
      }
    },
    "matches_goal": {
      "type": "noul",
      "instructions": "Does the proposed action directly match the user's stated goal?"
    }
  }
}

This is a review signal, not permission to execute. Allowlist enforcement, path validation, sandboxing, and user confirmation still belong in code. Jev’s own documentation warns that adversarial text in state can move an answer, so it must not become the sole security boundary.

Check RAG evidence before generation

Jev can classify whether a retrieved passage supports a claim before a generative model writes the answer:

{
  "state": {
    "question": "Does the service retain customer prompts for training?",
    "claim": "Customer requests are not used to train Jev.",
    "passage": "Jev is not trained on customer requests or responses."
  },
  "model": "jev-1.13.0",
  "questions": {
    "support": {
      "type": "choice",
      "instructions": "How well does the passage support the claim?",
      "criteria": {
        "supported": "The passage directly supports the claim",
        "contradicted": "The passage conflicts with the claim",
        "insufficient": "The passage does not settle the claim"
      }
    },
    "contains_instruction": {
      "type": "noul",
      "instructions": "Does the passage contain an instruction aimed at changing the evaluator's behavior?"
    }
  }
}

The application still needs to preserve the source URL and quote. Jev judges the relationship between claim and passage; it does not browse, establish provenance, or write the final cited answer.

Triage moderation and operations queues

Moderation reports, invoices, incidents, and agent traces all end up in queues. Jev can classify the queue, score severity, and flag missing evidence:

{
  "state": {
    "source": "monitoring alert",
    "service": "checkout-api",
    "summary": "p99 latency rose from 180 ms to 2.4 s over the last 20 minutes while the error rate stayed near 0.2%",
    "context": "Deploy checkout-api v2.31.0 finished 25 minutes ago"
  },
  "model": "jev-1.13.0",
  "questions": {
    "owner": {
      "type": "choice",
      "instructions": "Which team should take the first response for this alert?",
      "criteria": {
        "service_team": "The reporting service's own code or configuration",
        "platform": "Shared infrastructure, networking, or managed dependencies",
        "database": "Storage, replication, or query performance",
        "unclear": "The available evidence does not point to one owner"
      }
    },
    "severity": {
      "type": "score",
      "instructions": "How much customer impact does the summary describe?",
      "criteria": [
        "No confirmed customer impact, worth watching",
        "Degraded latency for some customers",
        "Customers blocked or data at risk"
      ]
    },
    "missing_evidence": {
      "type": "noul",
      "instructions": "Is the alert missing context a first responder would need before acting?"
    }
  }
}

Low-confidence or high-impact items, and anything flagged for missing evidence, go to a human reviewer. Exact totals, due dates, and account permissions stay in deterministic code because Jev 1.13 is explicitly weak at counting, arithmetic, and date comparison.

Route work to the right model or human

Use Jev in front of more expensive handlers. A Choice can select deterministic lookup, a small generative model, a reasoning model, or human review:

{
  "state": {
    "request": "Summarize the attached vendor contract and flag the clauses that change our data-retention obligations",
    "attachments": ["vendor-contract-v7.pdf"],
    "requester": "procurement"
  },
  "model": "jev-1.13.0",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which handler should receive this request?",
      "criteria": {
        "deterministic": "A lookup, calculation, or template can answer it exactly",
        "small_model": "Short generation or extraction a cheap model handles well",
        "reasoning_model": "Long-document analysis or multi-step reasoning",
        "human": "Judgment, negotiation, or accountability beyond the model stack"
      }
    },
    "in_scope": {
      "type": "noul",
      "instructions": "Does the request fall inside the documented scope of the available handlers?"
    }
  }
}

Confidence determines whether the route is safe to accept. Below the threshold, send the request to a human instead of accepting a cheap guess that the matching handler will only have to redo later. This architecture spends generation tokens only when the task needs generation, rather than asking a novelist to sort every envelope.

Jev vs LLMs, classifiers, and rules

Jev is not automatically better than the alternatives. It occupies a specific slot:

Plain JSON mode guarantees valid JSON, not adherence to a supplied schema. Strict structured-output APIs can enforce supported JSON schemas, including required keys and enum values.

Schema enforcement is therefore not unique to Jev. Its distinction is a decision-specific interface built around Choice, Score, and Noul, with probability distributions and confidence for bounded judgments.

A conventional classifier may be the better choice for a stable, high-volume task when you already have good labels, training infrastructure, and predictable categories. In one early spam experiment, Jev reached 98.6% accuracy on a 5,733-email ham, spam, and phishing test without task-specific fine-tuning or labeled examples in its requests, while a TF-IDF logistic-regression baseline trained on labeled messages reached 98.9% (full writeup). The criteria had been refined after reviewing labeled examples, so this was useful early evidence, not magic zero-data victory.

Rules win whenever the answer can be computed exactly. Do not ask any model whether an invoice is overdue if two parsed dates and a comparison operator can settle it.

The cost and latency story is still notable.

TypeSafe reports 70 to 500 ms end-to-end latency and $0.042 per million input tokens for suitable requests.

Its launch workflow evaluation produced headline claims of 193.6 times faster and 444.6 times cheaper than its selected LLM comparison, but TypeSafe says those figures are likely near the high end of real-world gains and notes possible benchmark bias.

When not to use TypeSafe AI Jev

Jev 1.13 is not trained to write text. It will not draft a customer reply, produce code, summarize a report, or explain why it chose an answer. Use a generative model when the output itself must be created. The missing explanation also matters for evaluation work: an LLM judge can describe a failure, while Jev returns probabilities that tell you where to inspect, not how to fix the problem.

Keep arithmetic, counting, numeric interpolation, and date comparisons in code. TypeSafe’s limitations page says Jev can read dates as text but does not reliably treat them as ordered values. It also warns about literal phrasing, multi-hop indirection, irrelevant context, contradictory criteria, and adversarial content.

More context is not automatically better. Retrieve and filter first, then send the fields needed for the decision. A 64,000-token limit is capacity, not a challenge.

Test non-English workloads separately. TypeSafe says English is Jev’s strongest training language and other languages are not handled equally well.

Most importantly, separate a valid answer from a correct answer. A typed output prevents parser failures and out-of-schema labels. It does not prevent a confident, valid, expensive mistake.

How to evaluate Jev on your workload

Start in shadow mode:

1. Pick one reversible decision with a closed answer set.
2. Freeze a representative labeled dataset and the exact criteria text.
3. Run Jev and the current baseline on identical records.
4. Measure per-class errors, false automatic actions, human-review rate, calibration, end-to-end latency, and cost per completed decision.
5. Tune thresholds by consequence. Sending a ticket to the wrong queue and approving a destructive action do not deserve the same confidence floor.
6. Pin the model version and rerun the suite before changing either model or criteria.
7. Keep permissions, arithmetic, and state changes in deterministic code.

Do not optimize only for overall accuracy. A model can look good while failing badly on a rare queue that matters. Track confusion by class and inspect probability bands: cases scored near 0.9 should be correct more often than cases scored near 0.6. If that relationship does not hold on your data, the threshold is decoration.

Include review capacity in the evaluation. A cautious threshold that sends 70 percent of cases to a human may be safe, but it has not automated much. The useful operating point balances wrong automatic actions against the cost of review.

Should you use TypeSafe AI Jev?

Pilot TypeSafe AI Jev when the answer space is bounded, the judgment is semantic, and software consumes the result often enough for decision latency and cost to matter. Support routing, relevance checks, moderation labels, model routing, and broad evaluation coverage are credible starting points.

Keep an LLM when the output must be written, explained, or reasoned through. Keep code when the answer can be computed exactly. Keep a human in the path when a wrong but valid decision has serious consequences and your own calibration data is thin.

Jev’s useful idea is not that every LLM should be replaced. It is that generation and judgment do not have to be the same model call. Split them, measure them independently, and make code responsible for the final action.

TypeSafe AI Jev: Structured Decision Models Explained was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The hard part of CloudFront policies isn’t picking one off the managed list. It’s combining the three policy types — cache, origin request, response headers — for an actual application. The right cache policy for a SPA isn’t right for its API. Forwarding Authorization to your origin without poisoning the cache turns out to be impossible with a custom origin request policy. Multi-tenant routing on Host doesn't partition the cache by default, and most tutorials don't mention it.

Four architectures cover most of what teams actually build on CloudFront: a SPA on S3 with an API behind a separate path, an authenticated API with JWT or session cookies, multi-tenant SaaS with Host-based routing, and an image CDN with on-the-fly transformations. Each one has a canonical policy stack, a set of gotchas that bite in production, and one or two places where CloudFront Functions or Lambda@Edge become necessary - because some of these patterns can't be solved with policies alone.

This builds on three earlier deep dives that cover the per-policy fundamentals: cache policies, origin request policies, and response headers policies. I’ll assume you’ve read them or know the equivalents — this article is about combinations, not basics.

Table of contents

• The four CloudFront events and where edge functions fit
• Pattern 1: SPA on S3 + API behind a separate path
• Pattern 2: Authenticated API with JWT or session cookies
• Pattern 3: Multi-tenant SaaS with Host-based routing
• Pattern 4: Image CDN with on-the-fly transformations
• What to read next

The four CloudFront events and where edge functions fit

Every viewer request that reaches CloudFront passes through four lifecycle events: viewer request (when CloudFront receives the request, before the cache lookup), origin request (only on cache miss, before forwarding to origin), origin response (after CloudFront receives the origin’s response, before caching it), and viewer response (just before CloudFront sends the response to the viewer). The two origin events fire only on cache misses; the two viewer events fire every time. Cached responses skip both origin events entirely. Per the AWS Lambda@Edge trigger-events docs, CloudFront also skips viewer-response functions when the origin returns HTTP ≥ 400, and skips all four events on automatic HTTP→HTTPS redirects.

Two compute primitives can run code at these events: CloudFront Functions and Lambda@Edge. The choice usually isn’t subtle — they’re built for different things.

The biggest practical constraints: CloudFront Functions can’t make network calls and only run on viewer events. Neither service can inspect the response body returned by the origin — Lambda@Edge can replace a response body or generate one from scratch in request triggers, but the origin-response trigger doesn’t expose the origin’s body to the function (you can overwrite it but not read it). For true read-and-transform body manipulation, you need a real origin compute service like a Lambda function URL or S3 Object Lambda. Lambda@Edge is regional, slower than CloudFront Functions, and harder to debug, but it can read request bodies (with the include-body opt-in for POST/PUT methods) and run on all four events. AWS publishes a direct comparison — worth bookmarking.

A 2023 addition matters here: CloudFront KeyValueStore, accessible from CloudFront Functions running the cloudfront-js-2.0 runtime, lets you store configuration data at the edge without redeploying function code. For multi-tenant scenarios where per-tenant config has to be looked up at the edge, this often replaces what would have been a Lambda@Edge function with a DynamoDB call.

Pattern 1: SPA on S3 + API behind a separate path

A single CloudFront distribution with two cache behaviors: /api/* routes to API Gateway, an ALB, or a Lambda function URL; everything else routes to an S3 bucket holding the SPA shell and assets. Each behavior gets its own three-policy stack.

Static path (default * behavior → S3): API path (/api/* → API Gateway / ALB / Lambda function URL):

Cache

Managed-CachingDisabled for fully dynamic, or a custom policy if some endpoints are cacheable

Origin request

Managed-AllViewerExceptHostHeader for API Gateway / Lambda function URLs; Managed-AllViewer for ALBs that accept any host

Response headers

None if same-origin; Managed-CORS-with-preflight-and-SecurityHeadersPolicy if the SPA loads from a different domain

The custom error response trap

The trap: custom error responses are configured at the distribution level, not per cache behavior. A 404 → /index.html rule applied for the SPA also rewrites genuine API 404s to the SPA shell with HTTP 200, which silently breaks every client expecting a real 404 from the API. There are two real fixes:

The other fix is Lambda@Edge on origin-response, scoped to the S3 cache behavior only — but that’s heavier, costs more, and adds a regional dependency to what should be edge logic. The CloudFront Function path is the right call almost every time. Whichever fix you pick, test API 404 and 403 responses explicitly after deploying — silent rewrites are easy to miss until a client complains about always getting HTML back from /api/users/9999.

OAC, not OAI

For the S3 origin, use Origin Access Control rather than the legacy Origin Access Identity. OAC supports SigV4 signing, all S3 regions launched after December 2022, KMS server-side encryption, and dynamic methods like PUT and DELETE. OAI is in maintenance mode. The CloudFront restrict-S3-access docs mark OAC as the current recommendation. Existing distributions on OAI keep working — there’s no urgent migration — but new distributions should use OAC.

One more S3-specific constraint to know: caching based on the Authorization header isn't supported for S3 origins, per the CloudFront header-caching docs. If you need per-user authenticated access to S3 content, use signed URLs or signed cookies - that pattern shows up again in the next section.

Pattern 2: Authenticated API with JWT or session cookies

Caching a JWT-authenticated API is where CloudFront’s policy model gets uncomfortable. The hard constraint: Authorization cannot be allow-listed in a custom origin request policy. AWS's CloudFormation API rejects it at deploy time. The CDK issue #28883 is the canonical bug report, and the AWS re:Post Q&A on forwarding the Authorization header is the official workaround page.

This means there’s no supported way to forward only Authorization to your origin while keeping it out of the cache key. Your options collapse to a small set:

The first is to include Authorization in the cache policy header list, which auto-forwards it to the origin (anything in the cache key is automatically forwarded). The cost is that every distinct token becomes its own cache entry - for a JWT-authenticated app, that's one cache entry per active user. Cache hit ratio approaches zero on shared resources.

The third is a CloudFront Function on viewer-request that copies Authorization to a custom header (e.g. X-Internal-Auth). A custom header name can be allow-listed in a custom origin request policy. The function is small - a single line of JavaScript - but the indirection is real and worth flagging in your distribution config.

The minimum-TTL silent leak

The fix is either CachingDisabled (minimum TTL = 0, ignoring origin Cache-Control for caching is disabled by definition) or a custom cache policy with MinTTL = 0. For authenticated APIs that should never be cached at the edge, CachingDisabled is the safe default.

Signed URLs for cacheable per-user content

For cacheable, access-controlled content, signed URLs and signed cookies are the pattern AWS documents most directly. If your app fits the shape of “per-resource auth that’s cacheable” rather than “per-request auth on dynamic data,” signed URLs are usually simpler than anything you can build with the three-policy model.

Lightweight token validation at the edge

CloudFront Functions can validate a JWT signature at viewer-request and reject unauthenticated traffic before it ever reaches your origin. The AWS JWT validation example shows the pattern: parse the token, verify the signature with a hardcoded secret, allow or 401. With the cloudfront-js-2.0 runtime, crypto.createHmac is available, which makes this practical for HS256-signed tokens.

The honest limitation: CloudFront Functions can’t fetch JWKS, can’t call KMS or Secrets Manager, and can’t introspect tokens against an OAuth server. The signing key has to be embedded in the function code or a KeyValueStore entry. For RS256 tokens with key rotation, Lambda@Edge with a JWKS fetch is still the right tool — but it’s a meaningfully heavier dependency than a CloudFront Function with KVS.

Pattern 3: Multi-tenant SaaS with Host-based routing

The architecture sounds clean, but CloudFront’s default behavior breaks it in a way that’s easy to miss until production traffic exposes it.

Host is not in the cache key by default

Per the AWS re:Post answer on default cache key composition and the understanding-the-cache-key docs, CloudFront’s default cache key consists of the distribution’s domain name plus the URL path (plus the OPTIONS method when applicable). The viewer’s Host header - the alternate domain name that determined which tenant they were trying to reach - is not part of the cache key unless you explicitly add it.

HostHeaderOnly origin request policy

If your origin needs the viewer’s Host for its own tenant routing - a multi-tenant ALB, an EKS ingress that maps Host to namespace, a reverse proxy doing virtual hosts - the Managed-HostHeaderOnly origin request policy forwards just the Host header and nothing else. Per the managed origin request policies docs, it's the inverse of AllViewerExceptHostHeader.

Be careful not to confuse the two. AllViewerExceptHostHeader strips Host and forwards everything else, used when origin is API Gateway and shouldn't see the viewer's domain. HostHeaderOnly forwards Host and nothing else, used when origin needs Host for routing and you want a clean origin request without cookies or query strings. Pairing the right one with the right cache policy is the whole pattern.

Per-tenant response headers can’t be done with policies

Response headers policies are configured per cache behavior, not per request. Cache behaviors match on path patterns, not on Host. So a single cache behavior shared across tenants gets one response headers policy - every tenant receives identical CSP, identical security headers, identical CORS. There's no built-in way to vary response headers by tenant.

If your tenants need different CSPs (one allowlists Stripe, another allowlists PayPal), different CORS origins, or different security headers, you need a CloudFront Function on viewer-response that reads the request’s Host and rewrites the response headers. With CloudFront KeyValueStore for per-tenant config lookup, this is a practical pattern - define the per-tenant headers as KVS entries keyed by tenant domain, look them up in the function, and rewrite. AWS's aws-samples/sample-cloudfront-saas-manager-nginx-ingress-migration repo demonstrates the broader pattern.

One caveat from the docs: viewer-response functions don’t fire when the origin returns HTTP ≥ 400. Your error responses won’t get the per-tenant header treatment. For a tenant-specific 500 page, you need either custom error responses pointing to per-tenant content (configured at the distribution level — ouch, see Pattern 1) or Lambda@Edge on origin-response.

CloudFront SaaS Manager and multi-tenant distributions

In April 2025, AWS announced the general availability of CloudFront SaaS Manager, which introduces a new distribution type: the multi-tenant distribution. A multi-tenant distribution is a template defining shared origins, cache behaviors, and policies; each distribution tenant represents a domain. Per the multi-tenant distribution docs, tenants can override AWS WAF web ACLs, TLS certificates, and geographic restrictions individually.

This solves the certificate scaling problem that previously capped multi-tenant designs at the alternate domain name limit. Standard distributions allow 100 alternate domain names per distribution by default (requestable for increase), with hard ALB-side limits when using ALBs as origins. With multi-tenant distributions, the quotas shift: the default limit is 10,000 distribution tenants per AWS account (across up to 20 multi-tenant distributions per account), with up to 100 aliases per tenant. Per the tenant certificate docs, a tenant inherits the shared ACM certificate from the multi-tenant distribution by default — or, for tenants that need their own custom domain, you can attach a tenant-level managed CloudFront certificate that ACM provisions and renews automatically.

What SaaS Manager does not change is the policy story. Cache, origin request, and response headers policies are still attached at the multi-tenant distribution (template) level, and they’re not tenant-overridable in the current GA. Per-tenant response headers still require a CloudFront Function. The “Host not in cache key by default” rule still applies. SaaS Manager is an operational and certificate-scaling improvement, not a policy-model change.

If you’re starting a new multi-tenant CloudFront deployment in 2026, SaaS Manager is the right path. If you’re maintaining an existing multi-tenant distribution that hasn’t hit certificate or CNAME limits, there’s no urgent reason to migrate — the underlying policy model is the same.

Pattern 4: Image CDN with on-the-fly transformations

Query strings drive the transform: /photo.jpg?w=300&format=webp returns a 300px-wide WebP version of the original. The naive policy combination breaks two ways: caching by "all query strings" fragments the cache by every UTM and fbclid, and naive Accept header forwarding fragments it by every browser's distinct Accept string.

AWS publishes a reference implementation for this pattern that’s worth reading in full. The architecture: S3 stores transformed images with a TTL lifecycle policy, a Lambda function URL with OAC handles cache misses by transforming the image and writing it back to S3, and CloudFront uses Origin Failover — primary origin is the S3 bucket, secondary is the Lambda function URL. On a cache miss, CloudFront tries S3 first, gets a 403 if the transformed image doesn’t exist, and falls back to the Lambda function URL. The Lambda transforms, writes to S3, and returns. Subsequent requests for the same transform hit S3 directly.

The complete sample is at aws-samples/image-optimization — CDK code plus the Lambda function. The AWS-published Dynamic Image Transformation for CloudFront solution is the heavier production-grade variant.

The cache policy: whitelist, not all

The cache policy whitelists exactly the transform parameters: w, h, format, q, and whatever else your URL scheme supports. Setting query string behavior to all is the cardinal mistake - it adds tracking parameters ( utm_*, fbclid, gclid, etc.) to the cache key, fragmenting the cache by analytics noise.

To enforce canonical URLs at the edge, the standard pattern is a CloudFront Function on viewer-request that sorts query parameters alphabetically, drops anything not on the allow-list, and lowercases values. AWS publishes this exact function as an example in the docs. The result: ?w=300&format=webp and ?format=webp&w=300&utm_source=email produce the same cache key.

Accept vs Accept-Encoding: only one is normalized

CloudFront has dedicated, normalized handling for Accept-Encoding (the cache policy's EnableAcceptEncodingGzip and EnableAcceptEncodingBrotli flags collapse Accept-Encoding to a small set of values before adding it to the cache key, per the cache policy docs). It does not do this for Accept. Putting Accept in the cache key directly fragments by every distinct viewer string.

Lambda function URL with OAC, not Lambda@Edge

The current AWS reference architecture uses Lambda function URLs with Origin Access Control, not Lambda@Edge, for image transformation work. This is a 2023–2024 change worth flagging because most older tutorials still recommend Lambda@Edge.

The reasons: Lambda function URLs with OAC are private (only signed CloudFront requests can invoke them), execute in a single region with full SDK access including S3 writes, and — critically — function URLs are origins, which means they can sit in an origin group as the secondary failover target. Lambda@Edge is a hook that runs on origins, not an origin itself, so the failover-to-transformer pattern requires a real second origin to attach the hook to.

There’s still a place for Lambda@Edge in image processing — if you specifically need request-body access (e.g. for image upload transformations), Lambda@Edge on viewer-request with the body opt-in is the only way. But for read-side resize work, the function URL pattern is the modern recommendation.

What to read next

Cache, origin request, and response headers policies are the foundation of most CloudFront configurations. The production patterns above show where those policies are enough on their own, and where they need to be combined with other CloudFront features — CloudFront Functions, Lambda@Edge, Origin Access Control, custom error responses, Origin Failover, signed URLs, or SaaS Manager. That is usually where the interesting design work starts: not in choosing one policy, but in understanding how the policies interact with the rest of the distribution.

If one of these patterns matches what you’re building, the next step is to read the relevant AWS source directly. The CloudFront Functions documentation is worth reading if you’re doing URI rewrites, header manipulation, JWT checks, or query normalization at the edge. For multi-tenant SaaS, start with the CloudFront SaaS Manager announcement and the multi-tenant distribution docs. For image transformation, the aws-samples/image-optimization repo is the most useful starting point.

CloudFront has a lot of old tutorials, partial examples, and conflicting advice floating around. I’ve tried to keep the patterns here tied to current AWS behavior and primary sources, but the safest habit is the same one you should use for any edge configuration: verify the specific feature, quota, and policy interaction against the AWS docs before you ship it.

Originally published at https://u11d.com on July 8, 2026.

CloudFront Policy Patterns for Production: SPA+API, JWT Auth, Multi-Tenant SaaS, and Image CDN |… was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why selling products tied to a moving market requires a transaction model, not merely a price feed

Most e-commerce systems are built around an assumption so fundamental that it rarely needs to be stated: a product has a price.

That price may vary between regions, currencies, customer groups, or promotional periods, but at any given moment it behaves like a stable property of the product. A customer sees it, adds the product to a cart, proceeds through checkout, and completes the order. The architecture assumes that the value presented at the beginning of this journey will still make sense at the end.

For products tied directly to a live market, this assumption breaks down.

A gold coin, an industrial metal component, or another commodity-linked product does not have a price in the traditional catalog sense. Its value is continuously reconstructed from an external quote, the amount of material contained in the product, the merchant’s spread, additional premiums, currency conversion, and other commercial rules.

The displayed number is therefore not a permanent attribute. It is a temporary interpretation of the market.

Once this distinction becomes visible, dynamic pricing stops looking like a storefront feature and starts looking like transaction infrastructure.

The hidden interval between seeing a price and paying it

Imagine a customer adding a gold product to their cart at 10:04. They compare delivery options, enter their address, create an account, and complete payment eight minutes later.

During those eight minutes, the underlying market may move.

The difference may be small enough to ignore on a single order. Across a large catalog, a volatile trading session, or a high-value transaction, it can materially affect the merchant’s margin. The store must then decide whether to honor the earlier value, recalculate the order during checkout, or prevent the transaction from completing until a new quote is accepted.

None of these choices is purely technical.

Keeping the original value transfers market risk to the merchant. Recalculating it without warning transfers uncertainty to the customer. Allowing the total to move continuously makes checkout difficult to understand and even harder to trust.

This is the real problem of spot-priced commerce. It is not simply that prices change. It is that the market continues to move while the transaction is already in progress.

Traditional commerce platforms are usually very good at representing fixed prices. They are considerably less prepared to represent a price as something that has a source, a calculation, a timestamp, a period of validity, and an eventual expiration.

Yet this is precisely what a market-linked price is.

A market-data API only solves the visible part

The most obvious response is to connect the store to a market-data provider. The backend retrieves the latest quote, applies a margin, and sends the result to the storefront.

This creates a live price, but it does not create a reliable transaction.

The quote still needs to be refreshed and stored. The product price must be calculated consistently. The storefront and backend must agree on the result. The system must decide what happens when the external provider becomes unavailable. Most importantly, there must be a moment at which the moving price becomes a stable checkout commitment.

Without that final step, a store may be accurate while the customer is browsing and still complete an order using a value that no longer reflects the market.

The distinction is subtle but important. A live price describes the present. A transaction needs a controlled bridge between the present and the moment of payment.

This bridge is the price lock.

A price is better understood as a lifecycle

In static commerce, pricing can often be reduced to a database lookup. In spot-priced commerce, the final amount emerges from a sequence of states.

The system first receives a market quote. It then combines that quote with product and merchant-specific rules. The result is displayed to the customer and may continue changing while they browse. When checkout begins, the calculated value is temporarily locked. Before the order is completed, the backend verifies that the lock is still valid. Finally, the system preserves enough information to explain how the amount was produced.

What appears to the customer as a single number is therefore the outcome of an entire lifecycle:

market quote → commercial calculation → live display → checkout lock → validation → auditable order

The reliability of the transaction depends on every stage.

A current quote processed using an incorrect spread still creates the wrong price. A correct calculation displayed by the storefront but not enforced by the backend remains vulnerable. A valid price lock that is never checked before order completion provides no actual protection. A final amount stored without its inputs may be impossible to explain later.

The architecture must preserve the continuity of the price from the market-data source to the completed order.

From market value to commercial value

The external quote is rarely the amount a customer ultimately pays.

A merchant may need to account for the weight of the underlying material, percentage and fixed spreads, manufacturing premiums, handling costs, regional rules, currency conversion, or product-specific adjustments.

A one-ounce coin and a half-ounce coin refer to the same underlying market but require different calculations. Two products with identical material content may have different premiums because of minting, availability, brand, or operational cost. A business selling internationally may also need to translate the market quote into several currencies while preserving consistent rounding and tax behavior.

This makes pricing logic part of the commercial model of the business.

It should be explicit, deterministic, and controlled by the backend. A merchant should be able to answer not only what the product cost, but how that amount was derived from the market conditions and rules in effect at the time.

Fluctum reflects this separation by keeping spot prices and merchant pricing rules outside Medusa ‘s standard static price tables. The final value is calculated dynamically using the current quote, the product’s weight, and configured spread and premium factors.

This approach matters because it avoids pretending that a rapidly changing value is a permanent catalog property. The product retains its commercial rules, while the current market provides the changing input.

Live storefronts need stable checkouts

While a customer is browsing, there is value in keeping prices visibly aligned with the market. A product page or cart can update without a full reload, helping the customer understand that the displayed amount reflects current conditions.

But checkout serves a different purpose.

Once the customer begins entering personal information, choosing delivery, and authorizing payment, the total must become predictable. A price that continues changing throughout these steps may be technically accurate, but it is commercially unusable.

The system therefore needs a clear boundary between browsing and transacting.

In Fluctum, prices remain live while the customer browses. When they proceed to checkout, the system creates fresh locks for the dynamically priced cart items. The total then remains fixed across the checkout stages even if the underlying spot price continues to move. Before the order is completed, the backend validates that the necessary locks exist and have not expired.

This creates a temporary agreement between the customer and the merchant. The customer receives enough time to complete the transaction at a known price. The merchant defines how long that commitment remains acceptable.

The lock is not an inconvenience added to the buying process. It is the mechanism that makes the process understandable.

The duration of trust

Every price lock introduces a business decision: how long should the merchant honor the quote?

A very short duration reduces market exposure, but may expire before legitimate customers finish entering their details or completing external payment authorization. A long duration creates a comfortable checkout experience, but increases the period during which the merchant carries the risk of a moving market.

The correct answer cannot be determined from architecture alone.

It depends on the volatility of the underlying asset, typical order value, payment method, checkout complexity, and the actual time customers need to complete the process. A store selling relatively low-value products may accept a longer window. A merchant handling large bullion orders may require a much tighter policy.

This is why lock duration should be treated as an operational parameter rather than a hard-coded technical constant.

The system should also make expiration understandable to the customer. If a quote is no longer valid, checkout should not simply fail. The customer should be told that the market price has changed, shown the refreshed amount, and given an opportunity to accept it.

A controlled repricing event preserves trust. An unexplained error destroys it.

Failure reveals the real architecture

Dynamic pricing systems are easy to demonstrate when every dependency is healthy. The market feed responds, the network is stable, the customer moves quickly, and payment completes on time.

Production systems are defined by what happens when these assumptions fail.

A market-data provider may become temporarily unavailable. A customer may leave checkout open and return later. The cart may change after the lock is created. A payment provider may introduce an external redirect that lasts longer than expected. Two backend instances may briefly operate with different information. A pricing configuration may change while transactions are in progress.

Each of these cases forces the system to answer a question about authority.

Which quote is valid? Which calculation should be trusted? Does an existing lock still correspond to the current cart? Can the last received market value still be used? At what point must the store refuse to create a new transaction?

The answers should be encoded in the system, not improvised during an incident.

Fluctum preserves the last successfully received spot price when a configured provider is temporarily unavailable, allowing the existing pricing and locking flow to continue as long as a stored price exists. The scheduled ingestion process continues attempting to retrieve new data.

For a production implementation, however, the merchant should also define the commercial freshness of that stored quote. A value may be technically available in the database while no longer being acceptable for new orders. The maximum permitted age of a quote, the possibility of pausing new locks, and any fallback-provider strategy should reflect the business’s exposure to volatility.

The goal is not uninterrupted selling at any cost. It is controlled behavior when certainty is temporarily reduced.

The backend must remain the authority

A live storefront may perform calculations to update the interface quickly, but the browser cannot be the final authority over a transactional price.

Client-side state can be outdated, interrupted, or manipulated. Even without malicious behavior, the storefront and backend may diverge because they received different market updates or applied different rounding rules.

The backend must therefore decide whether the amount is eligible to become an order.

When the customer attempts to complete checkout, the server should verify that every dynamically priced item has a corresponding lock, that the lock still represents the cart, and that it has not expired. It should rely on stored transactional data rather than simply accepting a number submitted by the frontend.

This principle extends beyond dynamic pricing. Interfaces present state; servers protect commitments.

In market-linked commerce, the distinction becomes particularly important because even a small inconsistency can be multiplied across high-value transactions.

Auditability is part of pricing, not an afterthought

When an order is questioned later, the final total alone may not be enough.

Customer support may need to explain why a product cost a particular amount. Finance may need to reconcile orders against market conditions. Engineers may need to investigate an apparent pricing discrepancy. A merchant may want to analyze whether spreads adequately protected margin during volatile periods.

To support these needs, the system should preserve the context of the calculation.

Fluctum’s price locks store the calculated unit price together with the spot price and the spread and premium factors used to produce it. This makes the locked value reconstructable after the transaction rather than leaving it as an unexplained number.

This is more than useful logging.

A static price can often be explained by pointing to a catalog configuration. A dynamic price must be explained by reconstructing a moment in time. The market input, merchant rules, and validity period are all part of the meaning of the final amount.

Auditability therefore begins when the price is created, not when someone later asks a question about it.

The limitations of manual updates

Many merchants begin by updating prices manually or by running a script every few hours. At small scale, this may be entirely reasonable.

The approach becomes fragile when the catalog grows, the market becomes more volatile, or margins become thinner. Increasing the update frequency reduces the gap between the catalog and the market, but it does not eliminate the transactional interval between cart creation and payment.

A product can be updated every minute and still be sold using a price that became outdated during an eight-minute checkout.

Manual and scheduled catalog updates solve a synchronization problem. They do not solve the problem of temporary price commitment.

This is why the transition to real-time pricing is not simply a matter of running the same update mechanism more often. It requires a different model of how prices behave inside the transaction.

The true scope of building it yourself

A custom pricing engine may be the correct choice for businesses with proprietary trading systems, complex hedging workflows, unusual regulatory constraints, or an existing commerce platform that cannot be changed.

But the engineering scope is often underestimated.

The visible requirement may sound simple: connect a market feed and show a live price. The complete system must also manage scheduled ingestion, provider errors, quote storage, pricing formulas, storefront synchronization, cart behavior, checkout locks, expiration, server-side validation, payment timing, audit records, monitoring, and operational recovery.

None of these components is individually exotic. Their interaction is what creates complexity.

The most expensive mistakes are rarely dramatic system failures. They are transactions that appear successful while using the wrong assumptions: an old quote, an invalid lock, an inconsistent calculation, or a cart that no longer matches the price being honored.

Building from scratch offers full control, but it also means owning every one of these failure modes.

Where Fluctum fits

Fluctum was created as an open-source dynamic-pricing foundation for Medusa stores selling products connected to live market values.

It combines scheduled spot-price ingestion, dynamic calculation rules, real-time storefront updates, and checkout price locking in one coherent flow. It is available both as an installable Medusa plugin and as a starter project containing a Medusa backend, a Next.js storefront, and the supporting local infrastructure needed to run the process end to end.

The included implementation focuses on precious metals, but the architectural model is broader. Any product whose price can be expressed as a changing external value combined with stable commercial rules can potentially follow the same lifecycle.

Fluctum does not remove the need for business-specific decisions. A production deployment may still require a chosen market-data provider, custom pricing formulas, ERP or inventory integration, payment configuration, storefront adaptation, monitoring, and operational policies for periods when market data is unavailable.

What it removes is the need to begin with an empty codebase.

The software is available under the MIT license, allowing businesses to run, modify, self-host, and extend it without a per-store or per-transaction licensing model.

The business value is control, not movement

Dynamic pricing is often described as a way to make product prices move automatically.

That description misses the most important benefit.

The value does not come from movement itself. It comes from controlling when a price may move, when it must stop moving, how long it remains valid, and what evidence survives after the order is completed.

For the merchant, this means better protection against stale-price transactions and more consistent application of commercial rules. For the customer, it means seeing a current price while browsing and receiving a stable, understandable quote during checkout. For the organization operating the store, it means less dependence on manual updates and a clearer path for investigating pricing decisions.

Automation is useful, but predictability is what makes it commercially valuable.

From static catalog to transactional pricing

Selling market-linked products requires a conceptual shift.

The price is no longer a field attached permanently to a product. It is a time-sensitive state created from external data and commercial policy. It remains fluid while the customer browses, becomes temporarily fixed when the transaction begins, and must be validated before it can become an order.

A reliable system must preserve this state from the market feed to the payment boundary.

It must know where the price came from, how it was calculated, when it was locked, how long it remains acceptable, and what should happen when any of those assumptions no longer hold.

This is why live prices alone are not enough.

A live feed can tell a store what the market is doing now. A well-designed pricing lifecycle determines whether the business can safely transact on that information.

Fluctum provides an open-source foundation for implementing that lifecycle in Medusa. It connects the changing reality of the market with the stability a customer expects from checkout-without turning either side of the transaction into an afterthought.

Originally published at https://u11d.com on August 5, 2026.

Building Reliable Checkouts for Spot-Priced Products was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you run queue processors, batch workers, or event-driven workloads that sit idle for hours between bursts, you’re paying for compute you don’t need. Kubernetes HPA can scale these deployments to zero replicas — no KEDA, no Knative, no external controllers required. You need one feature gate, an external metrics source, and about twenty minutes of setup. When the queue is empty your pods disappear, and if you pair this with cluster autoscaler, the nodes disappear too. Real scale-to-zero, using nothing but native Kubernetes primitives.

Quick Reference

Local Setup with kind

Since HPAScaleToZero requires an explicit feature gate, we need a cluster that has it enabled on both the API server and the controller manager. kind makes this straightforward - especially on Kubernetes 1.36, which at the time of writing is too new for most managed providers.

If you haven’t already built the node image:

kind build node-image --type release v1.36.0

Create a cluster config that enables the feature gate:

# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
featureGates:
  HPAScaleToZero: true
nodes:
  - role: control-plane
  - role: worker

kind create cluster --name hpa-scale-to-zero --config kind-config.yaml --image kindest/node:v1.36.0

The featureGates field at the cluster level propagates the flag to all relevant components (kube-apiserver, kube-controller-manager, kubelet). No need to manually patch component configs.

The Metrics Pipeline

The HPA controller can’t scale from zero based on CPU or memory — there are no pods to measure. You need a metric that exists outside the workload itself. For queue-based workloads, the natural choice is the queue length: how many items are waiting to be processed.

We’ll use Redis as the queue (specifically a Redis list), expose its length via a redis-exporter sidecar, scrape it with Prometheus, and surface it to the Kubernetes metrics API through prometheus-adapter. This is the same pipeline pattern you’d use in production — the only difference is we’re running everything in a single kind cluster.

Deploy Redis with an Exporter

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis \
  --set architecture=standalone \
  --set auth.enabled=false \
  --set metrics.enabled=true \
  --set metrics.extraArgs.check-keys=work-queue

The metrics.enabled=true deploys a redis-exporter sidecar alongside Redis. The --check-keys work-queue argument tells the exporter to emit redis_key_size{key="work-queue"} - the length of our Redis list. That's the metric we'll use to drive the HPA. The chart also sets up the correct Prometheus scrape annotations automatically.

Deploy Prometheus and the Adapter

The prometheus-community Helm charts get us running in two commands:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

helm install prometheus prometheus-community/prometheus \
  --set server.service.type=ClusterIP \
  --set alertmanager.enabled=false \
  --set kube-state-metrics.enabled=false \
  --set prometheus-node-exporter.enabled=false \
  --set prometheus-pushgateway.enabled=false

This gives us a minimal Prometheus that auto-discovers pods annotated with prometheus.io/scrape: "true" - which the Bitnami Redis chart already configures.

Now deploy the prometheus-adapter with a custom external metrics rule:

helm install prometheus-adapter prometheus-community/prometheus-adapter \
  --set prometheus.url="http://prometheus-server" \
  --set prometheus.port=80 \
  --set-json 'rules.external=[{"seriesQuery":"{__name__=\"redis_key_size\",key=\"work-queue\"}","metricsQuery":"sum(<<.Series>>{<<.LabelMatchers>>})","name":{"as":"redis_queue_length"},"resources":{"namespaced":false}}]'

This rule tells the adapter: take the redis_key_size metric where key="work-queue", expose it as an external metric called redis_queue_length, and don't filter by namespace (since the queue is a cluster-wide resource - there's only one Redis).

After a minute or so, verify the external metric is available:

kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/default/redis_queue_length" | jq .

You should see a response with a value of 0 (since the queue is empty).

The Worker and HPA

The worker is deliberately simple — a shell script that pops items from the Redis list and “processes” them by sleeping for a second. In production this would be your actual consumer code.

Important: start the deployment with replicas: 1, not zero. The HPA controller uses a ScaledToZero condition internally - it only scales from zero if it was the one that previously scaled the workload to zero. A deployment that starts at zero replicas with a fresh HPA will never scale up. Let the HPA handle the initial scale-down to zero on its own.

# worker.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: queue-worker
spec:
  replicas: 1  # start at 1 — the HPA will scale to zero once metrics are available
  selector:
    matchLabels:
      app: queue-worker
  template:
    metadata:
      labels:
        app: queue-worker
    spec:
      containers:
        - name: worker
          image: redis:7
          command:
            - /bin/sh
            - -c
            - |
              while true; do
                item=$(redis-cli -h redis-master BRPOP work-queue 30)
                if [ -n "$item" ]; then
                  echo "Processing: $item"
                  sleep 1  # simulate work
                fi
              done

Now the HPA that scales this deployment between 0 and 10 replicas based on the queue length:

# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: queue-worker
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: queue-worker
  minReplicas: 0  # this is what HPAScaleToZero enables
  maxReplicas: 10
  metrics:
    - type: External
      external:
        metric:
          name: redis_queue_length
        target:
          type: Value
          value: "5"  # one pod per 5 queue items
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 60
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15

The target.value: "5" means the HPA will try to maintain a ratio of one pod per five pending items. When the queue has 20 items, you get 4 pods. When it drops to zero, you get zero pods. The behavior.scaleDown section shortens the stabilization window from the default 5 minutes to 60 seconds - useful for demos and workloads where you want faster scale-to-zero.

Seeing It in Action

Apply the worker and HPA:

kubectl apply -f worker.yaml -f hpa.yaml

Open a watch in one terminal:

kubectl get hpa queue-worker -w

Since the queue is empty and the deployment starts at 1 replica, the HPA will first scale it down to zero. This initial scale-down is critical — it sets the internal ScaledToZero condition that enables future scale-from-zero behavior. After about a minute (our shortened stabilization window), you'll see replicas drop to 0.

Now push 20 items into the queue:

kubectl exec redis-master-0 -c redis -- sh -c '
  for i in $(seq 1 20); do
    redis-cli LPUSH work-queue "job-$i"
  done
'

Within 30–60 seconds (Prometheus scrape interval + adapter refresh + HPA sync period), you’ll see the HPA scale the deployment from 0 to 4 replicas. The workers will process the items — one per second per worker — and as the queue drains, the replica count drops. Once the queue is empty and the metric reads zero, the HPA scales the deployment back to zero replicas. Pods gone.

Here’s what the kubectl get hpa queue-worker -w output looks like over the full cycle:

NAME           REFERENCE                 TARGETS   MINPODS   MAXPODS   REPLICAS
queue-worker   Deployment/queue-worker   0/5       0         10        1
queue-worker   Deployment/queue-worker   0/5       0         10        0
queue-worker   Deployment/queue-worker   20/5      0         10        0
queue-worker   Deployment/queue-worker   20/5      0         10        4
queue-worker   Deployment/queue-worker   8/5       0         10        4
queue-worker   Deployment/queue-worker   0/5       0         10        2
queue-worker   Deployment/queue-worker   0/5       0         10        0

Push items again — the HPA scales from zero immediately, no manual intervention needed. The cycle repeats indefinitely.

Cluster Autoscaler Integration

When a deployment scales to zero, its pods vanish. If those pods were the only workload on a node, the node becomes empty. Cluster autoscaler (or any node lifecycle manager) will notice the idle node and remove it after its configurable cool-down period — typically 10 minutes.

This is where the real cost savings live. You’re not just saving pod-level resources; you’re saving entire node-hours. For a workload that processes a queue for two hours a day and sits idle for twenty-two, you go from paying for 24 node-hours to paying for roughly 2.5 (accounting for scale-up overhead).

The cold-start chain matters. When an item hits the queue after a period of silence, here’s what happens in sequence:

1. Prometheus scrapes the redis-exporter (scrape interval, typically 15s)
2. Prometheus-adapter picks up the new value (adapter refresh, typically 30s)
3. HPA sync loop fires (default 15s) and decides to scale up
4. Scheduler assigns the pod to a node — if no nodes are available, cluster autoscaler provisions one (60–120s for cloud providers)
5. Kubelet pulls the container image and starts the pod
6. Pod becomes Ready

In a warm cluster (nodes already present), steps 1–5 take about 30–60 seconds total. When a new node must be provisioned, add 1–2 minutes. For workloads where a minute or two of latency is unacceptable, consider these mitigations:

• Smaller container images reduce pull time. Distroless or scratch-based images start faster.
• Priority-based overprovisioning: deploy a low-priority “placeholder” pod that reserves a node. When real work arrives, the placeholder gets preempted and the worker starts immediately — no node provisioning needed.
• Shorter scrape intervals on Prometheus reduce the detection lag.

For batch and queue workloads, the 30–60 second cold start is typically fine. You’re processing a backlog, not serving interactive requests.

When to Use This vs. KEDA

KEDA is the most popular alternative for event-driven autoscaling in Kubernetes. It supports 60+ scalers (Redis, SQS, RabbitMQ, Kafka, Azure Queue, and many more), handles the metrics plumbing internally, and can scale to zero without any feature gate.

Use native HPA scale-to-zero when:

• You already have Prometheus and a metrics adapter deployed
• You want fewer moving parts and no additional CRDs
• Your scaling logic is simple (one metric, linear scaling)
• You prefer to stay within the boundaries of native Kubernetes APIs

Use KEDA when:

• You don’t have Prometheus or don’t want to maintain the adapter
• You need advanced scaling logic (multiple triggers, complex cooldowns, cron-based scaling)
• You want out-of-the-box support for dozens of event sources without manual adapter configuration
• You need ScaledJobs (scaling Kubernetes Jobs rather than Deployments)

There’s no shame in either choice. KEDA is excellent software. The native approach is simpler when your infrastructure already includes Prometheus — you’re just connecting pieces that already exist.

Gotchas

You cannot use CPU or memory metrics to scale from zero. This is the most common mistake. When replica count is zero, there are no pods, so there’s no CPU or memory to measure. The HPA controller requires at least one non-resource metric (external or custom) to make scaling decisions at zero replicas. If you configure only resource metrics, the HPA will refuse to scale from zero.

The deployment must not start at zero replicas. This is the subtlest gotcha and I haven’t seen it documented clearly anywhere. The HPA controller maintains a ScaledToZero condition internally. It only scales FROM zero if it was the one that previously scaled the workload TO zero. If you deploy with replicas: 0 and create a fresh HPA, the controller sees zero replicas but no ScaledToZero condition, and sets ScalingActive: False with reason ScalingDisabled. The fix is simple: start with replicas: 1 and let the HPA scale it down naturally. Once the HPA has performed that initial scale-to-zero, the ScaledToZero condition is set to True and all subsequent scale-from-zero operations work correctly.

The stabilization window still applies at zero. By default, the HPA waits 5 minutes of sustained low metrics before scaling down. This applies to the transition from 1 to 0 as well. If you want faster scale-to-zero, configure the behavior.scaleDown section with a shorter stabilizationWindowSeconds.

The feature gate is alpha — but don’t let that scare you. HPAScaleToZero has been available since Kubernetes 1.16 without breaking changes. It hasn't graduated to beta primarily due to KEP process inertia, not because of instability. The implementation is a small conditional in the HPA controller that allows minReplicas: 0 when the feature gate is enabled. It's been running in production clusters for years.

PodDisruptionBudgets at zero replicas. A PDB with minAvailable: 1 on a deployment that's at zero replicas won't prevent the scale-to-zero - PDBs apply to voluntary eviction of running pods, and scaling down is a different path. However, consider what happens if you have a PDB and scale from zero to one: the single pod is protected by the PDB immediately upon becoming ready.

Wrapping Up

The combination of native HPA scale-to-zero, external metrics from Prometheus, and cluster autoscaler gives you genuine pay-for-what-you-use economics on idle workloads. No third-party controllers, no additional CRDs, no vendor lock-in. The feature gate has been stable for twenty releases. Enable it, point your HPA at a queue metric, set minReplicas: 0, and stop paying for compute that's doing nothing.

The KEP tracking this feature is KEP-2021: HPA Scale to Zero — if you want to see it graduate to beta and become the default, that’s the issue to watch and engage with.

Originally published at https://u11d.com on May 6, 2026.

Kubernetes HPA Scale to Zero Without KEDA: Native Autoscaling for Idle Workloads was originally published in uninterrupted engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.