hishel 1.0.0.dev2__py3-none-any.whl → 1.0.0.dev3__py3-none-any.whl

hishel/asgi.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import logging
+import typing as t
+from email.utils import formatdate
+from typing import AsyncIterator
+
+from hishel import AsyncBaseStorage, CacheOptions, Headers, Request, Response
+from hishel._async_cache import AsyncCacheProxy
+
+# Configure logger for this module
+logger = logging.getLogger(__name__)
+
+
+class _ASGIScope(t.TypedDict, total=False):
+    """ASGI HTTP scope type."""
+
+    type: str
+    asgi: dict[str, str]
+    http_version: str
+    method: str
+    scheme: str
+    path: str
+    query_string: bytes
+    root_path: str
+    headers: list[tuple[bytes, bytes]]
+    server: tuple[str, int | None] | None
+    client: tuple[str, int] | None
+    state: dict[str, t.Any]
+    extensions: dict[str, t.Any]
+
+
+_Scope = _ASGIScope
+_Receive = t.Callable[[], t.Awaitable[dict[str, t.Any]]]
+_Send = t.Callable[[dict[str, t.Any]], t.Awaitable[None]]
+_ASGIApp = t.Callable[[_Scope, _Receive, _Send], t.Awaitable[None]]
+
+
+class ASGICacheMiddleware:
+    """
+    ASGI middleware that provides HTTP caching capabilities.
+
+    This middleware intercepts HTTP requests and responses, caching them
+    according to HTTP caching specifications (RFC 9111) or custom rules.
+
+    The middleware uses async iterators for request and response bodies,
+    ensuring memory-efficient streaming without loading entire payloads
+    into memory. This is particularly important for large file uploads
+    or downloads.
+
+    This implementation is thread-safe by creating a new cache proxy for
+    each request with closures that capture the request context.
+
+    Args:
+        app: The ASGI application to wrap.
+        storage: The storage backend to use for caching. Defaults to AsyncSqliteStorage.
+        cache_options: Configuration options for caching behavior.
+        ignore_specification: If True, bypasses HTTP caching rules and caches all responses.
+
+    Example:
+        ```python
+        from hishel.asgi import ASGICacheMiddleware
+        from hishel import AsyncSqliteStorage, CacheOptions
+
+        # Wrap your ASGI app
+        app = ASGICacheMiddleware(
+            app=my_asgi_app,
+            storage=AsyncSqliteStorage(),
+            cache_options=CacheOptions(),
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        app: _ASGIApp,
+        storage: AsyncBaseStorage | None = None,
+        cache_options: CacheOptions | None = None,
+        ignore_specification: bool = False,
+    ) -> None:
+        self.app = app
+        self.storage = storage
+        self._cache_options = cache_options
+        self._ignore_specification = ignore_specification
+
+        logger.info(
+            "Initialized ASGICacheMiddleware with storage=%s, ignore_specification=%s",
+            type(storage).__name__ if storage else "None",
+            ignore_specification,
+        )
+
+    async def __call__(self, scope: _Scope, receive: _Receive, send: _Send) -> None:
+        """
+        Handle an ASGI request.
+
+        Args:
+            scope: The ASGI scope dictionary.
+            receive: The ASGI receive callable.
+            send: The ASGI send callable.
+        """
+        # Only handle HTTP requests
+        if scope["type"] != "http":
+            logger.debug("Skipping non-HTTP request: type=%s", scope["type"])
+            await self.app(scope, receive, send)
+            return
+
+        method = scope.get("method", "UNKNOWN")
+        path = scope.get("path", "/")
+        query_string = scope.get("query_string", b"").decode("latin1")
+        full_path = f"{path}?{query_string}" if query_string else path
+
+        logger.debug("Incoming HTTP request: method=%s path=%s", method, full_path)
+
+        try:
+            # Create a closure that captures scope and receive for this specific request
+            # This makes the code thread-safe by avoiding shared instance state
+            async def send_request_to_app(request: Request) -> Response:
+                """
+                Send a request to the wrapped ASGI application and return the response.
+                This closure captures 'scope' and 'receive' from the outer function scope.
+                """
+                logger.debug("Sending request to wrapped application: url=%s", request.url)
+
+                # Create a buffered receive callable that replays the request body from the stream
+                body_iterator = request.aiter_stream()
+                body_exhausted = False
+                bytes_received = 0
+
+                async def inner_receive() -> dict[str, t.Any]:
+                    nonlocal body_exhausted, bytes_received
+                    if body_exhausted:
+                        return {"type": "http.disconnect"}
+
+                    try:
+                        chunk = await body_iterator.__anext__()
+                        bytes_received += len(chunk)
+                        logger.debug("Received request body chunk: size=%d bytes", len(chunk))
+                        return {
+                            "type": "http.request",
+                            "body": chunk,
+                            "more_body": True,
+                        }
+                    except StopAsyncIteration:
+                        body_exhausted = True
+                        logger.debug(
+                            "Request body fully consumed: total_bytes=%d",
+                            bytes_received,
+                        )
+                        return {
+                            "type": "http.request",
+                            "body": b"",
+                            "more_body": False,
+                        }
+
+                # Collect response from the app
+                response_started = False
+                status_code = 200
+                response_headers: list[tuple[bytes, bytes]] = []
+                response_body_chunks: list[bytes] = []
+                bytes_sent = 0
+
+                async def inner_send(message: dict[str, t.Any]) -> None:
+                    nonlocal response_started, status_code, response_headers, bytes_sent
+                    if message["type"] == "http.response.start":
+                        response_started = True
+                        status_code = message["status"]
+                        response_headers = message.get("headers", [])
+                        logger.debug("Application response started: status=%d", status_code)
+                    elif message["type"] == "http.response.body":
+                        body_chunk = message.get("body", b"")
+                        if body_chunk:
+                            response_body_chunks.append(body_chunk)
+                            bytes_sent += len(body_chunk)
+                            logger.debug(
+                                "Received response body chunk: size=%d bytes",
+                                len(body_chunk),
+                            )
+
+                try:
+                    # Call the wrapped application with captured scope
+                    await self.app(scope, inner_receive, inner_send)
+                    logger.info(
+                        "Application response complete: status=%d total_bytes=%d chunks=%d",
+                        status_code,
+                        bytes_sent,
+                        len(response_body_chunks),
+                    )
+                except Exception as e:
+                    logger.error(
+                        "Error calling wrapped application: url=%s error=%s",
+                        request.url,
+                        str(e),
+                        exc_info=True,
+                    )
+                    raise
+
+                # Convert to internal Response
+                headers_dict = {key.decode("latin1"): value.decode("latin1") for key, value in response_headers}
+
+                # Add Date header if not present
+                if not any(key.lower() == "date" for key in headers_dict.keys()):
+                    date_header = formatdate(timeval=None, localtime=False, usegmt=True)
+                    headers_dict["Date"] = date_header
+                    logger.debug("Added Date header to response: %s", date_header)
+
+                async def response_stream() -> AsyncIterator[bytes]:
+                    for chunk in response_body_chunks:
+                        yield chunk
+
+                return Response(
+                    status_code=status_code,
+                    headers=Headers(headers_dict),
+                    stream=response_stream(),
+                    metadata={},
+                )
+
+            # Create a new cache proxy for this request with the closure
+            # This ensures complete isolation between concurrent requests
+            cache_proxy = AsyncCacheProxy(
+                request_sender=send_request_to_app,
+                storage=self.storage,
+                cache_options=self._cache_options,
+                ignore_specification=self._ignore_specification,
+            )
+
+            # Convert ASGI request to internal Request (using async iterator, not reading into memory)
+            request = self._asgi_to_internal_request(scope, receive)
+            logger.debug("Converted ASGI request to internal format: url=%s", request.url)
+
+            # Handle request through cache proxy
+            logger.debug("Handling request through cache proxy")
+            response = await cache_proxy.handle_request(request)
+
+            logger.info(
+                "Request processed: method=%s path=%s status=%d",
+                method,
+                full_path,
+                response.status_code,
+            )
+
+            # Send the cached or fresh response
+            await self._send_internal_response(response, send)
+            logger.debug("Response sent successfully")
+
+        except Exception as e:
+            logger.error(
+                "Error processing request: method=%s path=%s error=%s",
+                method,
+                full_path,
+                str(e),
+                exc_info=True,
+            )
+            raise
+
+    def _asgi_to_internal_request(self, scope: _Scope, receive: _Receive) -> Request:
+        """
+        Convert an ASGI HTTP scope to an internal Request object.
+
+        Args:
+            scope: The ASGI scope dictionary.
+            receive: The ASGI receive callable.
+
+        Returns:
+            The internal Request object.
+        """
+        # Build URL
+        scheme = scope.get("scheme", "http")
+        server = scope.get("server")
+
+        if server is None:
+            server = ("localhost", 80)
+            logger.debug("No server info in scope, using default: localhost:80")
+
+        host = server[0]
+        port = server[1] if server[1] is not None else (443 if scheme == "https" else 80)
+
+        # Add port to host if non-standard
+        if (scheme == "http" and port != 80) or (scheme == "https" and port != 443):
+            host = f"{host}:{port}"
+
+        path = scope.get("path", "/")
+        query_string = scope.get("query_string", b"")
+        if query_string:
+            path = f"{path}?{query_string.decode('latin1')}"
+
+        url = f"{scheme}://{host}{path}"
+        method = scope.get("method", "GET")
+
+        # Extract headers
+        headers_dict = {key.decode("latin1"): value.decode("latin1") for key, value in scope.get("headers", [])}
+
+        logger.debug(
+            "Building internal request: method=%s url=%s headers_count=%d",
+            method,
+            url,
+            len(headers_dict),
+        )
+
+        # Create async iterator for request body that reads from ASGI receive
+        async def request_stream() -> AsyncIterator[bytes]:
+            while True:
+                message = await receive()
+                if message["type"] == "http.request":
+                    body = message.get("body", b"")
+                    if body:
+                        yield body
+                    if not message.get("more_body", False):
+                        break
+                elif message["type"] == "http.disconnect":
+                    logger.debug("Client disconnected during request body streaming")
+                    break
+
+        return Request(
+            method=method,
+            url=url,
+            headers=Headers(headers_dict),
+            stream=request_stream(),
+            # Metadatas don't make sense in ASGI scope, so we leave it empty
+            metadata={},
+        )
+
+    async def _send_internal_response(self, response: Response, send: _Send) -> None:
+        """
+        Send an internal Response to the ASGI send callable.
+
+        Args:
+            response: The internal Response object.
+            send: The ASGI send callable.
+        """
+        logger.debug(
+            "Sending response to client: status=%d headers_count=%d",
+            response.status_code,
+            len(response.headers),
+        )
+
+        # Convert headers to ASGI format
+        headers: list[tuple[bytes, bytes]] = [
+            (key.encode("latin1"), value.encode("latin1")) for key, value in response.headers.items()
+        ]
+
+        try:
+            # Send response.start
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": response.status_code,
+                    "headers": headers,
+                }
+            )
+            logger.debug("Response headers sent")
+
+            # Send response body in chunks
+            bytes_sent = 0
+            chunk_count = 0
+            async for chunk in response.aiter_stream():
+                await send(
+                    {
+                        "type": "http.response.body",
+                        "body": chunk,
+                        "more_body": True,
+                    }
+                )
+                bytes_sent += len(chunk)
+                chunk_count += 1
+                logger.debug("Sent response chunk: size=%d bytes", len(chunk))
+
+            # Send final empty chunk to signal end
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": b"",
+                    "more_body": False,
+                }
+            )
+            logger.info(
+                "Response fully sent: status=%d total_bytes=%d chunks=%d",
+                response.status_code,
+                bytes_sent,
+                chunk_count,
+            )
+
+        except Exception as e:
+            logger.error(
+                "Error sending response: status=%d error=%s",
+                response.status_code,
+                str(e),
+                exc_info=True,
+            )
+            raise
+
+    async def aclose(self) -> None:
+        """Close the storage backend and release resources."""
+        logger.info("Closing ASGICacheMiddleware and storage backend")
+        try:
+            if self.storage:
+                await self.storage.close()
+                logger.info("Storage backend closed successfully")
+        except Exception as e:
+            logger.error("Error closing storage backend: %s", str(e), exc_info=True)
+            raise

hishel/fastapi.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import typing as t
+
+from hishel._utils import generate_http_date
+
+try:
+    import fastapi
+except ImportError as e:
+    raise ImportError(
+        "fastapi is required to use hishel.fastapi module. "
+        "Please install hishel with the 'fastapi' extra, "
+        "e.g., 'pip install hishel[fastapi]'."
+    ) from e
+
+
+def cache(
+    *,
+    max_age: int | None = None,
+    s_maxage: int | None = None,
+    public: bool = False,
+    private: bool | list[str] = False,
+    no_cache: bool | list[str] = False,
+    no_store: bool = False,
+    no_transform: bool = False,
+    must_revalidate: bool = False,
+    must_understand: bool = False,
+    proxy_revalidate: bool = False,
+    immutable: bool = False,
+    stale_while_revalidate: int | None = None,
+    stale_if_error: int | None = None,
+) -> t.Any:
+    """
+    Add HTTP Cache-Control headers to FastAPI responses.
+
+    This function provides a convenient way to set cache control directives
+    on FastAPI responses according to RFC 9111 (HTTP Caching) and related standards.
+
+    Args:
+        max_age: Maximum time in seconds a response can be cached.
+            [RFC 9111, Section 5.2.2.1]
+            Example: max_age=3600 sets "Cache-Control: max-age=3600"
+            Use for both private and shared caches.
+
+        s_maxage: Maximum time in seconds for shared caches (proxies, CDNs).
+            [RFC 9111, Section 5.2.2.10]
+            Overrides max_age for shared caches only.
+            Example: s_maxage=7200 sets "s-maxage=7200"
+            Private caches (browsers) ignore this directive.
+
+        public: Marks response as cacheable by any cache.
+            [RFC 9111, Section 5.2.2.9]
+            Explicitly allows caching even if Authorization header is present.
+            Example: public=True adds "public" to Cache-Control
+
+        private: Marks response as cacheable only by private caches (browsers).
+            [RFC 9111, Section 5.2.2.7]
+            Shared caches (proxies, CDNs) MUST NOT store the response.
+            Can be True (applies to entire response) or a list of field names
+            (applies only to specific headers).
+            Examples:
+                - private=True adds "private" to Cache-Control
+                - private=["Set-Cookie"] adds 'private="Set-Cookie"' to Cache-Control
+            Useful for user-specific data.
+
+        no_cache: Response can be cached but MUST be revalidated before use.
+            [RFC 9111, Section 5.2.2.4]
+            Cache MUST check with origin server before serving cached copy.
+            Can be True (requires revalidation for entire response) or a list
+            of field names (requires revalidation only for specific headers).
+            Examples:
+                - no_cache=True adds "no-cache" to Cache-Control
+                - no_cache=["Set-Cookie", "Authorization"] adds 'no-cache="Set-Cookie, Authorization"'
+            Different from no_store - allows caching with mandatory validation.
+
+        no_store: Response MUST NOT be stored in any cache.
+            [RFC 9111, Section 5.2.2.5]
+            Most restrictive directive - prevents all caching.
+            Example: no_store=True adds "no-store" to Cache-Control
+            Use for sensitive data (passwords, personal information).
+
+        no_transform: Prohibits any transformations to the response.
+            [RFC 9111, Section 5.2.2.6]
+            Prevents proxies from modifying content (compression, format conversion).
+            Example: no_transform=True adds "no-transform" to Cache-Control
+
+        must_revalidate: Cache MUST revalidate stale responses.
+            [RFC 9111, Section 5.2.2.2]
+            Prevents serving stale content even if client accepts it.
+            Example: must_revalidate=True adds "must-revalidate" to Cache-Control
+            Stronger than no-cache - applies only when response becomes stale.
+
+        must_understand: Cache MUST understand response status code to cache it.
+            [RFC 9111, Section 5.2.2.3]
+            Prevents caching of responses with unknown status codes.
+            Example: must_understand=True adds "must-understand" to Cache-Control
+
+        proxy_revalidate: Like must_revalidate but only for shared caches.
+            [RFC 9111, Section 5.2.2.8]
+            Shared caches MUST revalidate stale responses.
+            Private caches can serve stale content without revalidation.
+            Example: proxy_revalidate=True adds "proxy-revalidate" to Cache-Control
+
+        immutable: Response body will never change.
+            [RFC 8246]
+            Optimization hint that revalidation is unnecessary during freshness period.
+            Example: immutable=True adds "immutable" to Cache-Control
+            Useful for versioned assets (e.g., /static/app.v123.js)
+
+        stale_while_revalidate: Allow stale response while revalidating in background.
+            [RFC 5861, Section 3]
+            Time in seconds cache can serve stale content while fetching fresh copy.
+            Example: stale_while_revalidate=86400 adds "stale-while-revalidate=86400"
+            Improves performance by avoiding cache misses.
+
+        stale_if_error: Allow stale response if origin server returns error.
+            [RFC 5861, Section 4]
+            Time in seconds cache can serve stale content when origin is unavailable.
+            Example: stale_if_error=3600 adds "stale-if-error=3600"
+            Improves availability during server failures.
+
+    Returns:
+        A dependency function that adds Cache-Control headers to the response.
+
+    Examples:
+        >>> from fastapi import FastAPI
+        >>> from hishel.fastapi import cache
+        >>>
+        >>> app = FastAPI()
+        >>>
+        >>> # Static assets - cache for 1 year, immutable
+        >>> @app.get("/static/logo.png")
+        >>> async def get_logo(
+        ...     _: None = cache(max_age=31536000, public=True, immutable=True)
+        ... ):
+        ...     return {"image": "logo.png"}
+        >>>
+        >>> # API endpoint - cache for 5 minutes, private
+        >>> @app.get("/api/user/profile")
+        >>> async def get_profile(
+        ...     _: None = cache(max_age=300, private=True)
+        ... ):
+        ...     return {"name": "John"}
+        >>>
+        >>> # CDN with shared cache - different TTLs for browsers and proxies
+        >>> @app.get("/api/public/data")
+        >>> async def get_data(
+        ...     _: None = cache(max_age=300, s_maxage=3600, public=True)
+        ... ):
+        ...     return {"data": "public"}
+        >>>
+        >>> # Sensitive data - no caching
+        >>> @app.get("/api/secrets")
+        >>> async def get_secrets(
+        ...     _: None = cache(no_store=True)
+        ... ):
+        ...     return {"secret": "value"}
+        >>>
+        >>> # Cacheable but must revalidate
+        >>> @app.get("/api/critical")
+        >>> async def get_critical(
+        ...     _: None = cache(max_age=3600, must_revalidate=True)
+        ... ):
+        ...     return {"critical": "data"}
+        >>>
+        >>> # Stale-while-revalidate for better performance
+        >>> @app.get("/api/news")
+        >>> async def get_news(
+        ...     _: None = cache(max_age=300, stale_while_revalidate=86400, public=True)
+        ... ):
+        ...     return {"news": "articles"}
+        >>>
+        >>> # Private directive with specific field names
+        >>> @app.get("/api/user/data")
+        >>> async def get_user_data(
+        ...     _: None = cache(max_age=600, private=["Set-Cookie"])
+        ... ):
+        ...     return {"data": "user_specific"}
+        >>>
+        >>> # No-cache with field names - revalidate only specific headers
+        >>> @app.get("/api/conditional")
+        >>> async def get_conditional(
+        ...     _: None = cache(max_age=3600, no_cache=["Set-Cookie", "Authorization"])
+        ... ):
+        ...     return {"data": "conditional_cache"}
+
+    Notes:
+        - Conflicting directives (e.g., public and private) will both be set.
+          Choose appropriate combinations based on your caching strategy.
+        - no_store is the strongest directive and prevents all caching.
+        - For CDNs, use s_maxage to set different TTLs for proxies vs browsers.
+        - Use immutable with versioned URLs for maximum cache efficiency.
+        - Combine stale_while_revalidate with max_age for better UX.
+        - private and no_cache can accept field names to apply directives
+          selectively to specific headers rather than the entire response.
+
+    See Also:
+        - RFC 9111: HTTP Caching (https://www.rfc-editor.org/rfc/rfc9111.html)
+        - RFC 8246: HTTP Immutable Responses (https://www.rfc-editor.org/rfc/rfc8246.html)
+        - RFC 5861: HTTP Cache-Control Extensions (https://www.rfc-editor.org/rfc/rfc5861.html)
+    """
+
+    def add_cache_headers(response: fastapi.Response) -> t.Any:
+        """Add Cache-Control headers to the response."""
+        directives: list[str] = []
+
+        # IMPORTANT
+        response.headers["Date"] = generate_http_date()
+
+        # Add directives with values
+        if max_age is not None:
+            directives.append(f"max-age={max_age}")
+
+        if s_maxage is not None:
+            directives.append(f"s-maxage={s_maxage}")
+
+        if stale_while_revalidate is not None:
+            directives.append(f"stale-while-revalidate={stale_while_revalidate}")
+
+        if stale_if_error is not None:
+            directives.append(f"stale-if-error={stale_if_error}")
+
+        # Add boolean directives
+        if public:
+            directives.append("public")
+
+        # Handle private (can be bool or list of field names)
+        if private is True:
+            directives.append("private")
+        elif isinstance(private, list) and private:
+            field_names = ", ".join(private)
+            directives.append(f'private="{field_names}"')
+
+        # Handle no_cache (can be bool or list of field names)
+        if no_cache is True:
+            directives.append("no-cache")
+        elif isinstance(no_cache, list) and no_cache:
+            field_names = ", ".join(no_cache)
+            directives.append(f'no-cache="{field_names}"')
+
+        if no_store:
+            directives.append("no-store")
+
+        if no_transform:
+            directives.append("no-transform")
+
+        if must_revalidate:
+            directives.append("must-revalidate")
+
+        if must_understand:
+            directives.append("must-understand")
+
+        if proxy_revalidate:
+            directives.append("proxy-revalidate")
+
+        if immutable:
+            directives.append("immutable")
+
+        # Set the Cache-Control header if any directives were specified
+        if directives:
+            response.headers["Cache-Control"] = ", ".join(directives)
+
+    return fastapi.Depends(add_cache_headers)