pxa-drm-server 0.1.0__py3-none-any.whl

pxa_drm_server/__init__.py

@@ -0,0 +1,26 @@
+"""pxa-drm-server — 파일 암복호화 API 서버.
+
+개발자는 ``domain_core.py`` 에 세 함수만 구현하면 된다::
+
+    def encrypt(filepath: str) -> bool: ...
+    def decrypt(filepath: str) -> bool: ...
+    def check(filepath: str) -> bool: ...
+
+REST API / 로깅 / 에러처리 / 표준 응답 / 오브젝트 스토리지 입출력은
+이 패키지가 pxa-common 위에서 처리한다.
+
+    pxa-drm-server init      # 시작 템플릿 생성
+    pxa-drm-server           # 서버 실행
+"""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("pxa-drm-server")
+except PackageNotFoundError:      # 설치 없이 소스에서 바로 쓰는 경우
+    __version__ = "0.0.0.dev0"
+
+# app 이 __version__ 을 쓰므로 버전을 정한 뒤에 import 한다.
+from .app import create_app  # noqa: E402
+from .codes import DrmCode  # noqa: E402
+
+__all__ = ["create_app", "DrmCode", "__version__"]

pxa_drm_server/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m pxa_drm_server`` 실행 지원."""
+import sys
+
+from .main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pxa_drm_server/api/__init__.py

@@ -0,0 +1 @@
+"""REST API 패키지."""

pxa_drm_server/api/v1/__init__.py

@@ -0,0 +1,4 @@
+"""API v1."""
+from .routes import router
+
+__all__ = ["router"]

pxa_drm_server/api/v1/routes.py

@@ -0,0 +1,83 @@
+"""기본 제공 REST API (v1).
+
+세 가지 작업(encrypt / decrypt / check)에 대해 각각 세 가지 대상 지정 방식을
+지원한다. 라우터는 대상 해석과 실행을 service 에 위임하고 응답만 돌려준다.
+
+    GET|POST /api/v1/encrypt?filepath=/download/file.docx
+    GET|POST /api/v1/encrypt?uri=ABC:download/file.docx
+    POST     /api/v1/encrypt   (multipart: file=@file.docx)
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pxa_common import ApiResponse
+from pxa_common.fastapi import APIRouter, Depends, File, Query, UploadFile
+
+from ...runtime import DrmRuntime, get_runtime
+from ...service import OPERATIONS, build_source, run_operation
+
+router = APIRouter(prefix="/api/v1", tags=["drm"])
+
+_SUMMARY = {
+    "encrypt": "파일 암호화",
+    "decrypt": "파일 복호화",
+    "check": "파일 암호화 여부 확인",
+}
+
+_FILEPATH_DESC = "서버가 접근 가능한 파일 경로 (예: /download/file.docx)"
+_URI_DESC = "오브젝트 스토리지 경로, '버킷별칭:오브젝트키' 형식 (예: ABC:download/file.docx)"
+_RESPONSE_DESC = "첨부파일 요청의 응답 형식. file=결과 파일 다운로드, json=표준 JSON 응답"
+
+
+def _register(operation: str) -> None:
+    """작업 하나에 대한 GET/POST 엔드포인트를 등록한다."""
+    summary = _SUMMARY[operation]
+
+    @router.get(
+        f"/{operation}",
+        summary=f"{summary} (filepath / uri)",
+        operation_id=f"{operation}_by_query",
+        response_model=ApiResponse,
+    )
+    async def _by_query(
+        filepath: Optional[str] = Query(None, description=_FILEPATH_DESC),
+        uri: Optional[str] = Query(None, description=_URI_DESC),
+        runtime: DrmRuntime = Depends(get_runtime),
+    ):
+        source = build_source(runtime, filepath=filepath, uri=uri)
+        return await run_operation(runtime, operation, source)
+
+    @router.post(
+        f"/{operation}",
+        summary=f"{summary} (filepath / uri / 첨부파일)",
+        operation_id=f"{operation}_by_payload",
+    )
+    async def _by_payload(
+        filepath: Optional[str] = Query(None, description=_FILEPATH_DESC),
+        uri: Optional[str] = Query(None, description=_URI_DESC),
+        response: Optional[str] = Query(None, description=_RESPONSE_DESC),
+        file: Optional[UploadFile] = File(None, description="처리할 첨부파일"),
+        runtime: DrmRuntime = Depends(get_runtime),
+    ):
+        source = build_source(runtime, filepath=filepath, uri=uri, file=file)
+        return await run_operation(runtime, operation, source, response_mode=response)
+
+
+for _operation_name in OPERATIONS:
+    _register(_operation_name)
+
+
+@router.get("/health", summary="상태 확인", response_model=ApiResponse)
+async def health(runtime: DrmRuntime = Depends(get_runtime)):
+    """서버와 도메인 모듈이 준비되었는지 확인한다."""
+    return ApiResponse.ok(
+        result={
+            "status": "ok",
+            "domain": {
+                name: runtime.domain.has(name) for name in OPERATIONS
+            },
+            "buckets": sorted(runtime.storage.buckets),
+        },
+        message="서버가 정상 동작 중입니다.",
+    )

