"""计算节点 API 安全配置：Swagger / ReDoc / OpenAPI 文档路由开关。"""
from __future__ import annotations

import os
from typing import Any


def docs_enabled() -> bool:
    """判断 FastAPI 文档路由（/docs、/redoc、/openapi.json）是否开放。

    显式配置 ENABLE_DOCS 时以之为准；否则仅在关闭 token 鉴权
    （COMPUTE_AUTH_ENABLED=false，本地开发）时开放，生产环境默认关闭，
    避免未授权访问泄露 API 结构。
    """
    raw = os.getenv("ENABLE_DOCS", "").strip().lower()
    if raw in {"true", "false"}:
        return raw == "true"
    auth_enabled = os.getenv("COMPUTE_AUTH_ENABLED", "true").lower() == "true"
    return not auth_enabled


def docs_kwargs() -> dict[str, Any]:
    """返回传入 FastAPI 的文档路由参数。

    关闭时 FastAPI 不注册 /docs、/redoc、/openapi.json，访问一律返回 404。
    """
    if docs_enabled():
        return {}
    return {"docs_url": None, "redoc_url": None, "openapi_url": None}