simulo 0.26.0__py3-none-any.whl

simulo/_client/install_samples.py

@@ -0,0 +1,267 @@
+"""Install the public Simulo sample collection with a normal Git clone."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+SAMPLES_REPOSITORY_URL = "https://github.com/simulo-org/simulo-samples.git"
+DEFAULT_SAMPLES_DIRECTORY_NAME = "simulo-samples"
+CLONE_TIMEOUT_S = 300
+_MAX_GIT_STDERR_INPUT_BYTES = 4096
+_MAX_GIT_STDERR_RENDERED_BYTES = 4096
+_GIT_OUTPUT_PREFIX = "  | git: "
+_GIT_PROGRESS_PREFIXES = (
+    "Cloning into ",
+    "Receiving objects:",
+    "Resolving deltas:",
+    "remote: Enumerating objects:",
+    "remote: Counting objects:",
+    "remote: Compressing objects:",
+    "remote: Total ",
+)
+
+
+class InstallSamplesError(RuntimeError):
+    """Raised when the samples cannot be installed."""
+
+
+class InstallSamplesUsageError(ValueError):
+    """Raised when the requested install destination is unsafe to use."""
+
+
+@dataclass(frozen=True)
+class InstalledSamples:
+    """The local sample collection created by :func:`install_samples`."""
+
+    path: Path
+
+
+def _git_environment() -> dict[str, str]:
+    """Return a non-interactive environment for a public clone."""
+    environment = dict(os.environ)
+    for key in tuple(environment):
+        if any(fragment in key.upper() for fragment in ("TOKEN", "SECRET", "CREDENTIAL")):
+            environment.pop(key)
+    environment.pop("GIT_CONFIG_PARAMETERS", None)
+    environment.update(
+        {
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_ASKPASS": "",
+            "GCM_INTERACTIVE": "never",
+            "GIT_CONFIG_COUNT": "1",
+            "GIT_CONFIG_KEY_0": "credential.helper",
+            "GIT_CONFIG_VALUE_0": "",
+        }
+    )
+    return environment
+
+
+def _run_git(argv: list[str], *, timeout_s: int, env: dict[str, str]) -> subprocess.CompletedProcess[str]:
+    """Run Git through the one seam tests replace."""
+    return subprocess.run(argv, capture_output=True, check=False, env=env, text=True, timeout=timeout_s)
+
+
+def _stderr_tail(stderr: str | bytes | None) -> str:
+    if isinstance(stderr, bytes):
+        stderr = stderr.decode(errors="replace")
+    if not stderr:
+        return ""
+    encoded = stderr.encode("utf-8", errors="replace")
+    bounded_bytes = encoded[-_MAX_GIT_STDERR_INPUT_BYTES:]
+    was_truncated = len(bounded_bytes) < len(encoded)
+    bounded = bounded_bytes.decode("utf-8", errors="replace")
+    lines = bounded.splitlines()
+    starts_mid_line = was_truncated and encoded[-_MAX_GIT_STDERR_INPUT_BYTES - 1] not in (ord("\n"), ord("\r"))
+    if starts_mid_line and len(lines) > 1:
+        lines = lines[1:]
+    non_progress_lines = [line for line in lines if not line.startswith(_GIT_PROGRESS_PREFIXES)]
+    return _quote_git_output(non_progress_lines[-10:])
+
+
+def _quote_git_output(lines: list[str]) -> str:
+    """Prefix Git output without exceeding the CLI's rendered stderr bound."""
+    output: list[str] = []
+    output_bytes = 0
+    prefix_bytes = len(_GIT_OUTPUT_PREFIX.encode("utf-8"))
+    for line in reversed(lines):
+        printable_line = "".join(character for character in line if character.isprintable())
+        quoted_line = f"{_GIT_OUTPUT_PREFIX}{printable_line}"
+        quoted_line_bytes = len(quoted_line.encode("utf-8", errors="replace"))
+        separator_bytes = 1 if output else 0
+        if output_bytes + separator_bytes + quoted_line_bytes <= _MAX_GIT_STDERR_RENDERED_BYTES:
+            output.insert(0, quoted_line)
+            output_bytes += separator_bytes + quoted_line_bytes
+        elif not output:
+            available_line_bytes = _MAX_GIT_STDERR_RENDERED_BYTES - prefix_bytes
+            output.append(
+                _GIT_OUTPUT_PREFIX
+                + printable_line.encode("utf-8", errors="replace")[-available_line_bytes:].decode(errors="ignore")
+            )
+            break
+        else:
+            break
+    return "\n".join(output)
+
+
+def _remove_read_only_path(function: object, path: str, _exc_info: object) -> None:
+    """Make Windows Git object files writable, then retry rmtree's operation."""
+    # Known and owned Windows residual: this misses directory junctions, which Python 3.11 rmtree can follow; staging
+    # access follows inherited ACLs.
+    if not os.path.islink(path):
+        os.chmod(path, 0o700)
+    function(path)  # type: ignore[operator]
+
+
+def _directory_identity(path: Path) -> tuple[int, int]:
+    status = path.stat()
+    return status.st_dev, status.st_ino
+
+
+def _remove_staging_directory(staging: Path, identity: tuple[int, int]) -> None:
+    try:
+        current_identity = _directory_identity(staging)
+    except FileNotFoundError:
+        return
+    except OSError:
+        print(f"warning: could not inspect partial samples install at {staging}", file=sys.stderr)
+        return
+    if current_identity != identity:
+        print(f"warning: partial samples install path no longer belongs to this invocation: {staging}", file=sys.stderr)
+        return
+    try:
+        shutil.rmtree(staging, onerror=_remove_read_only_path)
+    except OSError:
+        print(f"warning: could not remove partial samples install at {staging}", file=sys.stderr)
+
+
+def _clone_failure(
+    reason: str, stderr: str | bytes | None, *, explain_public_repository: bool = False
+) -> InstallSamplesError:
+    tail = _stderr_tail(stderr)
+    explanation = (
+        "The samples repository is public and this command does not sign in.\n"
+        "An authentication error means Git could not reach the repository or its host, not that there is a problem "
+        "with your account."
+    )
+    message = f"{reason}\n{tail}" if tail else reason
+    if explain_public_repository:
+        message = f"{message}\n{explanation}"
+    return InstallSamplesError(message)
+
+
+def _target_exists_error(target: Path) -> InstallSamplesUsageError:
+    if not target.is_dir():
+        return InstallSamplesUsageError(f"{target} exists and is not a directory.")
+    return InstallSamplesUsageError(f"{target} already exists.")
+
+
+def _git_is_reachable_through_working_directory(
+    named_git_path: Path, git_executable: Path, working_directory: Path
+) -> bool:
+    """Return whether resolving Git depends on the current working directory."""
+    return not named_git_path.is_absolute() or working_directory in {
+        named_git_path.parent,
+        named_git_path.parent.resolve(),
+        git_executable.parent,
+    }
+
+
+def _clone_has_sample_files(staging: Path) -> bool:
+    """Return whether a successful clone produced a user-visible worktree entry.
+
+    An unreadable staging directory counts as no sample files. This is the only
+    filesystem read on the success path, and letting an OSError escape here would
+    abandon the staging directory and break the promise that a failed install
+    leaves nothing behind.
+    """
+    try:
+        return any(entry.name != ".git" for entry in staging.iterdir())
+    except OSError:
+        return False
+
+
+def install_samples(
+    parent_directory: Path,
+    *,
+    repository_url: str = SAMPLES_REPOSITORY_URL,
+    directory_name: str = DEFAULT_SAMPLES_DIRECTORY_NAME,
+    timeout_s: int = CLONE_TIMEOUT_S,
+) -> InstalledSamples:
+    """Clone samples into *parent_directory* and reveal them atomically."""
+    target = parent_directory / directory_name
+    if target.exists():
+        raise _target_exists_error(target)
+
+    git_path = shutil.which("git")
+    if git_path is None:
+        raise InstallSamplesError(
+            "Git is required to install samples. Get it from https://git-scm.com/downloads and try again."
+        )
+    named_git_path = Path(git_path)
+    working_directory = Path.cwd().resolve()
+    git_executable = named_git_path.resolve()
+    if _git_is_reachable_through_working_directory(named_git_path, git_executable, working_directory):
+        raise InstallSamplesError(
+            f"Refusing resolved Git executable {git_executable}: its PATH entry is relative to or resolves through "
+            "the current working directory. Run this command from a different directory, or use a Git executable "
+            "outside the working directory."
+        )
+
+    staging = parent_directory / f".{directory_name}.partial-{os.getpid()}"
+    try:
+        staging.mkdir()
+    except FileExistsError:
+        raise InstallSamplesError(f"Partial samples install path already exists: {staging}.") from None
+    except OSError as exc:
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not prepare samples install at {staging}: {reason}.") from None
+    staging_identity = _directory_identity(staging)
+
+    print("Cloning the samples with full history; this can take a minute.", file=sys.stderr)
+    argv = [str(git_executable), "clone", "--", repository_url, str(staging)]
+    try:
+        completed = _run_git(argv, timeout_s=timeout_s, env=_git_environment())
+    except subprocess.TimeoutExpired as exc:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone timed out after {timeout_s} seconds. "
+            f"If your connection needs longer, clone it by hand with git clone {repository_url}.",
+            exc.stderr,
+        ) from None
+    except KeyboardInterrupt:
+        _remove_staging_directory(staging, staging_identity)
+        raise
+    except OSError as exc:
+        _remove_staging_directory(staging, staging_identity)
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not start Git clone: {reason}.") from None
+
+    if completed.returncode != 0:
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure(
+            f"Git clone failed with exit code {completed.returncode}.",
+            completed.stderr,
+            explain_public_repository=True,
+        )
+
+    if not _clone_has_sample_files(staging):
+        _remove_staging_directory(staging, staging_identity)
+        raise _clone_failure("Git clone produced an empty working tree.", completed.stderr)
+
+    if target.exists():
+        _remove_staging_directory(staging, staging_identity)
+        raise _target_exists_error(target)
+
+    try:
+        os.rename(staging, target)
+    except OSError as exc:
+        _remove_staging_directory(staging, staging_identity)
+        reason = exc.strerror or str(exc)
+        raise InstallSamplesError(f"Could not finish installing samples: {reason}.") from None
+
+    return InstalledSamples(path=target.resolve())

