robin-cloud-client 0.1.0__tar.gz

robin_cloud_client-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# TypeScript / Node
+node_modules/
+typescript/dist/
+*.tsbuildinfo
+.turbo/
+coverage/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

robin_cloud_client-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: robin-cloud-client
+Version: 0.1.0
+Summary: Python client for Robin-Cloud storage and logs (X-Api-Key auth)
+Project-URL: Homepage, https://github.com/robintech-seoul/robin-cloud-client
+Project-URL: Repository, https://github.com/robintech-seoul/robin-cloud-client
+Author: RobinTech
+License: MIT
+Keywords: logs,robin-cloud,s3,sdk,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# robin-cloud-client (Python)
+
+Robin-Cloud 스토리지·로그를 API 키로 이용하는 Python SDK.
+
+```bash
+pip install robin-cloud-client
+```
+
+## 사용
+
+```python
+from robincloud import RobinCloud
+
+rc = RobinCloud(api_key="rbk_…", project="raxis")
+# 또는 환경변수: ROBIN_CLOUD_API_KEY, ROBIN_CLOUD_BASE_URL
+
+# 스토리지
+rc.storage.create_bucket("assets")                       # storage:admin 스코프 필요
+rc.storage.upload("assets", "img/logo.png", data)        # presign→PUT→complete 자동
+raw = rc.storage.download("assets", "img/logo.png")      # -> bytes
+listing = rc.storage.list_objects("assets", prefix="img/")
+rc.storage.delete("assets", keys=["img/logo.png"])
+
+# 로그
+for src in rc.logs.sources():
+    print(src.pod, src.containers)
+print(rc.logs.tail(source="web-1", lines=200))
+
+rc.close()   # 또는 with RobinCloud(...) as rc:
+```
+
+## 에러
+
+상태코드가 타입 예외로 매핑된다: `AuthenticationError`(401), `PermissionDeniedError`(403),
+`NotFoundError`(404), `ConflictError`(409), `PayloadTooLargeError`(413), `ValidationError`(422),
+`ServiceUnavailableError`(503), 그 외 `ApiError`. 모두 `RobinCloudError` 하위.
+
+```python
+from robincloud import PermissionDeniedError
+try:
+    rc.storage.create_bucket("x")
+except PermissionDeniedError as e:
+    print(e.status_code, e.message)   # 403 "key is missing required scope 'storage:admin'"
+```
+
+## 범위
+
+- 스토리지(버킷·오브젝트·업로드/다운로드·이동·삭제·public URL) + 로그(소스·tail).
+- 키 발급/폐기는 세션 인증이라 SDK 범위 밖(콘솔 UI).
+- 업로드는 단일 presigned PUT(~5GB 상한). 멀티파트는 백로그.
+
+## 개발
+
+```bash
+cd python
+uv venv && uv pip install -e ".[dev]"
+uv run pytest          # respx 모킹, 실 네트워크 없음
+uv run ruff check .
+```

robin_cloud_client-0.1.0/README.md

