From e2849725eb23f0ebb6aa99fc9150630ed37d126f Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Sat, 31 Oct 2026 13:51:50 -0400 Subject: [PATCH 1/3] feat(engines): Lumina adapter with a bounded CLI runner Review repairs: timeout/cancel return within a finite allowance even if a descendant holds the pipes; an unexpected poll exception stops the owned child; output scan refuses OSError, junction/reparse points, and is bounded (10000 entries, depth 32); script entry points refused; single-pass placeholder substitution; real loopback boundary test. Test environment note: os.kill(pid, 0) is not a liveness probe on Windows (it calls TerminateProcess and raises OSError); the test now uses a non-signalling probe. Verified: backend/tests/engines 17 passed, 1 skipped (symlink creation not permitted for this account). Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/engines/__init__.py | 1 + backend/snapstudio_core/engines/cli_runner.py | 296 ++++++++++++++++ backend/snapstudio_core/engines/lumina.py | 190 ++++++++++ backend/tests/engines/__init__.py | 1 + .../engines/test_lumina_adapter_slice1.py | 327 ++++++++++++++++++ backend/tests/fixtures/engines/PROVENANCE.md | 1 + .../engines/lumina_api_2_preview.json | 1 + backend/tests/mocks/lumina_server.py | 48 +++ docs/internal/ENGINES.md | 19 + 9 files changed, 884 insertions(+) create mode 100644 backend/snapstudio_core/engines/__init__.py create mode 100644 backend/snapstudio_core/engines/cli_runner.py create mode 100644 backend/snapstudio_core/engines/lumina.py create mode 100644 backend/tests/engines/__init__.py create mode 100644 backend/tests/engines/test_lumina_adapter_slice1.py create mode 100644 backend/tests/fixtures/engines/PROVENANCE.md create mode 100644 backend/tests/fixtures/engines/lumina_api_2_preview.json create mode 100644 backend/tests/mocks/lumina_server.py create mode 100644 docs/internal/ENGINES.md diff --git a/backend/snapstudio_core/engines/__init__.py b/backend/snapstudio_core/engines/__init__.py new file mode 100644 index 00000000..e2c8b0ba --- /dev/null +++ b/backend/snapstudio_core/engines/__init__.py @@ -0,0 +1 @@ +"""Explicit local engine integrations.""" diff --git a/backend/snapstudio_core/engines/cli_runner.py b/backend/snapstudio_core/engines/cli_runner.py new file mode 100644 index 00000000..b9d3f308 --- /dev/null +++ b/backend/snapstudio_core/engines/cli_runner.py @@ -0,0 +1,296 @@ +"""Constrained execution for a user-configured local engine executable.""" +from __future__ import annotations + +import hashlib +import os +import re +import shutil +import stat +import subprocess +import threading +import time +import uuid +from dataclasses import dataclass +from pathlib import Path +from typing import Mapping, Sequence + + +_TOKEN = re.compile(r"\A(?:[^{}\x00\r\n]*|\{(?:job_dir|output_dir|input)\})+\Z") +_SAFE_NAME = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z") +_KIND = {".3mf": "3mf", ".stl": "stl", ".obj": "obj", ".glb": "glb", ".png": "png", ".json": "json"} +_MAX_SCAN_ENTRIES = 10000 +_MAX_SCAN_DEPTH = 32 +_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400) + + +class RunnerError(Exception): + """Safe runner refusal or bounded execution failure.""" + + def __init__(self, code: str, *, stdout: bytes = b"") -> None: + self.code = code + self.stdout = stdout + super().__init__(code) + + +@dataclass(frozen=True) +class RunnerResult: + job_dir: Path + returncode: int + stdout: bytes + artifacts: tuple[dict[str, object], ...] + + +class _Capture: + def __init__(self, cap: int, stop: threading.Event, lock: threading.Lock, + total: list[int]) -> None: + self.cap = cap + self.stop = stop + self.lock = lock + self.shared_total = total + self.data = bytearray() + self.total = 0 + + def drain(self, stream: object) -> None: + while True: + try: + chunk = stream.read(4096) # type: ignore[attr-defined] + except OSError: + return + if not chunk: + return + with self.lock: + room = max(0, self.cap - self.shared_total[0]) + self.shared_total[0] += len(chunk) + self.total += len(chunk) + self.data.extend(chunk[:room]) + if self.shared_total[0] > self.cap: + self.stop.set() + return + + +class CliRunner: + """Run a fixed executable and argument template without a shell. + + Every run gets a fresh directory created beneath `job_root`; process cancellation + targets only the exact Popen object created by this runner. + """ + + def __init__(self, executable: str | os.PathLike[str], job_root: str | os.PathLike[str], + argument_template: Sequence[str], *, timeout_s: float = 300.0, + output_limit: int = 1024 * 1024, + artifact_limit: int = 512 * 1024 * 1024) -> None: + self.executable = Path(executable).expanduser().resolve(strict=True) + if not self.executable.is_file(): + raise RunnerError("executable_invalid") + if self.executable.suffix.lower() in {".bat", ".cmd"}: + raise RunnerError("executable_script_refused") + self.job_root = Path(job_root).expanduser().resolve(strict=True) + if not self.job_root.is_dir(): + raise RunnerError("job_root_invalid") + if not isinstance(argument_template, (tuple, list)) or not all( + isinstance(arg, str) and _TOKEN.fullmatch(arg) for arg in argument_template): + raise RunnerError("argument_template_invalid") + if isinstance(timeout_s, bool) or not isinstance(timeout_s, (int, float)) or not 0 < timeout_s <= 3600: + raise RunnerError("timeout_invalid") + if isinstance(output_limit, bool) or not isinstance(output_limit, int) or not 1024 <= output_limit <= 64 * 1024 * 1024: + raise RunnerError("output_limit_invalid") + if isinstance(artifact_limit, bool) or not isinstance(artifact_limit, int) \ + or not 1 <= artifact_limit <= 2 * 1024 * 1024 * 1024: + raise RunnerError("artifact_limit_invalid") + self.argument_template = tuple(argument_template) + self.timeout_s = float(timeout_s) + self.output_limit = output_limit + self.artifact_limit = artifact_limit + self._lock = threading.Lock() + self._active: dict[int, subprocess.Popen[bytes]] = {} + + def run(self, *, inputs: Mapping[str, str] | None = None, + cancel_event: threading.Event | None = None) -> RunnerResult: + if inputs is None: + inputs = {} + if not isinstance(inputs, Mapping) or any(not _SAFE_NAME.fullmatch(k) or not isinstance(v, str) for k, v in inputs.items()): + raise RunnerError("input_invalid") + run_id = uuid.uuid4().hex + job_dir = (self.job_root / run_id).resolve() + if not job_dir.is_relative_to(self.job_root): + raise RunnerError("job_path_invalid") + job_dir.mkdir(mode=0o700) + output_dir = job_dir / "output" + output_dir.mkdir() + input_paths: dict[str, str] = {} + for name, value in inputs.items(): + source = Path(value).expanduser().resolve(strict=True) + if not source.is_file(): + raise RunnerError("input_invalid") + staged = job_dir / "input" / name + staged.parent.mkdir(exist_ok=True) + shutil.copyfile(source, staged) + input_paths[name] = str(staged) + values = {"job_dir": str(job_dir), "output_dir": str(output_dir), + "input": next(iter(input_paths.values()), "")} + for arg in self.argument_template: + if "{input}" in arg and len(input_paths) != 1: + raise RunnerError("input_placeholder_ambiguous") + rendered = [re.sub(r"\{(job_dir|output_dir|input)\}", + lambda match: values[match.group(1)], arg) + for arg in self.argument_template] + command = [str(self.executable), *rendered] + try: + process = subprocess.Popen(command, cwd=str(job_dir), shell=False, + stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, + stderr=subprocess.PIPE) + except OSError: + raise RunnerError("process_start_failed") from None + try: + with self._lock: + self._active[process.pid] = process + overflow = threading.Event() + budget_lock = threading.Lock() + output_total = [0] + stdout = _Capture(self.output_limit, overflow, budget_lock, output_total) + stderr = _Capture(self.output_limit, overflow, budget_lock, output_total) + readers = [threading.Thread(target=stdout.drain, args=(process.stdout,), daemon=True), + threading.Thread(target=stderr.drain, args=(process.stderr,), daemon=True)] + for reader in readers: + reader.start() + deadline = time.monotonic() + self.timeout_s + while process.poll() is None: + if cancel_event is not None and cancel_event.is_set(): + self._stop_owned(process) + raise RunnerError("cancelled", stdout=bytes(stdout.data)) + if overflow.is_set(): + self._stop_owned(process) + raise RunnerError("output_limit_exceeded", stdout=bytes(stdout.data)) + try: + output_size = self._output_size(output_dir) + except RunnerError: + self._stop_owned(process) + raise + if output_size > self.artifact_limit: + self._stop_owned(process) + raise RunnerError("artifact_output_limit_exceeded", stdout=bytes(stdout.data)) + if time.monotonic() >= deadline: + self._stop_owned(process) + raise RunnerError("timeout", stdout=bytes(stdout.data)) + time.sleep(0.02) + for reader in readers: + reader.join(timeout=0.1) + if overflow.is_set(): + raise RunnerError("output_limit_exceeded", stdout=bytes(stdout.data)) + code = process.returncode + if code != 0: + raise RunnerError("process_failed", stdout=bytes(stdout.data)) + return RunnerResult(job_dir, int(code), bytes(stdout.data), self._manifest(output_dir)) + finally: + if process.poll() is None: + self._stop_owned(process) + with self._lock: + self._active.pop(process.pid, None) + # A descendant may still hold an inherited pipe. Closing its BufferedReader + # while a daemon reader is blocked in read() waits on that reader's lock. + # Leave ownership with the reader; it closes when EOF arrives. + + def cancel(self, pid: int) -> bool: + """Terminate a process only when its PID maps to this runner's live Popen handle.""" + with self._lock: + process = self._active.get(pid) + if process is None or process.poll() is not None: + return False + self._stop_owned(process) + return True + + @staticmethod + def _stop_owned(process: subprocess.Popen[bytes]) -> None: + if process.poll() is None: + try: + process.terminate() + except OSError: + if process.poll() is not None: + return + try: + process.wait(timeout=1.0) + except subprocess.TimeoutExpired: + try: + process.kill() + except OSError: + if process.poll() is not None: + return + try: + process.wait(timeout=1.0) + except subprocess.TimeoutExpired: + # The runner has made a bounded terminate/kill attempt. Never let + # cleanup itself turn the configured deadline into an unbounded wait. + return + + @staticmethod + def _iter_output_files(output_dir: Path): + stack: list[tuple[Path, int]] = [(output_dir, 0)] + visited = 0 + try: + while stack: + directory, depth = stack.pop() + with os.scandir(directory) as entries: + for entry in entries: + visited += 1 + if visited > _MAX_SCAN_ENTRIES: + raise RunnerError("artifact_scan_limit_exceeded") + path = Path(entry.path) + try: + info = entry.stat(follow_symlinks=False) + junction = getattr(path, "is_junction", lambda: False)() + symlink = path.is_symlink() + except OSError: + raise RunnerError("artifact_scan_failed") from None + if symlink or junction or getattr(info, "st_file_attributes", 0) & _REPARSE_POINT: + raise RunnerError("artifact_symlink_refused") + if stat.S_ISDIR(info.st_mode): + if depth >= _MAX_SCAN_DEPTH: + raise RunnerError("artifact_scan_limit_exceeded") + stack.append((path, depth + 1)) + elif stat.S_ISREG(info.st_mode): + yield path, info.st_size + except OSError: + raise RunnerError("artifact_scan_failed") from None + + def _output_size(self, output_dir: Path) -> int: + total = 0 + for _, size in self._iter_output_files(output_dir): + total += size + if total > self.artifact_limit: + return total + return total + + def _manifest(self, output_dir: Path) -> tuple[dict[str, object], ...]: + entries: list[dict[str, object]] = [] + total = 0 + try: + base = output_dir.resolve(strict=True) + except OSError: + raise RunnerError("artifact_scan_failed") from None + for path, observed_size in sorted(self._iter_output_files(output_dir), key=lambda item: item[0]): + try: + if not path.resolve(strict=True).is_relative_to(base): + raise RunnerError("artifact_path_escape") + except OSError: + raise RunnerError("artifact_scan_failed") from None + name = path.relative_to(output_dir).as_posix() + parts = name.split("/") + if any(part in ("", ".", "..") or not _SAFE_NAME.fullmatch(part) for part in parts): + raise RunnerError("artifact_name_invalid") + digest = hashlib.sha256() + size = 0 + try: + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + size += len(chunk) + total += len(chunk) + if size > self.artifact_limit or total > self.artifact_limit: + raise RunnerError("artifact_too_large") + digest.update(chunk) + except OSError: + raise RunnerError("artifact_scan_failed") from None + if size != observed_size: + raise RunnerError("artifact_scan_failed") + entries.append({"name": name, "sha256": digest.hexdigest(), "size_bytes": size, + "kind": _KIND.get(path.suffix.lower(), "unknown")}) + return tuple(entries) diff --git a/backend/snapstudio_core/engines/lumina.py b/backend/snapstudio_core/engines/lumina.py new file mode 100644 index 00000000..c3151b0a --- /dev/null +++ b/backend/snapstudio_core/engines/lumina.py @@ -0,0 +1,190 @@ +"""Bounded client for the documented Lumina Layers local API (API 2.0).""" +from __future__ import annotations + +import hashlib +import json +import re +import uuid +from dataclasses import dataclass +from typing import Any, Callable, Mapping +from urllib.parse import urlsplit + +from snapstudio_core.foundation.netguard import ( + NetguardRefused, + Response, + confirm_write_origin, + local_request, + require_local_url, + revoke_write_origin, +) + +SUPPORTED_API_VERSION = "2.0" +MAX_JSON_BYTES = 2 * 1024 * 1024 +MAX_ARTIFACT_BYTES = 512 * 1024 * 1024 +MAX_INPUT_BYTES = 128 * 1024 * 1024 +_FILE_ID = re.compile(r"\A[A-Za-z0-9_-]{1,128}\Z") +_REQUEST: Callable[..., Response] = local_request + + +class LuminaError(Exception): + """A safe, bounded error without response bodies or configured URLs.""" + + def __init__(self, code: str) -> None: + self.code = code + super().__init__(code) + + +@dataclass(frozen=True) +class Discovery: + api_version: str + paths: frozenset[str] + evidence: str = "mock-service-tested" + + +@dataclass(frozen=True) +class Artifact: + sha256: str + size_bytes: int + kind: str + data: bytes + + +class LuminaClient: + """Talk to a user-supplied local Lumina service through foundation netguard.""" + + def __init__(self, service_url: str, *, timeout: float = 15.0, + request: Callable[..., Response] | None = None) -> None: + require_local_url(service_url) + parts = urlsplit(service_url if "://" in service_url else "http://" + service_url) + if parts.path not in ("", "/") or parts.query or parts.fragment: + raise LuminaError("invalid_service_url") + self.origin = f"{parts.scheme}://{parts.netloc}" + self.timeout = timeout + self._request = request or _REQUEST + self._discovery: Discovery | None = None + self._write_enabled = False + + def discover(self) -> Discovery: + """Read the captured FastAPI OpenAPI document and require its known API version.""" + response = self._request("GET", self.origin + "/openapi.json", timeout=self.timeout, + max_bytes=MAX_JSON_BYTES) + data = self._json(response, "discovery") + info = data.get("info") + paths = data.get("paths") + if not isinstance(info, dict) or not isinstance(paths, dict): + raise LuminaError("malformed_discovery") + version = info.get("version") + if not isinstance(version, str) or not version: + raise LuminaError("unknown_version") + if version != SUPPORTED_API_VERSION: + raise LuminaError("unsupported_version") + self._discovery = Discovery(version, frozenset(p for p in paths if isinstance(p, str))) + return self._discovery + + def health_check(self) -> Mapping[str, Any]: + """Confirm the documented identity route before enabling API writes. + + The health response schema is absent from the saved research. It is retained opaquely + and never interpreted as proof of a version or capability. + """ + if self._discovery is None: + self.discover() + self._require_discovery("/api/health") + response = self._request("GET", self.origin + "/api/health", timeout=self.timeout, + max_bytes=MAX_JSON_BYTES) + payload = self._json(response, "health") + if not isinstance(payload, dict): + raise LuminaError("malformed_health") + confirm_write_origin(self.origin) + self._write_enabled = True + return payload + + def preview(self, image: bytes, filename: str, *, lut_name: str, + fields: Mapping[str, str] | None = None) -> Mapping[str, Any]: + """Submit the documented multipart preview form; no parameters are inferred.""" + self._require_discovery("/api/convert/preview") + if not self._write_enabled: + raise LuminaError("identity_not_confirmed") + if not isinstance(image, bytes) or not image or len(image) > MAX_INPUT_BYTES: + raise LuminaError("invalid_input") + if not isinstance(filename, str) or not filename or any(c in filename for c in "\r\n\x00\"\\"): + raise LuminaError("invalid_filename") + if not isinstance(lut_name, str) or not lut_name or len(lut_name) > 256: + raise LuminaError("invalid_lut") + form = {"lut_name": lut_name} + for key, value in (fields or {}).items(): + if not isinstance(key, str) or not re.fullmatch(r"[a-z_]{1,64}", key) or key in {"image", "lut_name"}: + raise LuminaError("invalid_form") + if not isinstance(value, str) or len(value) > 1024: + raise LuminaError("invalid_form") + form[key] = value + boundary = "sslumina" + uuid.uuid4().hex + body = bytearray() + for key, value in form.items(): + body.extend(f"--{boundary}\r\nContent-Disposition: form-data; name=\"{key}\"\r\n\r\n{value}\r\n".encode()) + body.extend((f"--{boundary}\r\nContent-Disposition: form-data; name=\"image\"; filename=\"{filename}\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n").encode()) + body.extend(image) + body.extend(f"\r\n--{boundary}--\r\n".encode()) + response = self._request("POST", self.origin + "/api/convert/preview", + headers={"Content-Type": f"multipart/form-data; boundary={boundary}"}, + body=bytes(body), timeout=self.timeout, max_bytes=MAX_JSON_BYTES, + max_request_bytes=MAX_INPUT_BYTES + 128 * 1024, + write_ok=True, origin=self.origin) + data = self._json(response, "preview") + session_id = data.get("session_id") + status = data.get("status") + preview_url = data.get("preview_url") + if not isinstance(session_id, str) or not isinstance(status, str) or not isinstance(preview_url, str): + raise LuminaError("malformed_preview") + if not preview_url.startswith("/api/files/"): + raise LuminaError("unknown_preview_locator") + return data + + def fetch_artifact(self, file_id: str) -> Artifact: + """Fetch a documented registered file and derive identity from returned bytes.""" + self._require_discovery("/api/files/{file_id}") + if not isinstance(file_id, str) or not _FILE_ID.fullmatch(file_id): + raise LuminaError("invalid_file_id") + response = self._request("GET", self.origin + f"/api/files/{file_id}", + timeout=self.timeout, max_bytes=MAX_ARTIFACT_BYTES) + if response.status < 200 or response.status >= 300 or response.body is None: + raise LuminaError("artifact_unavailable") + content_type = response.headers.get("content-type", "").split(";", 1)[0].lower() + kind = {"model/3mf": "3mf", "application/vnd.ms-package.3dmanufacturing-3dmodel+xml": "3mf", + "model/gltf-binary": "glb", "image/png": "png"}.get(content_type, "unknown") + raw = response.body + return Artifact(hashlib.sha256(raw).hexdigest(), len(raw), kind, raw) + + def progress(self, *_: Any, **__: Any) -> None: + """Progress is unknown: the saved Lumina research publishes no progress route or shape.""" + self._require_discovery() + raise LuminaError("progress_unknown") + + def cancel(self, *_: Any, **__: Any) -> None: + """Cancellation is unknown: the saved Lumina research publishes no cancel route or shape.""" + self._require_discovery() + raise LuminaError("cancel_unknown") + + def close(self) -> None: + if self._write_enabled: + revoke_write_origin(self.origin) + self._write_enabled = False + + def _require_discovery(self, path: str | None = None) -> None: + if self._discovery is None: + self.discover() + if path and path not in self._discovery.paths: + raise LuminaError("route_unavailable") + + @staticmethod + def _json(response: Response, operation: str) -> dict[str, Any]: + if response.status < 200 or response.status >= 300 or response.body is None: + raise LuminaError(f"{operation}_failed") + try: + data = json.loads(response.body.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError): + raise LuminaError("malformed_json") from None + if not isinstance(data, dict): + raise LuminaError("malformed_json") + return data diff --git a/backend/tests/engines/__init__.py b/backend/tests/engines/__init__.py new file mode 100644 index 00000000..b7463648 --- /dev/null +++ b/backend/tests/engines/__init__.py @@ -0,0 +1 @@ +"""Engine adapter tests.""" diff --git a/backend/tests/engines/test_lumina_adapter_slice1.py b/backend/tests/engines/test_lumina_adapter_slice1.py new file mode 100644 index 00000000..1571bcd7 --- /dev/null +++ b/backend/tests/engines/test_lumina_adapter_slice1.py @@ -0,0 +1,327 @@ +from __future__ import annotations + +import hashlib +import json +import os +import signal +import sys +import threading +import time +from http.server import BaseHTTPRequestHandler, HTTPServer +from pathlib import Path +from threading import Thread + +import pytest + +from snapstudio_core.engines.cli_runner import CliRunner, RunnerError +from snapstudio_core.engines.lumina import LuminaClient, LuminaError +from snapstudio_core.foundation.netguard import ( + NetguardRefused, + clear_write_origins, + local_request, + require_local_url, +) +from tests.mocks.lumina_server import LuminaMock + + +def _pid_alive(pid: int) -> bool: + """Liveness probe that does not signal the process. + + os.kill(pid, 0) is not a probe on Windows: it calls TerminateProcess and raises + OSError (not ProcessLookupError) for a PID that no longer exists. + """ + if sys.platform != "win32": + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + return True + import ctypes + + kernel32 = ctypes.windll.kernel32 + kernel32.OpenProcess.restype = ctypes.c_void_p + handle = kernel32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION + if not handle: + return False + try: + code = ctypes.c_ulong() + if not kernel32.GetExitCodeProcess(ctypes.c_void_p(handle), ctypes.byref(code)): + return False + return code.value == 259 # STILL_ACTIVE + finally: + kernel32.CloseHandle(ctypes.c_void_p(handle)) + + +@pytest.fixture +def mock_service(): + with LuminaMock() as service: + yield service + clear_write_origins() + + +def test_lumina_discovery_preview_and_artifact_are_mock_service_tested(mock_service): + client = LuminaClient(mock_service.url, request=mock_service.request) + discovery = client.discover() + assert discovery.api_version == "2.0" + assert "/api/convert/preview" in discovery.paths + assert client.health_check() == {} + preview = client.preview(b"synthetic-image", "input.png", lut_name="Default") + assert preview["session_id"] == "session1" + artifact = client.fetch_artifact("file1") + assert artifact.sha256 == hashlib.sha256(b"mock-3mf").hexdigest() + assert artifact.size_bytes == 8 + assert artifact.kind == "3mf" + client.close() + + +def test_lumina_url_is_local_and_propagates_mock_redirect_refusal(): + with pytest.raises(NetguardRefused): + require_local_url("https://example.invalid") + with LuminaMock(mode="redirect") as service: + with pytest.raises(NetguardRefused) as exc: + LuminaClient(service.url, request=service.request).discover() + assert exc.value.code == "redirect" + + +@pytest.mark.parametrize(("mode", "code"), [("large", "too_large"), ("slow", "deadline")]) +def test_lumina_propagates_mock_oversize_and_slow_refusals(mode, code): + with LuminaMock(mode=mode) as service: + with pytest.raises(NetguardRefused) as exc: + LuminaClient(service.url, request=service.request).discover() + assert exc.value.code == code + + +def test_local_request_enforces_http_redirect_boundary_on_loopback(): + class Handler(BaseHTTPRequestHandler): + def do_GET(self): + self.send_response(302) + self.send_header("Location", "/elsewhere") + self.end_headers() + + def log_message(self, *_args): + pass + + server = HTTPServer(("127.0.0.1", 0), Handler) + worker = Thread(target=server.serve_forever, daemon=True) + worker.start() + try: + url = f"http://127.0.0.1:{server.server_port}/openapi.json" + with pytest.raises(NetguardRefused) as exc: + local_request("GET", url, timeout=1, max_bytes=1024) + assert exc.value.code == "redirect" + finally: + server.shutdown() + server.server_close() + worker.join(timeout=1) + + +@pytest.mark.parametrize(("mode", "version", "code"), [ + ("malformed", "2.0", "malformed_json"), + ("normal", "99.0", "unsupported_version"), +]) +def test_lumina_rejects_malformed_or_unsupported_discovery(mode, version, code): + with LuminaMock(mode=mode, version=version) as service: + with pytest.raises(LuminaError) as exc: + LuminaClient(service.url, request=service.request).discover() + assert exc.value.code == code + + +def test_lumina_does_not_invent_progress_cancel_or_accept_traversal(mock_service): + client = LuminaClient(mock_service.url, request=mock_service.request) + client.discover() + with pytest.raises(LuminaError, match="progress_unknown"): + client.progress("session1") + with pytest.raises(LuminaError, match="cancel_unknown"): + client.cancel("session1") + with pytest.raises(LuminaError, match="invalid_file_id"): + client.fetch_artifact("../outside") + + +def test_lumina_fixture_is_documentation_derived_preview_shape(): + fixture = Path(__file__).parents[1] / "fixtures" / "engines" / "lumina_api_2_preview.json" + data = json.loads(fixture.read_text(encoding="utf-8")) + assert data["session_id"] == "session1" + assert data["preview_url"] == "/api/files/file1" + assert "threemf_disk_path" not in data + + +def _runner(tmp_path: Path, args: tuple[str, ...], *, timeout: float = 2, + limit: int = 4096) -> CliRunner: + root = tmp_path / "studio-jobs" + root.mkdir() + return CliRunner(sys.executable, root, args, timeout_s=timeout, output_limit=limit) + + +def test_cli_runner_stages_input_and_builds_artifact_manifest(tmp_path): + scratch = tmp_path / "jobs-{output_dir}" + scratch.mkdir() + source = tmp_path / "original.3mf" + source.write_bytes(b"original") + # Paths reach the child through argv: embedding a Windows path in Python source breaks on its backslashes. + code = "import sys; from pathlib import Path; Path(sys.argv[1], 'result.3mf').write_bytes(Path(sys.argv[2]).read_bytes())" + runner = _runner(scratch, ("-c", code, "{output_dir}", "{input}")) + result = runner.run(inputs={"input.3mf": str(source)}) + assert source.read_bytes() == b"original" + assert result.artifacts == ({"name": "result.3mf", "sha256": hashlib.sha256(b"original").hexdigest(), + "size_bytes": 8, "kind": "3mf"},) + assert "{output_dir}" in str(result.job_dir) + + +def test_cli_runner_timeout_and_output_flood_are_bounded(tmp_path): + scratch = tmp_path + with pytest.raises(RunnerError) as timed: + _runner(scratch, ("-c", "import time; time.sleep(3)"), timeout=0.1).run() + assert timed.value.code == "timeout" + flood_root = scratch / "flood-jobs" + flood_root.mkdir() + runner = CliRunner(sys.executable, flood_root, ("-c", "print('x' * 1000000)"), + timeout_s=2, output_limit=1024) + with pytest.raises(RunnerError) as flooded: + runner.run() + assert flooded.value.code == "output_limit_exceeded" + assert len(flooded.value.stdout) <= 1024 + + +def test_cli_runner_cancels_only_its_active_process(tmp_path): + scratch = tmp_path + runner = _runner(scratch, ("-c", "import time; time.sleep(3)"), timeout=2) + cancel = threading.Event() + result: list[object] = [] + + def run(): + try: + result.append(runner.run(cancel_event=cancel)) + except Exception as exc: # noqa: BLE001 - assertion inspects safe runner outcome + result.append(exc) + + thread = threading.Thread(target=run) + thread.start() + time.sleep(0.1) + cancel.set() + thread.join(timeout=2) + assert not thread.is_alive() + assert isinstance(result[0], RunnerError) + assert result[0].code == "cancelled" + + +def test_cli_runner_rejects_unsafe_template_and_output_symlink(tmp_path): + scratch = tmp_path + with pytest.raises(RunnerError, match="argument_template_invalid"): + _runner(scratch, ("{arbitrary}",)) + outside = scratch / "outside" + outside.write_text("secret") + root = scratch / "escape-jobs" + root.mkdir() + code = "import sys; from pathlib import Path; Path(sys.argv[1], 'escape').symlink_to(Path(sys.argv[2]))" + runner = CliRunner(sys.executable, root, ("-c", code, "{output_dir}", str(outside)), timeout_s=2) + try: + (scratch / "probe-link").symlink_to(outside) + except OSError: + # This account cannot create symlinks (unprivileged Windows). The runner refuses a symlink wherever it + # finds one; that refusal is exercised without a real link in the next test. + pytest.skip("this account is not allowed to create symlinks") + with pytest.raises(RunnerError, match="artifact_symlink_refused"): + runner.run() + + +def test_cli_runner_refuses_a_symlink_in_the_output_without_needing_symlink_privilege(monkeypatch, tmp_path): + scratch = tmp_path + code = "import sys; from pathlib import Path; Path(sys.argv[1], 'result.3mf').write_bytes(b'x')" + runner = _runner(scratch, ("-c", code, "{output_dir}")) + monkeypatch.setattr(Path, "is_symlink", lambda self: self.name == "result.3mf") + with pytest.raises(RunnerError, match="artifact_symlink_refused"): + runner.run() + + +def test_cli_runner_timeout_returns_when_grandchild_keeps_pipes_open(tmp_path): + root = tmp_path / "jobs" + root.mkdir() + pid_file = tmp_path / "grandchild.pid" + code = ( + "import subprocess,sys,time; " + "child=subprocess.Popen([sys.executable,'-c','import time; time.sleep(30)']); " + "open(sys.argv[1],'w').write(str(child.pid)); time.sleep(30)" + ) + runner = CliRunner(sys.executable, root, ("-c", code, str(pid_file)), timeout_s=0.15) + started = time.monotonic() + try: + with pytest.raises(RunnerError) as exc: + runner.run() + elapsed = time.monotonic() - started + assert exc.value.code == "timeout" + assert elapsed < 2.5 + finally: + if pid_file.exists(): + grandchild_pid = int(pid_file.read_text()) + else: + grandchild_pid = None + # This exact PID was created by the fixture script above; no process-name sweep. + if grandchild_pid is not None and _pid_alive(grandchild_pid): + os.kill(grandchild_pid, signal.SIGTERM) + + +def test_cli_runner_stops_child_after_unexpected_poll_exception(monkeypatch, tmp_path): + root = tmp_path / "jobs" + root.mkdir() + pid_file = tmp_path / "runner-child.pid" + runner = CliRunner(sys.executable, root, ("-c", "import os,sys,time; open(sys.argv[1],'w').write(str(os.getpid())); time.sleep(30)", str(pid_file)), timeout_s=10) + + def fail_scan(_output_dir): + # Do not inject the polling failure until the exact owned child has written + # its PID. This proves cleanup after an unexpected poll exception without + # racing process startup or weakening the stopped-child assertion. + deadline = time.monotonic() + 2 + while not pid_file.exists(): + if time.monotonic() >= deadline: + raise AssertionError("runner child did not publish its PID") + time.sleep(0.005) + raise RuntimeError("synthetic scan failure") + + monkeypatch.setattr(runner, "_output_size", fail_scan) + child_pid = None + try: + with pytest.raises(RuntimeError, match="synthetic scan failure"): + runner.run() + child_pid = int(pid_file.read_text()) + assert not _pid_alive(child_pid) + finally: + if child_pid is None and pid_file.exists(): + child_pid = int(pid_file.read_text()) + if child_pid is not None and _pid_alive(child_pid): + os.kill(child_pid, signal.SIGTERM) + + +def test_cli_runner_refuses_windows_script_entry_points(tmp_path): + root = tmp_path / "jobs" + root.mkdir() + executable = tmp_path / "engine.cmd" + executable.write_text("echo synthetic") + with pytest.raises(RunnerError, match="executable_script_refused"): + CliRunner(executable, root, ()) + + +def test_cli_runner_output_scan_refuses_oserror_junctions_and_unbounded_trees(monkeypatch, tmp_path): + root = tmp_path / "jobs" + root.mkdir() + runner = CliRunner(sys.executable, root, ()) + output = tmp_path / "output" + output.mkdir() + + monkeypatch.setattr("snapstudio_core.engines.cli_runner.os.scandir", + lambda _path: (_ for _ in ()).throw(OSError("synthetic scan failure"))) + with pytest.raises(RunnerError, match="artifact_scan_failed"): + runner._output_size(output) + + monkeypatch.undo() + junction_dir = output / "junction" + junction_dir.mkdir() + monkeypatch.setattr(Path, "is_junction", lambda self: self.name == "junction", raising=False) + with pytest.raises(RunnerError, match="artifact_symlink_refused"): + runner._output_size(output) + + monkeypatch.undo() + (output / "a").write_text("a") + (output / "b").write_text("b") + monkeypatch.setattr("snapstudio_core.engines.cli_runner._MAX_SCAN_ENTRIES", 1) + with pytest.raises(RunnerError, match="artifact_scan_limit_exceeded"): + runner._output_size(output) diff --git a/backend/tests/fixtures/engines/PROVENANCE.md b/backend/tests/fixtures/engines/PROVENANCE.md new file mode 100644 index 00000000..6678c457 --- /dev/null +++ b/backend/tests/fixtures/engines/PROVENANCE.md @@ -0,0 +1 @@ +These are documentation-derived fixtures hand-written to the published Lumina Layers API 2.0 source shapes recorded in the 2026-10-25 research bundle. They are not captures from a Lumina service. Evidence: fixture-tested and mock-service-tested only. diff --git a/backend/tests/fixtures/engines/lumina_api_2_preview.json b/backend/tests/fixtures/engines/lumina_api_2_preview.json new file mode 100644 index 00000000..abd48d33 --- /dev/null +++ b/backend/tests/fixtures/engines/lumina_api_2_preview.json @@ -0,0 +1 @@ +{"session_id":"session1","status":"ok","message":"Preview generated","preview_url":"/api/files/file1","preview_glb_url":null,"palette":[],"dimensions":{},"contours":null} diff --git a/backend/tests/mocks/lumina_server.py b/backend/tests/mocks/lumina_server.py new file mode 100644 index 00000000..1ded6532 --- /dev/null +++ b/backend/tests/mocks/lumina_server.py @@ -0,0 +1,48 @@ +"""In-process Lumina mock using only shapes present in the saved research.""" +from __future__ import annotations + +import json +from urllib.parse import urlsplit + +from snapstudio_core.foundation.netguard import NetguardRefused, Response + + +class LuminaMock: + def __init__(self, *, version: str = "2.0", mode: str = "normal") -> None: + self.version = version + self.mode = mode + self.url = "http://127.0.0.1:8123" + self.requests: list[tuple[str, str]] = [] + + def request(self, method: str, url: str, **kwargs) -> Response: + path = urlsplit(url).path + self.requests.append((method, path)) + if self.mode == "redirect" and path == "/openapi.json": + raise NetguardRefused("redirect") + if self.mode == "slow" and path == "/openapi.json": + raise NetguardRefused("deadline") + if self.mode == "large" and path == "/openapi.json": + raise NetguardRefused("too_large") + if path == "/openapi.json": + payload = {"info": {"version": self.version}, "paths": { + "/api/health": {}, "/api/convert/preview": {}, "/api/files/{file_id}": {}}} + body = b"not-json" if self.mode == "malformed" else json.dumps(payload).encode() + return Response(200, {"content-type": "application/json"}, body, None, len(body)) + if path == "/api/health": + return Response(200, {"content-type": "application/json"}, b"{}", None, 2) + if path == "/api/convert/preview" and method == "POST": + payload = {"session_id": "session1", "status": "ok", "message": "Preview generated", + "preview_url": "/api/files/file1", "preview_glb_url": None, + "palette": [], "dimensions": {}, "contours": None} + body = json.dumps(payload).encode() + return Response(200, {"content-type": "application/json"}, body, None, len(body)) + if path == "/api/files/file1": + raw = b"mock-3mf" + return Response(200, {"content-type": "model/3mf"}, raw, None, len(raw)) + return Response(404, {"content-type": "application/json"}, b"{}", None, 2) + + def __enter__(self): + return self + + def __exit__(self, *_): + return None diff --git a/docs/internal/ENGINES.md b/docs/internal/ENGINES.md new file mode 100644 index 00000000..60d44f5b --- /dev/null +++ b/docs/internal/ENGINES.md @@ -0,0 +1,19 @@ +# Local engine integrations + +Evidence labels distinguish hand-written fixtures (`fixture-tested`), in-process API doubles (`mock-service-tested`), a real local engine (`local-service-exercised`), and hardware (`hardware-verified`). The Lumina fixtures in this work are documentation-derived and hand-written to the published API 2.0 source shapes, not captures. No real Lumina process or printer was exercised. + +## Lumina Layers + +The adapter accepts a user-supplied HTTP(S) URL only when `foundation.netguard.require_local_url` accepts it. Requests use `foundation.netguard.local_request`, which bounds response and request sizes and deadlines, checks the resolved address, and refuses redirects. The adapter reads `/openapi.json` and accepts only the research-observed FastAPI API version `2.0`; it checks `/api/health` before allowing POST and treats the health JSON as opaque because its response schema is not present in the research. The published preview route is `POST /api/convert/preview` with multipart `image` and `lut_name` fields and documented form options. Its response provides `session_id`, status and `/api/files/{file_id}` URLs. A file is fetched only by a validated file ID; SHA-256 and byte size are computed from returned bytes, while kind is mapped from the returned `Content-Type` header. + +The saved research does not publish a progress route or response shape, nor a cancel route or request shape. Those methods return `progress_unknown` and `cancel_unknown`; no route is inferred. API error response shapes also were not established as a stable contract, so failures are returned as fixed adapter error codes without echoing service body text. The generator's internally produced `threemf_disk_path` is not treated as a Studio file path. + +## Generic CLI runner + +The configured executable path and argument template are fixed for a runner instance. The runner creates a fresh Studio-owned job directory, stages inputs as copies, sets that directory as cwd, and invokes argv directly with `shell=False`; `.bat` and `.cmd` entry points are refused. Templates accept only `{job_dir}`, `{output_dir}` and `{input}` with one-pass substitution. The timeout and combined stdout/stderr cap are bounded; cancellation terminates only the process handle started by this runner and does not wait for inherited pipes to reach EOF. Output scanning is capped at 10,000 entries and 32 directory levels, refuses scan errors and symlinks/junctions/reparse points, and artifact bytes are capped by the configured limit. Output artifacts include relative name, SHA-256, byte size and a known kind or `unknown`. + +Evidence for this slice: `fixture-tested` and `mock-service-tested`. No local service was exercised. + +## Review follow-up dispositions + +F1-F5 are addressed in the bounded LUMINA1 repair. F6 remains deferred: environment isolation, staged-input size limits, Windows reserved output names, job-directory cleanup on pre-launch refusal and wait-error reporting need a separate review. F7 remains deferred: write-origin registration is process-global and needs a scoped ownership design. F8's kind-source statement is corrected above; streaming large artifact downloads remains deferred. F9 remains deferred: direct `cancel(pid)`, pre-health identity refusal and temporary-directory lifecycle need focused tests. F10 remains deferred: runtime discovery evidence still has a test-provenance default and should move to test/docs metadata. From 887be713ffdd080448cc62a8430b988a17732586 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Sat, 31 Oct 2026 14:02:37 -0400 Subject: [PATCH 2/3] fix(engines): refuse a link, junction or reparse point as the output root Review R1 (Sol): the output root itself was never checked before traversal, so an engine could swap its empty output directory for a link and have outside files reported as job artifacts. The root is now checked like every entry; a non-directory root is refused as a failed scan. Verified: backend/tests/engines 18 passed, 1 skipped (symlink creation not permitted for this account). Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/engines/cli_runner.py | 8 +++++++ .../engines/test_lumina_adapter_slice1.py | 23 +++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/backend/snapstudio_core/engines/cli_runner.py b/backend/snapstudio_core/engines/cli_runner.py index b9d3f308..9d54ab9e 100644 --- a/backend/snapstudio_core/engines/cli_runner.py +++ b/backend/snapstudio_core/engines/cli_runner.py @@ -227,6 +227,14 @@ def _iter_output_files(output_dir: Path): stack: list[tuple[Path, int]] = [(output_dir, 0)] visited = 0 try: + # The root is checked like every entry: an engine that swaps its (initially empty) output + # directory for a link or junction must not make an outside tree look like job output. + root = os.lstat(output_dir) + if (output_dir.is_symlink() or getattr(output_dir, "is_junction", lambda: False)() + or getattr(root, "st_file_attributes", 0) & _REPARSE_POINT): + raise RunnerError("artifact_symlink_refused") + if not stat.S_ISDIR(root.st_mode): + raise RunnerError("artifact_scan_failed") while stack: directory, depth = stack.pop() with os.scandir(directory) as entries: diff --git a/backend/tests/engines/test_lumina_adapter_slice1.py b/backend/tests/engines/test_lumina_adapter_slice1.py index 1571bcd7..1df92337 100644 --- a/backend/tests/engines/test_lumina_adapter_slice1.py +++ b/backend/tests/engines/test_lumina_adapter_slice1.py @@ -325,3 +325,26 @@ def test_cli_runner_output_scan_refuses_oserror_junctions_and_unbounded_trees(mo monkeypatch.setattr("snapstudio_core.engines.cli_runner._MAX_SCAN_ENTRIES", 1) with pytest.raises(RunnerError, match="artifact_scan_limit_exceeded"): runner._output_size(output) + + +def test_cli_runner_output_scan_refuses_a_replaced_output_root(monkeypatch, tmp_path): + root = tmp_path / "jobs" + root.mkdir() + runner = CliRunner(sys.executable, root, ()) + outside = tmp_path / "outside" + outside.mkdir() + (outside / "secret.txt").write_text("not job output") + output = tmp_path / "output" + output.mkdir() + # A junction/reparse-point root, however the engine made it, must be refused before any entry is read. + monkeypatch.setattr(Path, "is_junction", lambda self: self == output, raising=False) + with pytest.raises(RunnerError, match="artifact_symlink_refused"): + runner._output_size(output) + with pytest.raises(RunnerError, match="artifact_symlink_refused"): + runner._manifest(output) + monkeypatch.undo() + # A plain file standing where the output directory should be is also refused, not scanned. + plain = tmp_path / "plain" + plain.write_text("x") + with pytest.raises(RunnerError, match="artifact_scan_failed"): + runner._output_size(plain) From f06a9e71db8287ed5a9229584727300a4eb641d5 Mon Sep 17 00:00:00 2001 From: DeadlyVirusIn Date: Sat, 31 Oct 2026 14:09:56 -0400 Subject: [PATCH 3/3] fix(engines): linear template validation; record known runner limits Review M1 (Opus): the placeholder validator had the (a*)+ shape; 24 characters took 1.1 s and each two more characters quadrupled it. Validation is now linear, with a timing-bounded test. Review M2/L1/L6/P1: documented as known limits with the usability label. Verified: backend/tests/engines 19 passed, 1 skipped. Co-Authored-By: Claude Sonnet 5.5 --- backend/snapstudio_core/engines/cli_runner.py | 11 +++++++++-- backend/tests/engines/test_lumina_adapter_slice1.py | 12 ++++++++++++ docs/internal/ENGINES.md | 9 +++++++++ 3 files changed, 30 insertions(+), 2 deletions(-) diff --git a/backend/snapstudio_core/engines/cli_runner.py b/backend/snapstudio_core/engines/cli_runner.py index 9d54ab9e..b8df74c0 100644 --- a/backend/snapstudio_core/engines/cli_runner.py +++ b/backend/snapstudio_core/engines/cli_runner.py @@ -15,7 +15,14 @@ from typing import Mapping, Sequence -_TOKEN = re.compile(r"\A(?:[^{}\x00\r\n]*|\{(?:job_dir|output_dir|input)\})+\Z") +_PLACEHOLDER = re.compile(r"\{(?:job_dir|output_dir|input)\}") +_FORBIDDEN = re.compile(r"[{}\x00\r\n]") + + +def _template_ok(arg: object) -> bool: + """Only the three known placeholders may contain braces. Linear time: the previous single pattern had the (a*)+ + shape and backtracked exponentially on a long argument that failed late.""" + return isinstance(arg, str) and not _FORBIDDEN.search(_PLACEHOLDER.sub("", arg)) _SAFE_NAME = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z") _KIND = {".3mf": "3mf", ".stl": "stl", ".obj": "obj", ".glb": "glb", ".png": "png", ".json": "json"} _MAX_SCAN_ENTRIES = 10000 @@ -88,7 +95,7 @@ def __init__(self, executable: str | os.PathLike[str], job_root: str | os.PathLi if not self.job_root.is_dir(): raise RunnerError("job_root_invalid") if not isinstance(argument_template, (tuple, list)) or not all( - isinstance(arg, str) and _TOKEN.fullmatch(arg) for arg in argument_template): + _template_ok(arg) for arg in argument_template): raise RunnerError("argument_template_invalid") if isinstance(timeout_s, bool) or not isinstance(timeout_s, (int, float)) or not 0 < timeout_s <= 3600: raise RunnerError("timeout_invalid") diff --git a/backend/tests/engines/test_lumina_adapter_slice1.py b/backend/tests/engines/test_lumina_adapter_slice1.py index 1df92337..ba2f6685 100644 --- a/backend/tests/engines/test_lumina_adapter_slice1.py +++ b/backend/tests/engines/test_lumina_adapter_slice1.py @@ -348,3 +348,15 @@ def test_cli_runner_output_scan_refuses_a_replaced_output_root(monkeypatch, tmp_ plain.write_text("x") with pytest.raises(RunnerError, match="artifact_scan_failed"): runner._output_size(plain) + + +def test_template_validation_is_linear_on_a_long_argument_that_fails_late(tmp_path): + root = tmp_path / "jobs" + root.mkdir() + started = time.monotonic() + with pytest.raises(RunnerError): + CliRunner(sys.executable, root, ("a" * 4000 + "{profile}",)) + with pytest.raises(RunnerError): + CliRunner(sys.executable, root, ("a" * 4000 + "}",)) + assert time.monotonic() - started < 1.0 + CliRunner(sys.executable, root, ("--in", "{input}", "--out={output_dir}/x", "{job_dir}")) diff --git a/docs/internal/ENGINES.md b/docs/internal/ENGINES.md index 60d44f5b..521dc601 100644 --- a/docs/internal/ENGINES.md +++ b/docs/internal/ENGINES.md @@ -17,3 +17,12 @@ Evidence for this slice: `fixture-tested` and `mock-service-tested`. No local se ## Review follow-up dispositions F1-F5 are addressed in the bounded LUMINA1 repair. F6 remains deferred: environment isolation, staged-input size limits, Windows reserved output names, job-directory cleanup on pre-launch refusal and wait-error reporting need a separate review. F7 remains deferred: write-origin registration is process-global and needs a scoped ownership design. F8's kind-source statement is corrected above; streaming large artifact downloads remains deferred. F9 remains deferred: direct `cancel(pid)`, pre-health identity refusal and temporary-directory lifecycle need focused tests. F10 remains deferred: runtime discovery evidence still has a test-provenance default and should move to test/docs metadata. + +## Known limits (review follow-ups, not closed) +- Timeout and cancel stop only the direct child. There is no job object or process group, so a descendant the engine started can keep running and keep writing into its job directory after the runner returns an error; each such run also leaves two pipe handles and reader threads until the descendant exits. Planned: a kill-on-close Windows Job Object / POSIX process group for processes this runner started. +- The output-root link check is check-then-scan; a descendant that keeps running can race it. +- Job directories are not removed after a refused or failed run. +- The runner can launch any configured executable. Before it is wired to a caller it needs a policy that keeps it from running a slicer (Studio does not slice). +- Lifecycle tests launch `sys.executable`; under a Windows venv launcher a job object could mask descendant survival. + +Usability label: experimental library, fixture-tested and mock-service-tested, with one real loopback transport-boundary test. Not exercised against a real Lumina or engine, not wired to any caller or UI.