Class RpcRequest

src/notebooklm/_middleware/core.py:55–102

HTTP-shape request envelope passed through the middleware chain. The chain wraps ``Kernel.post``. Every middleware sees an already-encoded HTTP request — encoding lives *above* the chain in :meth:`RpcExecutor.rpc_call`. RPC-level metadata that middlewares need (rpc method id, idempo

@dataclass(frozen=True)
class RpcRequest:
    """HTTP-shape request envelope passed through the middleware chain.

    The chain wraps ``Kernel.post``. Every middleware sees an already-encoded
    HTTP request — encoding lives *above* the chain in :meth:`RpcExecutor.rpc_call`.
    RPC-level metadata that middlewares need (rpc
    method id, idempotency, operation variant, log labels, build-request
    callback, etc.) travels through :attr:`context`.

    Frozen: middlewares that want to alter the request build a new
    :class:`RpcRequest` via :func:`dataclasses.replace`. The
    :class:`AuthRefreshMiddleware` does exactly this when
    rebuilding headers and URL after an auth refresh.

    :attr:`context` is mutable by reference (it's a plain :class:`dict`) and
    is shared across the chain by design — see ADR-0009 §"Per-request
    behavior". Middlewares that want isolation should make a shallow copy
    before mutating.
    """

    url: str
    """Fully-built ``batchexecute`` URL with ``authuser`` and ``_reqid`` set."""

    headers: Mapping[str, str]
    """HTTP headers for this attempt (auth headers, ``X-Goog-AuthUser``, …).

    Typed as :class:`~collections.abc.Mapping` (read-only protocol) rather
    than :class:`dict` so the frozen-dataclass contract extends to the
    header values: middlewares that want to add or alter headers build a
    new :class:`RpcRequest` via :func:`dataclasses.replace` with a freshly
    constructed dict (e.g.
    ``dataclasses.replace(request, headers={**request.headers, "X-Foo": "1"})``).
    Concrete :class:`dict` instances satisfy this annotation, so callers
    that pass a literal ``{...}`` need no special treatment.
    """

    body: bytes
    """Encoded ``batchexecute`` body bytes for this attempt."""

    context: dict[str, Any] = field(default_factory=dict)
    """RPC-level metadata the chain reads.

    The allowed vocabulary is exported as
    :data:`ALLOWED_RPC_CONTEXT_KEYS` and mirrored in ADR-0009. Middlewares
    and the transport terminal use the ``RPC_CONTEXT_*`` constants for
    lookups and writes; adding a key requires updating this module, ADR-0009,
    and the lint-style unit test that guards the vocabulary.
    """


@dataclass(frozen=True)