pxa_drm_server/app.py

@@ -0,0 +1,80 @@
+"""FastAPI 앱 팩토리.
+
+pxa-common 이 제공하는 기반(설정 / 로깅 / 표준응답 / 예외처리 / 메시지)을
+한자리에서 조립한다. 개발자는 ``domain_core.py`` 만 작성하면 되고
+이 파일을 수정할 일은 없다.
+
+    from pxa_drm_server import create_app
+    app = create_app()
+"""
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import yaml
+from pxa_common import (
+    RequestLoggingMiddleware,
+    get_app_config,
+    get_messages_config,
+    load_message_files,
+    register_exception_handlers,
+    register_messages,
+    setup_logging,
+)
+from pxa_common.fastapi import FastAPI
+
+from . import __version__
+from .api.v1 import router as v1_router
+from .runtime import build_runtime
+
+__all__ = ["create_app"]
+
+_MESSAGE_FILE = Path(__file__).parent / "messages" / "drm.yaml"
+
+logger = logging.getLogger("pxa")
+
+
+def _load_messages() -> None:
+    """서버 기본 메시지 -> 애플리케이션 메시지(config) 순으로 등록한다."""
+    if _MESSAGE_FILE.is_file():
+        data = yaml.safe_load(_MESSAGE_FILE.read_text(encoding="utf-8")) or {}
+        register_messages(data)
+    files = get_messages_config().files
+    if files:
+        load_message_files(files)
+
+
+def create_app() -> FastAPI:
+    """DRM 서버 앱을 만든다."""
+    setup_logging()
+    _load_messages()
+
+    app_cfg = get_app_config()
+    runtime = build_runtime()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        logger.info(
+            "%s 기동 완료 (debug=%s, buckets=%s)",
+            app_cfg.name, app_cfg.debug, sorted(runtime.storage.buckets) or "없음",
+        )
+        yield
+        logger.info("%s 종료", app_cfg.name)
+
+    app = FastAPI(
+        title=app_cfg.name,
+        description="파일 암복호화 API 서버 (pxa-common 기반)",
+        version=__version__,
+        debug=app_cfg.debug,
+        lifespan=lifespan,
+    )
+
+    # 요청 로깅(request-id + 처리시간) / 표준 예외 처리
+    app.add_middleware(RequestLoggingMiddleware)
+    register_exception_handlers(app)
+
+    app.state.drm_runtime = runtime
+    app.include_router(v1_router)
+    return app

pxa_drm_server/asgi.py

@@ -0,0 +1,12 @@
+"""ASGI 진입점.
+
+    uvicorn pxa_drm_server.asgi:app --host 0.0.0.0 --port 8000
+
+이 모듈을 import 하는 순간 설정을 읽고 domain_core 를 로드한다.
+(CLI 가 이 모듈을 건드리지 않아야 ``pxa-drm-server init`` 이 domain_core 없이도 동작한다.)
+"""
+from __future__ import annotations
+
+from .app import create_app
+
+app = create_app()

pxa_drm_server/codes.py

