runta-sdk 0.2.2__tar.gz → 0.2.4__tar.gz

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runta-sdk
-Version: 0.2.2
+Version: 0.2.4
 Summary: Python SDK for Runta runtime management
 Author: Runta
 License-Expression: MIT
@@ -134,6 +134,37 @@ runtime.files.upload("./project", "/workspace/project")
 runtime.files.download("/workspace/dist", "./artifacts/")
 ```
 
+To merge a directory's **contents** into an existing local directory, use:
+
+```python
+runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+# AsyncRuntime exposes the same method:
+await runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+```
+
+This creates the destination if needed, overwrites matching files, and preserves
+unrelated files without appending `dist`. The source must be a directory (a
+source directory symlink is followed). File/directory conflicts raise an error;
+existing directories are never recursively removed. Empty sources preserve the
+existing destination and its root metadata. The merge is **not transactional**:
+failure or cancellation may leave partially merged files. Existing `download()`
+path and replacement behavior is unchanged.
+
+The new method reads the downloaded seekable archive directly, without a second
+archive or a complete staging copy. It always applies safe tar data filtering,
+including to members returned by an optional synchronous
+`filter(member, destination)` callback. Return `None` to skip a member, for
+example to ignore FIFOs and device nodes; by default these are rejected.
+Permissions follow `tarfile.data_filter` (including removal of unsafe mode bits
+and ownership). Safe links are preserved where supported; the standard library
+copies archive referents when link creation is unavailable. Unresolvable dangling
+symlinks are skipped on platforms that cannot create them, preserving any
+existing entry at that destination. The SDK uses native
+filtered link fallback when available and provides a safe compatibility path on
+older Python patch releases. A build without `tarfile.data_filter` still raises
+an error rather than extracting unsafely. As with standard tar extraction, do not
+allow another process to modify the destination concurrently during extraction.
+
 Runtime, Checkpoint, and Secret queries, file reads, Runtime creation and deletion,
 resource and egress updates, and streaming transfers retry transient failures
 with exponential backoff and full jitter. The default is 16 total attempts,

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/README.md

@@ -106,6 +106,37 @@ runtime.files.upload("./project", "/workspace/project")
 runtime.files.download("/workspace/dist", "./artifacts/")
 ```
 
+To merge a directory's **contents** into an existing local directory, use:
+
+```python
+runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+# AsyncRuntime exposes the same method:
+await runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+```
+
+This creates the destination if needed, overwrites matching files, and preserves
+unrelated files without appending `dist`. The source must be a directory (a
+source directory symlink is followed). File/directory conflicts raise an error;
+existing directories are never recursively removed. Empty sources preserve the
+existing destination and its root metadata. The merge is **not transactional**:
+failure or cancellation may leave partially merged files. Existing `download()`
+path and replacement behavior is unchanged.
+
+The new method reads the downloaded seekable archive directly, without a second
+archive or a complete staging copy. It always applies safe tar data filtering,
+including to members returned by an optional synchronous
+`filter(member, destination)` callback. Return `None` to skip a member, for
+example to ignore FIFOs and device nodes; by default these are rejected.
+Permissions follow `tarfile.data_filter` (including removal of unsafe mode bits
+and ownership). Safe links are preserved where supported; the standard library
+copies archive referents when link creation is unavailable. Unresolvable dangling
+symlinks are skipped on platforms that cannot create them, preserving any
+existing entry at that destination. The SDK uses native
+filtered link fallback when available and provides a safe compatibility path on
+older Python patch releases. A build without `tarfile.data_filter` still raises
+an error rather than extracting unsafely. As with standard tar extraction, do not
+allow another process to modify the destination concurrently during extraction.
+
 Runtime, Checkpoint, and Secret queries, file reads, Runtime creation and deletion,
 resource and egress updates, and streaming transfers retry transient failures
 with exponential backoff and full jitter. The default is 16 total attempts,

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/integrations/harbor/runta_harbor/environment.py

@@ -6,7 +6,6 @@ import json
 import os
 import shlex
 import tarfile
-import tempfile
 import time
 import uuid
 from abc import ABC, abstractmethod
@@ -51,6 +50,15 @@ _RUNTA_CONTAINER_CA_ENV = {
 }
 
 
+def transfer_tar_filter(
+    member: tarfile.TarInfo, destination: str
+) -> tarfile.TarInfo | None:
+    """Skip empty special nodes; supported Harbor releases may not export this."""
+    if member.isdev():
+        return None
+    return tarfile.data_filter(member, destination)
+
+
 def _with_runta_container_ca_env(
     env: dict[str, str] | None,
 ) -> dict[str, str]:
@@ -936,27 +944,11 @@ class RuntaEnvironment(BaseEnvironment):
     async def _runtime_download_dir(
         self, source_dir: str, target_dir: Path | str
     ) -> None:
