HTTP Response Cache Filter

A utility that filters HTTP response headers before caching based on Cache-Control directives.

Overview

Build a Python module that implements HTTP response header filtering logic for caching systems. The module should respect Cache-Control directives that specify which headers should not be cached, following RFC 9111 specifications for both shared and private caches.

Capabilities

Parse Cache-Control directives with field names

• Parses no-cache="Authorization, X-Custom" and extracts the list of header names @test
• Parses private="Set-Cookie, X-User-ID" and extracts the list of header names @test
• Handles directives without field names (e.g., no-cache without quotes) by returning an empty list @test

Filter headers for storage based on no-cache directive

• Given response headers {"Content-Type": "text/html", "Authorization": "Bearer token", "Cache-Control": "no-cache=\"Authorization\""}, returns filtered headers without the Authorization header @test
• Given response headers with Cache-Control: no-cache="Set-Cookie, X-Custom", removes both Set-Cookie and X-Custom headers from the result @test
• Given response headers with Cache-Control: no-cache (no field names), returns all headers unchanged @test

Filter headers based on private directive in shared cache mode

• In shared cache mode, given Cache-Control: private="Set-Cookie", removes Set-Cookie from the filtered headers @test
• In shared cache mode, given Cache-Control: private="Set-Cookie, X-User-Data", removes both specified headers @test
• In private cache mode, given Cache-Control: private="Set-Cookie", returns all headers including Set-Cookie (private directives are ignored in private caches) @test

Handle combined directives

• Given Cache-Control: no-cache="Authorization", private="Set-Cookie" in shared cache mode, removes both Authorization and Set-Cookie @test
• Given Cache-Control: no-cache="Authorization", private="Set-Cookie" in private cache mode, removes only Authorization (ignores private directive) @test

Implementation

@generates

API

from typing import Dict, List

def parse_cache_control_field_names(cache_control_value: str, directive: str) -> List[str]:
    """
    Parse field names from a Cache-Control directive.

    Args:
        cache_control_value: The value of the Cache-Control header
        directive: The directive to extract field names from ('no-cache' or 'private')

    Returns:
        List of header field names specified in the directive, or empty list if none specified
    """
    pass

def filter_headers_for_cache(
    headers: Dict[str, str],
    is_shared_cache: bool = False
) -> Dict[str, str]:
    """
    Filter response headers based on Cache-Control directives before storing in cache.

    Removes headers specified in:
    - no-cache directive field names (both shared and private caches)
    - private directive field names (only in shared caches)

    Args:
        headers: Dictionary of HTTP response headers (case-insensitive keys)
        is_shared_cache: True for shared caches (proxy, CDN), False for private caches (browser)

    Returns:
        Filtered dictionary of headers suitable for caching
    """
    pass

Dependencies { .dependencies }

hishel { .dependency }

Provides HTTP caching functionality and Cache-Control parsing capabilities.