URL_shortener_functional.md

ID	Requirement	Key Details & Acceptance Criteria
FR-1	Redirection	Service must redirect /{shortCode} to its target URL. • Returns 200/301/302 as configured. • No body on 301/302. • Preserves UTM/query unless configured to strip.
FR-2	Deduplication (Per User)	If the same user shortens the same normalized URL, return the existing short code. Normalization: scheme-insensitive (optionally force https), strip trailing slash, default ports, ordered query params, punycode for IDNs. Acceptance: identical shortCode for same user+URL; different users may get different codes.
FR-3	Default TTL	New links default to 1-year expiry. Acceptance: after created_at + 365 days, redirect returns 404/410 (per config).
FR-4	Custom TTL	Client may override TTL at creation; min 1 h, max 2 y (configurable). Acceptance: expires exactly at created_at + ttl.
FR-5	Short-Code Generation	URL-safe, case-sensitive codes (Base62/Base64URL), length 6-10 (configurable). Avoid collisions; retry on conflict. Acceptance: collision rate ≤ 10⁻⁹; codes match regex ^[A-Za-z0-9_-]{6,10}$ (or chosen alphabet).
FR-6	Purge from Operational Store	Expired links + hot metadata removed ≤ 30 days post-expiry. Optional cold archival (Parquet/Object store) for audit. Acceptance: no expired records older than 30 days in OLTP.
FR-7	Idempotent Create API	POST /links with same (userId, normalizedUrl, ttl) is idempotent via client-supplied key. Acceptance: replays within 24 h return HTTP 200 with original payload.
FR-8	Update & Delete	Update TTL (within bounds) or toggle active/inactive. Delete disables immediately. Acceptance: cache reflects change within ≤ 5 s.
FR-9	Rate Limiting & Abuse Controls	Per-user & per-IP quotas on create/resolve. Blocklisted domains/patterns. Acceptance: configurable; returns 429 on limit exceed.
FR-10	Observability	Structured logs, metrics (QPS, p50/p95/p99, 5xx), distributed traces. Acceptance: dashboards & alerts for all SLIs below.