-        # Resolve only the source directory: tar otherwise archives a top-level
-        # symlink rather than its contents. Keep nested-link extraction checks.
-        result = await self._runtime_exec_raw(
-            f"CDPATH= cd -P -- {shlex.quote(source_dir)} && pwd -P", timeout_sec=30
+        await self._require_runtime().files.download_dir_contents(
+            source_dir,
+            str(target_dir),
+            filter=transfer_tar_filter,
         )
-        self._check(result, "resolve download source directory")
-        source_dir = result.stdout.removesuffix("\n")
-        target = Path(target_dir)
-        target.mkdir(parents=True, exist_ok=True)
-        with tempfile.TemporaryDirectory() as tmp_dir:
-            source = Path(tmp_dir) / "contents"
-            await self._require_runtime().files.download(source_dir, str(source))
-            # Harbor downloads contents into an existing directory, whereas the
-            # SDK downloads the source directory itself to a staged destination.
-            # Retain Harbor's safe content merge, including existing destination
-            # symlink checks. This merge archive stays local.
-            archive_path = Path(tmp_dir) / "merge.tar"
-            with tarfile.open(archive_path, "w") as archive:
-                archive.add(source, arcname=".")
-            with tarfile.open(archive_path, "r") as archive:
-                archive.extractall(target, filter="data")
 
     async def _runtime_ensure_dirs(self, dirs: list[str]) -> None:
         if not dirs:

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "runta-sdk"
-version = "0.2.2"
+version = "0.2.4"
 description = "Python SDK for Runta runtime management"
 readme = "README.md"
 requires-python = ">=3.10"

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/runta_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runta-sdk
-Version: 0.2.2
+Version: 0.2.4
 Summary: Python SDK for Runta runtime management
 Author: Runta
 License-Expression: MIT
@@ -134,6 +134,37 @@ runtime.files.upload("./project", "/workspace/project")
 runtime.files.download("/workspace/dist", "./artifacts/")
 ```
 
+To merge a directory's **contents** into an existing local directory, use:
+
+```python
+runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+# AsyncRuntime exposes the same method:
+await runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+```
+
+This creates the destination if needed, overwrites matching files, and preserves
+unrelated files without appending `dist`. The source must be a directory (a
+source directory symlink is followed). File/directory conflicts raise an error;
+existing directories are never recursively removed. Empty sources preserve the
+existing destination and its root metadata. The merge is **not transactional**:
+failure or cancellation may leave partially merged files. Existing `download()`
+path and replacement behavior is unchanged.
+
+The new method reads the downloaded seekable archive directly, without a second
+archive or a complete staging copy. It always applies safe tar data filtering,
+including to members returned by an optional synchronous
+`filter(member, destination)` callback. Return `None` to skip a member, for
+example to ignore FIFOs and device nodes; by default these are rejected.
+Permissions follow `tarfile.data_filter` (including removal of unsafe mode bits
+and ownership). Safe links are preserved where supported; the standard library
+copies archive referents when link creation is unavailable. Unresolvable dangling
+symlinks are skipped on platforms that cannot create them, preserving any
+existing entry at that destination. The SDK uses native
+filtered link fallback when available and provides a safe compatibility path on
+older Python patch releases. A build without `tarfile.data_filter` still raises
+an error rather than extracting unsafely. As with standard tar extraction, do not
+allow another process to modify the destination concurrently during extraction.
+
 Runtime, Checkpoint, and Secret queries, file reads, Runtime creation and deletion,
 resource and egress updates, and streaming transfers retry transient failures
 with exponential backoff and full jitter. The default is 16 total attempts,

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/runta_sdk.egg-info/SOURCES.txt

@@ -336,6 +336,8 @@ tests/test_connection_pool.py
 tests/test_delete_runtime_retry.py
 tests/test_directory_upload.py
 tests/test_directory_upload_concurrency.py
+tests/test_download_dir_contents.py
+tests/test_download_dir_contents_live.py
 tests/test_execution.py
 tests/test_execution_result_stream.py
 tests/test_fetch_openapi.py

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/src/runta/__init__.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 
 import asyncio
 import time
+import tarfile
 import uuid
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from concurrent.futures import Future, ThreadPoolExecutor
 from dataclasses import dataclass, field
 from enum import Enum
@@ -1588,6 +1589,41 @@ class FileManager(_SdkOwnedHandle):
             destination_is_directory=destination_is_directory,
         )
 
+    def download_dir_contents(
+        self,
+        src: str,
+        dst: str,
+        *,
+        filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+    ) -> None:
+        """Merge a runtime directory's contents into a local directory.
+
+        Existing unrelated files are preserved and matching files overwritten.
+        Source directory links are followed; nested links are preserved when
+        supported. Safe data filtering is always enforced, including after a
+        custom tarfile-style filter. Special files are rejected unless skipped
+        by that callback. Permissions follow tarfile.data_filter semantics.
+
+        This operation is not transactional: failures or cancellation can leave
+        partially merged contents. A file/directory type conflict raises instead
+        of deleting a directory. An empty source preserves existing contents.
+
+        Args:
+            src: Source directory inside the runtime.
+            dst: Local directory, created if absent; no source name is appended.
+            filter: Optional synchronous (TarInfo, destination) callback. Return
+                None to skip a member. Async callbacks are not supported.
+
+        Examples:
+            >>> runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+        """
+        self._runtime._client._http.download_dir_contents(
+            self._runtime.id,
+            src,
+            Path(dst),
+            filter=filter,
+        )
+
 
 class AsyncFileManager(_SdkOwnedHandle):
     """Reads, writes, uploads, and downloads runtime files asynchronously."""
@@ -1662,6 +1698,41 @@ class AsyncFileManager(_SdkOwnedHandle):
             destination_is_directory=destination_is_directory,
         )
 
+    async def download_dir_contents(
+        self,
+        src: str,
+        dst: str,
+        *,
+        filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+    ) -> None:
+        """Merge a runtime directory's contents into a local directory.
+
+        Existing unrelated files are preserved and matching files overwritten.
+        Source directory links are followed; nested links are preserved when
+        supported. Safe data filtering is always enforced, including after a
+        custom tarfile-style filter. Special files are rejected unless skipped
+        by that callback. Permissions follow tarfile.data_filter semantics.
+
+        This operation is not transactional: failures or cancellation can leave
+        partially merged contents. A file/directory type conflict raises instead
+        of deleting a directory. An empty source preserves existing contents.
+
+        Args:
+            src: Source directory inside the runtime.
+            dst: Local directory, created if absent; no source name is appended.
+            filter: Optional synchronous (TarInfo, destination) callback. Return
+                None to skip a member. Async callbacks are not supported.
+
+        Examples:
+            >>> await runtime.files.download_dir_contents("/workspace/dist", "./artifacts")
+        """
+        await self._runtime._client._http.download_dir_contents(
+            self._runtime.id,
+            src,
+            Path(dst),
+            filter=filter,
+        )
+
 
 class RuntimeCheckpointManager(_SdkOwnedHandle):
     """Creates, lists, and deletes checkpoints for a runtime."""

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/src/runta/_internal/async_http.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from collections.abc import Awaitable, Mapping, Sequence
 from pathlib import Path
 import time
+import tarfile
 from typing import Any, Callable
 from uuid import uuid4
 
@@ -517,6 +518,29 @@ class _AsyncHttpClient:
             _file_io=self._file_io,
         )
 
+    async def download_dir_contents(
+        self,
+        runtime_id: str,
+        src: str,
+        dst: Path,
+        *,
+        filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+    ) -> None:
+        from .streaming_transfer import async_download_dir_contents
+
+        await async_download_dir_contents(
+            self.endpoint,
+            self.token,
+            runtime_id,
+            src,
+            dst,
+            filter=filter,
+            timeout=self.timeout,
+            attempts=self.retry_max_attempts,
+            _tls=self._websocket_tls,
+            _file_io=self._file_io,
+        )
+
     async def update_runtime_status(
         self, runtime_id: str, action: str
     ) -> _public.RuntimeInfo:

{runta_sdk-0.2.2 → runta_sdk-0.2.4}/src/runta/_internal/openapi/models/runtime.py

@@ -63,6 +63,8 @@ class Runtime:
             destination, bypassing secret injection, LLM capture, token saving, and model routing.
         vnc_error_code (None | str | Unset): Bounded machine-readable VNC startup failure code.
         error_code (None | str | Unset): Bounded machine-readable provisioning failure code.
+        error_message (None | str | Unset): Current runtime failure reason, bounded to 4096 UTF-8 bytes. Cleared when
+            the failure recovers.
     """
 
     display_name: str
@@ -92,6 +94,7 @@ class Runtime:
     tls_passthrough_hosts: list[str] | Unset = UNSET
     vnc_error_code: None | str | Unset = UNSET
     error_code: None | str | Unset = UNSET
+    error_message: None | str | Unset = UNSET
     additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
@@ -181,6 +184,12 @@ class Runtime:
         else:
             error_code = self.error_code
 
+        error_message: None | str | Unset
+        if isinstance(self.error_message, Unset):
+            error_message = UNSET
+        else:
+            error_message = self.error_message
+
         field_dict: dict[str, Any] = {}
         field_dict.update(self.additional_properties)
         field_dict.update(
@@ -218,6 +227,8 @@ class Runtime:
             field_dict["vnc_error_code"] = vnc_error_code
         if error_code is not UNSET:
             field_dict["error_code"] = error_code
+        if error_message is not UNSET:
+            field_dict["error_message"] = error_message
 
         return field_dict
 
@@ -379,6 +390,15 @@ class Runtime:
 
         error_code = _parse_error_code(d.pop("error_code", UNSET))
 
+        def _parse_error_message(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        error_message = _parse_error_message(d.pop("error_message", UNSET))
+
         runtime = cls(
             display_name=display_name,
             egress_policy=egress_policy,
@@ -407,6 +427,7 @@ class Runtime:
             tls_passthrough_hosts=tls_passthrough_hosts,
             vnc_error_code=vnc_error_code,
             error_code=error_code,
+            error_message=error_message,
         )
 
         runtime.additional_properties = d