System design / Lesson 2
Trace the request flow
Follow a redirect from client to cache and database, including expiry checks and dependency failures.
Follow one request
A component diagram shows what exists. A request flow shows what each component must do, in order, for one person to get a result. Begin with a single GET /k7m2q. Draw the successful path, then interrupt each dependency and ask what the handler can still know.
We continue the illustrative URL shortener from the requirements lesson: generated immutable codes, optional absolute expiry, and no editing or revocation in the first version. Valid codes return 302; missing or expired codes return 404. A required database lookup that fails returns 503. These are proposed policies, not observed repository behavior.
Before reaching the handler, a browser may resolve the hostname and establish a connection with TLS. Existing connections and cached DNS results can skip some setup. These steps affect user latency, but the handler’s dependency budget begins when the application receives the request. Keep that boundary clear when comparing timings.
Draw the boundaries
- Client sends GET
The request identifies a short code, not the destination.
- Handler checks the request
Parse the code and start the request budget.
- Optional cache lookup
Read a destination plus its absolute expiry deadline.
- Usable cached record
Validate the deadline and continue to the response.
- Otherwise, persistent lookup
Establish whether a current, valid record exists.
- Valid stored record
Attempt a bounded cache fill, then recheck validity.
- Handler returns 302 and Location
The client makes a separate request to the destination.
The service returns a destination; it does not fetch that page. Store the authoritative mapping before acknowledging POST /links creation. A later cache fill is disposable. A successful cache write cannot substitute for a committed database record.
GET /k7m2q HTTP/1.1
Host: short.example
HTTP/1.1 302 Found
Location: https://example.org/guide
Cache-Control: no-storeRFC 9110 describes 302 and Location. Here, propose Cache-Control: no-store on redirect and error responses so cooperating HTTP caches do not bypass future application checks. This HTTP cache policy is separate from the service’s internal cache.
Name every outcome
| Observation | Next action or response |
|---|---|
| Valid cache hit | Check deadline; return 302 without a database read. |
| Cache miss, timeout, malformed, or expired record | Use the remaining budget for persistent storage. |
| Database returns a valid record | Attempt cache fill, recheck deadline, return 302. |
| Database establishes missing or expired | Return 404. |
| Required database lookup fails or times out | Return 503; do not report the code as missing. |
| Cache fill fails | Record the failure; a still-valid record can return 302. |
“Cache error” and “database error” have different consequences. A cache is optional in this design. If the database remains available, the request can still succeed. If a valid cache hit already supplies the answer, this design does not consult the database.
Startup needs a separate decision: this proposal allows serving when the cache is unavailable, provided storage is ready. Request-time fallback alone does not guarantee that behavior. The optional Go case study has its own startup constraint and should not be read as implementing this HTTP contract.
Preserve validity
Every usable record must carry the destination and optional expires_at. Validate the deadline after retrieving either copy. A check at the exact deadline rejects the link: validity requires the current time to be strictly before the deadline. Recheck immediately before issuing the redirect if intervening work could cross that boundary.
record = read_optional_cache(code)
if record is unusable:
record = read_persistent_store(code)
if lookup failed: return 503
if missing: return 404
validate absolute deadline
if expired: return 404
attempt bounded cache fill; record failures
validate record again immediately before responding
if expired: return 404
return 302 with Location = record.destinationFor illustration, cap internal cache retention at five minutes and at the remaining business lifetime. Skip writes when no positive lifetime remains. That reduces stale retention; the deadline check still enforces validity. A response can arrive after expiry because the network takes time. The promise concerns the service’s final validity decision.
Expiry checks do not solve every consistency problem. This first scope keeps destinations and deadlines immutable and never reuses codes. If someone deletes or changes a database row outside that contract, an existing cache entry can still redirect until its retention ends. A five-minute cap bounds that exposure only when every write has that cap and reads never extend it. Immediate revocation would need a stronger design, such as authoritative revalidation or a coordinated invalidation policy. Later lessons can expand the scope.
Bound the work
A fallback that waits forever is not useful. As illustrative limits, allow 100 ms for application work, with at most 10 ms for cache read, 60 ms for storage, and 5 ms for cache fill, all constrained by the remaining request budget. Leave time for parsing and the response. These limits are design inputs, not measured latency or proof of the earlier p95 target.
In Go, derive work from r.Context(), add a deadline with context.WithTimeout, pass it to context-aware clients, and call the returned cancel function. Cancellation signals work to stop; dependency clients must honor it, and connection and server timeouts still need configuration.
Use no automatic retries initially. Retrying a slow database can multiply load during an outage and spend the response budget twice. Add retries only for a defined transient failure, with a bounded attempt count and shared deadline. Attach a request or trace ID to logs; measure handler latency, response counts, cache outcomes, and database errors. Avoid logging full destinations, which may contain private query data.
Practice
1. Cache lookup times out, but storage returns a valid record. What happens?
Continue within the remaining request budget, attempt only a bounded cache fill, recheck expiry, and return 302. Record the cache failure separately from the successful redirect.
2. The deadline passes during cache fill. Can the handler redirect?
No. The final validity check rejects the record with 404. Cache retention cannot authorize an expired link.
3. A database row is manually deleted while its cache entry remains. Does expiry validation fix it?
No. An unexpired copy can still pass. Deletion or immediate revocation changes the consistency requirement; define its allowed delay and choose a revalidation or invalidation strategy before promising it.