wehub-resource-sync
1189 lines
44 KiB
Python
1189 lines
44 KiB
Python
import abc
|
|
import io
|
|
import shlex
|
|
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
|
from pathlib import Path, PurePath
|
|
from typing import Literal, TypeVar
|
|
|
|
from typing_extensions import Self
|
|
|
|
from ...editor import ApplyPatchOperation
|
|
from ...run_config import (
|
|
DEFAULT_MAX_LOCAL_DIR_FILE_CONCURRENCY,
|
|
DEFAULT_MAX_MANIFEST_ENTRY_CONCURRENCY,
|
|
SandboxArchiveLimits,
|
|
SandboxConcurrencyLimits,
|
|
)
|
|
from ..apply_patch import PatchFormat, WorkspaceEditor
|
|
from ..entries import BaseEntry
|
|
from ..errors import (
|
|
ExecNonZeroError,
|
|
ExecTransportError,
|
|
ExposedPortUnavailableError,
|
|
InvalidManifestPathError,
|
|
MountConfigError,
|
|
PtySessionNotFoundError,
|
|
WorkspaceArchiveWriteError,
|
|
WorkspaceReadNotFoundError,
|
|
)
|
|
from ..files import FileEntry
|
|
from ..manifest import Manifest
|
|
from ..materialization import MaterializationResult, MaterializedFile
|
|
from ..types import ExecResult, ExposedPortEndpoint, User
|
|
from ..util.parse_utils import parse_ls_la
|
|
from ..workspace_paths import (
|
|
WorkspacePathPolicy,
|
|
coerce_posix_path,
|
|
posix_path_as_path,
|
|
posix_path_for_error,
|
|
sandbox_path_str,
|
|
)
|
|
from . import archive_ops, manifest_ops, snapshot_lifecycle
|
|
from .dependencies import Dependencies
|
|
from .pty_types import PtyExecUpdate
|
|
from .runtime_helpers import (
|
|
RESOLVE_WORKSPACE_PATH_HELPER,
|
|
RuntimeHelperScript,
|
|
)
|
|
from .sandbox_session_state import SandboxSessionState
|
|
|
|
_PtyEntryT = TypeVar("_PtyEntryT")
|
|
_RUNTIME_HELPER_CACHE_KEY_UNSET = object()
|
|
_WORKSPACE_ROOT_PROBE_TIMEOUT_S = 10.0
|
|
_WRITE_ACCESS_CHECK_SCRIPT = (
|
|
'target="$1"\n'
|
|
'if [ -e "$target" ]; then\n'
|
|
' [ -f "$target" ] && [ -w "$target" ]\n'
|
|
" exit $?\n"
|
|
"fi\n"
|
|
'parent=$(dirname "$target")\n'
|
|
'while [ ! -e "$parent" ]; do\n'
|
|
' next=$(dirname "$parent")\n'
|
|
' if [ "$next" = "$parent" ]; then\n'
|
|
" exit 1\n"
|
|
" fi\n"
|
|
' parent="$next"\n'
|
|
"done\n"
|
|
'[ -d "$parent" ] && [ -w "$parent" ] && [ -x "$parent" ]\n'
|
|
)
|
|
_MKDIR_ACCESS_CHECK_SCRIPT = (
|
|
'target="$1"\n'
|
|
'parents="$2"\n'
|
|
'if [ -e "$target" ] || [ -L "$target" ]; then\n'
|
|
' [ -d "$target" ] && [ -x "$target" ]\n'
|
|
" exit $?\n"
|
|
"fi\n"
|
|
'parent=$(dirname "$target")\n'
|
|
'if [ "$parents" = "1" ]; then\n'
|
|
' while [ ! -e "$parent" ]; do\n'
|
|
' next=$(dirname "$parent")\n'
|
|
' if [ "$next" = "$parent" ]; then\n'
|
|
" exit 1\n"
|
|
" fi\n"
|
|
' parent="$next"\n'
|
|
" done\n"
|
|
"fi\n"
|
|
'[ -d "$parent" ] && [ -w "$parent" ] && [ -x "$parent" ]\n'
|
|
)
|
|
_RM_ACCESS_CHECK_SCRIPT = (
|
|
'target="$1"\n'
|
|
'recursive="$2"\n'
|
|
'if [ ! -e "$target" ] && [ ! -L "$target" ]; then\n'
|
|
' [ "$recursive" = "1" ]\n'
|
|
" exit $?\n"
|
|
"fi\n"
|
|
'parent=$(dirname "$target")\n'
|
|
'[ -d "$parent" ] && [ -w "$parent" ] && [ -x "$parent" ]\n'
|
|
)
|
|
|
|
|
|
class BaseSandboxSession(abc.ABC):
|
|
state: SandboxSessionState
|
|
_dependencies: Dependencies | None = None
|
|
_dependencies_closed: bool = False
|
|
_runtime_persist_workspace_skip_relpaths: set[Path] | None = None
|
|
_pre_stop_hooks: list[Callable[[], Awaitable[None]]] | None = None
|
|
_pre_stop_hooks_ran: bool = False
|
|
_runtime_helpers_installed: set[PurePath] | None = None
|
|
_runtime_helper_cache_key: object = _RUNTIME_HELPER_CACHE_KEY_UNSET
|
|
_workspace_path_policy_cache: (
|
|
tuple[str, tuple[tuple[str, bool], ...], WorkspacePathPolicy] | None
|
|
) = None
|
|
# True when start() is reusing a backend whose workspace files may still be present.
|
|
# This controls whether start() can avoid a full manifest apply for non-snapshot resumes.
|
|
_start_workspace_state_preserved: bool = False
|
|
# True when start() is reusing a backend whose OS users and groups may still be present.
|
|
# This controls whether snapshot restore needs to reprovision manifest-managed accounts.
|
|
_start_system_state_preserved: bool = False
|
|
# Snapshot of serialized workspace readiness after backend startup/reconnect.
|
|
# Providers may set this to True during start only after a preserved-backend probe succeeds.
|
|
_start_workspace_root_ready: bool | None = None
|
|
_max_manifest_entry_concurrency: int | None = DEFAULT_MAX_MANIFEST_ENTRY_CONCURRENCY
|
|
_max_local_dir_file_concurrency: int | None = DEFAULT_MAX_LOCAL_DIR_FILE_CONCURRENCY
|
|
_archive_limits: SandboxArchiveLimits | None = None
|
|
|
|
async def start(self) -> None:
|
|
try:
|
|
await self._ensure_backend_started()
|
|
self._start_workspace_root_ready = self.state.workspace_root_ready
|
|
await self._probe_workspace_root_for_preserved_resume()
|
|
await self._prepare_backend_workspace()
|
|
await self._ensure_runtime_helpers()
|
|
await self._start_workspace()
|
|
except Exception as e:
|
|
await self._after_start_failed()
|
|
wrapped = self._wrap_start_error(e)
|
|
if wrapped is e:
|
|
raise
|
|
raise wrapped from e
|
|
await self._after_start()
|
|
self.state.workspace_root_ready = True
|
|
|
|
def _set_concurrency_limits(self, limits: SandboxConcurrencyLimits) -> None:
|
|
limits.validate()
|
|
self._max_manifest_entry_concurrency = limits.manifest_entries
|
|
self._max_local_dir_file_concurrency = limits.local_dir_files
|
|
|
|
def _set_archive_limits(self, limits: SandboxArchiveLimits | None) -> None:
|
|
if limits is not None:
|
|
limits.validate()
|
|
self._archive_limits = limits
|
|
|
|
async def _ensure_backend_started(self) -> None:
|
|
"""Start, reconnect, or recreate the backend before workspace setup runs."""
|
|
|
|
return
|
|
|
|
async def _prepare_backend_workspace(self) -> None:
|
|
"""Prepare provider-specific workspace prerequisites before manifest or snapshot work."""
|
|
|
|
return
|
|
|
|
async def _probe_workspace_root_for_preserved_resume(self) -> bool:
|
|
"""Probe whether a preserved backend already has a usable workspace root."""
|
|
|
|
if not self._workspace_state_preserved_on_start() or self._start_workspace_root_ready:
|
|
return self._can_reuse_preserved_workspace_on_resume()
|
|
|
|
try:
|
|
result = await self.exec(
|
|
"test",
|
|
"-d",
|
|
self.state.manifest.root,
|
|
timeout=_WORKSPACE_ROOT_PROBE_TIMEOUT_S,
|
|
shell=False,
|
|
)
|
|
except Exception:
|
|
return False
|
|
|
|
if not result.ok():
|
|
return False
|
|
|
|
self._mark_workspace_root_ready_from_probe()
|
|
return True
|
|
|
|
def _mark_workspace_root_ready_from_probe(self) -> None:
|
|
"""Record that the preserved-backend workspace root was proven ready."""
|
|
|
|
self.state.workspace_root_ready = True
|
|
self._start_workspace_root_ready = True
|
|
|
|
def _set_start_state_preserved(self, workspace: bool, *, system: bool | None = None) -> None:
|
|
"""Record whether this start begins with preserved backend state."""
|
|
|
|
self._start_workspace_state_preserved = workspace
|
|
self._start_system_state_preserved = workspace if system is None else system
|
|
|
|
def _workspace_state_preserved_on_start(self) -> bool:
|
|
"""Return whether start begins with previously persisted workspace state."""
|
|
|
|
return self._start_workspace_state_preserved
|
|
|
|
def _system_state_preserved_on_start(self) -> bool:
|
|
"""Return whether start begins with previously provisioned OS/user state."""
|
|
|
|
return self._start_system_state_preserved
|
|
|
|
async def _start_workspace(self) -> None:
|
|
"""Restore snapshot or apply manifest state after backend startup is complete."""
|
|
|
|
if await self.state.snapshot.restorable(dependencies=self.dependencies):
|
|
can_reuse_workspace = await self._can_reuse_restorable_snapshot_workspace()
|
|
if can_reuse_workspace:
|
|
# The preserved workspace already matches the snapshot, so only rebuild ephemeral
|
|
# manifest state that intentionally was not persisted.
|
|
await self._reapply_ephemeral_manifest_on_resume()
|
|
else:
|
|
# Fresh workspaces and drifted preserved workspaces both need the durable snapshot
|
|
# restored before ephemeral state is rebuilt.
|
|
await self._restore_snapshot_into_workspace_on_resume()
|
|
if self.should_provision_manifest_accounts_on_resume():
|
|
await self.provision_manifest_accounts()
|
|
await self._reapply_ephemeral_manifest_on_resume()
|
|
elif self._can_reuse_preserved_workspace_on_resume():
|
|
# There is no durable snapshot to restore, but a reconnected backend may still need
|
|
# ephemeral mounts/files refreshed without reapplying the full manifest.
|
|
await self._reapply_ephemeral_manifest_on_resume()
|
|
else:
|
|
# A fresh backend without a restorable snapshot needs the full manifest materialized.
|
|
await self._apply_manifest(
|
|
provision_accounts=self.should_provision_manifest_accounts_on_resume()
|
|
)
|
|
|
|
async def _can_reuse_restorable_snapshot_workspace(self) -> bool:
|
|
"""Return whether a restorable snapshot can be skipped for this start."""
|
|
|
|
if not self._can_reuse_preserved_workspace_on_resume():
|
|
return False
|
|
is_running = await self.running()
|
|
return await self._can_skip_snapshot_restore_on_resume(is_running=is_running)
|
|
|
|
def _can_reuse_preserved_workspace_on_resume(self) -> bool:
|
|
"""Return whether preserved workspace state is proven safe to reuse."""
|
|
|
|
workspace_root_ready = self._start_workspace_root_ready
|
|
if workspace_root_ready is None:
|
|
workspace_root_ready = self.state.workspace_root_ready
|
|
return self._workspace_state_preserved_on_start() and workspace_root_ready
|
|
|
|
async def _after_start(self) -> None:
|
|
"""Run provider bookkeeping after workspace setup succeeds."""
|
|
|
|
return
|
|
|
|
async def _after_start_failed(self) -> None:
|
|
"""Run provider bookkeeping after workspace setup fails."""
|
|
|
|
return
|
|
|
|
def _wrap_start_error(self, error: Exception) -> Exception:
|
|
"""Return a provider-specific start error, or the original error."""
|
|
|
|
return error
|
|
|
|
async def stop(self) -> None:
|
|
"""
|
|
Persist/snapshot the workspace.
|
|
|
|
Note: `stop()` is intentionally persistence-only. Sandboxes that need to tear down
|
|
sandbox resources (Docker containers, remote sessions, etc.) should implement
|
|
`shutdown()` instead.
|
|
"""
|
|
try:
|
|
try:
|
|
await self._before_stop()
|
|
await self._persist_snapshot()
|
|
except Exception as e:
|
|
wrapped = self._wrap_stop_error(e)
|
|
if wrapped is e:
|
|
raise
|
|
raise wrapped from e
|
|
finally:
|
|
await self._after_stop()
|
|
|
|
async def _before_stop(self) -> None:
|
|
"""Run transient process cleanup before snapshot persistence."""
|
|
|
|
await self.pty_terminate_all()
|
|
|
|
async def _persist_snapshot(self) -> None:
|
|
"""Persist/snapshot the workspace."""
|
|
|
|
await snapshot_lifecycle.persist_snapshot(self)
|
|
|
|
def _wrap_stop_error(self, error: Exception) -> Exception:
|
|
"""Return a provider-specific stop error, or the original error."""
|
|
|
|
return error
|
|
|
|
async def _after_stop(self) -> None:
|
|
"""Run provider bookkeeping after stop finishes or fails."""
|
|
|
|
return
|
|
|
|
def supports_docker_volume_mounts(self) -> bool:
|
|
"""Return whether this backend attaches Docker volume mounts before manifest apply."""
|
|
|
|
return False
|
|
|
|
def supports_pty(self) -> bool:
|
|
return False
|
|
|
|
async def shutdown(self) -> None:
|
|
"""
|
|
Tear down sandbox resources (best-effort).
|
|
|
|
Default is a no-op. Sandbox-specific sessions (e.g. Docker) should override.
|
|
"""
|
|
await self._before_shutdown()
|
|
await self._shutdown_backend()
|
|
await self._after_shutdown()
|
|
|
|
async def _before_shutdown(self) -> None:
|
|
"""Run transient process cleanup before backend shutdown."""
|
|
|
|
await self.pty_terminate_all()
|
|
|
|
async def _shutdown_backend(self) -> None:
|
|
"""Tear down provider-specific backend resources."""
|
|
|
|
return
|
|
|
|
async def _after_shutdown(self) -> None:
|
|
"""Run provider bookkeeping after backend shutdown."""
|
|
|
|
return
|
|
|
|
async def __aenter__(self) -> Self:
|
|
await self.start()
|
|
return self
|
|
|
|
async def aclose(self) -> None:
|
|
"""Run the session cleanup lifecycle outside of ``async with``.
|
|
|
|
This performs the same session-owned cleanup as ``__aexit__()``: persist/snapshot the
|
|
workspace via ``stop()``, tear down session resources via ``shutdown()``, and close
|
|
session-scoped dependencies. If the session came from a sandbox client, call the client's
|
|
``delete()`` separately for backend-specific deletion such as removing a Docker container
|
|
or deleting a temporary host workspace.
|
|
"""
|
|
try:
|
|
await self.run_pre_stop_hooks()
|
|
await self.stop()
|
|
await self.shutdown()
|
|
finally:
|
|
await self._aclose_dependencies()
|
|
|
|
async def __aexit__(
|
|
self,
|
|
exc_type: type[BaseException] | None,
|
|
exc: BaseException | None,
|
|
tb: object | None,
|
|
) -> None:
|
|
await self.aclose()
|
|
|
|
@property
|
|
def dependencies(self) -> Dependencies:
|
|
dependencies = self._dependencies
|
|
if dependencies is None:
|
|
dependencies = Dependencies()
|
|
self._dependencies = dependencies
|
|
self._dependencies_closed = False
|
|
return dependencies
|
|
|
|
def set_dependencies(self, dependencies: Dependencies | None) -> None:
|
|
if dependencies is None:
|
|
return
|
|
self._dependencies = dependencies
|
|
self._dependencies_closed = False
|
|
|
|
def register_pre_stop_hook(self, hook: Callable[[], Awaitable[None]]) -> None:
|
|
"""Register an async hook to run once before the session workspace is persisted."""
|
|
|
|
hooks = self._pre_stop_hooks
|
|
if hooks is None:
|
|
hooks = []
|
|
self._pre_stop_hooks = hooks
|
|
hooks.append(hook)
|
|
self._pre_stop_hooks_ran = False
|
|
|
|
async def run_pre_stop_hooks(self) -> None:
|
|
"""Run registered pre-stop hooks once before workspace persistence."""
|
|
|
|
hooks = self._pre_stop_hooks
|
|
if hooks is None or self._pre_stop_hooks_ran:
|
|
return
|
|
self._pre_stop_hooks_ran = True
|
|
cleanup_error: BaseException | None = None
|
|
for hook in hooks:
|
|
try:
|
|
await hook()
|
|
except BaseException as exc:
|
|
if cleanup_error is None:
|
|
cleanup_error = exc
|
|
if cleanup_error is not None:
|
|
raise cleanup_error
|
|
|
|
async def _run_pre_stop_hooks(self) -> None:
|
|
await self.run_pre_stop_hooks()
|
|
|
|
async def _aclose_dependencies(self) -> None:
|
|
dependencies = self._dependencies
|
|
if dependencies is None or self._dependencies_closed:
|
|
return
|
|
self._dependencies_closed = True
|
|
await dependencies.aclose()
|
|
|
|
@staticmethod
|
|
def _workspace_relpaths_overlap(lhs: Path, rhs: Path) -> bool:
|
|
return lhs == rhs or lhs in rhs.parents or rhs in lhs.parents
|
|
|
|
def _mount_relpaths_within_workspace(self) -> set[Path]:
|
|
root = self._workspace_root_path()
|
|
mount_relpaths: set[Path] = set()
|
|
for _mount_entry, mount_path in self.state.manifest.mount_targets():
|
|
try:
|
|
mount_relpaths.add(mount_path.relative_to(root))
|
|
except ValueError:
|
|
continue
|
|
return mount_relpaths
|
|
|
|
def _overlapping_mount_relpaths(self, rel_path: Path) -> set[Path]:
|
|
return {
|
|
mount_relpath
|
|
for mount_relpath in self._mount_relpaths_within_workspace()
|
|
if self._workspace_relpaths_overlap(rel_path, mount_relpath)
|
|
}
|
|
|
|
def _native_snapshot_requires_tar_fallback(self) -> bool:
|
|
for mount_entry, _mount_path in self.state.manifest.mount_targets():
|
|
if not mount_entry.mount_strategy.supports_native_snapshot_detach(mount_entry):
|
|
return True
|
|
return False
|
|
|
|
def register_persist_workspace_skip_path(self, path: Path | str) -> Path:
|
|
"""Exclude a runtime-created workspace path from future workspace snapshots.
|
|
|
|
Use this for session side effects that are not part of durable workspace state, such as
|
|
generated mount config or ephemeral sink output.
|
|
"""
|
|
|
|
rel_path = Manifest._coerce_rel_path(path)
|
|
Manifest._validate_rel_path(rel_path)
|
|
if rel_path in (Path(""), Path(".")):
|
|
raise ValueError("Persist workspace skip paths must target a concrete relative path.")
|
|
overlapping_mounts = self._overlapping_mount_relpaths(rel_path)
|
|
if overlapping_mounts:
|
|
overlapping_mount = min(overlapping_mounts, key=lambda p: (len(p.parts), p.as_posix()))
|
|
raise MountConfigError(
|
|
message="persist workspace skip path must not overlap mount path",
|
|
context={
|
|
"skip_path": rel_path.as_posix(),
|
|
"mount_path": overlapping_mount.as_posix(),
|
|
},
|
|
)
|
|
|
|
if self._runtime_persist_workspace_skip_relpaths is None:
|
|
self._runtime_persist_workspace_skip_relpaths = set()
|
|
self._runtime_persist_workspace_skip_relpaths.add(rel_path)
|
|
return rel_path
|
|
|
|
def _persist_workspace_skip_relpaths(self) -> set[Path]:
|
|
skip_paths = set(self.state.manifest.ephemeral_persistence_paths())
|
|
if self._runtime_persist_workspace_skip_relpaths:
|
|
skip_paths.update(self._runtime_persist_workspace_skip_relpaths)
|
|
return skip_paths
|
|
|
|
async def exec(
|
|
self,
|
|
*command: str | Path,
|
|
timeout: float | None = None,
|
|
shell: bool | list[str] = True,
|
|
user: str | User | None = None,
|
|
) -> ExecResult:
|
|
"""Execute a command inside the session.
|
|
|
|
:param command: Command and args (will be stringified).
|
|
:param timeout: Optional wall-clock timeout in seconds.
|
|
:param shell: Whether to run this command in a shell. If ``True`` is provided,
|
|
the command will be run prefixed by ``sh -lc``. A custom shell prefix may be used
|
|
by providing a list.
|
|
|
|
:returns: An ``ExecResult`` containing stdout/stderr and exit code.
|
|
|
|
:raises TimeoutError: If the sandbox cannot complete within `timeout`.
|
|
"""
|
|
|
|
sanitized_command = self._prepare_exec_command(*command, shell=shell, user=user)
|
|
return await self._exec_internal(*sanitized_command, timeout=timeout)
|
|
|
|
async def resolve_exposed_port(self, port: int) -> ExposedPortEndpoint:
|
|
self._assert_exposed_port_configured(port)
|
|
return await self._resolve_exposed_port(port)
|
|
|
|
def _assert_exposed_port_configured(self, port: int) -> None:
|
|
if port not in self.state.exposed_ports:
|
|
raise ExposedPortUnavailableError(
|
|
port=port,
|
|
exposed_ports=self.state.exposed_ports,
|
|
reason="not_configured",
|
|
)
|
|
|
|
def _prepare_exec_command(
|
|
self,
|
|
*command: str | Path,
|
|
shell: bool | list[str],
|
|
user: str | User | None,
|
|
) -> list[str]:
|
|
sanitized_command = [str(c) for c in command]
|
|
|
|
if shell:
|
|
joined = (
|
|
sanitized_command[0]
|
|
if len(sanitized_command) == 1
|
|
else shlex.join(sanitized_command)
|
|
)
|
|
if isinstance(shell, list):
|
|
sanitized_command = shell + [joined]
|
|
else:
|
|
sanitized_command = ["sh", "-lc", joined]
|
|
|
|
if user:
|
|
if isinstance(user, User):
|
|
user = user.name
|
|
|
|
assert isinstance(user, str)
|
|
|
|
sanitized_command = ["sudo", "-u", user, "--"] + sanitized_command
|
|
|
|
return sanitized_command
|
|
|
|
def _resolve_pty_session_entry(
|
|
self, *, pty_processes: Mapping[int, _PtyEntryT], session_id: int
|
|
) -> _PtyEntryT:
|
|
entry = pty_processes.get(session_id)
|
|
if entry is None:
|
|
raise PtySessionNotFoundError(session_id=session_id)
|
|
return entry
|
|
|
|
async def pty_exec_start(
|
|
self,
|
|
*command: str | Path,
|
|
timeout: float | None = None,
|
|
shell: bool | list[str] = True,
|
|
user: str | User | None = None,
|
|
tty: bool = False,
|
|
yield_time_s: float | None = None,
|
|
max_output_tokens: int | None = None,
|
|
) -> PtyExecUpdate:
|
|
_ = (command, timeout, shell, user, tty, yield_time_s, max_output_tokens)
|
|
raise NotImplementedError("PTY execution is not supported by this sandbox session")
|
|
|
|
async def pty_write_stdin(
|
|
self,
|
|
*,
|
|
session_id: int,
|
|
chars: str,
|
|
yield_time_s: float | None = None,
|
|
max_output_tokens: int | None = None,
|
|
) -> PtyExecUpdate:
|
|
_ = (session_id, chars, yield_time_s, max_output_tokens)
|
|
raise NotImplementedError("PTY execution is not supported by this sandbox session")
|
|
|
|
async def pty_terminate_all(self) -> None:
|
|
return
|
|
|
|
@abc.abstractmethod
|
|
async def _exec_internal(
|
|
self,
|
|
*command: str | Path,
|
|
timeout: float | None = None,
|
|
) -> ExecResult: ...
|
|
|
|
async def _resolve_exposed_port(self, port: int) -> ExposedPortEndpoint:
|
|
raise ExposedPortUnavailableError(
|
|
port=port,
|
|
exposed_ports=self.state.exposed_ports,
|
|
reason="backend_unavailable",
|
|
context={"backend": type(self).__name__},
|
|
)
|
|
|
|
def _runtime_helpers(self) -> tuple[RuntimeHelperScript, ...]:
|
|
return ()
|
|
|
|
def _current_runtime_helper_cache_key(self) -> object | None:
|
|
return None
|
|
|
|
def _sync_runtime_helper_install_cache(self) -> None:
|
|
current_key = self._current_runtime_helper_cache_key()
|
|
cached_key = self._runtime_helper_cache_key
|
|
if cached_key is _RUNTIME_HELPER_CACHE_KEY_UNSET:
|
|
self._runtime_helper_cache_key = current_key
|
|
return
|
|
if cached_key != current_key:
|
|
self._runtime_helpers_installed = None
|
|
self._runtime_helper_cache_key = current_key
|
|
|
|
async def _ensure_runtime_helper_installed(self, helper: RuntimeHelperScript) -> PurePath:
|
|
self._sync_runtime_helper_install_cache()
|
|
installed = self._runtime_helpers_installed
|
|
if installed is None:
|
|
installed = set()
|
|
self._runtime_helpers_installed = installed
|
|
|
|
install_path = helper.install_path
|
|
if install_path in installed:
|
|
probe = await self.exec(*helper.present_command(), shell=False)
|
|
if probe.ok():
|
|
return install_path
|
|
self._sync_runtime_helper_install_cache()
|
|
installed = self._runtime_helpers_installed
|
|
if installed is None:
|
|
installed = set()
|
|
self._runtime_helpers_installed = installed
|
|
installed.discard(install_path)
|
|
|
|
result = await self.exec(*helper.install_command(), shell=False)
|
|
if not result.ok():
|
|
raise ExecNonZeroError(
|
|
result,
|
|
command=("install_runtime_helper", str(install_path)),
|
|
)
|
|
|
|
self._sync_runtime_helper_install_cache()
|
|
installed = self._runtime_helpers_installed
|
|
if installed is None:
|
|
installed = set()
|
|
self._runtime_helpers_installed = installed
|
|
installed.add(install_path)
|
|
return install_path
|
|
|
|
async def _ensure_runtime_helpers(self) -> None:
|
|
for helper in self._runtime_helpers():
|
|
await self._ensure_runtime_helper_installed(helper)
|
|
|
|
def _workspace_path_policy(self) -> WorkspacePathPolicy:
|
|
root = self.state.manifest.root
|
|
grants_key = tuple(
|
|
(grant.path, grant.read_only) for grant in self.state.manifest.extra_path_grants
|
|
)
|
|
cached = self._workspace_path_policy_cache
|
|
if cached is not None and cached[0] == root and cached[1] == grants_key:
|
|
return cached[2]
|
|
|
|
policy = WorkspacePathPolicy(
|
|
root=root,
|
|
extra_path_grants=self.state.manifest.extra_path_grants,
|
|
)
|
|
self._workspace_path_policy_cache = (root, grants_key, policy)
|
|
return policy
|
|
|
|
def _workspace_root_path(self) -> Path:
|
|
return posix_path_as_path(self._workspace_path_policy().sandbox_root())
|
|
|
|
async def _validate_path_access(self, path: Path | str, *, for_write: bool = False) -> Path:
|
|
return self.normalize_path(path, for_write=for_write)
|
|
|
|
async def _validate_remote_path_access(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
for_write: bool = False,
|
|
) -> Path:
|
|
"""Validate an SDK file path against the remote sandbox filesystem before IO.
|
|
|
|
The returned path is the normalized workspace path, not the resolved realpath. This keeps
|
|
safe leaf symlink operations working normally, such as removing a symlink instead of its
|
|
target, while still rejecting paths whose resolved remote target escapes all allowed roots.
|
|
"""
|
|
|
|
path_policy = self._workspace_path_policy()
|
|
root = path_policy.sandbox_root()
|
|
workspace_path = path_policy.normalize_sandbox_path(path, for_write=for_write)
|
|
original_path = coerce_posix_path(path)
|
|
helper_path = await self._ensure_runtime_helper_installed(RESOLVE_WORKSPACE_PATH_HELPER)
|
|
extra_grant_args = tuple(
|
|
arg
|
|
for root, read_only in path_policy.extra_path_grant_rules()
|
|
for arg in (root.as_posix(), "1" if read_only else "0")
|
|
)
|
|
command = (
|
|
str(helper_path),
|
|
root.as_posix(),
|
|
workspace_path.as_posix(),
|
|
"1" if for_write else "0",
|
|
*extra_grant_args,
|
|
)
|
|
result = await self.exec(*command, shell=False)
|
|
if result.ok():
|
|
resolved = result.stdout.decode("utf-8", errors="replace").strip()
|
|
if resolved:
|
|
# Preserve the requested workspace path so leaf symlinks keep their normal
|
|
# semantics while the remote realpath check still enforces path confinement.
|
|
return posix_path_as_path(workspace_path)
|
|
raise ExecTransportError(
|
|
command=(
|
|
"resolve_workspace_path",
|
|
root.as_posix(),
|
|
workspace_path.as_posix(),
|
|
"1" if for_write else "0",
|
|
*extra_grant_args,
|
|
),
|
|
context={
|
|
"reason": "empty_stdout",
|
|
"exit_code": result.exit_code,
|
|
"stdout": "",
|
|
"stderr": result.stderr.decode("utf-8", errors="replace"),
|
|
},
|
|
)
|
|
|
|
reason: Literal["absolute", "escape_root"] = (
|
|
"absolute" if original_path.is_absolute() else "escape_root"
|
|
)
|
|
if result.exit_code == 111:
|
|
raise InvalidManifestPathError(
|
|
rel=original_path.as_posix(),
|
|
reason=reason,
|
|
context={
|
|
"resolved_path": result.stderr.decode("utf-8", errors="replace").strip(),
|
|
},
|
|
)
|
|
if result.exit_code == 113:
|
|
raise ValueError(result.stderr.decode("utf-8", errors="replace").strip())
|
|
if result.exit_code == 114:
|
|
stderr = result.stderr.decode("utf-8", errors="replace")
|
|
context: dict[str, object] = {"reason": "read_only_extra_path_grant"}
|
|
for line in stderr.splitlines():
|
|
if line.startswith("read-only extra path grant: "):
|
|
context["grant_path"] = line.removeprefix("read-only extra path grant: ")
|
|
elif line.startswith("resolved path: "):
|
|
context["resolved_path"] = line.removeprefix("resolved path: ")
|
|
raise WorkspaceArchiveWriteError(
|
|
path=posix_path_for_error(workspace_path), context=context
|
|
)
|
|
raise ExecNonZeroError(
|
|
result,
|
|
command=(
|
|
"resolve_workspace_path",
|
|
root.as_posix(),
|
|
workspace_path.as_posix(),
|
|
"1" if for_write else "0",
|
|
*extra_grant_args,
|
|
),
|
|
)
|
|
|
|
@abc.abstractmethod
|
|
async def read(self, path: Path, *, user: str | User | None = None) -> io.IOBase:
|
|
"""Read a file from the session's workspace.
|
|
|
|
:param path: Absolute path in the container or path relative to the
|
|
workspace root.
|
|
:param user: Optional sandbox user to perform the read as.
|
|
:returns: A readable file-like object.
|
|
:raises: FileNotFoundError: If the path does not exist.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
async def write(
|
|
self,
|
|
path: Path,
|
|
data: io.IOBase,
|
|
*,
|
|
user: str | User | None = None,
|
|
) -> None:
|
|
"""Write a file into the session's workspace.
|
|
|
|
:param path: Absolute path in the container or path relative to the
|
|
workspace root.
|
|
:param data: A file-like object positioned at the start of the payload.
|
|
:param user: Optional sandbox user to perform the write as.
|
|
"""
|
|
|
|
async def _check_read_with_exec(
|
|
self, path: Path | str, *, user: str | User | None = None
|
|
) -> Path:
|
|
workspace_path = await self._validate_path_access(path)
|
|
path_arg = sandbox_path_str(workspace_path)
|
|
cmd = ("sh", "-lc", '[ -r "$1" ]', "sh", path_arg)
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise WorkspaceReadNotFoundError(
|
|
path=posix_path_as_path(coerce_posix_path(path)),
|
|
context={
|
|
"command": ["sh", "-lc", "<read_access_check>", path_arg],
|
|
"stdout": result.stdout.decode("utf-8", errors="replace"),
|
|
"stderr": result.stderr.decode("utf-8", errors="replace"),
|
|
},
|
|
)
|
|
return workspace_path
|
|
|
|
async def _check_write_with_exec(
|
|
self, path: Path | str, *, user: str | User | None = None
|
|
) -> Path:
|
|
workspace_path = await self._validate_path_access(path, for_write=True)
|
|
path_arg = sandbox_path_str(workspace_path)
|
|
cmd = ("sh", "-lc", _WRITE_ACCESS_CHECK_SCRIPT, "sh", path_arg)
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise WorkspaceArchiveWriteError(
|
|
path=workspace_path,
|
|
context={
|
|
"command": ["sh", "-lc", "<write_access_check>", path_arg],
|
|
"stdout": result.stdout.decode("utf-8", errors="replace"),
|
|
"stderr": result.stderr.decode("utf-8", errors="replace"),
|
|
},
|
|
)
|
|
return workspace_path
|
|
|
|
async def _check_mkdir_with_exec(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
parents: bool = False,
|
|
user: str | User | None = None,
|
|
) -> Path:
|
|
workspace_path = await self._validate_path_access(path, for_write=True)
|
|
parents_flag = "1" if parents else "0"
|
|
path_arg = sandbox_path_str(workspace_path)
|
|
cmd = ("sh", "-lc", _MKDIR_ACCESS_CHECK_SCRIPT, "sh", path_arg, parents_flag)
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise WorkspaceArchiveWriteError(
|
|
path=workspace_path,
|
|
context={
|
|
"command": [
|
|
"sh",
|
|
"-lc",
|
|
"<mkdir_access_check>",
|
|
path_arg,
|
|
parents_flag,
|
|
],
|
|
"stdout": result.stdout.decode("utf-8", errors="replace"),
|
|
"stderr": result.stderr.decode("utf-8", errors="replace"),
|
|
},
|
|
)
|
|
return workspace_path
|
|
|
|
async def _check_rm_with_exec(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
recursive: bool = False,
|
|
user: str | User | None = None,
|
|
) -> Path:
|
|
workspace_path = await self._validate_path_access(path, for_write=True)
|
|
recursive_flag = "1" if recursive else "0"
|
|
path_arg = sandbox_path_str(workspace_path)
|
|
cmd = ("sh", "-lc", _RM_ACCESS_CHECK_SCRIPT, "sh", path_arg, recursive_flag)
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise WorkspaceArchiveWriteError(
|
|
path=workspace_path,
|
|
context={
|
|
"command": [
|
|
"sh",
|
|
"-lc",
|
|
"<rm_access_check>",
|
|
path_arg,
|
|
recursive_flag,
|
|
],
|
|
"stdout": result.stdout.decode("utf-8", errors="replace"),
|
|
"stderr": result.stderr.decode("utf-8", errors="replace"),
|
|
},
|
|
)
|
|
return workspace_path
|
|
|
|
@abc.abstractmethod
|
|
async def running(self) -> bool:
|
|
"""
|
|
:returns: whether the underlying sandbox is currently running.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
async def persist_workspace(self) -> io.IOBase:
|
|
"""Serialize the session's workspace into a byte stream.
|
|
|
|
:returns: A readable byte stream representing the workspace contents.
|
|
Portable tar streams must use workspace-relative member paths rather than
|
|
embedding the source backend's workspace root directory.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
async def hydrate_workspace(self, data: io.IOBase) -> None:
|
|
"""Populate the session's workspace from a serialized byte stream.
|
|
|
|
:param data: A readable byte stream as produced by `persist_workspace`.
|
|
Portable tar streams are extracted underneath this session's workspace root.
|
|
"""
|
|
|
|
async def ls(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
user: str | User | None = None,
|
|
) -> list[FileEntry]:
|
|
"""List directory contents.
|
|
|
|
:param path: Path to list.
|
|
:param user: Optional sandbox user to list as.
|
|
:returns: A list of `FileEntry` objects.
|
|
"""
|
|
path = await self._validate_path_access(path)
|
|
|
|
path_arg = sandbox_path_str(path)
|
|
cmd = ("ls", "-la", "--", path_arg)
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise ExecNonZeroError(result, command=cmd)
|
|
|
|
return parse_ls_la(result.stdout.decode("utf-8", errors="replace"), base=path_arg)
|
|
|
|
async def rm(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
recursive: bool = False,
|
|
user: str | User | None = None,
|
|
) -> None:
|
|
"""Remove a file or directory.
|
|
|
|
:param path: Path to remove.
|
|
:param recursive: If true, remove directories recursively.
|
|
:param user: Optional sandbox user to remove as.
|
|
"""
|
|
path = await self._validate_path_access(path, for_write=True)
|
|
|
|
cmd: list[str] = ["rm"]
|
|
if recursive:
|
|
cmd.append("-rf")
|
|
cmd.extend(["--", sandbox_path_str(path)])
|
|
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise ExecNonZeroError(result, command=cmd)
|
|
|
|
async def mkdir(
|
|
self,
|
|
path: Path | str,
|
|
*,
|
|
parents: bool = False,
|
|
user: str | User | None = None,
|
|
) -> None:
|
|
"""Create a directory.
|
|
|
|
:param path: Directory to create on the remote.
|
|
:param parents: If true, create missing parents.
|
|
:param user: Optional sandbox user to create the directory as.
|
|
"""
|
|
path = await self._validate_path_access(path, for_write=True)
|
|
|
|
cmd: list[str] = ["mkdir"]
|
|
if parents:
|
|
cmd.append("-p")
|
|
cmd.append(sandbox_path_str(path))
|
|
|
|
result = await self.exec(*cmd, shell=False, user=user)
|
|
if not result.ok():
|
|
raise ExecNonZeroError(result, command=cmd)
|
|
|
|
async def extract(
|
|
self,
|
|
path: Path | str,
|
|
data: io.IOBase,
|
|
*,
|
|
compression_scheme: Literal["tar", "zip"] | None = None,
|
|
archive_limits: SandboxArchiveLimits | None = None,
|
|
) -> None:
|
|
"""
|
|
Write a compressed archive to a destination on the remote.
|
|
Optionally extract the archive once written.
|
|
|
|
:param path: Path on the host machine to extract to
|
|
:param data: a file-like io stream.
|
|
:param compression_scheme: either "tar" or "zip". If not provided,
|
|
it will try to infer from the path.
|
|
:param archive_limits: optional per-call archive resource limits. If omitted,
|
|
the session default is used.
|
|
"""
|
|
if archive_limits is not None:
|
|
archive_limits.validate()
|
|
effective_archive_limits = (
|
|
archive_limits if archive_limits is not None else self._archive_limits
|
|
)
|
|
|
|
await archive_ops.extract_archive(
|
|
self,
|
|
path,
|
|
data,
|
|
compression_scheme=compression_scheme,
|
|
archive_limits=effective_archive_limits,
|
|
)
|
|
|
|
async def apply_patch(
|
|
self,
|
|
operations: ApplyPatchOperation
|
|
| dict[str, object]
|
|
| list[ApplyPatchOperation | dict[str, object]],
|
|
*,
|
|
patch_format: PatchFormat | Literal["v4a"] = "v4a",
|
|
) -> str:
|
|
return await WorkspaceEditor(self).apply_patch(operations, patch_format=patch_format)
|
|
|
|
def normalize_path(self, path: Path | str, *, for_write: bool = False) -> Path:
|
|
policy = self._workspace_path_policy()
|
|
return policy.normalize_path(path, for_write=for_write)
|
|
|
|
def describe(self) -> str:
|
|
return self.state.manifest.describe()
|
|
|
|
async def _extract_tar_archive(
|
|
self,
|
|
*,
|
|
archive_path: Path,
|
|
destination_root: Path,
|
|
data: io.IOBase,
|
|
archive_limits: SandboxArchiveLimits | None = None,
|
|
) -> None:
|
|
await archive_ops.extract_tar_archive(
|
|
self,
|
|
archive_path=archive_path,
|
|
destination_root=destination_root,
|
|
data=data,
|
|
archive_limits=archive_limits,
|
|
)
|
|
|
|
async def _extract_zip_archive(
|
|
self,
|
|
*,
|
|
archive_path: Path,
|
|
destination_root: Path,
|
|
data: io.IOBase,
|
|
archive_limits: SandboxArchiveLimits | None = None,
|
|
) -> None:
|
|
await archive_ops.extract_zip_archive(
|
|
self,
|
|
archive_path=archive_path,
|
|
destination_root=destination_root,
|
|
data=data,
|
|
archive_limits=archive_limits,
|
|
)
|
|
|
|
@staticmethod
|
|
def _safe_zip_member_rel_path(member) -> Path | None:
|
|
return archive_ops.safe_zip_member_rel_path(member)
|
|
|
|
async def _apply_manifest(
|
|
self,
|
|
*,
|
|
only_ephemeral: bool = False,
|
|
provision_accounts: bool = True,
|
|
) -> MaterializationResult:
|
|
return await manifest_ops.apply_manifest(
|
|
self,
|
|
only_ephemeral=only_ephemeral,
|
|
provision_accounts=provision_accounts,
|
|
)
|
|
|
|
async def apply_manifest(self, *, only_ephemeral: bool = False) -> MaterializationResult:
|
|
return await self._apply_manifest(
|
|
only_ephemeral=only_ephemeral,
|
|
provision_accounts=not only_ephemeral,
|
|
)
|
|
|
|
async def provision_manifest_accounts(self) -> None:
|
|
await manifest_ops.provision_manifest_accounts(self)
|
|
|
|
def should_provision_manifest_accounts_on_resume(self) -> bool:
|
|
"""Return whether resume should reprovision manifest-managed users and groups."""
|
|
|
|
return not self._system_state_preserved_on_start()
|
|
|
|
async def _reapply_ephemeral_manifest_on_resume(self) -> None:
|
|
"""Rebuild ephemeral manifest state without touching persisted workspace files."""
|
|
|
|
await self.apply_manifest(only_ephemeral=True)
|
|
|
|
async def _restore_snapshot_into_workspace_on_resume(self) -> None:
|
|
"""Clear the live workspace contents and repopulate them from the persisted snapshot."""
|
|
|
|
await snapshot_lifecycle.restore_snapshot_into_workspace_on_resume(self)
|
|
|
|
async def _live_workspace_matches_snapshot_on_resume(self) -> bool:
|
|
"""Return whether the running sandbox workspace definitely matches the stored snapshot."""
|
|
|
|
return await snapshot_lifecycle.live_workspace_matches_snapshot_on_resume(self)
|
|
|
|
async def _can_skip_snapshot_restore_on_resume(self, *, is_running: bool) -> bool:
|
|
"""Return whether resume can safely reuse the running workspace without restore."""
|
|
|
|
return await snapshot_lifecycle.can_skip_snapshot_restore_on_resume(
|
|
self,
|
|
is_running=is_running,
|
|
)
|
|
|
|
def _snapshot_fingerprint_cache_path(self) -> Path:
|
|
"""Return the runtime-owned path for this session's cached snapshot fingerprint."""
|
|
|
|
return snapshot_lifecycle.snapshot_fingerprint_cache_path(self)
|
|
|
|
def _workspace_fingerprint_skip_relpaths(self) -> set[Path]:
|
|
"""Return workspace paths that should be omitted from snapshot fingerprinting."""
|
|
|
|
return snapshot_lifecycle.workspace_fingerprint_skip_relpaths(self)
|
|
|
|
async def _compute_and_cache_snapshot_fingerprint(self) -> dict[str, str]:
|
|
"""Compute the current workspace fingerprint in-container and atomically cache it."""
|
|
|
|
return await snapshot_lifecycle.compute_and_cache_snapshot_fingerprint(self)
|
|
|
|
async def _read_cached_snapshot_fingerprint(self) -> dict[str, str]:
|
|
"""Read the cached snapshot fingerprint record from the running sandbox."""
|
|
|
|
return await snapshot_lifecycle.read_cached_snapshot_fingerprint(self)
|
|
|
|
def _parse_snapshot_fingerprint_record(
|
|
self, payload: bytes | bytearray | str
|
|
) -> dict[str, str]:
|
|
"""Validate and normalize a cached snapshot fingerprint JSON payload."""
|
|
|
|
return snapshot_lifecycle.parse_snapshot_fingerprint_record(payload)
|
|
|
|
async def _delete_cached_snapshot_fingerprint_best_effort(self) -> None:
|
|
"""Remove the cached snapshot fingerprint file without raising on cleanup failure."""
|
|
|
|
await snapshot_lifecycle.delete_cached_snapshot_fingerprint_best_effort(self)
|
|
|
|
def _snapshot_fingerprint_version(self) -> str:
|
|
"""Return the version tag for the current snapshot fingerprint algorithm."""
|
|
|
|
return snapshot_lifecycle.snapshot_fingerprint_version()
|
|
|
|
def _resume_manifest_digest(self) -> str:
|
|
"""Return a stable digest of the manifest state that affects resume correctness."""
|
|
|
|
return snapshot_lifecycle.resume_manifest_digest(self)
|
|
|
|
async def _apply_entry_batch(
|
|
self,
|
|
entries: Sequence[tuple[Path, BaseEntry]],
|
|
*,
|
|
base_dir: Path,
|
|
) -> list[MaterializedFile]:
|
|
return await manifest_ops.apply_entry_batch(self, entries, base_dir=base_dir)
|
|
|
|
def _manifest_base_dir(self) -> Path:
|
|
return Path.cwd()
|
|
|
|
async def _exec_checked_nonzero(self, *command: str | Path) -> ExecResult:
|
|
result = await self.exec(*command, shell=False)
|
|
if not result.ok():
|
|
raise ExecNonZeroError(result, command=command)
|
|
return result
|
|
|
|
async def _clear_workspace_root_on_resume(self) -> None:
|
|
"""
|
|
Best-effort cleanup step for snapshot resume.
|
|
|
|
We intentionally clear *contents* of the workspace root rather than deleting the root
|
|
directory itself. Some sandboxes configure their process working directory to the workspace
|
|
root (e.g. Modal sandboxes), and deleting the directory can make subsequent exec() calls
|
|
fail with "failed to find initial working directory".
|
|
"""
|
|
|
|
await snapshot_lifecycle.clear_workspace_root_on_resume(self)
|
|
|
|
def _workspace_resume_mount_skip_relpaths(self) -> set[Path]:
|
|
return snapshot_lifecycle.workspace_resume_mount_skip_relpaths(self)
|
|
|
|
async def _clear_workspace_dir_on_resume_pruned(
|
|
self,
|
|
*,
|
|
current_dir: Path,
|
|
skip_rel_paths: set[Path],
|
|
) -> None:
|
|
await snapshot_lifecycle.clear_workspace_dir_on_resume_pruned(
|
|
self,
|
|
current_dir=current_dir,
|
|
skip_rel_paths=skip_rel_paths,
|
|
)
|