HTTP Cache State Tracker

A diagnostic tool that monitors and reports on HTTP caching behavior by tracking cache state transitions and operations.

Problem Description

Build a cache state tracking system that wraps an HTTP client with caching capabilities and provides detailed insights into caching operations. The system should track when responses are served from cache, when cache misses occur, when revalidation happens, and when responses are stored.

Your implementation should handle multiple caching scenarios including fresh cache hits, cache misses, stale response revalidation, and responses that cannot be cached.

Requirements

Core Functionality

The system must provide:

1. An HTTP client wrapper with built-in caching support that can make GET requests
2. State tracking that captures cache operations (hits, misses, stores, revalidations)
3. A reporting interface that returns cache statistics including:
   • Total requests made
   • Number of cache hits (responses served from cache)
   • Number of cache misses (requests that went to origin)
   • Number of revalidations (stale responses that required checking with origin)
   • Number of responses stored in cache

Behavior Specifications

• When a request is made for the first time, it should result in a cache miss and the response should be stored if cacheable
• When a subsequent request is made for a cached resource with fresh content, it should result in a cache hit
• When a cached resource becomes stale but has revalidation headers, the system should perform revalidation
• The system should correctly identify and track when responses cannot be cached (e.g., no-store directive)
• Statistics should accurately reflect the cumulative behavior across multiple requests

Test Cases

Fresh Cache Hit

• Making two identical requests to a cacheable endpoint results in one cache miss and one cache hit @test

Cache Miss and Store

• The first request to any endpoint results in a cache miss, and if cacheable, the response is stored @test

Revalidation Tracking

• When accessing a stale cached resource that supports revalidation, the system tracks it as a revalidation operation @test

Implementation

@generates

API

class CacheStateTracker:
    """
    Tracks HTTP caching state transitions and operations.
    """

    def __init__(self, base_url: str):
        """
        Initialize the cache state tracker.

        Args:
            base_url: The base URL for HTTP requests
        """
        pass

    def get(self, path: str) -> dict:
        """
        Make a GET request and track caching behavior.

        Args:
            path: The URL path to request

        Returns:
            Response data as a dictionary
        """
        pass

    def get_stats(self) -> dict:
        """
        Get cache statistics.

        Returns:
            Dictionary with keys:
            - total_requests: Total number of requests made
            - cache_hits: Number of responses served from cache
            - cache_misses: Number of requests that went to origin
            - revalidations: Number of stale responses revalidated
            - stored_responses: Number of responses stored in cache
        """
        pass

    def reset_stats(self):
        """
        Reset all statistics to zero.
        """
        pass

Dependencies { .dependencies }

hishel { .dependency }

Provides HTTP caching support with state machine implementation.