stellarmesh-storage 0.1.1__tar.gz

stellarmesh_storage-0.1.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: stellarmesh-storage
+Version: 0.1.1
+Summary: Stellarmesh 对象存储控制面与预签名数据面客户端
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+
+# stellarmesh-storage
+
+`stellarmesh-storage` 提供严格类型的同步与异步 Python 客户端，通过项目级 `storage-service` 获取预签名请求，并让对象字节直接在客户端与 S3 或 MinIO 之间传输。
+
+```python
+from stellarmesh_storage import Client, ClientConfig
+
+config = ClientConfig(
+    base_url="http://storage-service:8090",
+    token="storage-project-service-token-00000001",
+    timeout_seconds=5.0,
+    max_attempts=3,
+)
+
+with Client(config) as client:
+    client.upload_file("documents", "reports/a.pdf", "/work/a.pdf")
+    client.download_file("documents", "reports/a.pdf", "/work/result.pdf")
+```
+
+包提供 Stat、Delete、预签名 GET/PUT、显式 Multipart、单次文件上传和原子文件下载。控制面 service token 不会进入数据面请求，CreateMultipart 与 CompleteMultipart 不会因不确定结果自动重试。
+
+完整接入、重试和安全边界见仓库文档 `docs/sdk/python/storage.md`。

stellarmesh_storage-0.1.1/README.md

@@ -0,0 +1,22 @@
+# stellarmesh-storage
+
+`stellarmesh-storage` 提供严格类型的同步与异步 Python 客户端，通过项目级 `storage-service` 获取预签名请求，并让对象字节直接在客户端与 S3 或 MinIO 之间传输。
+
+```python
+from stellarmesh_storage import Client, ClientConfig
+
+config = ClientConfig(
+    base_url="http://storage-service:8090",
+    token="storage-project-service-token-00000001",
+    timeout_seconds=5.0,
+    max_attempts=3,
+)
+
+with Client(config) as client:
+    client.upload_file("documents", "reports/a.pdf", "/work/a.pdf")
+    client.download_file("documents", "reports/a.pdf", "/work/result.pdf")
+```
+
+包提供 Stat、Delete、预签名 GET/PUT、显式 Multipart、单次文件上传和原子文件下载。控制面 service token 不会进入数据面请求，CreateMultipart 与 CompleteMultipart 不会因不确定结果自动重试。
+
+完整接入、重试和安全边界见仓库文档 `docs/sdk/python/storage.md`。