@@ -0,0 +1,46 @@
+"""DRM 서버 애플리케이션 코드.
+
+pxa-common 의 ``AppCode`` 규약(코드 / 기본 메시지 / HTTP 상태)을 그대로 따른다.
+공통 코드(pxa-10000, pxa-2000x)는 ``AppCode`` 를 쓰고, DRM 도메인에서만
+의미가 있는 코드를 여기에 추가한다.
+
+  - pxa-21xxx : 도메인(암복호화) 처리 관련
+  - pxa-22xxx : 파일/스토리지 입출력 관련
+
+새 코드가 필요하면 이 Enum 에만 한 줄 추가한다.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class DrmCode(str, Enum):
+    """DRM 서버 전용 애플리케이션 코드."""
+
+    # ---- 도메인(개발자 구현) 처리 ----
+    ENCRYPT_FAILED = ("pxa-21001", "파일 암호화에 실패했습니다.", 200)
+    DECRYPT_FAILED = ("pxa-21002", "파일 복호화에 실패했습니다.", 200)
+    DOMAIN_ERROR = ("pxa-21003", "도메인 처리 중 오류가 발생했습니다.", 200)
+    DOMAIN_NOT_IMPLEMENTED = ("pxa-21004", "도메인 기능이 구현되지 않았습니다.", 200)
+    DOMAIN_CONTRACT_ERROR = ("pxa-21005", "도메인 함수의 반환값이 올바르지 않습니다.", 200)
+
+    # ---- 파일 / 스토리지 ----
+    FILE_NOT_FOUND = ("pxa-22001", "대상 파일을 찾을 수 없습니다.", 200)
+    PATH_NOT_ALLOWED = ("pxa-22002", "허용되지 않은 경로입니다.", 200)
+    INVALID_URI = ("pxa-22003", "uri 형식이 올바르지 않습니다.", 200)
+    BUCKET_NOT_CONFIGURED = ("pxa-22004", "설정되지 않은 버킷입니다.", 200)
+    STORAGE_ERROR = ("pxa-22005", "오브젝트 스토리지 처리 중 오류가 발생했습니다.", 200)
+    UPLOAD_ERROR = ("pxa-22006", "첨부파일 처리 중 오류가 발생했습니다.", 200)
+    FILE_TOO_LARGE = ("pxa-22007", "파일 크기가 허용 범위를 초과했습니다.", 200)
+
+    def __new__(cls, code: str, message: str, http_status: int):
+        obj = str.__new__(cls, code)
+        obj._value_ = code
+        obj.code = code
+        obj.message = message
+        obj.http_status = http_status
+        return obj
+
+    @property
+    def is_success(self) -> bool:
+        return self.code.startswith("pxa-1")

pxa_drm_server/config.py

@@ -0,0 +1,101 @@
+"""DRM 서버 설정.
+
+pxa-common 의 설정 관리(``load_section``)를 그대로 사용한다.
+우선순위는 **환경변수(PXA_*) > config.yaml > 기본값** 이며,
+config 파일 경로는 환경변수 ``PXA_CONFIG`` 로 지정한다.
+
+오브젝트 스토리지 접근키처럼 민감한 값은 파일에 두지 말고 환경변수로 넣는다::
+
+    PXA_STORAGE__BUCKETS__ABC__ACCESS_KEY=...
+    PXA_STORAGE__BUCKETS__ABC__SECRET_KEY=...
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pxa_common import load_section
+from pxa_common.fastapi import BaseModel, Field, model_validator
+
+
+class DrmConfig(BaseModel):
+    """domain_core 로딩과 작업 방식."""
+
+    # 개발자가 구현한 모듈. 파일 경로(domain_file)를 주면 그쪽이 우선한다.
+    domain_module: str = "domain_core"
+    domain_file: Optional[str] = None
+    # 임시 작업 디렉토리. 비우면 OS 임시 디렉토리를 쓴다.
+    work_dir: Optional[str] = None
+    # 첨부파일 업로드 허용 크기(MB). 0 이하면 제한 없음.
+    max_upload_size_mb: int = 512
+    # 첨부파일 요청의 기본 응답 형식: "file"(결과 파일 다운로드) 또는 "json".
+    upload_response: str = "file"
+
+
+class LocalConfig(BaseModel):
+    """filepath(서버 로컬 경로) 처리 방식."""
+
+    # 비우면 모든 경로를 허용한다. 지정하면 해당 디렉토리 하위만 허용한다.
+    allowed_roots: list[str] = Field(default_factory=list)
+    # True 면 원본 파일을 그대로 도메인에 넘긴다(제자리 처리).
+    # False 면 작업본을 만들어 처리하고 성공 시에만 원자적으로 교체한다.
+    in_place: bool = False
+
+
+class BucketConfig(BaseModel):
+    """S3 호환 오브젝트 스토리지 버킷 하나의 접근 정보."""
+
+    bucket: str
+    endpoint_url: Optional[str] = None
+    access_key: str = ""
+    secret_key: str = ""
+    region: str = "us-east-1"
+    # MinIO/Ceph 등 S3 호환 스토리지는 보통 "path" 가 안전하다.
+    addressing_style: str = "path"
+    signature_version: Optional[str] = None
+    verify_ssl: bool = True
+
+
+class StorageConfig(BaseModel):
+    """버킷 별칭 -> 접근 정보. uri 의 'ABC:key' 에서 ABC 가 별칭이다."""
+
+    buckets: dict[str, BucketConfig] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _merge_aliases(cls, data):
+        """대소문자만 다른 별칭을 하나로 합친다.
+
+        환경변수 override(PXA_STORAGE__BUCKETS__ABC__ACCESS_KEY)는 pxa-common 에서
+        경로가 소문자로 변환되므로, config.yaml 의 'ABC' 와 환경변수의 'abc' 가
+        따로 생긴다. 둘을 합쳐야 "키는 환경변수로" 라는 사용법이 성립한다.
+        나중에 온 값(환경변수)이 이긴다.
+        """
+        if not isinstance(data, dict):
+            return data
+        buckets = data.get("buckets")
+        if not isinstance(buckets, dict):
+            return data
+        merged: dict = {}
+        for alias, value in buckets.items():
+            key = str(alias).lower()
+            if isinstance(value, dict) and isinstance(merged.get(key), dict):
+                merged[key] = {**merged[key], **value}
+            else:
+                merged[key] = value
+        return {**data, "buckets": merged}
+
+    def resolve(self, alias: str) -> Optional[BucketConfig]:
+        """버킷 별칭을 찾는다(대소문자 무시)."""
+        return self.buckets.get(alias.lower())
+
+
+def get_drm_config() -> DrmConfig:
+    return load_section("drm", DrmConfig)
+
+
+def get_local_config() -> LocalConfig:
+    return load_section("local", LocalConfig)
+
+
+def get_storage_config() -> StorageConfig:
+    return load_section("storage", StorageConfig)