@@ -0,0 +1,59 @@
+# robin-cloud-client (Python)
+
+Robin-Cloud 스토리지·로그를 API 키로 이용하는 Python SDK.
+
+```bash
+pip install robin-cloud-client
+```
+
+## 사용
+
+```python
+from robincloud import RobinCloud
+
+rc = RobinCloud(api_key="rbk_…", project="raxis")
+# 또는 환경변수: ROBIN_CLOUD_API_KEY, ROBIN_CLOUD_BASE_URL
+
+# 스토리지
+rc.storage.create_bucket("assets")                       # storage:admin 스코프 필요
+rc.storage.upload("assets", "img/logo.png", data)        # presign→PUT→complete 자동
+raw = rc.storage.download("assets", "img/logo.png")      # -> bytes
+listing = rc.storage.list_objects("assets", prefix="img/")
+rc.storage.delete("assets", keys=["img/logo.png"])
+
+# 로그
+for src in rc.logs.sources():
+    print(src.pod, src.containers)
+print(rc.logs.tail(source="web-1", lines=200))
+
+rc.close()   # 또는 with RobinCloud(...) as rc:
+```
+
+## 에러
+
+상태코드가 타입 예외로 매핑된다: `AuthenticationError`(401), `PermissionDeniedError`(403),
+`NotFoundError`(404), `ConflictError`(409), `PayloadTooLargeError`(413), `ValidationError`(422),
+`ServiceUnavailableError`(503), 그 외 `ApiError`. 모두 `RobinCloudError` 하위.
+
+```python
+from robincloud import PermissionDeniedError
+try:
+    rc.storage.create_bucket("x")
+except PermissionDeniedError as e:
+    print(e.status_code, e.message)   # 403 "key is missing required scope 'storage:admin'"
+```
+
+## 범위
+
+- 스토리지(버킷·오브젝트·업로드/다운로드·이동·삭제·public URL) + 로그(소스·tail).
+- 키 발급/폐기는 세션 인증이라 SDK 범위 밖(콘솔 UI).
+- 업로드는 단일 presigned PUT(~5GB 상한). 멀티파트는 백로그.
+
+## 개발
+
+```bash
+cd python
+uv venv && uv pip install -e ".[dev]"
+uv run pytest          # respx 모킹, 실 네트워크 없음
+uv run ruff check .
+```

robin_cloud_client-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "robin-cloud-client"
+version = "0.1.0"
+description = "Python client for Robin-Cloud storage and logs (X-Api-Key auth)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "RobinTech" }]
+keywords = ["robin-cloud", "storage", "logs", "s3", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/robintech-seoul/robin-cloud-client"
+Repository = "https://github.com/robintech-seoul/robin-cloud-client"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/robincloud"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

robin_cloud_client-0.1.0/src/robincloud/__init__.py

@@ -0,0 +1,38 @@
+"""robin-cloud-client — Robin-Cloud 스토리지·로그 Python SDK (X-Api-Key 인증)."""
+
+from .client import RobinCloud
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RobinCloudError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import Bucket, Folder, LogSource, ObjectEntry, ObjectListing, UploadResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RobinCloud",
+    # errors
+    "RobinCloudError",
+    "ApiError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "PayloadTooLargeError",
+    "ValidationError",
+    "ServiceUnavailableError",
+    # models
+    "Bucket",
+    "Folder",
+    "ObjectEntry",
+    "ObjectListing",
+    "UploadResult",
+    "LogSource",
+]

robin_cloud_client-0.1.0/src/robincloud/client.py

