instance-repo 1.6.0.dev0__tar.gz → 1.6.0.dev2__tar.gz

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.6.0.dev0
+Version: 1.6.0.dev2
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/instance_repo/__init__.py

@@ -20,7 +20,7 @@ from .errors import (
     RegistrationFailed, TransportError,
 )
 
-__version__ = "1.6.0.dev0"
+__version__ = "1.6.0.dev2"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/instance_repo/clients/instances.py

@@ -571,10 +571,19 @@ class InstancesClient:
     def delete(self, dataset: str, version: str, instance_id: str, *,
                split: str | None = None,
                environment: str | None = None,
-               metadata_model: str | None = None) -> None:
+               metadata_model: str | None = None,
+               delete_files: bool = False) -> None:
         """删除单个实例的元数据记录（``DELETE /datasets/instances/detail``）。
 
-        仅删除 MongoDB 记录，不删除 OSS 对象。后续 ingest 扫描可能重建该记录。
+        默认仅删除 MongoDB 记录，后续 ingest 可能重建记录。
+
+        ``delete_files=True`` 显式删除 canonical split-first 布局下该实例的
+        JSON、assets 和 report 子树，然后删除数据库记录。不会删除 ACR 镜像或
+        OSS 历史版本。仅走私网，要求服务端签发 ListObjects/DeleteObject 权限；
+        SDK 不授予或推断 Admin/Writer 权限，实际权限以服务端和 OSS 为准。
+        OSS 失败时保留数据库记录；数据库失败时文件可能已删，原参数可重试。
+        此操作不具备跨 OSS/数据库事务性，调用方必须先停止同实例的上传/ingest。
+        非 canonical storage_path 不支持文件删除，不能用 manifest 扩大删除范围。
         """
         from urllib.parse import quote
         if not (dataset or "").strip():
@@ -598,8 +607,96 @@ class InstancesClient:
             requested_model = getattr(self._p, "metadata_model", None)
         params.append(("metadata_model",
                        business_metadata_model(requested_model)))
+        if not isinstance(delete_files, bool):
+            raise SchemaError("delete_files must be a bool")
+        if delete_files:
+            self._delete_instance_files(
+                dataset.strip(), (version or "").strip(), instance_id.strip(),
+                split=split, environment=env,
+                metadata_model=requested_model)
         qs = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
-        self._t.delete(f"/apis/v1/datasets/instances/detail?{qs}")
+        failure = None
+        try:
+            self._t.delete(f"/apis/v1/datasets/instances/detail?{qs}")
+        except Exception as exc:
+            if not delete_files:
+                raise
+            status = getattr(exc, "status", None)
+            code = getattr(exc, "biz_code", None)
+            failure = TransportError(
+                "OSS files were removed but instance metadata deletion failed; "
+                "retry the same deletion after resolving server authorization or availability",
+                status=status if isinstance(status, int) else None,
+                biz_code=code if isinstance(code, int) else None)
+        # Raise after leaving the raw error handler: ``from None`` inside it
+        # hides the traceback but still retains signed URLs in __context__.
+        if failure is not None:
+            raise failure from None
+
+    def _delete_instance_files(self, dataset: str, version: str, instance_id: str, *,
+                               split: str | None, environment: str,
+                               metadata_model: str | None) -> None:
+        """Validate the complete locator before either storage or metadata mutation."""
+        lay = self._layout(metadata_model)
+        P.DatasetName.parse(dataset)
+        validate_instance_id(instance_id)
+        # Reject aliases/traversal instead of letting Layout strip slashes.
+        for name, value in (("version", version), ("split", split)):
+            if name == "version" and not value:
+                continue
+            if not isinstance(value, str) or value != value.strip():
+                raise SchemaError(f"{name} must be a canonical path segment")
+            validate_instance_id(value)
+        P.DatasetName.parse(lay.prefix)
+        bound_env = (getattr(self._p, "dataset_environment", "") or "").strip()
+        if not bound_env or environment != bound_env:
+            raise SchemaError(
+                "file deletion requires environment to match the storage profile")
+        bucket = getattr(self._p, "oss_bucket", "")
+        if not bucket or getattr(self._content, "bucket_name", None) != bucket:
+            raise SchemaError("file deletion requires a matching OSS content store")
+        operation = getattr(self._content, "delete_instance", None)
+        if not callable(operation):
+            raise SchemaError("content store does not support instance file deletion")
+        # Read the registered record without OSS discovery. A custom storage_path
+        # must never turn a canonical-layout delete into deletion of other bytes.
+        meta = self.get(dataset, version, instance_id, split,
+                        environment=environment, metadata_model=lay.model,
+                        fallback_to_oss=False)
+        if meta is None or (
+                meta.dataset, meta.dataset_version, meta.instance_id, meta.split
+        ) != (dataset, version, instance_id, split):
+            raise SchemaError("file deletion requires the matching registered instance")
+        main = lay.metadata_key(dataset, instance_id, version=version, split=split)
+        assets = lay.assets_dir(dataset, instance_id, version=version, split=split)
+        report = lay.report_key(dataset, instance_id, version=version, split=split)
+        main_uri = f"oss://{bucket}/{main}"
+        allowed = (f"oss://{bucket}/{assets}",
+                   f"oss://{bucket}/{report.rsplit('/', 1)[0]}/")
+        if not any(entry.file_path == main_uri for entry in meta.manifest):
+            raise SchemaError("file deletion requires a canonical metadata JSON manifest")
+        for entry in meta.manifest:
+            uri = entry.file_path
+            if not isinstance(uri, str) or not (
+                    uri == main_uri or any(
+                        uri == prefix.rstrip("/") or uri.startswith(prefix)
+                        for prefix in allowed)):
+                raise SchemaError(
+                    "file deletion only supports canonical instance manifests")
+        failure = None
+        try:
+            operation(dataset, version, instance_id, split=split, layout=lay)
+        except Exception as exc:
+            # Do not propagate OSS exceptions containing signed URLs/credentials.
+            status = getattr(exc, "status", None)
+            failure = TransportError(
+                "instance file deletion failed; metadata was not deleted; "
+                "check server-issued ListObjects/DeleteObject permission and "
+                "private connectivity; files may be partially removed; "
+                "stop concurrent writers before retrying",
+                status=status if isinstance(status, int) else None)
+        if failure is not None:
+            raise failure from None
 
     def update(self, dataset: str, version: str, instance_id: str, *,
                split: str | None = None, dataset_split_id: str | None = None,

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/instance_repo/store/oss.py

@@ -485,6 +485,75 @@ class OssContentStore(BaseContentStore):
             _OperationIntent.NON_DOWNLOAD, prefix, dataset, list_all,
             list_only=list_only)
 