pxa_drm_server/domain.py

@@ -0,0 +1,122 @@
+"""domain_core 로더 / 호출 어댑터.
+
+서버는 기동 시 개발자가 작성한 ``domain_core`` 모듈을 읽어 들이고,
+요청이 오면 ``encrypt(filepath)`` / ``decrypt(filepath)`` / ``check(filepath)``
+를 호출한다. 개발자는 이 파일을 볼 필요가 없다.
+
+- 동기 함수는 워커 스레드에서 실행해 이벤트 루프를 막지 않는다.
+- ``async def`` 로 구현해도 그대로 동작한다.
+- 반환값은 반드시 ``True`` / ``False`` 여야 한다.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from starlette.concurrency import run_in_threadpool
+
+from .config import DrmConfig, get_drm_config
+from .errors import DomainContractError, DomainError, DomainNotImplementedError
+
+logger = logging.getLogger("pxa")
+
+# 개발자가 구현해야 하는 함수. encrypt/decrypt 는 필수, check 는 선택이다.
+REQUIRED_FUNCTIONS = ("encrypt", "decrypt")
+OPTIONAL_FUNCTIONS = ("check",)
+
+
+def _load_module_from_file(path: Path):
+    """파일 경로에서 모듈을 직접 읽어 들인다(config: drm.domain_file)."""
+    spec = importlib.util.spec_from_file_location("domain_core", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"도메인 파일을 읽을 수 없습니다: {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["domain_core"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_domain_module(cfg: Optional[DrmConfig] = None):
+    """설정에 따라 domain_core 모듈을 로드하고 계약을 검증한다."""
+    cfg = cfg or get_drm_config()
+
+    if cfg.domain_file:
+        path = Path(cfg.domain_file).expanduser().resolve()
+        if not path.is_file():
+            raise RuntimeError(f"drm.domain_file 경로에 파일이 없습니다: {path}")
+        module = _load_module_from_file(path)
+        origin = str(path)
+    else:
+        # 프로젝트 루트(실행 디렉토리)의 domain_core.py 도 찾을 수 있게 한다.
+        cwd = str(Path.cwd())
+        if cwd not in sys.path:
+            sys.path.insert(0, cwd)
+        try:
+            module = importlib.import_module(cfg.domain_module)
+        except ImportError as exc:
+            raise RuntimeError(
+                f"도메인 모듈 '{cfg.domain_module}' 을(를) 찾을 수 없습니다. "
+                f"domain_core.py 를 만들거나 config 의 drm.domain_module / "
+                f"drm.domain_file 을 확인하세요."
+            ) from exc
+        origin = getattr(module, "__file__", cfg.domain_module)
+
+    missing = [n for n in REQUIRED_FUNCTIONS if not callable(getattr(module, n, None))]
+    if missing:
+        raise RuntimeError(
+            f"도메인 모듈({origin})에 다음 함수가 없습니다: {', '.join(missing)}. "
+            f"각 함수는 filepath 하나를 받아 True/False 를 반환해야 합니다."
+        )
+    for name in OPTIONAL_FUNCTIONS:
+        if not callable(getattr(module, name, None)):
+            logger.warning(
+                "도메인 모듈에 %s() 가 없습니다. /api/v1/%s 호출 시 pxa-21004 로 응답합니다.",
+                name, name,
+            )
+
+    logger.info("도메인 모듈 로드: %s", origin)
+    return module
+
+
+class DomainAdapter:
+    """도메인 함수 호출을 감싸 예외/반환값을 표준 오류로 바꾼다."""
+
+    def __init__(self, module: Any):
+        self.module = module
+
+    def has(self, name: str) -> bool:
+        return callable(getattr(self.module, name, None))
+
+    def _resolve(self, name: str) -> Callable[..., Any]:
+        func = getattr(self.module, name, None)
+        if not callable(func):
+            raise DomainNotImplementedError(
+                f"domain_core.{name}() 가 구현되어 있지 않습니다."
+            )
+        return func
+
+    async def call(self, name: str, filepath: Path) -> bool:
+        """domain_core.<name>(filepath) 를 호출하고 bool 을 돌려준다."""
+        func = self._resolve(name)
+        try:
+            if inspect.iscoroutinefunction(func):
+                result = await func(str(filepath))
+            else:
+                result = await run_in_threadpool(func, str(filepath))
+        except Exception as exc:  # 개발자 코드의 모든 예외를 표준 응답으로
+            logger.exception("domain_core.%s() 실행 중 예외", name)
+            raise DomainError(
+                f"domain_core.{name}() 실행 중 오류가 발생했습니다: {exc}"
+            ) from exc
+
+        if not isinstance(result, bool):
+            raise DomainContractError(
+                f"domain_core.{name}() 는 True/False 를 반환해야 합니다 "
+                f"(반환값 타입: {type(result).__name__})."
+            )
+        return result

pxa_drm_server/errors.py

@@ -0,0 +1,94 @@
+"""DRM 서버 전용 예외.
+
+모두 pxa-common 의 ``AppError`` 를 상속하므로
+``register_exception_handlers(app)`` 한 줄로 표준 응답(HTTP 200 + 코드)으로
+자동 변환된다. 개발자는 예외를 잡을 필요가 없다.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pxa_common import AppError
+
+from .codes import DrmCode
+
+
+class DrmError(AppError):
+    """DRM 서버 예외 베이스."""
+
+    code_enum: DrmCode = DrmCode.DOMAIN_ERROR
+
+    def __init__(self, message: Optional[str] = None, result: Any = None):
+        super().__init__(self.code_enum, message, result)
+
+
+class EncryptFailedError(DrmError):
+    """domain_core.encrypt() 가 False 를 반환 (pxa-21001)."""
+
+    code_enum = DrmCode.ENCRYPT_FAILED
+
+
+class DecryptFailedError(DrmError):
+    """domain_core.decrypt() 가 False 를 반환 (pxa-21002)."""
+
+    code_enum = DrmCode.DECRYPT_FAILED
+
+
+class DomainError(DrmError):
+    """domain_core 함수가 예외를 던짐 (pxa-21003)."""
+
+    code_enum = DrmCode.DOMAIN_ERROR
+
+
+class DomainNotImplementedError(DrmError):
+    """domain_core 에 해당 함수가 없음 (pxa-21004)."""
+
+    code_enum = DrmCode.DOMAIN_NOT_IMPLEMENTED
+
+
+class DomainContractError(DrmError):
+    """domain_core 함수가 True/False 가 아닌 값을 반환 (pxa-21005)."""
+
+    code_enum = DrmCode.DOMAIN_CONTRACT_ERROR
+
+
+class TargetNotFoundError(DrmError):
+    """대상 파일/오브젝트 없음 (pxa-22001)."""
+
+    code_enum = DrmCode.FILE_NOT_FOUND
+
+
+class PathNotAllowedError(DrmError):
+    """allowed_roots 밖의 경로 (pxa-22002)."""
+
+    code_enum = DrmCode.PATH_NOT_ALLOWED
+
+
+class InvalidUriError(DrmError):
+    """uri 형식 오류 (pxa-22003)."""
+
+    code_enum = DrmCode.INVALID_URI
+
+
+class BucketNotConfiguredError(DrmError):
+    """config 에 없는 버킷 별칭 (pxa-22004)."""
+
+    code_enum = DrmCode.BUCKET_NOT_CONFIGURED
+
+
+class StorageError(DrmError):
+    """오브젝트 스토리지 입출력 오류 (pxa-22005)."""
+
+    code_enum = DrmCode.STORAGE_ERROR
+
+
+class UploadError(DrmError):
+    """첨부파일 처리 오류 (pxa-22006)."""
+
+    code_enum = DrmCode.UPLOAD_ERROR
+
+
+class FileTooLargeError(DrmError):
+    """허용 크기 초과 (pxa-22007)."""
+
+    code_enum = DrmCode.FILE_TOO_LARGE