HTTP Cache Proxy with Stale Response Handling

Build an HTTP cache proxy that intelligently handles stale cached responses according to HTTP caching specifications. The proxy should support configurable staleness policies while respecting cache control directives that prohibit serving stale content.

Requirements

Your implementation should provide a cache proxy that:

1. Caches HTTP responses from upstream servers with configurable time-to-live (TTL)
2. Serves stale responses when the cached content has expired, but only when allowed by configuration and cache directives
3. Respects directive prohibitions that prevent stale content from being served, even when staleness is generally allowed
4. Supports multiple HTTP methods for caching (at minimum: GET and HEAD)

Functional Specifications

Stale Response Behavior

The cache proxy should determine whether to serve stale content based on:

• A configuration flag that enables or disables stale response serving
• Cache-Control directives in the cached response that prohibit stale serving
• The freshness lifetime of the cached response

When stale serving is enabled by configuration:

• Serve expired cached responses unless prohibited by directives
• When stale serving is prohibited by directives, always revalidate or fetch fresh content

When stale serving is disabled by configuration:

• Never serve expired cached responses
• Always revalidate or fetch fresh content when cache is stale

Directive Prohibitions

Your implementation must recognize and enforce these directives that prohibit serving stale content:

• no-cache: Requires revalidation before serving
• must-revalidate: Requires revalidation when stale
• proxy-revalidate: Requires revalidation when stale (for shared caches)

If any of these directives are present in a cached response's Cache-Control header, the cache must not serve the stale response without revalidation, regardless of the stale-serving configuration.

Cache Key Generation

• Use the request URL as the cache key
• Support caching for GET and HEAD methods

Response Metadata

Track whether responses were served from cache by including metadata with each response.

Test Cases

Basic stale serving { .test-case }

• Given a cache configured to allow stale responses @test
• When a response is cached with Cache-Control: max-age=10 and the cache expires after 15 seconds @test
• Then the stale cached response should be served without revalidation @test

Stale serving disabled { .test-case }

• Given a cache configured to disallow stale responses @test
• When a response is cached with Cache-Control: max-age=10 and the cache expires after 15 seconds @test
• Then the cache should fetch fresh content from the upstream server @test

no-cache directive prohibition { .test-case }

• Given a cache configured to allow stale responses @test
• When a response is cached with Cache-Control: max-age=10, no-cache and the cache expires after 15 seconds @test
• Then the cache should revalidate or fetch fresh content, not serve the stale response @test

must-revalidate directive prohibition { .test-case }

• Given a cache configured to allow stale responses @test
• When a response is cached with Cache-Control: max-age=10, must-revalidate and the cache expires after 15 seconds @test
• Then the cache should revalidate or fetch fresh content, not serve the stale response @test

proxy-revalidate directive prohibition for shared cache { .test-case }

• Given a shared cache configured to allow stale responses @test
• When a response is cached with Cache-Control: max-age=10, proxy-revalidate and the cache expires after 15 seconds @test
• Then the cache should revalidate or fetch fresh content, not serve the stale response @test

Implementation Notes

• Create a test file named test_stale_cache.py containing all test cases
• Use appropriate assertions to verify cache behavior
• Mock or simulate time passage for testing expiration scenarios
• Mock upstream server responses for testing

Dependencies { .dependencies }

hishel { .dependency }

Provides HTTP caching capabilities with RFC 9111 compliance, including stale response handling and cache control directive parsing.

API Expectations

Your implementation should demonstrate proper usage of cache configuration and policy mechanisms. The solution should be concise and leverage the caching library's built-in capabilities for staleness checking and directive handling.

@generates