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

  1. Client sends GET

    The request identifies a short code, not the destination.

  2. Handler checks the request

    Parse the code and start the request budget.

  3. Optional cache lookup

    Read a destination plus its absolute expiry deadline.

  4. Usable cached record

    Validate the deadline and continue to the response.

  5. Otherwise, persistent lookup

    Establish whether a current, valid record exists.

  6. Valid stored record

    Attempt a bounded cache fill, then recheck validity.

  7. Handler returns 302 and Location

    The client makes a separate request to the destination.

Proposed read path. The decision table below includes the unsuccessful branches.

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-store

RFC 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

Decisions for one proposed redirect request
ObservationNext action or response
Valid cache hitCheck deadline; return 302 without a database read.
Cache miss, timeout, malformed, or expired recordUse the remaining budget for persistent storage.
Database returns a valid recordAttempt cache fill, recheck deadline, return 302.
Database establishes missing or expiredReturn 404.
Required database lookup fails or times outReturn 503; do not report the code as missing.
Cache fill failsRecord 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.destination

For 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.