feat(edge): gate per-minor routing on published minors and add a staging zone (#175)

## Motivation

`UNION_SLOTS` is empty, so per-minor routing has never been exercised end to end. Before it can be enabled and advertised, two things were missing: a way to test it without pointing production at it, and evidence that the published indexes actually support it.

Verifying the data first turned up a defect that would have broken users the moment the flag was flipped.

## The defect

`contribPath()` redirects to `contrib/<minor>/` whenever the User-Agent carries any R minor, with no existence check and no fallback:

```ts
const rMinor = extractRMinor(userAgent);
return rMinor ? `/${slot}/latest/src/contrib/${rMinor}/${rest}` : flat;
```

Only `4.4`, `4.5` and `4.6` are published. `4.3` and `4.2` return 404 on all 16 slots. With `UNION_SLOTS` set, an R 4.3 client would be redirected to a non-existent index and see **zero** packages: a silent, total failure rather than a degraded one. R 4.3 is still advertised as supported on the website and in `docs/configuration.mdoc`, though `build-env-images` now pins only 4.6.0/4.5.3/4.4.3.

## Changes

- **Gate routing on `KNOWN_MINORS`** (default `4.4,4.5,4.6`), falling back to the flat index for anything else. Unknown minor now behaves exactly as today.
- **Honour `EXTRA_PUBLIC_HOSTS`.** `publicCdnOrigin()` falls back to the hardcoded `PUBLIC_CDN_ORIGIN` for any hostname not in `PUBLIC_CDN_HOSTS`, so a staging zone on a `b-cdn.net` hostname would redirect into *production* and silently measure the wrong system. This lets the identical script run on staging and redirect within itself.
- **Add the `cran-rpkgs-test` pull zone** with `UNION_SLOTS` pre-enabled for all 16 slots, same B2 origin, served on the bunny default hostname so it needs no DNS record and is never advertised.
- **Add `scripts/verify-r-minor-routing.sh`**, covering every `<arch>/<os>` slot: index reachability per minor, the union property against flat, `Path:` target resolution, coverage parity across minors, and with `--live` the real User-Agent routing, the non-R User-Agent case, and that tarballs are never rewritten.
- **Cover the fallback in the edge test suite** for both an unpublished minor (4.3) and a future one (4.7).

## Findings from the full run

112 passed, 16 failed across the 16 slots. Every failure is the same: no R 4.3 index.

All 16 slots carry union indexes that are supersets of flat, every sampled `Path:` target resolves, and all indexes were republished within minutes of each other, so the build side is healthy.

Coverage is **not** yet even, which is why "full coverage for ABI-sensitive packages" is not a claim to make yet:

| slot | flat | 4.4 | 4.5 | 4.6 |
|---|---|---|---|---|
| amd64/resolute | 24305 | 24402 | 24748 | 24395 |
| amd64/alpine324 | 24397 | 24457 | 24744 | 24448 |
| amd64/noble | 24780 | 24805 | 24805 | 24805 |

On the R 4.5-built distros (`resolute`, `alpine324`, and their arm64 twins) a 4.4 or 4.6 client sees ~300 fewer packages than a 4.5 client. On `noble`/`jammy`/`rhel9`/`alpine323` the spread is under 5. The new parity check encodes this with a configurable `PARITY_TOLERANCE`.

## Verification

- `just edge-test`: 18 steps pass. The two new steps were confirmed to fail with the `KNOWN_MINORS` gate removed and pass with it.
- `tofu validate`: passes. **Not applied** - no bunny.net or state credentials were available, so the staging zone still needs a `tofu apply`.
- `scripts/verify-r-minor-routing.sh`: full 16-slot run, results above.
- `shellcheck`: clean.

## Not done here

Applying the staging zone, then running `BASE=https://cran-rpkgs-test.b-cdn.net scripts/verify-r-minor-routing.sh --live` against it. Production `UNION_SLOTS` is deliberately left empty.

Reviewed-on: #175

edge/rpkgs-router.test.ts

@@ -17,6 +17,8 @@ const UNION_SLOTS = 'amd64/alpine324';
 
 const UA_R45_MUSL = 'R (4.5.3 x86_64-pc-linux-musl x86_64 linux-musl)';
 const UA_R46_MUSL = 'R (4.6.0 x86_64-pc-linux-musl x86_64 linux-musl)';
+const UA_R43_MUSL = 'R (4.3.3 x86_64-pc-linux-musl x86_64 linux-musl)';
+const UA_R47_MUSL = 'R (4.7.0 x86_64-pc-linux-musl x86_64 linux-musl)';
 const UA_R45_ALPINE = 'R/4.5.3 R (4.5.3 x86_64-pc-linux-musl x86_64 linux-musl) Alpine Linux 3.24';
 const UA_R45_RESOLUTE = 'R/4.5.3 (Ubuntu 26.04) (aarch64-unknown-linux-gnu aarch64 linux-gnu)';
 const UA_R45_FUTURE_UBUNTU =
@@ -96,6 +98,33 @@ Deno.test('rpkgs-router', async (t) => {
       assertEquals(res.location, `https://cran.rpkgs.com${SLOT}/4.6/PACKAGES.gz`);
     });
 
+    // We publish binaries only for the supported window. An excluded minor has
+    // no slot we can serve safely, so it goes to CRAN for sources rather than
+    // to a 404 or to binaries built under another minor.
+    await t.step('sends an excluded R minor to CRAN for the index', async () => {
+      const res = await probe(`${SLOT}/PACKAGES.gz`, UA_R43_MUSL);
+      assertEquals(res.location, 'https://cran.r-project.org/src/contrib/PACKAGES.gz');
+    });
+
+    await t.step('sends a future R minor to CRAN too', async () => {
+      const res = await probe(`${SLOT}/PACKAGES.gz`, UA_R47_MUSL);
+      assertEquals(res.location, 'https://cran.r-project.org/src/contrib/PACKAGES.gz');
+    });
+
+    // The index and the tarballs R resolves against it have to come from the
+    // same place. Serving one from CRAN and the other from here would hand R a
+    // binary where it expects a source tarball.
+    await t.step('sends an excluded minor to CRAN for tarballs as well', async () => {
+      const res = await probe(`${SLOT}/foo_1.0.tar.gz`, UA_R43_MUSL);
+      assertEquals(res.location, 'https://cran.r-project.org/src/contrib/foo_1.0.tar.gz');
+    });
+
+    await t.step('leaves an excluded minor alone on a slot outside UNION_SLOTS', async () => {
+      const res = await probe(`${OTHER_SLOT}/PACKAGES.gz`, UA_R43_MUSL);
+      assertEquals(res.location, null);
+      assertEquals(res.status, 200);
+    });
+
     await t.step('routes PACKAGES and PACKAGES.rds too', async () => {
       for (const file of ['PACKAGES', 'PACKAGES.rds']) {
         const res = await probe(`${SLOT}/${file}`, UA_R45_MUSL);
@@ -146,18 +175,12 @@ Deno.test('rpkgs-router', async (t) => {
 
     await t.step('resolves Ubuntu 26.04 to the resolute slot', async () => {
       const res = await probe('/src/contrib/PACKAGES.gz', UA_R45_RESOLUTE);
-      assertEquals(
-        res.location,
-        'https://cran.rpkgs.com/arm64/resolute/latest/src/contrib/PACKAGES.gz',
-      );
+      assertEquals(res.location, 'https://cran.rpkgs.com/arm64/resolute/latest/src/contrib/PACKAGES.gz');
     });
 
     await t.step('resolves a future Ubuntu release from its codename', async () => {
       const res = await probe('/src/contrib/PACKAGES.gz', UA_R45_FUTURE_UBUNTU);
-      assertEquals(
-        res.location,
-        'https://cran.rpkgs.com/arm64/dynamic-dugong/latest/src/contrib/PACKAGES.gz',
-      );
+      assertEquals(res.location, 'https://cran.rpkgs.com/arm64/dynamic-dugong/latest/src/contrib/PACKAGES.gz');
     });
 
     await t.step('sends an unidentifiable distro to CRAN', async () => {

edge/rpkgs-router.ts

@@ -27,7 +27,17 @@ import * as BunnySDK from 'https://esm.sh/@bunny.net/edgescript-sdk@0.12';
 
 const PUBLIC_CDN_ORIGIN = 'https://cran.rpkgs.com';
 const CRAN_ORIGIN = 'https://cran.r-project.org';
-const PUBLIC_CDN_HOSTS = new Set(['cran.rpkgs.com', 'cran.allianceswisspass.devxy.io']);
+const PUBLIC_CDN_HOSTS = new Set([
+  'cran.rpkgs.com',
+  'cran.allianceswisspass.devxy.io',
+  // Staging hostnames, so the identical script can run on a test pull zone and
+  // redirect within itself. Without this a test zone rewrites to
+  // PUBLIC_CDN_ORIGIN, quietly exercising production instead of itself.
+  ...(Deno.env.get('EXTRA_PUBLIC_HOSTS') ?? '')
+    .split(',')
+    .map((host) => host.trim())
+    .filter((host) => host.length > 0),
+]);
 
 /** Slots ("<arch>/<os>", comma separated) whose per-minor index is a union. */
 const UNION_SLOTS = new Set(
@@ -37,6 +47,21 @@ const UNION_SLOTS = new Set(
     .filter((slot) => slot.length > 0),
 );
 
+/**
+ * R minors for which a per-minor index is actually published.
+ *
+ * contribPath() has no way to probe the origin, so a minor that is not
+ * published here must fall back to the flat index. Routing an unlisted minor
+ * would send that client to a 404 and it would see no packages at all - a
+ * silent, total failure rather than a degraded one.
+ */
+const KNOWN_MINORS = new Set(
+  (Deno.env.get('KNOWN_MINORS') ?? '4.4,4.5,4.6')
+    .split(',')
+    .map((minor) => minor.trim())
+    .filter((minor) => minor.length > 0),
+);
+
 /** `/<arch>/<os>/latest/src/contrib[/<rest>]` */
 const SLOT_PATH_REGEX = /^\/(amd64|arm64)\/([a-z0-9._-]+)\/latest\/src\/contrib\/?(.*)$/;
 
@@ -96,6 +121,18 @@ function publicCdnOrigin(url: URL): string {
   return PUBLIC_CDN_HOSTS.has(url.hostname) ? url.origin : PUBLIC_CDN_ORIGIN;
 }
 
+/**
+ * True when the client reports an R minor that we deliberately do not serve.
+ *
+ * A client that reports no minor at all is not "unsupported": non-R fetchers
+ * (mirror scripts, image builds) must keep getting the flat slot. Only a
+ * known-and-excluded minor falls through to CRAN.
+ */
+function isExcludedMinor(userAgent: string): boolean {
+  const rMinor = extractRMinor(userAgent);
+  return rMinor !== null && !KNOWN_MINORS.has(rMinor);
+}
+
 function extractRMinor(userAgent: string): string | null {
   for (const regex of R_MINOR_REGEXES) {
     const match = userAgent.match(regex);
@@ -177,8 +214,8 @@ function parseMacUserAgent(userAgent: string): { os: string; arch: string; rver:
  * The contrib path a request should be served from, relative to the slot.
  *
  * Returns the per-minor path for an index file when the slot is known to carry
- * a union index and the client's R minor is known; otherwise the flat path,
- * which is what every client sees today.
+ * a union index and the client's R minor is one we publish; otherwise the flat
+ * path, which is what every client sees today.
  */
 function contribPath(slot: string, rest: string, userAgent: string): string {
   const flat = rest ? `/${slot}/latest/src/contrib/${rest}` : `/${slot}/latest/src/contrib`;
@@ -188,7 +225,7 @@ function contribPath(slot: string, rest: string, userAgent: string): string {
   }
 
   const rMinor = extractRMinor(userAgent);
-  return rMinor ? `/${slot}/latest/src/contrib/${rMinor}/${rest}` : flat;
+  return rMinor && KNOWN_MINORS.has(rMinor) ? `/${slot}/latest/src/contrib/${rMinor}/${rest}` : flat;
 }
 
 BunnySDK.net.http
@@ -224,6 +261,16 @@ BunnySDK.net.http
         return Promise.resolve(ctx.request);
       }
 
+      // An R minor outside the supported window has no binaries we can safely
+      // serve, so the whole interaction goes to CRAN: the index and the
+      // tarballs R will resolve against it. Serving the index from CRAN but
+      // tarballs from here would hand R a binary where it expects a source
+      // tarball, which fails in a far more confusing way than not being
+      // served at all.
+      if (UNION_SLOTS.has(slot) && isExcludedMinor(userAgent)) {
+        return Promise.resolve(redirectTo(`${CRAN_ORIGIN}/src/contrib/${rest}`));
+      }
+
       const target = contribPath(slot, rest, userAgent);
       if (target === path) {
         return Promise.resolve(ctx.request);
@@ -238,6 +285,10 @@ BunnySDK.net.http
         return Promise.resolve(redirectTo(`${CRAN_ORIGIN}${path}`));
       }
 
+      if (UNION_SLOTS.has(slot) && isExcludedMinor(userAgent)) {
+        return Promise.resolve(redirectTo(`${CRAN_ORIGIN}${path}`));
+      }
+
       const rest = srcContrib ? srcContrib[1] : '';
       return Promise.resolve(redirectTo(`${publicOrigin}${contribPath(slot, rest, userAgent)}`));
     }