Request Routing & Edge Resolution

ELI5

When someone types a short link into their browser, the edge worker acts like a traffic cop. It first checks if the URL looks like a file (has a dot) or a special path — those go straight to the marketing site. Otherwise it looks up the slug in its memory, decides if it should send the user straight to the destination or hide the destination behind a proxy, and then either redirects or serves the content.

Technical Deep Dive

Routing Decision Tree

zoomies-edge runs a deterministic decision tree on every incoming GET request:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8f4f8', 'primaryTextColor': '#2d3748', 'primaryBorderColor': '#90cdf4', 'lineColor': '#718096', 'secondaryColor': '#f0fff4', 'tertiaryColor': '#fefcbf'}}}%%
flowchart TD
    A[Incoming Request<br/>smo1.io/:slug] --> B{Slug contains dots<br/>or starts with _ ?}
    B -->|Yes| C[Proxy to<br/>whiskers-landing]
    B -->|No| D{Is it a<br/>known link slug?}
    D -->|No| C
    D -->|Yes| E{Link mode?}
    E -->|redirect| F[Append UTM params<br/>Return 302]
    E -->|proxy| G[Reverse-proxy to<br/>destination URL]
    F --> H[Browser follows<br/>redirect]
    G --> I[Response streams<br/>through Worker]
    C --> J[whiskers-landing<br/>serves page]

Slug Lookup Order

1. Cloudflare KV — check link:{slug} key first (sub-millisecond, no origin round-trip)
2. purr-api fallback — GET /api/links/slug/:slug (only on cache miss)
3. Cache write-back — store result in KV with 5-minute TTL (expirationTtl: 300)

If the slug is not found in either layer, the worker treats the path as a landing-page route and proxies to LANDING_ORIGIN (origin.smo1.io). This is why /about, /pricing, and unknown slugs all serve the marketing site.

Proxy vs. Redirect Mode

In proxy mode:

• Path segments are rewritten (/slug/dashboard → /dashboard on destination)
• Location headers are rewritten to maintain the slug prefix
• Set-Cookie domains are stripped to scope cookies to smo1.io
• The Worker uses redirect: 'manual' so it handles 3xx responses itself rather than letting the runtime follow them

Code Path (zoomies-edge)

// Simplified pseudocode of src/index.ts routing
if (slug.includes('.') || slug.startsWith('_')) {
  return proxyToLanding(request);   // static assets
}

const link = await resolveLink(slug);  // KV → API fallback
if (!link) {
  return proxyToLanding(request);   // /about, /pricing, 404 slugs
}

if (link.redirectMode === 'proxy') {
  return handleProxy(request, link);
}

return handleRedirect(request, link);  // 302 + UTM

Key Terms

• KV namespace → Cloudflare KV binding (LINKS_CACHE) used by the edge worker for link lookups
• LANDING_ORIGIN → Environment variable pointing to origin.smo1.io (the unproxied Vercel deployment of whiskers-landing)
• expirationTtl → KV write option setting a 300-second (5-minute) TTL on cached link entries
• redirect: manual → Fetch option that prevents the Workers runtime from automatically following HTTP redirects
• slug → The path segment after the domain (smo1.io/abc123 → abc123)

Q&A

Q: Why do slugs with dots go straight to the landing page? A: Static assets (images, fonts, .well-known files) contain dots. Routing them to the link lookup would cause unnecessary KV/API calls and false 404s.

Q: What happens if purr-api is down and the slug is not in KV? A: The worker falls back to proxying the request to whiskers-landing. The user sees the marketing site instead of a hard error — graceful degradation.

Q: Can a slug collide with a landing page route? A: Yes, but landing page routes are predictable (e.g., /about, /pricing). Slugs are 6-character random alphanumeric strings, making accidental collisions statistically negligible.

Q: Why is the landing origin origin.smo1.io and not smo1.io? A: Cloudflare proxies smo1.io to the Worker. If the Worker fetched smo1.io, it would call itself in an infinite loop. origin.smo1.io is a DNS record that bypasses the Cloudflare proxy. See smo1-018.

Examples

Think of the edge worker as a hotel concierge:

• A guest asks for “room 404” (a slug) — the concierge checks the room key board (KV), then the front desk computer (API), and hands the guest a map to the room (302 redirect)
• A guest asks for “the gym” (a landing page) — the concierge points them to the hotel amenities brochure (proxy to landing)
• A guest asks for “room-service.menu.pdf” (dot in path) — the concierge knows this is a document, not a room, and sends them to the business centre (landing/static asset)