stellarmesh_storage-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stellarmesh-storage"
+version = "0.1.1"
+description = "Stellarmesh 对象存储控制面与预签名数据面客户端"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+]
+
+[dependency-groups]
+dev = [
+  "build>=1,<2",
+  "jsonschema>=4,<5",
+  "mypy>=1.10,<2",
+  "openapi-spec-validator>=0.7,<1",
+  "PyYAML>=6,<7",
+  "pytest>=8,<9",
+  "pytest-asyncio>=0.23,<2",
+  "ruff>=0.6,<1",
+  "types-jsonschema>=4,<5",
+  "types-PyYAML>=6,<7",
+  "twine>=6,<7",
+]
+
+[tool.setuptools.package-data]
+stellarmesh_storage = ["py.typed"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["stellarmesh_storage"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "strict"
+testpaths = ["tests"]

stellarmesh_storage-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stellarmesh_storage-0.1.1/src/stellarmesh_storage/__init__.py

@@ -0,0 +1,45 @@
+"""Stellarmesh 对象存储客户端公共入口。"""
+
+from .async_client import AsyncClient
+from .client import Client
+from .errors import (
+    ClientClosedError,
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PreconditionFailedError,
+    StorageError,
+    UnauthorizedError,
+    UnavailableError,
+)
+from .models import (
+    Checksum,
+    ClientConfig,
+    CompletedPart,
+    MultipartUpload,
+    ObjectInfo,
+    PresignedRequest,
+)
+
+__all__ = [
+    "AsyncClient",
+    "Checksum",
+    "Client",
+    "ClientClosedError",
+    "ClientConfig",
+    "CompletedPart",
+    "ConflictError",
+    "ForbiddenError",
+    "InvalidRequestError",
+    "MultipartUpload",
+    "NotFoundError",
+    "ObjectInfo",
+    "PayloadTooLargeError",
+    "PreconditionFailedError",
+    "PresignedRequest",
+    "StorageError",
+    "UnauthorizedError",
+    "UnavailableError",
+]

stellarmesh_storage-0.1.1/src/stellarmesh_storage/_common.py

@@ -0,0 +1,105 @@
+"""同步和异步客户端共用的响应、重试与签名头处理。"""
+
+from __future__ import annotations
+
+import json
+from typing import TypeVar
+
+import httpx
+from pydantic import ValidationError
+
+from .constants import (
+    MAX_CONTROL_BODY_BYTES,
+    RETRYABLE_STATUS_CODES,
+    SERVICE_TOKEN_HEADER,
+)
+from .errors import (
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PreconditionFailedError,
+    StorageError,
+    UnauthorizedError,
+    UnavailableError,
+)
+from .models import ApiEnvelope, StrictModel
+
+ModelType = TypeVar("ModelType", bound=StrictModel)
+
+
+def retry_delay(attempt: int, initial: float, maximum: float) -> float:
+    """返回有上限的确定性指数退避。"""
+    return float(min(initial * (2 ** (attempt - 1)), maximum))
+
+
+def retryable_status(status_code: int) -> bool:
+    """判断 HTTP 状态是否允许安全操作重试。"""
+    return status_code in RETRYABLE_STATUS_CODES
+
+
+def parse_success(response: httpx.Response, model: type[ModelType]) -> ModelType:
+    """严格解析成功 envelope，不在异常中包含原始响应。"""
+    try:
+        envelope = ApiEnvelope[object].model_validate_json(response.content)
+        parsed = model.model_validate_json(json.dumps(envelope.data))
+    except (json.JSONDecodeError, ValidationError, ValueError) as error:
+        raise UnavailableError(
+            "storage service returned an invalid response",
+            status_code=response.status_code,
+        ) from error
+    if envelope.code != response.status_code:
+        raise UnavailableError(
+            "storage service returned an inconsistent response",
+            status_code=response.status_code,
+        )
+    return parsed
+
+
+def ensure_success(response: httpx.Response) -> None:
+    """校验不需要响应 data 的成功 envelope。"""
+    try:
+        envelope = ApiEnvelope[dict[str, object]].model_validate_json(response.content)
+    except (json.JSONDecodeError, ValidationError, ValueError) as error:
+        raise UnavailableError(
+            "storage service returned an invalid response",
+            status_code=response.status_code,
+        ) from error
+    if envelope.code != response.status_code:
+        raise UnavailableError(
+            "storage service returned an inconsistent response",
+            status_code=response.status_code,
+        )
+
+
+def response_error(status_code: int) -> StorageError:
+    """将服务或数据面状态转换为不含敏感信息的稳定异常。"""
+    mapping: dict[int, type[StorageError]] = {
+        400: InvalidRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        409: ConflictError,
+        412: PreconditionFailedError,
+        413: PayloadTooLargeError,
+    }
+    error_type = mapping.get(status_code, UnavailableError)
+    return error_type("storage request failed", status_code=status_code)
+
+
+def signed_headers(headers: dict[str, list[str]]) -> list[tuple[str, str]]:
+    """保留服务返回的全部 signed header 值。"""
+    if any(name.lower() == SERVICE_TOKEN_HEADER.lower() for name in headers):
+        raise UnavailableError("storage service returned a forbidden signed header")
+    return [(name, value) for name, values in headers.items() for value in values]
+
+
+def encode_control_payload(payload: dict[str, object]) -> bytes:
+    """生成有界 UTF-8 JSON 控制面请求。"""
+    encoded = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode(
+        "utf-8"
+    )
+    if len(encoded) > MAX_CONTROL_BODY_BYTES:
+        raise PayloadTooLargeError("storage control request exceeds 64 KiB")
+    return encoded

stellarmesh_storage-0.1.1/src/stellarmesh_storage/_operations.py

@@ -0,0 +1,183 @@
+"""同步与异步客户端共享的 Storage v1 控制面操作描述。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from .models import (
+    Checksum,
+    CompletedPart,
+    MultipartAbortRequest,
+    MultipartCompleteRequest,
+    MultipartCreateRequest,
+    MultipartPartRequest,
+    MultipartUpload,
+    ObjectInfo,
+    ObjectRequest,
+    PresignedRequest,
+    PresignGetRequest,
+    PresignPutRequest,
+    StrictModel,
+)
+
+ResponseType = TypeVar("ResponseType", bound=StrictModel)
+
+
+@dataclass(frozen=True, slots=True)
+class ModelOperation(Generic[ResponseType]):
+    """描述返回严格模型的控制面操作。"""
+
+    path: str
+    request: StrictModel
+    response_model: type[ResponseType]
+    retry: bool
+
+
+@dataclass(frozen=True, slots=True)
+class EmptyOperation:
+    """描述只校验成功 envelope 的控制面操作。"""
+
+    path: str
+    request: StrictModel
+    retry: bool
+
+
+def stat(
+    namespace: str, key: str, *, version_id: str | None
+) -> ModelOperation[ObjectInfo]:
+    return ModelOperation(
+        path="/v1/objects/stat",
+        request=ObjectRequest(namespace=namespace, key=key, version_id=version_id),
+        response_model=ObjectInfo,
+        retry=True,
+    )
+
+
+def delete(namespace: str, key: str, *, version_id: str | None) -> EmptyOperation:
+    return EmptyOperation(
+        path="/v1/objects/delete",
+        request=ObjectRequest(namespace=namespace, key=key, version_id=version_id),
+        retry=True,
+    )
+
+
+def presign_get(
+    namespace: str,
+    key: str,
+    *,
+    version_id: str | None,
+    expires_in: int,
+) -> ModelOperation[PresignedRequest]:
+    return ModelOperation(
+        path="/v1/presign/get",
+        request=PresignGetRequest(
+            namespace=namespace,
+            key=key,
+            version_id=version_id,
+            expires_in=expires_in,
+        ),
+        response_model=PresignedRequest,
+        retry=True,
+    )
+
+
+def presign_put(
+    namespace: str,
+    key: str,
+    *,
+    size: int,
+    content_type: str | None,
+    metadata: dict[str, str] | None,
+    checksum: Checksum | None,
+    expires_in: int,
+) -> ModelOperation[PresignedRequest]:
+    return ModelOperation(
+        path="/v1/presign/put",
+        request=PresignPutRequest(
+            namespace=namespace,
+            key=key,
+            size=size,
+            content_type=content_type,
+            metadata=metadata or {},
+            checksum=checksum,
+            expires_in=expires_in,
+        ),
+        response_model=PresignedRequest,
+        retry=True,
+    )
+
+
+def create_multipart(
+    namespace: str,
+    key: str,
+    *,
+    content_type: str | None,
+    metadata: dict[str, str] | None,
+    checksum: Checksum | None,
+) -> ModelOperation[MultipartUpload]:
+    return ModelOperation(
+        path="/v1/multipart/create",
+        request=MultipartCreateRequest(
+            namespace=namespace,
+            key=key,
+            content_type=content_type,
+            metadata=metadata or {},
+            checksum=checksum,
+        ),
+        response_model=MultipartUpload,
+        retry=False,
+    )
+
+
+def presign_part(
+    namespace: str,
+    key: str,
+    upload_id: str,
+    part_number: int,
+    *,
+    expires_in: int,
+) -> ModelOperation[PresignedRequest]:
+    return ModelOperation(
+        path="/v1/multipart/presign-part",
+        request=MultipartPartRequest(
+            namespace=namespace,
+            key=key,
+            upload_id=upload_id,
+            part_number=part_number,
+            expires_in=expires_in,
+        ),
+        response_model=PresignedRequest,
+        retry=True,
+    )
+
+
+def complete_multipart(
+    namespace: str,
+    key: str,
+    upload_id: str,
+    parts: list[CompletedPart],
+) -> ModelOperation[ObjectInfo]:
+    return ModelOperation(
+        path="/v1/multipart/complete",
+        request=MultipartCompleteRequest(
+            namespace=namespace,
+            key=key,
+            upload_id=upload_id,
+            parts=parts,
+        ),
+        response_model=ObjectInfo,
+        retry=False,
+    )
+
+
+def abort_multipart(namespace: str, key: str, upload_id: str) -> EmptyOperation:
+    return EmptyOperation(
+        path="/v1/multipart/abort",
+        request=MultipartAbortRequest(
+            namespace=namespace,
+            key=key,
+            upload_id=upload_id,
+        ),
+        retry=True,
+    )