dr-docker 0.4.0__py3-none-any.whl

dr_docker/__init__.py

@@ -0,0 +1,30 @@
+"""Typed Docker runtime contracts and subprocess adapter."""
+
+from .adapters import RuntimeAdapter, RuntimePrimitiveError
+from .docker_contract import (
+    DockerMount,
+    DockerRuntimeRequest,
+    DockerRuntimeResult,
+    ResourceLimits,
+    SecurityProfile,
+    TmpfsMount,
+)
+from .errors import ErrorCode, ErrorEnvelope
+from .subprocess_adapter import SubprocessDockerAdapter
+from .version import CONTRACT_VERSION, __version__
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "DockerMount",
+    "DockerRuntimeRequest",
+    "DockerRuntimeResult",
+    "ErrorCode",
+    "ErrorEnvelope",
+    "ResourceLimits",
+    "RuntimeAdapter",
+    "RuntimePrimitiveError",
+    "SecurityProfile",
+    "SubprocessDockerAdapter",
+    "TmpfsMount",
+    "__version__",
+]

dr_docker/_json_validation.py

@@ -0,0 +1,25 @@
+"""Internal helpers for strict JSON boundary validation."""
+
+from __future__ import annotations
+
+import math
+
+from pydantic import JsonValue
+
+
+def ensure_finite_json_value(value: JsonValue, *, path: str) -> None:
+    """Reject non-finite numbers to preserve deterministic JSON contracts."""
+
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"{path} must not contain NaN or infinity")
+        return
+
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            ensure_finite_json_value(item, path=f"{path}[{index}]")
+        return
+
+    if isinstance(value, dict):
+        for key, item in value.items():
+            ensure_finite_json_value(item, path=f"{path}.{key}")

dr_docker/adapters.py

@@ -0,0 +1,23 @@
+"""Adapter protocol and error type for runtime primitive consumers."""
+
+from typing import Protocol, runtime_checkable
+
+from .docker_contract import DockerRuntimeRequest, DockerRuntimeResult
+from .errors import ErrorEnvelope
+
+
+class RuntimePrimitiveError(Exception):
+    """Raised when a primitive operation fails with a typed infra envelope."""
+
+    def __init__(self, error: ErrorEnvelope) -> None:
+        super().__init__(error.message)
+        self.error = error
+
+
+@runtime_checkable
+class RuntimeAdapter(Protocol):
+    """Primitive Docker runtime executor."""
+
+    def execute_in_runtime(
+        self, request: DockerRuntimeRequest
+    ) -> DockerRuntimeResult: ...

dr_docker/cidfile.py

@@ -0,0 +1,76 @@
+"""Container ID file management for Docker subprocess execution."""
+
+import logging
+import os
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+PRIVATE_CID_DIR_PREFIX = "dr_docker_cid_dir_"
+_LOGGER = logging.getLogger(__name__)
+
+
+def is_private_cidfile_dir(path: Path) -> bool:
+    """Return True when path is a managed private cidfile directory."""
+    temp_root = Path(tempfile.gettempdir()).resolve()
+    candidate = path.resolve(strict=False)
+    return candidate.parent == temp_root and candidate.name.startswith(
+        PRIVATE_CID_DIR_PREFIX
+    )
+
+
+def new_cidfile_path(
+    *,
+    prefix: str = "dr_docker_cid_",
+    suffix: str = ".txt",
+) -> Path:
+    """Return a unique cidfile path that does not already exist."""
+    private_dir: Path | None = None
+    try:
+        private_dir = Path(tempfile.mkdtemp(prefix=PRIVATE_CID_DIR_PREFIX))
+        private_dir.chmod(0o700)
+    except OSError:
+        _LOGGER.exception("Failed to create secure CID temporary directory")
+        if private_dir is not None:
+            with suppress(OSError):
+                private_dir.rmdir()
+        raise
+
+    cidfile_fd = -1
+    if private_dir is None:
+        raise RuntimeError("Private CID directory was not created")
+    cidfile_path = private_dir / f"{prefix}pending{suffix}"
+    try:
+        # Allocate temp file; clean up dir on failure.
+        try:
+            cidfile_fd, cidfile_name = tempfile.mkstemp(
+                prefix=prefix,
+                suffix=suffix,
+                dir=private_dir,
+                text=True,
+            )
+            cidfile_path = Path(cidfile_name)
+        except BaseException:
+            _LOGGER.exception(
+                "Failed to allocate CID file in temporary directory: %s",
+                private_dir,
+            )
+            with suppress(OSError):
+                private_dir.rmdir()
+            raise
+    finally:
+        if cidfile_fd >= 0:
+            os.close(cidfile_fd)
+
+    try:
+        cidfile_path.unlink()
+    except OSError:
+        _LOGGER.exception(
+            "Failed to unlink placeholder CID file: %s",
+            cidfile_path,
+        )
+        with suppress(OSError):
+            private_dir.rmdir()
+        raise
+
+    return cidfile_path

