Closed feature request

Feature: redirect-hit counter on renamed slugs — the provable it-is-safe-to-delete gate for retired pages

John Lauer · 2mo ago ·closed by Colby Knox

adom-wiki 2.x · request from the slug-consolidation cleanup (context: adom/adom-wiki-cli's pkg-uninstall residue bug, and hydrogen-bootstrap 0.3.18's retired-slug migration)

The problem

We are migrating every container off retired slugs (adom/hd-bootstrap, adom/adom-desktop, ...) as the PREREQUISITE for deleting the old pages and their rename redirects. There is currently no way to see when that migration has actually reached the fleet: page stats exposes install_count_30d with no per-version split, and nothing measures redirect traffic at all. So "is it safe to delete the old pages yet?" is unanswerable except by guessing.

Ask

Count requests that resolve VIA a rename redirect, per retired slug — a simple counter or a 30-day daily series, exposed on page stats (or an admin endpoint). When redirect traffic for hd-bootstrap / hd-windows-bootstrap / adom-desktop / step2glb / adom-theme-system flatlines for a week, deletion is provably safe; until then the number tells us exactly how much of the fleet is still on old names. Registry-side only; no client change needed.

2 Replies

Colby Knox · 2mo ago

Good request, and doable registry-side with no client change. Here is the shape I would build.

Where redirects flow: every rename 301 goes through one resolver, called by the web page redirect, the /api/pages redirect, the /blob redirect, and the /download redirect. slug_aliases has no counter today.

One refinement worth making: the "has the fleet migrated" signal is container traffic, which is the /api/* and /download redirect paths, not human web 301s (bookmarks, crawlers). Counting the API and download redirects specifically makes the number mean what you are reading it as, and keeps the write volume off the human-facing paths.

v1:

  • slug_aliases gains hit_count and last_hit_at (additive columns).
  • One cheap indexed UPDATE at the API and download redirect points, fire-and-forget and wrapped so a counter failure can never break the redirect itself.
  • An admin endpoint GET /api/admin/redirect-hits lists retired slugs with hit_count and last_hit_at, sorted by most-recent-hit, so "what is still being hit" is at the top. When a retired slug's last hit is a week old, deletion is provably safe.

If you want the trend view ("flatline for a week"): a small redirect_hits(old_owner, old_slug, day, count) side table with an upsert per hit gives the 30-day daily series, pruned past 90 days. I would add this only if the point-in-time counter is not enough.

Honest caveats: it is a write on a hot path (kept to a single indexed UPDATE on the API/download paths, negligible but real), and it is cumulative from ship, so it cannot backfill history. The "safe to delete" clock starts at deploy, which is fine for a migration you are running now.

Leaving this open pending a go on building it.

Colby Knox · 2mo ago

Shipped to prod (registry-side, no client change) as of the deploy a few minutes ago.

What it does

Every 301 served on a retired slug now credits one hit to that slug. Covered redirect paths: the web page route, /api pages, /api packages (+ the /files store), /download, and /blob. A chained rename still credits the slug the caller actually requested (the entry hop), not an intermediate. The counter is best-effort: a write can never break the redirect it measures.

Two columns on each rename alias:

  • hit_count: monotonic total of 301s served on the retired slug
  • last_hit_at: UTC timestamp of the most recent hit (NULL = never)

How to read it

Admin only:

GET /api/admin/redirect-hits            # default 7-day flatline window
GET /api/admin/redirect-hits?window_days=30

Per alias it returns: old_owner/old_slug -> new_owner/new_slug, hit_count, last_hit_at, days_since_last_hit, and flatlined (no hit within window_days). Plus a summary: total_aliases, live, flatlined. Sorted most-recently-hit first, so live retired slugs surface at the top and the cold ones (your delete candidates) sink.

flatlined:true under a 7-day (or longer) window is the provable safe-to-delete signal: the old page and its redirect are unused, delete away.

On prod right now

973 rename aliases. Within seconds of deploy, adom/adom-native-browser and adom/adom-browser-extension already logged live hits, so real fleet traffic is being captured. hd-bootstrap / hd-windows-bootstrap / adom-desktop / step2glb / adom-theme-system are all in the list; watch their hit_count and last_hit_at.

One caveat

The counter starts at zero at this deploy, so it has no history yet. Anything not hit in the last few minutes currently reads last_hit_at:null / flatlined:true, which right now only means "quiet since deploy," not "dead for a week." Give it a real week of accumulation; after that, a still-null or week-old last_hit_at is the true signal.

This is the simple-counter option you offered, and last_hit_at answers "flatlined for a week?" exactly. If you also want the 30-day daily rate series (the migration curve, not just last-hit recency), that is a clean follow-up. Closing as delivered; say the word and I will add the series.

Log in to reply.