"""Settings for ``mgf-apiprobe``.

See: ``DESIGN.md`` §12 (profiles) and ``HANDOFF.md`` §3.2 (subclass
:class:`mgf.common.config.BaseAppSettings`, do NOT re-implement
settings layering).

Env prefix is ``APIPROBE_``. Profile loading + ``.apiprobe.toml`` files
land in v0.4; v0.1 reads from environment +
direct constructor kwargs only.
"""

from __future__ import annotations

from mgf.common.config import BaseAppSettings
from pydantic import Field


class ApiprobeSettings(BaseAppSettings, env_prefix="APIPROBE_"):
    """Top-level settings for ``mgf-apiprobe``.

    Read from env (prefix ``APIPROBE_``) or set directly:

    .. code-block:: bash

        export APIPROBE_TIMEOUT_SECONDS=30
        export APIPROBE_DEFAULT_USER_AGENT="my-suite/1.0"

    or:

    .. code-block:: python

        settings = ApiprobeSettings(timeout_seconds=30.0)
    """

    # ── Transport ─────────────────────────────────────────────────────────
    timeout_seconds: float = Field(
        default=30.0,
        gt=0,
        description=(
            "Per-request timeout. Applies to connect + read + write "
            "phases (httpx default behavior). Probes can override via "
            "``Probe.timeout(...)``."
        ),
    )
    max_retries: int = Field(
        default=0,
        ge=0,
        le=10,
        description=(
            "Default number of retries for transient failures (5xx, "
            "connection refused). v0.1 default is 0; tests should be "
            "deterministic. Probes can opt in via ``Probe.retry(...)``."
        ),
    )
    default_user_agent: str = Field(
        default="mgf-apiprobe/0.1.0",
        description=(
            "Sent as the ``User-Agent`` header when a probe does not "
            "set its own. Includes the package version so providers "
            "can correlate traffic."
        ),
    )
    verify_tls: bool = Field(
        default=True,
        description=(
            "TLS certificate verification. **Only set False in tests** "
            "(rule SC-*); leaving it disabled in production is a "
            "security finding (``security.tls.verify-disabled``)."
        ),
    )

    # ── Reporting ─────────────────────────────────────────────────────────
    fail_on_severity: str = Field(
        default="critical",
        description=(
            "Suite exit code: non-zero if any finding at or above this "
            "severity. One of ``info``, ``warn``, ``critical``. "
            "Default mirrors DESIGN.md §3.2 (CI fails on critical, "
            "warns on warn)."
        ),
    )

    # ── Suite execution ──────────────────────────────────────────────────
    max_concurrency: int = Field(
        default=10,
        ge=1,
        le=100,
        description=(
            "Maximum number of probes the suite runs concurrently. "
            "Bound below 100 to avoid swamping providers; tighten via "
            "this setting for shared rate-limited APIs. Set to 1 for "
            "deterministic ordering during debugging."
        ),
    )


__all__ = ["ApiprobeSettings"]
