HTTP Cache with Time-to-Live Management

Build a simple HTTP caching system that stores responses with configurable time-to-live (TTL) policies. The system should support both fixed expiration (TTL counted from creation time) and sliding expiration (TTL resets on each access).

Requirements

Core Functionality

The cache should store HTTP responses and automatically expire entries based on TTL settings. Implement a storage backend that:

1. Stores cache entries with request/response data and timestamps
2. Checks TTL on retrieval and returns None for expired entries
3. Supports default TTL configuration at storage creation
4. Allows per-entry TTL override
5. Supports both fixed and sliding expiration modes

Fixed vs Sliding Expiration

• Fixed expiration: TTL is counted from when the entry was created. Accessing an entry does not extend its lifetime.
• Sliding expiration: TTL resets each time an entry is accessed. The entry stays alive as long as it's accessed within the TTL window.

Test Cases

• Creating a cache entry with default TTL of 10 seconds stores the entry and retrieves it successfully before expiration @test
• Creating a cache entry with default TTL of 1 second returns None when retrieved after 2 seconds (entry expired) @test
• Creating an entry with per-entry TTL override of 5 seconds (when default is 10) expires after 5 seconds, not 10 @test
• With sliding expiration enabled, an entry with 3-second TTL remains valid after 5 seconds if accessed every 2 seconds @test
• With fixed expiration (default), an entry with 3-second TTL expires after 3 seconds even if accessed multiple times @test

Implementation

@generates

API

from typing import Optional, Any
from datetime import datetime

class CacheEntry:
    """Represents a cached HTTP response with metadata."""
    def __init__(self, key: str, data: Any, created_at: datetime):
        self.key = key
        self.data = data
        self.created_at = created_at

class CacheStorage:
    """
    Storage backend for HTTP cache entries with TTL management.

    Args:
        default_ttl: Default time-to-live in seconds for cache entries.
                    None means entries never expire.
        refresh_ttl_on_access: If True, enables sliding expiration (TTL resets on access).
                              If False (default), uses fixed expiration.
    """
    def __init__(self, default_ttl: Optional[int] = None, refresh_ttl_on_access: bool = False):
        pass

    def store(self, key: str, data: Any, ttl_override: Optional[int] = None) -> None:
        """
        Store a cache entry.

        Args:
            key: Unique identifier for the cache entry
            data: The data to cache (typically an HTTP response)
            ttl_override: Optional TTL in seconds that overrides default_ttl for this entry
        """
        pass

    def retrieve(self, key: str) -> Optional[CacheEntry]:
        """
        Retrieve a cache entry if it exists and hasn't expired.

        Args:
            key: Unique identifier for the cache entry

        Returns:
            The CacheEntry if found and not expired, None otherwise.
            For sliding expiration, this access updates the entry's timestamp.
        """
        pass

Dependencies { .dependencies }

hishel { .dependency }

Provides HTTP caching support with TTL management capabilities.

@satisfied-by