Cache Manager with Client-Side Cache Control

A utility module for making HTTP requests with sophisticated client-side cache control capabilities. The module should allow clients to specify how they want to use cached responses through request directives.

@generates

Capabilities

Handle max-stale directive

The system should support the max-stale directive, which allows accepting stale cached responses.

• When max-stale is specified without a value, any stale response should be acceptable @test
• When max-stale is specified with a value (e.g., 3600 seconds), responses stale for up to that duration should be acceptable @test
• When a response is expired but within the max-stale threshold, it should be returned from cache @test

Handle min-fresh directive

The system should support the min-fresh directive, which requires cached responses to remain fresh for a specified duration.

• When min-fresh is specified (e.g., 1800 seconds), only responses that will remain fresh for at least that duration should be returned @test
• When a cached response will expire within the min-fresh window, a new request should be made @test

Handle only-if-cached directive

The system should support the only-if-cached directive for offline operation.

• When only-if-cached is specified, no network request should be made if the resource is not in cache @test
• When only-if-cached is specified and a cached response exists, it should be returned regardless of expiration @test

Combine multiple directives

The system should handle combinations of cache control directives.

• When both max-stale and only-if-cached are specified together, the system should return stale cached responses without making network requests @test

API

"""
Cache Manager module for HTTP requests with client-side cache control.

This module provides functionality to make HTTP GET requests with
sophisticated cache control through request directives.
"""

def fetch_with_cache_control(url: str, cache_control: dict) -> dict:
    """
    Fetch a URL with specified client-side cache control directives.

    Args:
        url: The URL to fetch
        cache_control: Dictionary containing cache control directives:
            - 'max_stale': int or True (seconds or unlimited)
            - 'min_fresh': int (seconds)
            - 'only_if_cached': bool

    Returns:
        dict with keys:
            - 'content': Response content (str)
            - 'from_cache': Whether response came from cache (bool)
            - 'age': Age of cached response in seconds (int or None)
            - 'status': HTTP status code or 504 for cache miss with only_if_cached

    Raises:
        ValueError: If cache_control contains invalid directives
    """
    pass

def clear_cache():
    """
    Clear all cached responses.
    """
    pass

def get_cache_info() -> dict:
    """
    Get information about the current cache state.

    Returns:
        dict with keys:
            - 'size': Number of cached responses (int)
            - 'urls': List of cached URLs (list)
    """
    pass

Dependencies { .dependencies }

requests-cache { .dependency }

Provides HTTP caching with Cache-Control support.

@satisfied-by