+    def delete_instance(self, dataset: str, version: str, instance_id: str, *,
+                        split: str, layout) -> None:
+        """Delete only one canonical instance, using server-issued STS privately.
+
+        Per subtree: at most 1000 pages of 200 objects, O(200) memory, sequential
+        requests and existing bounded transport retries. Stop writers/ingesters
+        before calling; this is not an atomic delete or a version-history purge.
+        """
+        from ..errors import SchemaError
+        from ..validate import validate_instance_id
+
+        P.DatasetName.parse(dataset)
+        P.DatasetName.parse(layout.prefix)
+        for value in (instance_id, split):
+            validate_instance_id(value)
+        if version:
+            validate_instance_id(version)
+        scope = layout.sts_prefix(dataset)
+        metadata = layout.metadata_key(dataset, instance_id, version=version, split=split)
+        prefixes = (
+            layout.assets_dir(dataset, instance_id, version=version, split=split),
+            layout.report_key(dataset, instance_id, version=version, split=split)
+            .rsplit("/", 1)[0] + "/",
+        )
+        if not all(key.startswith(scope) for key in (metadata, *prefixes)):
+            raise SchemaError("instance deletion escaped the dataset root")
+
+        def remove(list_bucket, delete_bucket):
+            for prefix in prefixes:
+                marker = ""
+                for _ in range(1000):
+                    page = self._do(lambda: list_bucket.list_objects(
+                        prefix=prefix, marker=marker, max_keys=200))
+                    objects = list(page.object_list)
+                    if len(objects) > 200:
+                        raise SchemaError("OSS deletion page exceeds the requested limit")
+                    keys = [obj.key for obj in objects]
+                    if any(not isinstance(key, str) or not key.startswith(prefix)
+                           or (marker and key <= marker) for key in keys):
+                        raise SchemaError("OSS deletion listing escaped its instance subtree")
+                    next_marker = page.next_marker
+                    if page.is_truncated and (
+                            not isinstance(next_marker, str)
+                            or not next_marker.startswith(prefix)
+                            or next_marker <= marker
+                            or (keys and next_marker < max(keys))):
+                        raise SchemaError("OSS deletion listing returned an invalid marker")
+                    for key in keys:
+                        self._do(lambda key=key: delete_bucket.delete_object(key))
+                    if not page.is_truncated:
+                        break
+                    marker = next_marker
+                else:
+                    raise SchemaError("OSS deletion page budget exceeded; retry after quiescing writers")
+            # Remove the ingest source only after both scoped subtrees succeed.
+            self._do(lambda: delete_bucket.delete_object(metadata))
+
+        # Reuse the existing strict private-endpoint path (also used by downloads),
+        # without the public fallback used for ordinary non-download operations.
+        # Listing and object mutation are distinct grants on the server. Do not
+        # assume a normal writer/admin token includes ListObjects, or try to
+        # mutate with the discovery-only token.
+        list_bucket = self._execute_oss(
+            _OperationIntent.DOWNLOAD, scope, dataset, lambda bucket: bucket,
+            list_only=True)
+        delete_bucket = self._execute_oss(
+            _OperationIntent.DOWNLOAD, scope, dataset, lambda bucket: bucket)
+        remove(list_bucket, delete_bucket)
+
     def list_prefixes(self, prefix: str, *, list_only: bool = False,
                        dataset: str | None = None) -> list[str]:
         """List immediate child *directories* under *prefix* using ``delimiter='/'``.

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/instance_repo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.6.0.dev0
+Version: 1.6.0.dev2
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.6.0.dev0 → instance_repo-1.6.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.6.0.dev0"
+version = "1.6.0.dev2"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"