HTTP Cache Validator

A simple HTTP caching utility that automatically revalidates stale cached responses using conditional requests.

Overview

Build a tool that stores HTTP responses in a cache and automatically revalidates them when they become stale. When a cached response needs revalidation, the tool should send conditional HTTP requests using validator headers to check if the content has changed, allowing efficient bandwidth usage through 304 Not Modified responses.

Capabilities

Store Cached Responses

• Store an HTTP response with URL "https://api.example.com/data", ETag "abc123", Last-Modified "Wed, 21 Oct 2023 07:28:00 GMT", and status 200 in the cache @test
• Store an HTTP response with only ETag "xyz789" without Last-Modified header @test

Generate Conditional Requests

• When revalidating a cached response with ETag "abc123", generate a request with If-None-Match header set to "abc123" @test
• When revalidating a cached response with both ETag "abc123" and Last-Modified "Wed, 21 Oct 2023 07:28:00 GMT", prioritize ETag and set If-None-Match to "abc123" @test
• When revalidating a cached response with only Last-Modified "Wed, 21 Oct 2023 07:28:00 GMT", generate a request with If-Modified-Since set to "Wed, 21 Oct 2023 07:28:00 GMT" @test

Handle 304 Not Modified Responses

• When receiving a 304 response, keep the cached response body and merge new headers from the 304 response @test
• When receiving a 304 response with new ETag "def456", update the cached ETag while preserving the original body @test

Handle Fresh Content Responses

• When receiving a 200 response, replace the entire cached response with the new response data @test

Implementation

@generates

API

from typing import Optional, Dict

class CachedResponse:
    """Represents a cached HTTP response with validators."""
    url: str
    status_code: int
    body: str
    etag: Optional[str]
    last_modified: Optional[str]
    headers: Dict[str, str]

class ConditionalRequest:
    """Represents a conditional HTTP request for revalidation."""
    url: str
    headers: Dict[str, str]

class CacheValidator:
    """HTTP cache validator with conditional request support."""

    def store_response(self, response: CachedResponse) -> None:
        """Store a response in the cache."""
        pass

    def create_conditional_request(self, url: str) -> Optional[ConditionalRequest]:
        """
        Create a conditional request for revalidating a cached response.
        Generates If-None-Match if ETag exists, otherwise If-Modified-Since if Last-Modified exists.
        Returns None if no cached response exists.
        """
        pass

    def handle_revalidation_response(
        self,
        url: str,
        status_code: int,
        body: str,
        headers: Optional[Dict[str, str]] = None
    ) -> CachedResponse:
        """
        Handle revalidation response and update cache.
        For 304: merge headers into cached response, keep original body.
        For 200: replace entire cached response with new data.
        """
        pass

    def get_cached_response(self, url: str) -> Optional[CachedResponse]:
        """Retrieve a cached response by URL."""
        pass

Dependencies { .dependencies }

hishel { .dependency }

Provides HTTP caching with RFC 9111 compliance including conditional request generation and 304 Not Modified handling.

@satisfied-by