How would you govern one WireMock proxyAllTo( canary mapping against the live meter API across many suites?

## What a canary proxy mapping is After a refresh, the normal end state is a closed world: every mapping in the set answers from a recorded response, and no proxy leg survives. A **canary** is a deliberate exception — exactly one WireMock mapping, `proxyAllTo("https://meters.stadtwaerme.example")`, left in the set on purpose. Because it sits at a lower precedence than the recorded stubs, it never answers a call the set already covers. It answers only the calls the set does not cover, and in doing so it reaches the real district heating meter API. The mechanism is small. The governance is not, because that one mapping quietly converts a hermetic test set into something with a live outbound dependency. ## What it buys, and what it costs - **Buys:** an uncovered call produces a real response instead of a match failure, so the run tells you what the client now asks for and what the upstream actually answers. - **Buys:** it is one mapping, in the same set, in the same repository — nothing extra to deploy or maintain. - **Costs:** a network call inside a test run, with the flakiness, latency and DNS dependence that implies. - **Costs:** a credential in a place that previously needed none, because the real meter API will want authentication. - **Costs:** load on a service whose owners never agreed to it, multiplied by however many suites run. - **Costs:** the temptation to widen it. A canary that starts answering ordinary traffic has become a catch-all, and a catch-all makes everything pass. ## The decisions a lead actually owns 1. **Where it runs.** One scheduled job on one instance — not every developer's machine, and not every pull request. The value of the signal does not scale with how often you collect it; the cost does. 2. **Its precedence.** In WireMock, `DEFAULT_PRIORITY` is `5` and a lower number is matched first, so a canary at `atPriority(` with a higher number sits underneath the whole recorded set by construction. Getting this backwards turns the canary into the first thing every request hits. 3. **Its blast radius.** Restrict egress from that instance to the one upstream host. A proxy mapping is an outbound path, and an unrestricted one is an outbound path to anywhere the URL happens to point. 4. **Its removability.** Tag the mapping with `metadata` when you add it, so WireMock's `POST /__admin/mappings/remove-by-metadata` strips exactly it and nothing else. A canary you cannot cleanly remove is a canary that will still be there when someone runs the set in an environment with no route to the upstream. 5. **Its owner.** Someone must read what it produces, and the finding must land somewhere with a name on it. An unowned signal decays into a job that is red for a fortnight and then muted. ## Keeping it from becoming a catch-all The failure is gradual and always looks reasonable at each step. The canary catches an uncovered call, somebody notices the suite is more robust with it enabled, it gets turned on in more places, and eventually a request that should have failed loudly against a missing stub is quietly answered by the real service. At that point the set no longer tells you what it covers, and the suite passes for reasons nobody chose. Guards that hold up in practice: - Keep it to **one** mapping, and treat a second as a design smell rather than an extension. - Keep it out of the default configuration: the canary belongs to a named job, added at start-up and removed at the end. - Make its firing **visible**. A canary that answers a request has found something; that should be an outcome the job reports, not a silent success. - Never let it serve the paths the recorded set already covers. If it does, the precedence is wrong. ## Where this sits next to the refresh itself A refresh and a canary answer different questions with the same underlying transport. The refresh regenerates the whole set and hands you a diff to review deliberately. The canary is standing surveillance on one narrow thing — the calls your set does not answer — and it is cheap precisely because it does almost nothing most of the time. So the sensible arrangement is usually both, at different cadences: a scheduled refresh whose output a person reads, and a canary that only speaks when the client asks for something the set has never seen. If you can only have one, have the refresh: it is the one that produces reviewable evidence, and it does not leave a live outbound path in a test set that a hundred other runs will inherit. Finally, write down the exit. Under what circumstance does the canary come out — the API is being retired, egress policy tightens, the job stops being read? Deciding that at the point you add it is much cheaper than deciding it during an incident where a test set turns out to have been calling a production service for a year.