@@ -0,0 +1,91 @@
+"""RobinCloud — 진입 클라이언트. api-key 인증 + 프로젝트 기본값 + HTTP 계층."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+from .errors import RobinCloudError, error_for_response
+from .logs import LogsClient
+from .storage import StorageClient
+
+DEFAULT_BASE_URL = "https://console.robintech.cloud"
+_API_PREFIX = "/api/v1"
+
+
+class RobinCloud:
+    """Robin-Cloud 스토리지·로그 동기 클라이언트.
+
+    사용:
+        rc = RobinCloud(api_key="rbk_…", project="raxis")
+        rc.storage.upload("assets", "img/logo.png", data)
+        rc.logs.tail(source="web-1")
+
+    Args:
+        api_key: `rbk_…` 형식 API 키. 생략 시 환경변수 `ROBIN_CLOUD_API_KEY`.
+        project: 스토리지·로그 호출의 기본 프로젝트명. 호출별로 override 가능.
+        base_url: 콘솔 호스트. 생략 시 `ROBIN_CLOUD_BASE_URL` 또는
+            `https://console.robintech.cloud`.
+        timeout: 초 단위 요청 타임아웃(기본 30). 대용량 업로드/다운로드는 늘려라.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        project: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.environ.get("ROBIN_CLOUD_API_KEY")
+        if not key:
+            raise RobinCloudError(
+                "api_key is required (pass api_key=… or set ROBIN_CLOUD_API_KEY)"
+            )
+        base = (base_url or os.environ.get("ROBIN_CLOUD_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+        self._project = project
+        self._base_url = base
+        self._api_key = key
+        # BFF 호출용 인증 클라이언트. presigned S3 호출은 별도(api-key 미첨부).
+        self._http = httpx.Client(
+            base_url=base + _API_PREFIX,
+            headers={"X-Api-Key": key},
+            timeout=timeout,
+        )
+        self.storage = StorageClient(self)
+        self.logs = LogsClient(self)
+
+    # ── 내부 ───────────────────────────────────────────────────────────
+
+    def _resolve_project(self, project: Optional[str]) -> str:
+        p = project or self._project
+        if not p:
+            raise RobinCloudError(
+                "project is required — pass project=… to the call or set it on the client"
+            )
+        return p
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """BFF 요청(api-key 자동 첨부). 4xx/5xx는 타입 예외로 변환."""
+        resp = self._http.request(method, path, **kwargs)
+        if resp.is_error:
+            try:
+                body: Any = resp.json()
+            except Exception:
+                body = resp.text
+            raise error_for_response(resp.status_code, body)
+        return resp
+
+    # ── 수명주기 ───────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "RobinCloud":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

robin_cloud_client-0.1.0/src/robincloud/errors.py

@@ -0,0 +1,80 @@
+"""예외 계층 — HTTP 상태코드를 타입 있는 예외로 매핑한다 (docs/api-surface.md 에러 규약).
+
+상태코드가 계약이고 응답 바디 셰이프는 보장 대상이 아니므로(spec §7.3), 메시지는
+`detail`(FastAPI 기본)과 `error.message`(도메인 핸들러) 양쪽에서 관대하게 뽑는다.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class RobinCloudError(Exception):
+    """모든 SDK 예외의 베이스."""
+
+
+class ApiError(RobinCloudError):
+    """HTTP 에러 응답 — status_code와 서버 메시지를 담는다."""
+
+    def __init__(self, status_code: int, message: str, *, body: Any = None) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthenticationError(ApiError):
+    """401 — 키가 없거나 무효·폐기·만료."""
+
+
+class PermissionDeniedError(ApiError):
+    """403 — 스코프/프로젝트 바인딩/발급자 레벨 부족."""
+
+
+class NotFoundError(ApiError):
+    """404 — 버킷·오브젝트 없음(존재 은닉 포함)."""
+
+
+class ConflictError(ApiError):
+    """409 — 버킷 이름 중복, 비어있지 않은 버킷 삭제, 이동 대상 충돌 등."""
+
+
+class PayloadTooLargeError(ApiError):
+    """413 — 오브젝트가 max_object_bytes 초과 또는 버킷 쿼터 초과."""
+
+
+class ValidationError(ApiError):
+    """422 — 요청 검증 실패(잘못된 키·버킷명 등)."""
+
+
+class ServiceUnavailableError(ApiError):
+    """503 — 스토리지 기능 휴면(서버에 ROBIN_STORAGE_BUCKET 미설정) 또는 백엔드 일시 불가."""
+
+
+_STATUS_MAP = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    422: ValidationError,
+    503: ServiceUnavailableError,
+}
+
+
+def _extract_message(body: Any, fallback: str) -> str:
+    if isinstance(body, dict):
+        # FastAPI 기본: {"detail": "..."}. 도메인 핸들러: {"error": {"message": "..."}}.
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        err = body.get("error")
+        if isinstance(err, dict) and isinstance(err.get("message"), str):
+            return err["message"]
+    return fallback
+
+
+def error_for_response(status_code: int, body: Any, fallback: Optional[str] = None) -> ApiError:
+    message = _extract_message(body, fallback or f"HTTP {status_code}")
+    cls = _STATUS_MAP.get(status_code, ApiError)
+    return cls(status_code, message, body=body)

robin_cloud_client-0.1.0/src/robincloud/logs.py

@@ -0,0 +1,50 @@
+"""로그 네임스페이스 — `rc.logs.*`. 컴포넌트 파드의 최근 로그 tail 조회.
+
+서버는 serve의 `{status, data}` 봉투를 전달한다. SDK는 `data` 안쪽을 꺼내 준다.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+
+from .models import LogSource
+
+if TYPE_CHECKING:
+    from .client import RobinCloud
+
+_MAX_TAIL = 5000
+
+
+class LogsClient:
+    def __init__(self, rc: "RobinCloud") -> None:
+        self._rc = rc
+
+    def _base(self, project: Optional[str]) -> str:
+        return f"/projects/{self._rc._resolve_project(project)}"
+
+    def sources(self, *, project: Optional[str] = None) -> List[LogSource]:
+        """로그를 볼 수 있는 소스(파드+컨테이너) 목록."""
+        resp = self._rc._request("GET", f"{self._base(project)}/log-sources")
+        data = resp.json().get("data", {})
+        return [LogSource.from_api(s) for s in data.get("sources", [])]
+
+    def tail(
+        self,
+        source: str,
+        *,
+        container: Optional[str] = None,
+        lines: int = 1000,
+        project: Optional[str] = None,
+    ) -> str:
+        """선택한 파드/컨테이너의 최근 로그 tail 문자열.
+
+        Args:
+            source: 파드 이름(`sources()`의 `pod`).
+            container: 멀티컨테이너 파드에서 지정(생략 시 첫 컨테이너).
+            lines: 최근 N줄(서버 상한 5000).
+        """
+        params = {"source": source, "tail": min(lines, _MAX_TAIL)}
+        if container:
+            params["container"] = container
+        resp = self._rc._request("GET", f"{self._base(project)}/logs", params=params)
+        return resp.json().get("data", {}).get("content", "")

robin_cloud_client-0.1.0/src/robincloud/models.py

@@ -0,0 +1,105 @@
+"""응답 데이터 모델 — 서버 JSON을 감싸는 얇은 dataclass.
+
+미지 필드는 무시(관대한 파싱)해 서버가 필드를 추가해도 SDK가 깨지지 않는다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Bucket:
+    name: str
+    public: bool
+    used_bytes: int
+    quota_bytes: Optional[int]
+    object_count: int
+    created_at: Optional[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "Bucket":
+        return cls(
+            name=d["name"],
+            public=bool(d.get("public", False)),
+            used_bytes=int(d.get("used_bytes", 0) or 0),
+            quota_bytes=d.get("quota_bytes"),
+            object_count=int(d.get("object_count", 0) or 0),
+            created_at=d.get("created_at"),
+        )
+
+
+@dataclass
+class ObjectEntry:
+    name: str
+    key: Optional[str] = None
+    size_bytes: Optional[int] = None
+    content_type: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "ObjectEntry":
+        return cls(
+            name=d.get("name") or d.get("key", ""),
+            key=d.get("key"),
+            size_bytes=d.get("size_bytes"),
+            content_type=d.get("content_type"),
+            updated_at=d.get("updated_at"),
+        )
+
+
+@dataclass
+class Folder:
+    name: str
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "Folder":
+        return cls(name=d["name"])
+
+
+@dataclass
+class ObjectListing:
+    objects: List[ObjectEntry]
+    folders: List[Folder]
+    next_cursor: Optional[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "ObjectListing":
+        return cls(
+            objects=[ObjectEntry.from_api(o) for o in d.get("objects", [])],
+            folders=[Folder.from_api(f) for f in d.get("folders", [])],
+            next_cursor=d.get("next_cursor"),
+        )
+
+
+@dataclass
+class UploadResult:
+    key: str
+    size_bytes: int
+    etag: Optional[str]
+    status: str
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "UploadResult":
+        return cls(
+            key=d["key"],
+            size_bytes=int(d.get("size_bytes", 0) or 0),
+            etag=d.get("etag"),
+            status=d.get("status", "READY"),
+        )
+
+
+@dataclass
+class LogSource:
+    pod: str
+    status: Optional[str]
+    containers: List[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "LogSource":
+        return cls(
+            pod=d["pod"],
+            status=d.get("status"),
+            containers=list(d.get("containers", [])),
+        )