"""限流准入封装: 后端故障必须报错而非放行(降级方向铁律)。

非降级设计说明: 缓存/遥测挂 → 静默;限流挂 → 若放行,多 worker 会同时
失去闸门直接击穿网关,故一律 GovernanceBackendError 上抛。
"""

from __future__ import annotations

from typing import TYPE_CHECKING

from polygateway.errors import GovernanceBackendError

if TYPE_CHECKING:
    from polygateway.ports import Permit, RateLimiter
    from polygateway.types import SourceConfig, SourceStats


class QuotaGate:
    """RetryMW 面向限流后端的唯一入口;包装一切后端异常。"""

    def __init__(self, limiter: RateLimiter) -> None:
        self._limiter = limiter

    async def try_acquire(self, source: SourceConfig) -> Permit | None:
        try:
            return await self._limiter.try_acquire(source.name, source.est_tokens)
        except GovernanceBackendError:
            raise
        except Exception as exc:
            raise GovernanceBackendError(f"限流后端故障(try_acquire): {exc}") from exc

    async def stats(self, source: SourceConfig) -> SourceStats:
        try:
            return await self._limiter.source_stats(source.name)
        except GovernanceBackendError:
            raise
        except Exception as exc:
            raise GovernanceBackendError(f"限流后端故障(source_stats): {exc}") from exc

    async def mark_progress(self) -> None:
        try:
            await self._limiter.mark_progress()
        except GovernanceBackendError:
            raise
        except Exception as exc:
            raise GovernanceBackendError(f"限流后端故障(mark_progress): {exc}") from exc

    async def progress_age_s(self) -> float:
        try:
            return await self._limiter.progress_age_s()
        except GovernanceBackendError:
            raise
        except Exception as exc:
            raise GovernanceBackendError(f"限流后端故障(progress_age_s): {exc}") from exc