patbond-ai/app/config.py

"""集中配置：全部旋钮从环境变量读，一处定义。

为什么不用 pydantic-settings：当前运行时依赖只有 httpx 一个，为十来个环境变量
引入一个框架不划算。需要嵌套配置或复杂校验时再换。

**凭证纪律**（ADR-021）：密钥只从环境变量读，**绝不写默认值**。缺失时
`from_env()` 不抛异常——服务仍可启动并提供健康检查，只在真正要调用厂商时才
响亮失败。这与 Java 侧 `JwtVerifier`/`ServiceTokenSigner` 的既有约定一致：
缺配置是服务端错误，不该伪装成上游故障，但也不该让整个进程起不来。
"""

from __future__ import annotations

import os
from dataclasses import dataclass, field

from app.providers.volcengine.models import DEFAULT_BASE_URL


def _env(name: str, default: str = "") -> str:
    return os.environ.get(name, default).strip()


def _env_int(name: str, default: int) -> int:
    raw = _env(name)
    if not raw:
        return default
    try:
        return int(raw)
    except ValueError as exc:
        # 静默回落到默认值会让一次配置笔误变成难查的行为偏差。
        raise ValueError(f"环境变量 {name} 不是合法整数：{raw!r}") from exc


def _env_float(name: str, default: float) -> float:
    raw = _env(name)
    if not raw:
        return default
    try:
        return float(raw)
    except ValueError as exc:
        raise ValueError(f"环境变量 {name} 不是合法数字：{raw!r}") from exc


@dataclass(frozen=True)
class VolcengineSettings:
    """火山方舟（Ark）接入配置。

    :param api_key: `ARK_API_KEY`。**无默认值**，缺失时适配层在调用点报错。
    :param timeout_sec: 单次 HTTP 往返超时。**不是生成耗时**——提交与查询都是
        短请求（提交只入队即返回），把它调大成「等出图」会重新引入长连接占用与
        计费歧义，见 ADR-023 §4。
    :param video_model: 视频生成的默认模型 ID。仅作**兜底**：正常路径由 Java 侧
        从目录表的快照列传入，适配层不自行选模型（选型是目录的职责，且任务行里
        冻结的快照必须与实际调用的模型一致）。
    :param task_expiry_sec: 传给厂商的 `execution_expires_after`。厂商取值范围
        `[3600, 259200]`，默认 48 小时对交互式应用过长，故默认取下限 1 小时。
    """

    api_key: str = ""
    base_url: str = DEFAULT_BASE_URL
    timeout_sec: float = 10.0
    video_model: str = ""
    task_expiry_sec: int = 3600

    @classmethod
    def from_env(cls) -> VolcengineSettings:
        return cls(
            api_key=_env("ARK_API_KEY"),
            base_url=_env("ARK_BASE_URL", cls.base_url),
            timeout_sec=_env_float("ARK_TIMEOUT_SEC", cls.timeout_sec),
            video_model=_env("ARK_VIDEO_MODEL"),
            task_expiry_sec=_env_int("ARK_TASK_EXPIRY_SEC", cls.task_expiry_sec),
        )

    def __post_init__(self) -> None:
        # 厂商硬性区间。设成区间外的值会在提交时被厂商拒（InvalidParameter），
        # 那要花一次往返才知道，不如在启动时就说清楚。
        if not 3600 <= self.task_expiry_sec <= 259200:
            raise ValueError(
                f"ARK_TASK_EXPIRY_SEC 必须在 [3600, 259200] 之间（厂商限制），"
                f"当前 {self.task_expiry_sec}"
            )


@dataclass(frozen=True)
class ServiceAuthSettings:
    """校验 Java 侧服务身份 JWT 所需的配置（ADR-023 §5）。

    :param public_key: 与 `patbond-creation` 持有的私钥配对的 RS256 公钥。
        注意这是一对**独立于用户 token 的**密钥——理由见 ADR-023 §5。
    :param audience: 必须强制校验。缺了这一步，任何用同一密钥签出的 token 都能
        进来，而独立密钥对的意义正在于此。
    """

    public_key: str = ""
    issuer: str = "patbond-api"
    audience: str = "patbond-ai"
    required_type: str = "service"

    @classmethod
    def from_env(cls) -> ServiceAuthSettings:
        return cls(
            public_key=_env("PATBOND_SERVICE_JWT_PUBLIC_KEY"),
            issuer=_env("PATBOND_SERVICE_JWT_ISSUER", cls.issuer),
            audience=_env("PATBOND_SERVICE_JWT_AUDIENCE", cls.audience),
            required_type=_env("PATBOND_SERVICE_JWT_TYPE", cls.required_type),
        )


@dataclass(frozen=True)
class Settings:
    """本服务的全部配置。"""

    volcengine: VolcengineSettings = field(default_factory=VolcengineSettings)
    service_auth: ServiceAuthSettings = field(default_factory=ServiceAuthSettings)
    log_level: str = "INFO"

    @classmethod
    def from_env(cls) -> Settings:
        return cls(
            volcengine=VolcengineSettings.from_env(),
            service_auth=ServiceAuthSettings.from_env(),
            log_level=_env("PATBOND_AI_LOG_LEVEL", cls.log_level).upper(),
        )