← knowledge.oriz.in

URL shortener three-tier free stack — s.oriz.in primary, TinyURL fallback, GitHub Gist redirect zero-infra

decision architectureshort-linkcloudflaretinyurlgithub-gistquotamitigationfallback

URL shortener three-tier free stack — s.oriz.in primary, TinyURL fallback, GitHub Gist redirect zero-infra

Decision

The family runs three free URL-shortening tiers, each with a distinct role. All three are free, no card, no quota cliff at family scale.

Tier Service Role When
1 (primary) s.oriz.in CF Worker Self-hosted, branded, edge-cached Default for everything family-owned
2 (fallback) TinyURL API Free unlimited, no auth, no card Outside oriz.in, or s.oriz.in down
3 (zero-infra) GitHub Gist redirect Meta-refresh HTML page, immortal Both above unavailable, or critical immutable redirect

This decision builds on url-shortener-quota-mitigation.md (the cache-the-301 trick) — that decision keeps Tier 1 well inside the free envelope; this decision adds two further-fallback tiers so the surface is robust even if Cloudflare Workers itself is down.

Tier 1 (primary): s.oriz.in self-hosted CF Worker

Already locked at services/business/short-link/cloudflare-worker.md. Mitigation playbook (full detail in url-shortener-quota-mitigation.md):

  1. Edge-cache the 301 itself — Cache-Control: public, max-age=31536000, immutable + CDN-Cache-Control header on the redirect response. CF's edge cache serves repeats; the Worker is not invoked.
  2. Hot keys cached in Workers KV — ~1 ms lookup vs Worker compute path. KV free tier (100K reads/day, 1K writes/day, 1 GiB storage) has orders of magnitude of headroom.
  3. Per-edge POP cache miss math — ~250 CF POPs × 1 cold-miss per slug per year = 250 Worker hits per URL per year. Negligible.
  4. Realistic upper bound at family-wide traffic: ~1-2K Worker req/day (see Quota math below) vs 100K/day free quota — 50x headroom.

When to use: anything chirag127/oriz* originates that benefits from a branded short URL. Default mint surface for oriz-omnipost when a target platform truncates content.

Tier 2 (fallback): TinyURL API

Documented at services/business/short-link/tinyurl.md. Endpoint: https://tinyurl.com/api-create.php?url=<urlencoded>.

When to use:

Tier 3 (zero-infrastructure): GitHub Gist redirect HTML page

Documented at services/business/short-link/github-gist-redirect.md. A Gist hosted at gist.github.com/chirag127/<hash> containing a single HTML file:

<!doctype html>
<meta charset="utf-8">
<title>Redirecting…</title>
<meta http-equiv="refresh" content="0; url=<TARGET>">
<link rel="canonical" href="<TARGET>">
<script>location.replace('<TARGET>')</script>
<p>Redirecting to <a href="<TARGET>"><TARGET></a>…</p>

Rendered via gist.githubusercontent.com/.../raw/<file>.html (the raw URL is served as text/html by GitHub's gist raw endpoint when the file extension is .html).

When to use:

Quota math

Back-of-envelope Tier-1 load at projected family scale:

DAU (family-wide)                : ~1,000
Avg short-link clicks per visit  : ~5
                                  ----
Click events per day              : ~5,000

CF edge cache miss rate (per slug per POP per year):
  Slugs are immutable. After first miss, cached for 1 year.
  Active slugs at family scale: ~500-1,000
  CF POPs (geographic):         ~250
  Cold misses per active slug:   1 per POP per year

  ? ~250 misses × 1,000 slugs / 365 days = ~685 Worker req/day from cold-miss
  ? Add ~500/day from new-slug mints + KV writes
  ? Total: ~1,200 Worker req/day

Free quota                        : 100,000 Worker req/day
                                   ----
Headroom                          : ~83x
% of free envelope used           : ~1.2%

Sits comfortably inside rules/interaction/never-hit-quotas.md even with 10x growth.

Why this layering

Implications

Cross-refs