CDN Url Refreshing & Multi-layer Caching Design
Co-authored by Claude Sonnet 4.6
Videos, audio, and images in a client app are usually hosted on a CDN (OSS / S3). For auth and hot-link protection, the backend hands out signed, time-limited URLs — a plain GET after expiry returns 403. The tricky part is that the client has no control over when a URL is consumed: a user might tap a thumbnail right away, or scroll back to an old message a week later and only then start playback.
To handle this we introduced a resourceUrlExchange endpoint that swaps an “original URL” for “a signed URL that’s valid right now” before downloading or playing. But if every playback or render calls the endpoint, a list view easily fires dozens of concurrent requests, blocking first paint and burning bandwidth. This post walks through the five layers we built around that problem, and how they compose into a nearly transparent caching pipeline.
The snippets below happen to use a Flutter idiom, but the design itself is platform-agnostic — the same layering maps cleanly onto iOS, Android, Web, or RN clients; only the package names change.




