x4d-devkit 0.48.0rc3__tar.gz → 0.48.0rc5__tar.gz

{x4d_devkit-0.48.0rc3 → x4d_devkit-0.48.0rc5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.48.0rc3
+Version: 0.48.0rc5
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.48.0rc3 → x4d_devkit-0.48.0rc5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.48.0rc3"
+version = "0.48.0rc5"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"

x4d_devkit-0.48.0rc5/tests/test_image_export.py

@@ -0,0 +1,389 @@
+"""Synthetic offline export and typed-client tests; no platform or private media."""
+
+from copy import deepcopy
+from io import BytesIO
+import json
+import tarfile
+
+import httpx
+import pytest
+
+from tests.image_fixtures import IMAGE_BYTES, clip_payload, line_object
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import ImageContractError, canonical
+from x4d_devkit.image_clip import build_image_identity
+from x4d_devkit.image_export import (
+    COMPONENTS,
+    DOWNLOAD_CONTRACT,
+    EXPORT_CONTRACT,
+    EXPORT_README,
+    INDEX_CONTRACT,
+    JOB_CONTRACT,
+    PAGE_CONTRACT,
+    PREVIEW_CONTRACT,
+    clip_manifest_entry,
+    human_scope_index,
+    parse_image_export_job,
+    reference_path,
+    sha256,
+    validate_image_export_bundle,
+)
+
+EXPORT_ID = "imexp_" + "a" * 32
+NOW = "2026-10-26T12:00:00+00:00"
+
+
+def contents(*, references=False, state="unprocessed"):
+    clip = clip_payload()
+    if state != "confirmed_empty":
+        clip["image_annotation"]["objects"] = [line_object()]
+    clip["image_annotation"]["completion"][0]["state"] = state
+    clip["identity"] = build_image_identity(clip)
+    cid = clip["meta"]["clip_id"]
+    files = {f"clips/{cid}/{name}.json": canonical(clip[name]) for name in COMPONENTS}
+    files[f"consumption/{cid}/human_scopes.json"] = canonical(human_scope_index(clip))
+    if references:
+        for view in clip["meta"]["view_ids"]:
+            files[reference_path(cid, view)] = canonical(
+                {
+                    "contract_version": "x4d-image-preannotation-current-v1",
+                    "project_id": clip["meta"]["project_id"],
+                    "clip_id": cid,
+                    "view_id": view,
+                    "source_revision": clip["identity"]["source_revision"],
+                    "schema_fingerprint": clip["identity"]["schema_fingerprint"],
+                    "availability": "none",
+                    "published_at": None,
+                    "result_digest": None,
+                    "artifact": None,
+                }
+            )
+    for image in clip["sample_data"]:
+        files[f"clips/{cid}/{image['asset']['path']}"] = IMAGE_BYTES
+    return clip, files
+
+
+def bundle(tmp_path, clip, files, *, references=False, append=None, override=None):
+    cid = clip["meta"]["clip_id"]
+    index = canonical(
+        {
+            "contract_version": INDEX_CONTRACT,
+            "clip_id": cid,
+            "files": [
+                {"path": name, "size": len(raw), "sha256": sha256(raw)}
+                for name, raw in files.items()
+            ],
+        }
+    )
+    manifest = {
+        "contract_version": EXPORT_CONTRACT,
+        "export_id": EXPORT_ID,
+        "project_id": clip["meta"]["project_id"],
+        "created_at": NOW,
+        "include_preannotations": references,
+        "clips": [
+            clip_manifest_entry(clip, captured_at=NOW, file_index_sha256=sha256(index))
+        ],
+    }
+    entries = {
+        "manifest.json": canonical(manifest),
+        "README.md": EXPORT_README,
+        f"indexes/{cid}.json": index,
+        **files,
+    }
+    path = tmp_path / "export.tar"
+    with tarfile.open(path, "w") as archive:
+        for name, raw in entries.items():
+            info = tarfile.TarInfo(f"{EXPORT_ID}/{name}")
+            if override:
+                raw = override(name, raw)
+            info.size = len(raw)
+            archive.addfile(info, BytesIO(raw))
+        if append:
+            info = tarfile.TarInfo(append)
+            info.size = 1
+            archive.addfile(info, BytesIO(b"x"))
+    return path
+
+
+@pytest.mark.parametrize("state", ["unprocessed", "complete", "confirmed_empty"])
+@pytest.mark.parametrize("references", [False, True])
+def test_roundtrip_preserves_native_identity_and_explicit_completion(
+    tmp_path, state, references
+):
+    clip, files = contents(state=state, references=references)
+    result = validate_image_export_bundle(
+        bundle(tmp_path, clip, files, references=references)
+    )
+    assert result["images"] == 1
+    assert result["completion_counts"][state] >= 1
+    assert result["objects"] == (state != "confirmed_empty")
+    if state == "unprocessed":
+        assert result["completion_counts"]["complete"] == 0
+        assert result["completion_counts"]["confirmed_empty"] == 0
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "scope",
+        "scope-extra",
+        "missing",
+        "path",
+        "duplicate",
+        "identity",
+        "prediction-context",
+        "extra",
+    ],
+)
+def test_fail_closed_even_when_attacker_recomputes_transport_hashes(tmp_path, change):
+    clip, files = contents(references=True)
+    cid = clip["meta"]["clip_id"]
+    scope = f"consumption/{cid}/human_scopes.json"
+    append = None
+    if change.startswith("scope"):
+        value = json.loads(files[scope])
+        if change == "scope":
+            value["scopes"][0]["state"] = "complete"
+        else:
+            value["unexpected"] = True
+        files[scope] = canonical(value)
+    if change == "missing":
+        files.pop(scope)
+    if change == "path":
+        files["../escape"] = b"x"
+    if change == "duplicate":
+        append = f"{EXPORT_ID}/{scope}"
+    if change == "identity":
+        value = json.loads(files[f"clips/{cid}/identity.json"])
+        value["annotation_revision"] = "sha256:" + "0" * 64
+        files[f"clips/{cid}/identity.json"] = canonical(value)
+    if change == "prediction-context":
+        name = reference_path(cid, clip["meta"]["view_ids"][0])
+        value = json.loads(files[name])
+        value["source_revision"] = "sha256:" + "0" * 64
+        files[name] = canonical(value)
+    if change == "extra":
+        files[f"clips/{cid}/password.json"] = b"{}"
+    with pytest.raises((ImageContractError, ValueError)):
+        validate_image_export_bundle(
+            bundle(tmp_path, clip, files, references=True, append=append)
+        )
+
+
+def test_corrupt_bytes_and_budget_are_rejected_without_extraction(tmp_path):
+    clip, files = contents()
+    path = bundle(
+        tmp_path,
+        clip,
+        files,
+        override=lambda name, raw: b"z" * len(raw) if name.endswith(".jpg") else raw,
+    )
+    with pytest.raises(ImageContractError, match="SHA256"):
+        validate_image_export_bundle(path)
+    path = bundle(tmp_path, clip, files)
+    with pytest.raises(ImageContractError, match="budget"):
+        validate_image_export_bundle(path, max_json_bytes=10)
+    assert list(tmp_path.iterdir()) == [path]
+
+
+def job(status="queued"):
+    completed = status == "completed"
+    terminal = status in {"completed", "failed", "cancelled"}
+    return {
+        "contract_version": JOB_CONTRACT,
+        "export_id": EXPORT_ID,
+        "project_id": 7,
+        "clip_ids": ["clip_test"],
+        "include_preannotations": False,
+        "status": status,
+        "progress": {
+            "stage": status,
+            "processed": 0,
+            "total": 1,
+            "bytes": 0,
+            "elapsed_s": 0.0,
+            "rate": 0.0,
+            "eta_s": None,
+        },
+        "error": {"code": "test_failure", "message": "Explicit failure"}
+        if status == "failed"
+        else None,
+        "artifact": {"filename": EXPORT_ID + ".tar", "size": 10240, "sha256": "b" * 64}
+        if completed
+        else None,
+        "created_at": NOW,
+        "completed_at": NOW if terminal else None,
+        "can_cancel": not terminal,
+    }
+
+
+@pytest.mark.parametrize(
+    "status",
+    [
+        "queued",
+        "capturing",
+        "packaging",
+        "validating",
+        "uploading",
+        "completed",
+        "failed",
+        "cancelled",
+    ],
+)
+def test_job_states_are_strict(status):
+    assert parse_image_export_job(job(status)).to_dict()["status"] == status
+
+
+@pytest.mark.parametrize(
+    "change",
+    ["error", "artifact", "processed", "bool", "unknown", "terminal", "infinite"],
+)
+def test_invalid_job_states_fail(change):
+    value = job()
+    if change == "error":
+        value["error"] = {"code": "oops", "message": "not failed"}
+    if change == "artifact":
+        value["artifact"] = job("completed")["artifact"]
+    if change == "processed":
+        value["progress"]["processed"] = 2
+    if change == "bool":
+        value["project_id"] = True
+    if change == "unknown":
+        value["model_version"] = "forbidden"
+    if change == "terminal":
+        value["completed_at"] = NOW
+    if change == "infinite":
+        value["progress"]["rate"] = float("inf")
+    with pytest.raises((ImageContractError, ValueError)):
+        parse_image_export_job(value)
+
+
+def test_typed_client_scope_and_ephemeral_download_do_not_forward_credentials():
+    calls = []
+
+    def handler(request):
+        calls.append(request)
+        path = request.url.path
+        if path.endswith("/preview"):
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": PREVIEW_CONTRACT,
+                    "project_id": 7,
+                    "clip_id": "clip_test",
+                    "include_preannotations": False,
+                    "clip_ids": ["clip_test"],
+                    "excluded": [],
+                    "scope_token": "opaque-token",
+                    "expires_at": NOW,
+                },
+            )
+        if path.endswith("/download-link"):
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": DOWNLOAD_CONTRACT,
+                    "export_id": EXPORT_ID,
+                    "url": "http://storage.test/bucket/object?signature=private",
+                    "expires_at": NOW,
+                    **job("completed")["artifact"],
+                },
+            )
+        if path == "/api/v1/image-exports" and request.method == "GET":
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": PAGE_CONTRACT,
+                    "project_id": 7,
+                    "page": 1,
+                    "page_size": 50,
+                    "total": 1,
+                    "items": [job()],
+                },
+            )
+        return httpx.Response(200, json=job())
+
+    client = X4DClient("http://platform.test", token="platform-private-token")
+    client._http = httpx.Client(
+        base_url="http://platform.test",
+        headers={"Authorization": "Bearer platform-private-token"},
+        transport=httpx.MockTransport(handler),
+    )
+    preview = client.image_exports.preview(project_id=7, clip_id="clip_test")
+    created = client.image_exports.create(
+        project_id=7,
+        clip_id="clip_test",
+        scope_token=preview.to_dict()["scope_token"],
+        idempotency_key="key",
+    )
+    assert created.to_dict()["export_id"] == EXPORT_ID
+    assert client.image_exports.list(project_id=7).to_dict()["total"] == 1
+    for action in ("get", "cancel", "retry"):
+        assert (
+            getattr(client.image_exports, action)(EXPORT_ID).to_dict()["export_id"]
+            == EXPORT_ID
+        )
+    assert (
+        client.image_exports.download_link(EXPORT_ID)
+        .to_dict()["url"]
+        .startswith("http://storage.test/")
+    )
+    assert all(request.url.host == "platform.test" for request in calls)
+    assert json.loads(calls[1].content) == {
+        "project_id": 7,
+        "clip_id": "clip_test",
+        "include_preannotations": False,
+        "scope_token": "opaque-token",
+        "idempotency_key": "key",
+    }
+    with pytest.raises(ImageContractError):
+        client.image_exports.preview(project_id=True)
+    client.close()
+
+
+def test_client_rejects_foreign_response():
+    client = X4DClient("http://platform.test")
+    other = deepcopy(job())
+    other["export_id"] = "imexp_" + "c" * 32
+    client._http = httpx.Client(
+        base_url="http://platform.test",
+        transport=httpx.MockTransport(lambda r: httpx.Response(200, json=other)),
+    )
+    with pytest.raises(ImageContractError, match="foreign"):
+        client.image_exports.get(EXPORT_ID)
+    client.close()
+
+
+def test_offline_cli_reports_valid_bundle(tmp_path, capsys):
+    from types import SimpleNamespace
+    from x4d_devkit.cli import cmd_validate_image_export
+
+    clip, files = contents()
+    path = bundle(tmp_path, clip, files)
+    cmd_validate_image_export(
+        SimpleNamespace(path=path, max_json_bytes=64 * 1024 * 1024)
+    )
+    assert json.loads(capsys.readouterr().out)["ok"] is True
+    path.write_bytes(b"invalid tar")
+    with pytest.raises(SystemExit) as error:
+        cmd_validate_image_export(
+            SimpleNamespace(path=path, max_json_bytes=64 * 1024 * 1024)
+        )
+    assert error.value.code == 1
+    assert json.loads(capsys.readouterr().out)["ok"] is False
+
+
+def test_archive_member_history_is_not_retained(tmp_path, monkeypatch):
+    clip, files = contents()
+    path = bundle(tmp_path, clip, files)
+    original = tarfile.TarFile.next
+    history = []
+
+    def measured(archive):
+        history.append(len(archive.members))
+        return original(archive)
+
+    monkeypatch.setattr(tarfile.TarFile, "next", measured)
+    validate_image_export_bundle(path)
+    assert max(history) <= 1