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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runta-sdk
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for Runta runtime management
 Author: Runta
 License-Expression: MIT
@@ -134,6 +134,35 @@ 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. Use a current Python
+security patch release with safe tar link fallback; missing safety support 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.3}/README.md

@@ -106,6 +106,35 @@ 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. Use a current Python
+security patch release with safe tar link fallback; missing safety support 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.3}/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.3}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runta-sdk
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for Runta runtime management
 Author: Runta
 License-Expression: MIT
@@ -134,6 +134,35 @@ 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. Use a current Python
+security patch release with safe tar link fallback; missing safety support 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.3}/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.3}/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.3}/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.3}/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

{runta_sdk-0.2.2 → runta_sdk-0.2.3}/src/runta/_internal/streaming_transfer.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import copy
 import errno
 from contextlib import asynccontextmanager, contextmanager
 import json
@@ -17,7 +18,7 @@ import tempfile
 import threading
 import time
 from collections.abc import Callable
-from pathlib import Path
+from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Any, BinaryIO
 from urllib.parse import quote, urlsplit, urlunsplit
 
@@ -337,6 +338,77 @@ async def async_download_path(
             pool.close()
 
 
+def download_dir_contents(
+    endpoint: str,
+    token: str,
+    runtime_id: str,
+    src: str,
+    dst: Path,
+    *,
+    filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+    timeout: float,
+    attempts: int = _TRANSFER_ATTEMPTS,
+    _tls: _WebSocketTLS | None = None,
+) -> None:
+    """Download one seekable archive and merge its directory contents."""
+    with tempfile.TemporaryDirectory(prefix="runta-download-") as temp:
+        archive = Path(temp) / "payload.tar"
+        _retry_sync(
+            lambda: _sync_download_archive(
+                endpoint,
+                token,
+                runtime_id,
+                src,
+                archive,
+                timeout,
+                _tls=_tls,
+                directory_contents=True,
+            ),
+            attempts=attempts,
+        )
+        _extract_dir_contents(archive, dst, filter)
+
+
+async def async_download_dir_contents(
+    endpoint: str,
+    token: str,
+    runtime_id: str,
+    src: str,
+    dst: Path,
+    *,
+    filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+    timeout: float,
+    attempts: int = _TRANSFER_ATTEMPTS,
+    _tls: _WebSocketTLS | _AsyncWebSocketTLS | None = None,
+    _file_io: _AsyncFileIO | None = None,
+) -> None:
+    """Merge on the client's bounded, cancellation-safe file workers."""
+    owned_pool = _file_io is None
+    pool = _file_io or _AsyncFileIO(None, asyncio.get_running_loop)
+    try:
+        with pool.lease():
+            async with _async_download_workspace(pool) as temp:
+                archive = temp / "payload.tar"
+                await _retry_async(
+                    lambda: _async_download_archive(
+                        endpoint,
+                        token,
+                        runtime_id,
+                        src,
+                        archive,
+                        timeout,
+                        _tls=_tls,
+                        _file_io=pool,
+                        directory_contents=True,
+                    ),
+                    attempts=attempts,
+                )
+                await pool.run(_extract_dir_contents, archive, dst, filter)
+    finally:
+        if owned_pool:
+            pool.close()
+
+
 def execute(
     endpoint: str,
     token: str,
@@ -694,10 +766,11 @@ def _sync_download_archive(
     timeout: float,
     *,
     _tls: _WebSocketTLS | None = None,
+    directory_contents: bool = False,
 ) -> None:
-    parent, name = _remote_parent_and_name(src)
+    command, args = _download_archive_command(src, directory_contents)
     with _sync_socket(endpoint, token, runtime_id, timeout, _tls=_tls) as socket:
-        _send_start(socket.send, "tar", ["cf", "-", "-C", parent, name])
+        _send_start(socket.send, command, args)
         _send_close_stdin(socket.send)
         with archive.open("wb") as handle:
             _receive_completion(socket.recv, stdout=handle)
@@ -713,10 +786,11 @@ async def _async_download_archive(
     *,
     _tls: _WebSocketTLS | _AsyncWebSocketTLS | None = None,
     _file_io: _AsyncFileIO,
+    directory_contents: bool = False,
 ) -> None:
-    parent, name = _remote_parent_and_name(src)
+    command, args = _download_archive_command(src, directory_contents)
     async with _async_socket(endpoint, token, runtime_id, timeout, _tls=_tls) as socket:
-        await _async_send_start(socket.send, "tar", ["cf", "-", "-C", parent, name])
+        await _async_send_start(socket.send, command, args)
         await _async_send_close_stdin(socket.send)
         writer = _AsyncDownloadWriter(_file_io, archive)
         try:
@@ -1041,6 +1115,155 @@ async def _retry_async(
     )
 
 
+def _download_archive_command(
+    src: str, directory_contents: bool
+) -> tuple[str, list[str]]:
+    if directory_contents:
+        # cd follows only the source directory link; tar preserves nested links.
+        # Positional arguments preserve arbitrary names without shell interpolation.
+        return "sh", [
+            "-c",
+            'set -eu; CDPATH= cd -P -- "$1"; exec tar cf - .',
+            "_",
+            src,
+        ]
+    parent, name = _remote_parent_and_name(src)
+    return "tar", ["cf", "-", "-C", parent, name]
+
+
+def _safe_relative_name(name: str) -> None:
+    # Archive names are POSIX paths even on Windows. Reject Windows aliases too,
+    # so drive paths, separators and alternate data streams cannot bypass checks.
+    if (
+        not name
+        or "\\" in name
+        or ":" in name
+        or "\x00" in name
+        or PurePosixPath(name).is_absolute()
+        or PureWindowsPath(name).drive
+        or ".." in PurePosixPath(name).parts
+    ):
+        raise tarfile.FilterError("download archive contains an unsafe path")
+
+
+class _DirectoryMergeTarFile(tarfile.TarFile):
+    """Replace file entries without writing through existing destination aliases."""
+
+    def makefile(self, tarinfo: tarfile.TarInfo, targetpath: str) -> None:
+        # Do this at the actual write path, after filtering. A filter can also
+        # run for a link fallback's referent, whose path must remain untouched.
+        target = Path(targetpath)
+        if target.is_dir():
+            raise FileExistsError(
+                f"download member conflicts with destination type: {target}"
+            )
+        target.unlink(missing_ok=True)
+        super().makefile(tarinfo, targetpath)
+
+
+def _extract_dir_contents(
+    archive_path: Path,
+    dst: Path,
+    filter: Callable[[tarfile.TarInfo, str], tarfile.TarInfo | None] | None = None,
+) -> None:
+    data_filter = getattr(tarfile, "data_filter", None)
+    if data_filter is None or not hasattr(tarfile.TarFile, "makelink_with_filter"):
+        raise RuntimeError(
+            "directory content downloads require a security-patched Python "
+            "with tarfile.data_filter and filtered link fallback"
+        )
+    if dst.is_symlink():
+        raise tarfile.FilterError("download destination must not be a symbolic link")
+    with _DirectoryMergeTarFile.open(archive_path, "r:", errorlevel=1) as archive:
+        members = archive.getmembers()
+        if not members or members[0].name not in {".", "./"} or not members[0].isdir():
+            raise _public.ApiError(
+                "download archive did not contain a source directory"
+            )
+        # Rewrite the seekable archive's index as well as extraction members.
+        # tarfile uses this index (and the original data offsets) for link fallback.
+        for member in members:
+            _safe_relative_name(member.name)
+            if member.name in {".", "./"}:
+                if not member.isdir():
+                    raise tarfile.FilterError("invalid source directory member")
+                member.name = "."
+            elif member.name.startswith("./"):
+                member.name = member.name[2:]
+                _safe_relative_name(member.name)
+            else:
+                raise tarfile.FilterError(
+                    "download archive member is outside the source directory"
+                )
+            if member.islnk():
+                _safe_relative_name(member.linkname)
+                if not member.linkname.startswith("./"):
+                    raise tarfile.FilterError(
+                        "hard link is outside the source directory"
+                    )
+                member.linkname = member.linkname[2:]
+                _safe_relative_name(member.linkname)
+
+        dst.mkdir(parents=True, exist_ok=True)
+
+        def safe_filter(
+            member: tarfile.TarInfo, destination: str
+        ) -> tarfile.TarInfo | None:
+            if member.name == ".":
+                return None  # Do not apply the source root's metadata to dst.
+            _safe_relative_name(member.name)
+            # Check boundaries before invoking user code, but allow the callback
+            # to skip special files before data_filter rejects those file types.
+            if member.issym() or member.islnk():
+                link = member.linkname
+                if (
+                    PurePosixPath(link).is_absolute()
+                    or PureWindowsPath(link).drive
+                    or "\\" in link
+                    or ":" in link
+                    or "\x00" in link
+                ):
+                    raise tarfile.FilterError(
+                        "download archive contains an unsafe link"
+                    )
+            probe = copy.copy(member)
+            if probe.isdev():
+                probe.type = tarfile.REGTYPE
+            data_filter(probe, destination)
+            if filter is not None:
+                member = filter(copy.copy(member), destination)
+                if member is None:
+                    return None
+            _safe_relative_name(member.name)
+            if PurePosixPath(member.name) == PurePosixPath("."):
+                raise tarfile.FilterError(
+                    "a filter cannot replace the destination root"
+                )
+            if member.issym() or member.islnk():
+                link = member.linkname
+                if (
+                    PurePosixPath(link).is_absolute()
+                    or PureWindowsPath(link).drive
+                    or "\\" in link
+                    or ":" in link
+                    or "\x00" in link
+                ):
+                    raise tarfile.FilterError(
+                        "download archive contains an unsafe link"
+                    )
+            member = data_filter(member, destination)
+            target = Path(destination) / member.name
+            if target.exists() and target.is_dir() != member.isdir():
+                raise FileExistsError(
+                    f"download member conflicts with destination type: {target}"
+                )
+            return member
+
+        # errorlevel=1 (the default) propagates security/I/O failures while
+        # allowing stdlib's nonfatal unresolved-link fallback to skip a link.
+        archive.extractall(dst, filter=safe_filter)
+
+
 def _remote_parent_and_name(src: str) -> tuple[str, str]:
     normalized = src.rstrip("/") or "/"
     path = Path(normalized)