awoooi/apps/api/src/utils/k8s_naming.py

"""
K8s Resource Naming Utilities - ADR-016 資源名稱規範
=====================================================

提供 K8s 資源名稱正規化與驗證功能：
1. URL/域名 → 有效 K8s 名稱
2. 格式驗證 (RFC 1123)
3. 靜態映射表查詢

K8s 命名規則 (RFC 1123):
- 最多 63 字元
- 只能包含小寫字母、數字、連字號
- 必須以字母或數字開頭和結尾

版本: v1.0
建立: 2026-03-26 (台北時區)
建立者: Claude Code (首席架構師)

@see docs/adr/ADR-016-k8s-resource-naming.md
"""

import re
from dataclasses import dataclass
from enum import Enum
from typing import Final

import structlog

logger = structlog.get_logger(__name__)


# =============================================================================
# Constants
# =============================================================================

# K8s 名稱正則 (RFC 1123 subdomain)
K8S_NAME_PATTERN: Final[re.Pattern] = re.compile(
    r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
)

# 最大長度
K8S_NAME_MAX_LENGTH: Final[int] = 63


# =============================================================================
# Static Mapping Table (Fallback)
# =============================================================================

# URL/域名 → K8s Deployment 映射
# 當動態查詢失敗時使用
RESOURCE_MAPPING: Final[dict[str, tuple[str, str]]] = {
    # 域名 → (deployment_name, namespace)
    "api.awoooi.wooo.work": ("awoooi-api", "awoooi-prod"),
    "awoooi.wooo.work": ("awoooi-web", "awoooi-prod"),
    "wooo.work": ("awoooi-web", "awoooi-prod"),

    # 服務別名
    "awoooi-api": ("awoooi-api", "awoooi-prod"),
    "awoooi-web": ("awoooi-web", "awoooi-prod"),
    "openclaw": ("openclaw", "awoooi-prod"),

    # 內部服務
    "signoz": ("signoz-otel-collector", "signoz"),
    "langfuse": ("langfuse-web", "langfuse"),
}

# 非 K8s 資源標記 (這些主機不在 K8s 中)
NON_K8S_HOSTS: Final[set[str]] = {
    "prod-docker-188",
    "192.168.0.188",
    "192.168.0.110",
    "192.168.0.112",
}


# =============================================================================
# Types
# =============================================================================

class ResourceType(str, Enum):
    """資源類型"""
    DEPLOYMENT = "deployment"
    STATEFULSET = "statefulset"
    POD = "pod"
    SERVICE = "service"
    UNKNOWN = "unknown"


@dataclass
class NormalizeResult:
    """正規化結果"""
    success: bool
    original: str
    normalized: str | None
    namespace: str | None
    resource_type: ResourceType
    is_k8s_resource: bool
    confidence: float  # 0.0 - 1.0
    note: str | None = None


# =============================================================================
# Normalization Functions
# =============================================================================

def is_valid_k8s_name(name: str) -> bool:
    """
    檢查是否為有效的 K8s 資源名稱 (RFC 1123)

    Args:
        name: 資源名稱

    Returns:
        bool: 是否有效
    """
    if not name:
        return False
    if len(name) > K8S_NAME_MAX_LENGTH:
        return False
    return bool(K8S_NAME_PATTERN.match(name))


def strip_url_scheme(raw: str) -> str:
    """
    移除 URL scheme 和路徑

    Examples:
        https://api.awoooi.wooo.work/v1/health → api.awoooi.wooo.work
        http://192.168.0.188:8000 → 192.168.0.188
    """
    # 移除 scheme
    result = re.sub(r"^https?://", "", raw)
    # 移除 port
    result = re.sub(r":\d+.*$", "", result)
    # 移除路徑
    result = result.split("/")[0]
    return result.strip()


def to_k8s_safe_name(raw: str) -> str:
    """
    轉換為 K8s 安全名稱

    Examples:
        api.awoooi.wooo.work → api-awoooi-wooo-work
        My_Service_Name → my-service-name
    """
    # 轉小寫
    result = raw.lower()
    # 替換不允許的字元為連字號
    result = re.sub(r"[^a-z0-9-]", "-", result)
    # 合併多個連字號
    result = re.sub(r"-+", "-", result)
    # 移除開頭和結尾的連字號
    result = result.strip("-")
    # 截斷到最大長度
    if len(result) > K8S_NAME_MAX_LENGTH:
        result = result[:K8S_NAME_MAX_LENGTH].rstrip("-")
    return result


