test(proxy): fail the build when kamal-proxy grows a flag the gem cannot emit

[mhenrixon]

Summary

kamal-proxy v1.0.0.0 accepts 80 deploy flags and 31 run flags. The gem emits 34 and 3.

Most of R3 and R5 — rate limiting, IP allow lists, mTLS, the response cache, compression, header rules, redirects, canary splits, scale-to-zero — plus every ACME/DNS-01 option, ships in the image and cannot be turned on from deploy.yml.

Nothing noticed it happening. 23 feat commits landed between v0.9.2.2 and v1.0.0.0 and the gem's config surface never moved, because no test relates the two. Fixing the backlog without fixing the detection just resets the clock.

This adds the detection.

Closes #82

How it works

Piece	Role
bin/sync-proxy-flags	regenerates the flag manifest from the proxy's own --help
test/fixtures/kamal_proxy_flags.yml	the checked-in manifest, stamped with the version it came from
test/fixtures/deploy_with_every_proxy_option.yml	every proxy key the gem can express
test/proxy_flag_coverage_test.rb	the guard

Every flag must be emitted by the gem or waived with a reason. Waivers split in two, deliberately:

• NEVER_EXPOSED — a decision (--force is a CLI concern; --http-port is published by docker)
• R7_BACKLOG — a todo, keyed by its issue number

Collapsing those into one hash would let the backlog quietly become permanent, which is how this gap happened.

Two choices worth reviewing

Coverage is measured by generating the real commands, not by reading the keys of deploy_options. Costlier, but a config accessor that exists and is never wired does not pass. This is what makes each R7 issue self-verifying: implement it, delete its waiver, and the test proves the flag is actually emitted rather than merely named.

The flag list is generated from Cobra, never parsed out of the Go source. Not caution for its own sake — the flag counts I put in the R7 epic came from a regex over internal/cmd/*.go that silently missed every flag registered via Int64Var/Uint16Var, because the method name contains digits. Cobra found three the regex did not (cache-max-variants, cache-lease-ttl, cache-lease-wait). Building a drift guard on the technique that caused the drift would have been a poor foundation.

Corrected figures, epic #13's summary table is understated: 80/31 flags (not 79/29), 45 deploy + 25 run unexposed (not 44/26). No flag moves between R7 issues; I'll fix the table.

Test plan

• RED with an empty waiver list — reports all 45 + 25 unmapped flags with per-flag guidance
• Upstream adds a flag — injected brand-new-thing into the manifest; fails naming it, with the expose-or-waive instructions
• Upstream removes a waived flag — deleted canonical-host; fails naming the now-dead waiver
• MINIMUM_VERSION bumped without refreshing — set it to v1.0.1.1; fails telling you to run bin/sync-proxy-flags
• Fixture is load-bearing — deleted ssl_redirect from the fixture; --tls-redirect drops into the uncovered list
• bundle exec rubocop --parallel clean (205 files)
• Unit suite: 1188 runs, 2 failures — both the documented Apple-Silicon builder tests

bin/test not run: integration needs ghcr.io/mhenrixon/kamal-proxy:v1.0.0.0, which was still building when this was pushed. Must be green before merge — see below.

Deviations & judgment calls

Deviations

• Bundled the MINIMUM_VERSION bump v0.9.2.2 → v1.0.0.0. Not asked for, but the manifest must be generated against some version and the backlog is only accurate against this one — cache-max-variants, cache-lease-ttl and cache-lease-wait exist only in v1.0.0.0. Generating against v0.9.2.2 would have encoded a stale backlog on day one. This is the merge risk: integration tests now pull the v1.0.0.0 image. If you'd rather decouple, say so and I'll regenerate against v0.9.2.2 and land the bump separately.
• Also bumped the pinned version in docs/proxy.yml:341 — not optional, test_docs_example_run_version_matches_the_pinned_minimum_version enforces it.

Judgment calls

• Source of truth is a hybrid of the issue's options 1 and 2. The issue preferred a kamal-proxy flags --json subcommand, but that needs a proxy-repo change and another release before the gem can use it. bin/sync-proxy-flags runs the proxy's own --help instead — same authoritativeness, no cross-repo dependency. If flags --json lands later, only the script changes; the manifest format and the test do not.
• Dropped three waivers the issue's sketch assumed. host, tls and target are emitted by deploy_command_args. Waiving them would have been a lie that masked real coverage.
• Scoped to deploy and run. The other subcommands (list, stop, pause, drain, rollout, cache, domains) carry no operator-tunable options, so they are not a deploy.yml surface. Documented in the script.
• --recheck-targets-on-restore needed no waiver — it is already emitted unconditionally.