"""Metrics interface for SDK observability.

Implementations bridge to Prometheus, OTel, or custom backends.
The SDK ships with NoopMetrics (zero overhead) to avoid forcing
a metrics dependency.
"""

from __future__ import annotations

from typing import Protocol


class Metrics(Protocol):
    """Protocol defining the metrics contract for the NeonLink SDK."""

    def publish_success(self, topic: str, latency_sec: float) -> None: ...
    def publish_error(self, topic: str, err: Exception) -> None: ...
    def consume_success(self, topic: str, partition: int, latency_sec: float) -> None: ...
    def consume_error(self, topic: str, partition: int, err: Exception) -> None: ...
    def poison_pill_detected(self, topic: str, partition: int, offset: int) -> None: ...
    def poison_pill_blocked(self, topic: str, partition: int, offset: int) -> None: ...
    def consumer_lag(self, topic: str, partition: int, lag: int) -> None:
        """Report per-fetch processing lag (high watermark - current offset).

        This is NOT committed-offset group lag. For true consumer group lag,
        use Kafka admin APIs externally.
        """
        ...
    def circuit_breaker_state_change(self, name: str, from_state: str, to_state: str) -> None: ...
    def dlq_routed(self, original_topic: str, err: Exception) -> None: ...


class NoopMetrics:
    """Default metrics implementation with zero overhead. All methods are no-ops."""

    def publish_success(self, topic: str, latency_sec: float) -> None:
        pass

    def publish_error(self, topic: str, err: Exception) -> None:
        pass

    def consume_success(self, topic: str, partition: int, latency_sec: float) -> None:
        pass

    def consume_error(self, topic: str, partition: int, err: Exception) -> None:
        pass

    def poison_pill_detected(self, topic: str, partition: int, offset: int) -> None:
        pass

    def poison_pill_blocked(self, topic: str, partition: int, offset: int) -> None:
        pass

    def consumer_lag(self, topic: str, partition: int, lag: int) -> None:
        pass

    def circuit_breaker_state_change(self, name: str, from_state: str, to_state: str) -> None:
        pass

    def dlq_routed(self, original_topic: str, err: Exception) -> None:
        pass