dr_docker/cleanup.py

@@ -0,0 +1,59 @@
+"""Container cleanup utilities for Docker subprocess execution."""
+
+import logging
+import re
+import subprocess
+from pathlib import Path
+
+from .cidfile import is_private_cidfile_dir
+from .errors import ErrorCode, ErrorEnvelope
+
+_CID_PATTERN = re.compile(r"[0-9a-f]{64}", flags=re.IGNORECASE)
+_LOGGER = logging.getLogger(__name__)
+
+
+def _is_valid_container_id(identifier: str) -> bool:
+    return _CID_PATTERN.fullmatch(identifier) is not None
+
+
+def _docker_rm(identifier: str) -> None:
+    try:
+        subprocess.run(
+            ["docker", "rm", "-f", identifier],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except (
+        FileNotFoundError,
+        OSError,
+        subprocess.SubprocessError,
+    ):
+        return
+
+
+def cleanup_container_from_cidfile(cidfile: Path) -> None:
+    """Remove the container referenced by cidfile, then clean up the file."""
+    try:
+        cid = cidfile.read_text(encoding="utf-8").strip()
+    except OSError:
+        cid = ""
+    if cid and _is_valid_container_id(cid):
+        _docker_rm(cid)
+    try:
+        cidfile.unlink(missing_ok=True)
+    except OSError as exc:
+        envelope = ErrorEnvelope(
+            code=ErrorCode.INTERNAL_ERROR,
+            message=f"Failed to remove cidfile {cidfile}: {exc}",
+            details={"cidfile": str(cidfile)},
+        )
+        _LOGGER.warning(
+            "best-effort cleanup failed: %s", envelope.model_dump(mode="json")
+        )
+    parent_dir = cidfile.parent
+    if is_private_cidfile_dir(parent_dir):
+        try:
+            parent_dir.rmdir()
+        except OSError:
+            pass

dr_docker/docker_contract.py

@@ -0,0 +1,82 @@
+"""Docker primitive runtime contract models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .errors import ErrorEnvelope
+
+
+class DockerMount(BaseModel):
+    """Docker bind mount settings."""
+
+    source: str = Field(min_length=1)
+    target: str = Field(min_length=1)
+    read_only: bool = False
+
+
+class SecurityProfile(BaseModel):
+    """Container security hardening."""
+
+    read_only: bool = True
+    cap_drop: str = "ALL"
+    no_new_privileges: bool = True
+    network_disabled: bool = True
+
+
+class ResourceLimits(BaseModel):
+    """Container resource constraints."""
+
+    memory: str = "256m"
+    cpus: float = Field(default=0.5, gt=0)
+    pids_limit: int = Field(default=64, gt=0)
+    cpu_seconds: int | None = Field(default=None, gt=0)
+    fsize_bytes: int | None = Field(default=None, gt=0)
+    nofile: int | None = Field(default=None, gt=0)
+    nproc: int | None = Field(default=None, gt=0)
+
+
+class TmpfsMount(BaseModel):
+    """Tmpfs mount specification."""
+
+    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)
+
+    target: str = "/tmp"
+    size: str = "16m"
+    exec_: bool = Field(default=False, alias="exec", serialization_alias="exec")
+
+
+class DockerRuntimeRequest(BaseModel):
+    """Input payload for a primitive Docker runtime execution."""
+
+    image: str = Field(min_length=1)
+    command: list[str] = Field(default_factory=list)
+    entrypoint: str | None = None
+    env: dict[str, str] = Field(default_factory=dict)
+    mounts: list[DockerMount] = Field(default_factory=list)
+    tmpfs: list[TmpfsMount] = Field(default_factory=list)
+    timeout_seconds: int = Field(gt=0)
+    working_dir: str | None = None
+    stdin_payload: bytes | None = None
+    security: SecurityProfile = Field(default_factory=SecurityProfile)
+    resources: ResourceLimits = Field(default_factory=ResourceLimits)
+
+
+class DockerRuntimeResult(BaseModel):
+    """Output payload for a primitive Docker runtime execution."""
+
+    ok: bool
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""
+    duration_seconds: float | None = Field(default=None, ge=0)
+    container_id: str | None = None
+    error: ErrorEnvelope | None = None
+
+    @model_validator(mode="after")
+    def _reject_success_with_error(self) -> DockerRuntimeResult:
+        if self.ok and self.error is not None:
+            raise ValueError("error must be null when ok is true")
+        if not self.ok and self.error is None:
+            raise ValueError("error must be present when ok is false")
+        return self

dr_docker/errors.py

@@ -0,0 +1,33 @@
+"""Shared typed error envelope contracts."""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, JsonValue, field_validator
+
+from ._json_validation import ensure_finite_json_value
+
+
+class ErrorCode(str, Enum):
+    """Canonical error codes for primitive runtime integrations."""
+
+    TIMEOUT = "timeout"
+    UNAVAILABLE = "unavailable"
+    INTERNAL_ERROR = "internal_error"
+
+
+class ErrorEnvelope(BaseModel):
+    """Standard error payload shared across primitive contracts."""
+
+    code: ErrorCode
+    message: str = Field(min_length=1)
+    retriable: bool = False
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @field_validator("details")
+    @classmethod
+    def _ensure_json_safe_details(
+        cls, details: dict[str, JsonValue]
+    ) -> dict[str, JsonValue]:
+        for key, value in details.items():
+            ensure_finite_json_value(value, path=f"details.{key}")
+        return details

dr_docker/subprocess_adapter.py

@@ -0,0 +1,362 @@
+"""Concrete RuntimeAdapter using subprocess + Docker CLI."""
+
+from __future__ import annotations
+
+import logging
+import math
+import os
+import selectors
+import shutil
+import subprocess
+import time
+from contextlib import suppress
+from pathlib import Path
+from threading import Thread
+from typing import BinaryIO
+
+from .cidfile import new_cidfile_path
+from .cleanup import cleanup_container_from_cidfile
+from .docker_contract import (
+    DockerRuntimeRequest,
+    DockerRuntimeResult,
+)
+from .errors import ErrorCode, ErrorEnvelope
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _build_docker_cmd(
+    request: DockerRuntimeRequest,
+    cidfile: Path,
+) -> list[str]:
+    """Translate a DockerRuntimeRequest into docker run CLI args."""
+    sec = request.security
+    res = request.resources
+
+    cmd: list[str] = [
+        "docker",
+        "run",
+        "--interactive",
+        "--rm",
+        f"--cidfile={cidfile}",
+    ]
+
+    if request.entrypoint is not None:
+        cmd.extend(["--entrypoint", request.entrypoint])
+
+    # Security profile
+    if sec.read_only:
+        cmd.append("--read-only")
+    if sec.cap_drop:
+        cmd.append(f"--cap-drop={sec.cap_drop}")
+    if sec.no_new_privileges:
+        cmd.append("--security-opt=no-new-privileges")
+    if sec.network_disabled:
+        cmd.append("--network=none")
+
+    # Resource limits
+    cmd.append(f"--memory={res.memory}")
+    cmd.append(f"--cpus={res.cpus}")
+    cmd.append(f"--pids-limit={res.pids_limit}")
+    if res.cpu_seconds is not None:
+        cmd.extend(["--ulimit", f"cpu={res.cpu_seconds}:{res.cpu_seconds}"])
+    if res.fsize_bytes is not None:
+        cmd.extend(["--ulimit", f"fsize={res.fsize_bytes}:{res.fsize_bytes}"])
+    if res.nofile is not None:
+        cmd.extend(["--ulimit", f"nofile={res.nofile}:{res.nofile}"])
+    if res.nproc is not None:
+        cmd.extend(["--ulimit", f"nproc={res.nproc}:{res.nproc}"])
+
+    # Tmpfs mounts
+    for tmpfs in request.tmpfs:
+        exec_flag = ",exec" if tmpfs.exec_ else ""
+        opts = f"{tmpfs.target}:rw,nosuid{exec_flag},size={tmpfs.size}"
+        cmd.extend(["--tmpfs", opts])
+
+    # Bind mounts
+    for mount in request.mounts:
+        ro = ",readonly" if mount.read_only else ""
+        cmd.extend(
+            [
+                "--mount",
+                f"type=bind,source={mount.source},target={mount.target}{ro}",
+            ]
+        )
+
+    # Environment
+    for key, value in request.env.items():
+        cmd.extend(["-e", f"{key}={value}"])
+
+    # Working directory
+    if request.working_dir is not None:
+        cmd.extend(["-w", request.working_dir])
+
+    # Image + command
+    cmd.append(request.image)
+    cmd.extend(request.command)
+
+    return cmd
+
+
+def _collect_capped_process_output(
+    proc: subprocess.Popen[bytes],
+    *,
+    cmd: list[str],
+    timeout_seconds: float,
+    stdout_limit: int,
+    stderr_limit: int,
+) -> tuple[int, str, str]:
+    """Selector-based concurrent stdout/stderr reader with byte caps."""
+    stdout = proc.stdout
+    stderr = proc.stderr
+    if stdout is None or stderr is None:
+        missing = []
+        if stdout is None:
+            missing.append("stdout")
+        if stderr is None:
+            missing.append("stderr")
+        raise RuntimeError(
+            f"Missing subprocess {' and '.join(missing)} pipe(s) for command: {cmd!r}"
+        )
+
+    stream_buffers: dict[int, bytearray] = {
+        stdout.fileno(): bytearray(),
+        stderr.fileno(): bytearray(),
+    }
+    stream_limits = {
+        stdout.fileno(): stdout_limit,
+        stderr.fileno(): stderr_limit,
+    }
+    stream_totals = {
+        stdout.fileno(): 0,
+        stderr.fileno(): 0,
+    }
+    stream_truncated = {
+        stdout.fileno(): False,
+        stderr.fileno(): False,
+    }
+
+    with selectors.DefaultSelector() as selector:
+        selector.register(stdout, selectors.EVENT_READ)
+        selector.register(stderr, selectors.EVENT_READ)
+        start = time.monotonic()
+
+        while selector.get_map():
+            remaining = timeout_seconds - (time.monotonic() - start)
+            if remaining <= 0:
+                proc.kill()
+                proc.wait()
+                raise subprocess.TimeoutExpired(cmd=cmd, timeout=timeout_seconds)
+            events = selector.select(timeout=remaining)
+            for key, _ in events:
+                chunk = os.read(key.fd, 65536)
+                if not chunk:
+                    selector.unregister(key.fileobj)
+                    continue
+                stream_totals[key.fd] += len(chunk)
+                buffer = stream_buffers[key.fd]
+                limit = stream_limits[key.fd]
+                remaining_cap = limit - len(buffer)
+                if remaining_cap > 0:
+                    kept = chunk[:remaining_cap]
+                    buffer.extend(kept)
+                    if len(kept) < len(chunk):
+                        stream_truncated[key.fd] = True
+                else:
+                    stream_truncated[key.fd] = True
+
+    remaining = timeout_seconds - (time.monotonic() - start)
+    if remaining <= 0:
+        proc.kill()
+        proc.wait()
+        raise subprocess.TimeoutExpired(cmd=cmd, timeout=timeout_seconds)
+    try:
+        returncode = proc.wait(timeout=remaining)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+        raise
+
+    stdout_text = stream_buffers[stdout.fileno()].decode("utf-8", errors="replace")
+    stderr_text = stream_buffers[stderr.fileno()].decode("utf-8", errors="replace")
+    if stream_truncated[stdout.fileno()]:
+        stdout_text += (
+            "\n[stdout truncated: "
+            f"{stream_totals[stdout.fileno()]} bytes total, "
+            f"capped at {stdout_limit} bytes]"
+        )
+    if stream_truncated[stderr.fileno()]:
+        stderr_text += (
+            "\n[stderr truncated: "
+            f"{stream_totals[stderr.fileno()]} bytes total, "
+            f"capped at {stderr_limit} bytes]"
+        )
+
+    return returncode, stdout_text, stderr_text
+
+
+class SubprocessDockerAdapter:
+    """Execute Docker containers via subprocess with stream capping."""
+
+    def __init__(
+        self,
+        *,
+        max_stdout_bytes: int = 1_048_576,
+        max_stderr_bytes: int = 1_048_576,
+    ) -> None:
+        self._max_stdout_bytes = max_stdout_bytes
+        self._max_stderr_bytes = max_stderr_bytes
+
+    def execute_in_runtime(self, request: DockerRuntimeRequest) -> DockerRuntimeResult:
+        """Build docker run CLI, execute, return result."""
+        if not shutil.which("docker"):
+            return DockerRuntimeResult(
+                ok=False,
+                error=ErrorEnvelope(
+                    code=ErrorCode.UNAVAILABLE,
+                    message="Docker CLI not found on PATH",
+                ),
+            )
+
+        # Compute cpu_seconds from timeout if not explicitly set
+        resources = request.resources
+        if resources.cpu_seconds is None:
+            cpu_seconds = max(1, math.ceil(request.timeout_seconds))
+            resources = resources.model_copy(update={"cpu_seconds": cpu_seconds})
+            request = request.model_copy(update={"resources": resources})
+
+        try:
+            cidfile = new_cidfile_path()
+            cmd = _build_docker_cmd(request, cidfile)
+        except OSError as exc:
+            return DockerRuntimeResult(
+                ok=False,
+                error=ErrorEnvelope(
+                    code=ErrorCode.UNAVAILABLE,
+                    message=f"Failed to prepare Docker runtime: {exc}",
+                ),
+            )
+        start = time.monotonic()
+
+        try:
+            return self._run(cmd, request, cidfile, start)
+        finally:
+            cleanup_container_from_cidfile(cidfile)
+
+    def _run(
+        self,
+        cmd: list[str],
+        request: DockerRuntimeRequest,
+        cidfile: Path,
+        start: float,
+    ) -> DockerRuntimeResult:
+        try:
+            with subprocess.Popen(
+                cmd,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            ) as proc:
+                stdin = proc.stdin
+                if stdin is None:
+                    raise RuntimeError(
+                        f"Missing subprocess stdin pipe for command: {cmd!r}"
+                    )
+
+                writer = Thread(
+                    target=self._write_stdin_and_close,
+                    args=(stdin, request.stdin_payload),
+                    daemon=True,
+                )
+                writer.start()
+                try:
+                    returncode, stdout_text, stderr_text = (
+                        _collect_capped_process_output(
+                            proc,
+                            cmd=cmd,
+                            timeout_seconds=float(request.timeout_seconds),
+                            stdout_limit=self._max_stdout_bytes,
+                            stderr_limit=self._max_stderr_bytes,
+                        )
+                    )
+                finally:
+                    writer.join()
+
+            duration = time.monotonic() - start
+            container_id = self._read_cidfile(cidfile)
+
+            if returncode == 0:
+                return DockerRuntimeResult(
+                    ok=True,
+                    exit_code=returncode,
+                    stdout=stdout_text,
+                    stderr=stderr_text,
+                    duration_seconds=duration,
+                    container_id=container_id,
+                )
+            return DockerRuntimeResult(
+                ok=False,
+                exit_code=returncode,
+                stdout=stdout_text,
+                stderr=stderr_text,
+                duration_seconds=duration,
+                container_id=container_id,
+                error=ErrorEnvelope(
+                    code=ErrorCode.INTERNAL_ERROR,
+                    message=f"Container exited with code {returncode}",
+                ),
+            )
+
+        except subprocess.TimeoutExpired:
+            duration = time.monotonic() - start
+            return DockerRuntimeResult(
+                ok=False,
+                duration_seconds=duration,
+                container_id=self._read_cidfile(cidfile),
+                error=ErrorEnvelope(
+                    code=ErrorCode.TIMEOUT,
+                    message=(f"Container timed out after {request.timeout_seconds}s"),
+                    retriable=True,
+                ),
+            )
+        except (FileNotFoundError, OSError) as exc:
+            duration = time.monotonic() - start
+            return DockerRuntimeResult(
+                ok=False,
+                duration_seconds=duration,
+                error=ErrorEnvelope(
+                    code=ErrorCode.UNAVAILABLE,
+                    message=f"Docker execution failed: {exc}",
+                ),
+            )
+        except RuntimeError as exc:
+            duration = time.monotonic() - start
+            return DockerRuntimeResult(
+                ok=False,
+                duration_seconds=duration,
+                error=ErrorEnvelope(
+                    code=ErrorCode.INTERNAL_ERROR,
+                    message=str(exc),
+                ),
+            )
+
+    @staticmethod
+    def _read_cidfile(cidfile: Path) -> str | None:
+        try:
+            cid = cidfile.read_text(encoding="utf-8").strip()
+            return cid if cid else None
+        except OSError:
+            return None
+
+    @staticmethod
+    def _write_stdin_and_close(
+        stdin_pipe: BinaryIO,
+        stdin_payload: bytes | None,
+    ) -> None:
+        try:
+            if stdin_payload is not None:
+                with suppress(BrokenPipeError):
+                    stdin_pipe.write(stdin_payload)
+        finally:
+            with suppress(BrokenPipeError, OSError):
+                stdin_pipe.close()

dr_docker/version.py

@@ -0,0 +1,4 @@
+"""Version constants for dr_docker."""
+
+__version__ = "0.4.0"
+CONTRACT_VERSION = "0.4.0"

dr_docker-0.4.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: dr-docker
+Version: 0.4.0
+Summary: Docker runtime contracts and subprocess adapter
+Project-URL: Homepage, https://github.com/drothermel/dr-docker
+Project-URL: Repository, https://github.com/drothermel/dr-docker
+Project-URL: Issues, https://github.com/drothermel/dr-docker/issues
+Author: NL Stack
+License: MIT License
+        
+        Copyright (c) 2026 Danielle Rothermel
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: contracts,docker,runtime,sandbox,subprocess
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0,>=2.0
+Description-Content-Type: text/markdown
+
+# dr-docker
+
+Reusable Docker execution contracts and adapters.
+
+## Purpose
+
+This repo provides Docker runtime contracts and a concrete subprocess adapter:
+- Docker runtime request/result contracts with security and resource profiles
+- Runtime adapter protocol
+- Subprocess-based Docker adapter with stream capping and cidfile cleanup
+- Typed error envelopes
+
+## Public Surface
+
+```python
+from dr_docker import (
+    CONTRACT_VERSION,
+    DockerMount,
+    DockerRuntimeRequest,
+    DockerRuntimeResult,
+    ErrorCode,
+    ErrorEnvelope,
+    ResourceLimits,
+    RuntimeAdapter,
+    RuntimePrimitiveError,
+    SecurityProfile,
+    SubprocessDockerAdapter,
+    TmpfsMount,
+    __version__,
+)
+```
+
+## Contract Guarantees
+
+- `DockerRuntimeResult(ok=False)` requires `error`
+- Successful result envelopes must not include `error`
+- Error envelopes are typed (`ErrorCode`) with non-empty message and JSON-safe details
+- Supported `ErrorCode` values are `timeout`, `unavailable`, and `internal_error`
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest -q
+uv run ruff format --check
+uv run ruff check
+uv run ty check
+```
+
+## Publishing
+
+```bash
+cp .env.example .env
+# set PYPI_API_TOKEN in .env
+set -a; source .env; set +a
+uv build
+uvx twine check dist/*
+uvx twine upload -u __token__ -p "$PYPI_API_TOKEN" dist/*
+```

dr_docker-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+dr_docker/__init__.py,sha256=tkZXsRzZkMvrWcsIkMSQysgHW65MG-_gjLP8MQkIChQ,747
+dr_docker/_json_validation.py,sha256=u-3aF6QVXwdVvHZ6pcQ5AoYEBCg09ukmGWpcpbMyL_g,749
+dr_docker/adapters.py,sha256=VHZC8H_SOGU4_0aOQyQ8Y9bzWuvbB45xMpPRX99wmN4,673
+dr_docker/cidfile.py,sha256=bmAvOqRcRLVn9EekrjiB3zdc7uKBox2JK7znpD65E3Y,2243
+dr_docker/cleanup.py,sha256=VAGa9e50oupLpzMDWgWW4_t1Xz0ACkAUUa8xiT2pUDE,1655
+dr_docker/docker_contract.py,sha256=juRuUZ5xQL1vExfa2gA-3_BTKPprGYe7IUIoMnkfwf0,2587
+dr_docker/errors.py,sha256=m9zYukhar7OExyNBOn_So3DSFxnR36tJYuosqwzbcIE,930
+dr_docker/subprocess_adapter.py,sha256=t6eGDHPiZG6gAId5dppenPtiZL-6oujiRBTSF5YOAVM,11808
+dr_docker/version.py,sha256=fIxJcQUd7SPNcA6WpYQwPNvBo3VigOhykDYIYGB1P_0,89
+dr_docker-0.4.0.dist-info/METADATA,sha256=LZpIH7mMWM8ZMXY5gKGKOAEuT8u0Xahr_fu4ALIDg9s,3424
+dr_docker-0.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dr_docker-0.4.0.dist-info/licenses/LICENSE,sha256=COcMQ9vaxs7t9tuV-1VpdoDgunQqK1fdIfedkmmKLh4,1075
+dr_docker-0.4.0.dist-info/RECORD,,

dr_docker-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dr_docker-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danielle Rothermel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.