"""스토리지 계층 추상화 패키지 (plan ds-s1-backend-1 D 그룹, scaffold-first).

활성 백엔드 선택 = get_storage_backend():
  - env DS_STORAGE_BACKEND (기본 'local') 로 결정 — config.yaml storage 섹션 편집 없이도
    동작(검색실험 Soft Lock 동안 config 불가침). 실 활성(외부 백엔드)은 D-3.
  - 'local'        → LocalBackend(settings.nas_mount_path)  : 현행 NAS NFS, /file 동작 불변.
  - 'nas_api'/'nas'→ NasApiBackend(env DS_NAS_API_BASE_URL) : 미프로비전 시 503(silent fallback X).
"""

from __future__ import annotations

import os
from functools import lru_cache

from core.config import settings

from .base import StatResult, StorageBackend, StorageNotConfigured
from .local import LocalBackend
from .nas_api import NasApiBackend

__all__ = [
    "StorageBackend",
    "StorageNotConfigured",
    "StatResult",
    "LocalBackend",
    "NasApiBackend",
    "get_storage_backend",
]


@lru_cache(maxsize=1)
def get_storage_backend() -> StorageBackend:
    """활성 스토리지 백엔드 1개 반환 (프로세스 단위 캐시)."""
    backend = os.getenv("DS_STORAGE_BACKEND", "local").lower()
    if backend == "local":
        return LocalBackend(settings.nas_mount_path)
    if backend in ("nas_api", "nas"):
        return NasApiBackend(os.getenv("DS_NAS_API_BASE_URL"))
    raise StorageNotConfigured(f"unknown DS_STORAGE_BACKEND={backend!r}")