"""Python middleware base classes for the RPC framework."""

from __future__ import annotations

from abc import ABC, abstractmethod


class Interceptor(ABC):
    """Base class for Python RPC interceptors.

    Subclass this and override ``on_request`` and/or ``on_response``
    to add cross-cutting concerns like logging, auth, or metrics.

    Example::

        class AuthInterceptor(Interceptor):
            def __init__(self, token: str):
                self.token = token

            async def on_request(self, metadata: dict, body: bytes) -> tuple[dict, bytes]:
                metadata["authorization"] = f"Bearer {self.token}"
                return metadata, body
    """

    async def on_request(
        self,
        metadata: dict[str, str],
        body: bytes,
    ) -> tuple[dict[str, str], bytes]:
        """Called before the request is sent.

        Args:
            metadata: Mutable request metadata (headers).
            body: The request body bytes.

        Returns:
            The (possibly modified) metadata and body.
        """
        return metadata, body

    async def on_response(
        self,
        metadata: dict[str, str],
        body: bytes,
    ) -> tuple[dict[str, str], bytes]:
        """Called after the response is received.

        Args:
            metadata: Response metadata (headers).
            body: The response body bytes.

        Returns:
            The (possibly modified) metadata and body.
        """
        return metadata, body