simulo/_client/jobs_api.py

@@ -0,0 +1,224 @@
+"""HTTP client for the Simulo jobs API — stdlib ``urllib`` only, torch-free.
+
+The thin client and the executor behave as if on TWO SEPARATE MACHINES: this
+client NEVER reads the run store from disk — it talks HTTP to "the platform".
+Today that platform is the local stand-in (``simulo-backend serve``, serving
+``~/.simulo/runs`` on 127.0.0.1) or the real cloud control plane, once
+credentials or ``SIMULO_API_URL``/``SIMULO_ENV`` point at it. The wire contract
+lives in :mod:`simulo.interfaces.platform.runs` (routes, offset semantics,
+error shape). Request plumbing (the structured-error parser, the
+https-when-token guard) is shared with ``submit_api.py`` via ``http.py``.
+
+Configuration (environment):
+
+* ``SIMULO_API_URL`` — base URL of the jobs API. See ``config.resolve_base_url``
+  for the full precedence order (env -> ``SIMULO_ENV`` preset -> credentials ->
+  local default). Defaults to ``http://127.0.0.1:<JOBS_API_DEFAULT_PORT>`` (the
+  local stand-in) when nothing else resolves.
+* ``SIMULO_API_TOKEN`` — when set, sent as ``Authorization: Bearer <token>``.
+  This is the offline/manual override; the cloud path passes an explicit
+  ``token=`` (resolved from ``~/.simulo/credentials``) which takes precedence.
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.parse
+from typing import Any, Optional
+
+from simulo._client import http
+from simulo.interfaces.platform.runs import (
+    JOB_LOGS_ROUTE_TEMPLATE,
+    JOB_RESULT_ROUTE_TEMPLATE,
+    JOB_ROUTE_TEMPLATE,
+    JOB_SCOPE_MINE,
+    JOBS_API_DEFAULT_PORT,
+    JOBS_ROUTE,
+)
+
+API_URL_ENV = "SIMULO_API_URL"
+API_TOKEN_ENV = "SIMULO_API_TOKEN"
+
+_DEFAULT_BASE_URL = f"http://127.0.0.1:{JOBS_API_DEFAULT_PORT}"
+_REQUEST_TIMEOUT_S = 10.0  # every outbound call has an explicit timeout (NFR)
+
+_LIST_PAGE_LIMIT = 100  # the contract's page-size ceiling (LOG_CHUNK_MAX_BYTES-style cap)
+#: Safety cap on pages fetched by `list_jobs` (100k jobs) — guards against an
+#: infinite loop if a server bug always reports a full page; not a real limit.
+_LIST_MAX_PAGES = 1000
+
+#: Mirrors the sibling API clients' hint (submit_api.py / cancel_api.py /
+#: view_session_api.py) — one consistent, cloud-first unavailable message
+#: across every HTTP-talking module in ``_client``.
+_UNAVAILABLE_HINT = "Check SIMULO_API_URL / SIMULO_ENV, and that you are logged in (`simulo login`)."
+
+# Backward-compatible aliases: these three names used to be defined directly in
+# this module; they now live in http.py (shared with submit_api.py) but every
+# existing import site (`from simulo._client.jobs_api import JobsApiError, ...`)
+# must keep working unchanged.
+JobsApiError = http.HttpError
+JobsApiUnavailable = http.HttpUnavailable
+JobsApiHTTPError = http.HttpHTTPError
+
+
+class JobsApiClient:
+    """Client for the four read-only jobs endpoints."""
+
+    def __init__(self, base_url: Optional[str] = None, *, token: Optional[str] = None) -> None:
+        resolved = base_url or os.environ.get(API_URL_ENV) or _DEFAULT_BASE_URL
+        if not resolved.startswith(("http://", "https://")):
+            raise JobsApiError(f"{API_URL_ENV} must be an http(s) URL, got {resolved!r}.")
+        self._base_url = resolved.rstrip("/")
+        self._token = token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def list_jobs(self, *, scope: str = JOB_SCOPE_MINE) -> list[dict[str, Any]]:
+        """All job records the API returns, most recent first.
+
+        Loops every page at ``_LIST_PAGE_LIMIT`` (100) rather than fetching
+        page 1 alone, so a run store with more than 100 recorded jobs is not
+        silently truncated to the first page.
+
+        ``scope`` (contract ``runs.JOB_SCOPE_MINE``/``JOB_SCOPE_ORG``):
+        ``"mine"`` (the default) lists only jobs the caller themselves
+        submitted; ``"org"`` (``simulo jobs --org``) lists every job in the
+        organization. Sent on every request, including the default, so a
+        server too old to know the parameter simply ignores it (unaffected —
+        the parameter is additive).
+        """
+        items: list[dict[str, Any]] = []
+        page = 1
+        while page <= _LIST_MAX_PAGES:
+            payload = self._get(JOBS_ROUTE, {"limit": str(_LIST_PAGE_LIMIT), "page": str(page), "scope": scope})
+            page_items = payload.get("items") if isinstance(payload, dict) else None
+            if not isinstance(page_items, list):
+                raise JobsApiError(f"Malformed jobs list response from {self._base_url} (no 'items' array).")
+            items.extend(item for item in page_items if isinstance(item, dict))
+            if len(page_items) < _LIST_PAGE_LIMIT:
+                return items  # a short page means there is nothing more to fetch
+            page += 1
+        return items
+
+    def list_jobs_page(
+        self, *, limit: int, page: int = 1, scope: str = JOB_SCOPE_MINE
+    ) -> tuple[list[dict[str, Any]], int]:
+        """One page of *limit* job records (most recent first) plus the total
+        job count across every page.
+
+        The single-request counterpart to :meth:`list_jobs` (which loops
+        every page for a full listing — the CLI's ``simulo jobs --json``) —
+        backs the CLI's bounded table view, so it never pays for pages it
+        will not display. *page* defaults to the first; the CLI's
+        ``_fetch_list_view`` walks it forward for a view wider than one
+        server page.
+
+        ``scope``: see :meth:`list_jobs`.
+        """
+        payload = self._get(JOBS_ROUTE, {"limit": str(limit), "page": str(page), "scope": scope})
+        items = payload.get("items") if isinstance(payload, dict) else None
+        total = payload.get("total") if isinstance(payload, dict) else None
+        if not isinstance(items, list) or not isinstance(total, int):
+            raise JobsApiError(f"Malformed jobs list response from {self._base_url} (no 'items'/'total').")
+        return [item for item in items if isinstance(item, dict)], total
+
+    def get_latest_job(self, *, scope: str = JOB_SCOPE_MINE) -> Optional[dict[str, Any]]:
+        """The most recent job record, or ``None`` when no jobs exist yet.
+
+        The contract orders ``GET /v1/jobs`` most recent first, so the latest
+        job is simply the first item of page 1 — fetched with ``limit=1``,
+        never the full listing. This is the client-side resolution ``simulo
+        logs`` / ``simulo result`` use when the job id is omitted (the cloud
+        CLI keeps this exact behavior).
+        """
+        payload = self._get(JOBS_ROUTE, {"limit": "1", "page": "1", "scope": scope})
+        items = payload.get("items") if isinstance(payload, dict) else None
+        if not isinstance(items, list):
+            raise JobsApiError(f"Malformed jobs list response from {self._base_url} (no 'items' array).")
+        if not items:
+            return None
+        latest = items[0]
+        if not isinstance(latest, dict) or not isinstance(latest.get("job_id"), str) or not latest["job_id"]:
+            raise JobsApiError(f"Malformed job record in the jobs list from {self._base_url} (no 'job_id').")
+        return latest
+
+    def get_job(self, job_id: str, *, scope: str = JOB_SCOPE_MINE) -> dict[str, Any]:
+        """One job record. Raises :class:`JobsApiHTTPError` (404) when unknown."""
+        payload = self._get(JOB_ROUTE_TEMPLATE.format(job_id=_quote(job_id)), {"scope": scope})
+        if not isinstance(payload, dict):
+            raise JobsApiError("Malformed job record response for the selected job.")
+        return payload
+
+    def get_log_chunk(
+        self,
+        job_id: str,
+        offset: int,
+        *,
+        tail_bytes: Optional[int] = None,
+        scope: str = JOB_SCOPE_MINE,
+    ) -> tuple[str, int, str, Optional[int]]:
+        """One log chunk from ``offset``; returns ``(chunk, next_offset, status, start_offset)``.
+
+        Byte-offset semantics per the contract: resume from the returned
+        ``next_offset``; an empty chunk with an unchanged offset means "caught
+        up" — poll again while ``status`` is non-terminal.
+
+        ``tail_bytes`` (contract tail semantics; requires ``offset == 0``) asks
+        the server to start the read that many bytes before the END of the
+        stream. ``start_offset`` in the returned tuple is the server's computed
+        start position when tail was honored, and ``None`` otherwise —
+        including when ``tail_bytes`` was requested but the server is too old
+        to know the parameter (it then answers from offset 0 exactly like a
+        plain request; callers use ``start_offset is None`` to detect that and
+        degrade to full history rather than mis-trim).
+
+        **Unavailable logs.** A finished job whose archived log
+        has aged out of retention, or whose bytes the platform could not keep,
+        answers ``410`` and raises :class:`JobsApiHTTPError` with
+        ``status == 410`` and ``code`` in
+        :data:`~simulo.interfaces.platform.runs.LOG_ARCHIVE_UNAVAILABLE_CODES`
+        (``log_archive_expired`` / ``log_archive_lost``). This is a TERMINAL
+        condition — retrying the same request cannot succeed — and is
+        deliberately NOT an empty chunk, so a caller cannot mistake "these
+        logs no longer exist" for "this run printed nothing". A caller that
+        loops on ``next_offset`` must stop on it rather than retry; the CLI's
+        ``_report_log_archive_unavailable`` is the reference handling.
+        """
+        query = {"offset": str(offset), "scope": scope}
+        if tail_bytes is not None:
+            query["tail_bytes"] = str(tail_bytes)
+        payload = self._get(JOB_LOGS_ROUTE_TEMPLATE.format(job_id=_quote(job_id)), query)
+        if not isinstance(payload, dict):
+            raise JobsApiError("Malformed log chunk response for the selected job.")
+        chunk, next_offset, status = payload.get("chunk"), payload.get("next_offset"), payload.get("status")
+        if not isinstance(chunk, str) or not isinstance(next_offset, int) or not isinstance(status, str):
+            raise JobsApiError("Malformed log chunk response for the selected job.")
+        start_offset = payload.get("start_offset") if tail_bytes is not None else None
+        if start_offset is not None and not isinstance(start_offset, int):
+            raise JobsApiError("Malformed log chunk response for the selected job.")
+        return chunk, next_offset, status, start_offset
+
+    def get_result(self, job_id: str, *, scope: str = JOB_SCOPE_MINE) -> Any:
+        """The result JSON. 404 :class:`JobsApiHTTPError` until the job succeeded."""
+        return self._get(JOB_RESULT_ROUTE_TEMPLATE.format(job_id=_quote(job_id)), {"scope": scope})
+
+    def _get(self, path: str, query: Optional[dict[str, str]] = None) -> Any:
+        url = self._base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        token = self._token if self._token is not None else os.environ.get(API_TOKEN_ENV)
+        return http.request_json(
+            "GET",
+            url,
+            token=token,
+            api_base_url=self._base_url,
+            timeout=_REQUEST_TIMEOUT_S,
+            unavailable_hint=_UNAVAILABLE_HINT,
+        )
+
+
+def _quote(job_id: str) -> str:
+    """Percent-encode a job id for use as a single URL path segment."""
+    return http.quote_path_segment(job_id)