def normalize_resource_name(raw: str, default_namespace: str = "awoooi-prod") -> NormalizeResult:
    """
    正規化資源名稱 - 主入口函數

    流程：
    1. 檢查是否為非 K8s 資源
    2. 移除 URL scheme
    3. 查詢靜態映射表
    4. 轉換為 K8s 安全名稱
    5. 驗證格式

    Args:
        raw: 原始資源名稱 (可能是 URL、域名、或 K8s 名稱)
        default_namespace: 預設命名空間

    Returns:
        NormalizeResult: 正規化結果
    """
    if not raw:
        return NormalizeResult(
            success=False,
            original=raw,
            normalized=None,
            namespace=None,
            resource_type=ResourceType.UNKNOWN,
            is_k8s_resource=False,
            confidence=0.0,
            note="Empty resource name",
        )

    # Step 1: 檢查非 K8s 資源
    stripped = strip_url_scheme(raw)
    if stripped in NON_K8S_HOSTS or raw in NON_K8S_HOSTS:
        logger.info(
            "resource_is_non_k8s",
            original=raw,
            stripped=stripped,
        )
        return NormalizeResult(
            success=True,
            original=raw,
            normalized=stripped,
            namespace=None,
            resource_type=ResourceType.UNKNOWN,
            is_k8s_resource=False,
            confidence=1.0,
            note="Non-K8s host (VM/Container)",
        )

    # Step 2: 查詢靜態映射表
    lookup_key = stripped.lower()
    if lookup_key in RESOURCE_MAPPING:
        deployment, namespace = RESOURCE_MAPPING[lookup_key]
        logger.info(
            "resource_mapped_from_table",
            original=raw,
            deployment=deployment,
            namespace=namespace,
        )
        return NormalizeResult(
            success=True,
            original=raw,
            normalized=deployment,
            namespace=namespace,
            resource_type=ResourceType.DEPLOYMENT,
            is_k8s_resource=True,
            confidence=1.0,
            note="Mapped from static table",
        )

    # Step 3: 檢查是否已經是有效的 K8s 名稱
    if is_valid_k8s_name(raw):
        logger.info(
            "resource_already_valid",
            original=raw,
        )
        return NormalizeResult(
            success=True,
            original=raw,
            normalized=raw,
            namespace=default_namespace,
            resource_type=ResourceType.DEPLOYMENT,
            is_k8s_resource=True,
            confidence=0.0,  # 🔴 規則驗證，非 AI
            note="Already valid K8s name",
        )

    # Step 4: 嘗試轉換
    converted = to_k8s_safe_name(stripped)

    if is_valid_k8s_name(converted):
        logger.info(
            "resource_converted",
            original=raw,
            converted=converted,
        )
        return NormalizeResult(
            success=True,
            original=raw,
            normalized=converted,
            namespace=default_namespace,
            resource_type=ResourceType.DEPLOYMENT,
            is_k8s_resource=True,
            confidence=0.0,  # 🔴 規則轉換，非 AI
            note=f"Converted from '{raw}' (requires validation)",
        )

    # Step 5: 無法處理
    logger.warning(
        "resource_normalization_failed",
        original=raw,
        attempted=converted,
    )
    return NormalizeResult(
        success=False,
        original=raw,
        normalized=None,
        namespace=None,
        resource_type=ResourceType.UNKNOWN,
        is_k8s_resource=False,
        confidence=0.0,
        note=f"Cannot normalize '{raw}' to valid K8s name",
    )


def extract_resource_hints(raw: str) -> list[str]:
    """
    從原始名稱提取可能的資源關鍵字

    用於模糊匹配時的候選生成

    Examples:
        https://api.awoooi.wooo.work → ["api", "awoooi", "wooo", "work"]
        prod-docker-188 → ["prod", "docker", "188"]
    """
    stripped = strip_url_scheme(raw)
    # 分割所有非字母數字字元
    parts = re.split(r"[^a-z0-9]+", stripped.lower())
    # 過濾空字串和太短的詞
    return [p for p in parts if len(p) >= 2]