"""Transport and codec contracts for remote trait adapters.

The transport contracts are bytes-oriented. A codec may be attached to handle
serialization, but the transport boundary itself is always raw payload bytes.
"""

from __future__ import annotations

from typing import Protocol, runtime_checkable


@runtime_checkable
class Codec(Protocol):
    """Protocol for byte-oriented codecs."""

    def encode(self, value: object) -> bytes:
        ...

    def decode(self, payload: bytes) -> object:
        ...


@runtime_checkable
class Transport(Protocol):
    """Protocol for synchronous byte-oriented request/response transports."""

    codec: Codec | None

    def send(self, topic: str, payload: bytes) -> None:
        ...

    def request(self, topic: str, payload: bytes) -> bytes:
        ...


@runtime_checkable
class AsyncTransport(Protocol):
    """Protocol for asynchronous byte-oriented request/response transports."""

    codec: Codec | None

    async def send(self, topic: str, payload: bytes) -> None:
        ...

    async def request(self, topic: str, payload: bytes) -> bytes:
        ...


@runtime_checkable
class RemoteStorageTransport(Protocol):
    """Protocol for remote key/value storage transport."""

    def fetch(self, namespace: str, key: str) -> bytes | None:
        ...

    def store(self, namespace: str, key: str, payload: bytes) -> None:
        ...


@runtime_checkable
class CacheTransport(Protocol):
    """Protocol for cache transport with optional TTL semantics."""

    def get(self, key: str) -> bytes | None:
        ...

    def put(self, key: str, payload: bytes, *, ttl_seconds: int | None = None) -> None:
        ...

    def delete(self, key: str) -> None:
        ...


__all__ = [
    "AsyncTransport",
    "CacheTransport",
    "Codec",
    "RemoteStorageTransport",
    "Transport",
]
