recto-core 1.0.0__py3-none-any.whl

recto/__init__.py

@@ -0,0 +1,20 @@
+"""Recto — modern Windows-service wrapper.
+
+Public API surface:
+    recto.config.load_config        — parse + validate a service.yaml
+    recto.config.ServiceConfig      — top-level dataclass
+    recto.secrets.SecretSource      — ABC for pluggable secret backends
+    recto.secrets.SecretMaterial    — sealed type returned by SecretSource.fetch
+    recto.secrets.DirectSecret      — variant: secret materialized as a string
+    recto.secrets.SigningCapability — variant: secret never leaves enclave
+    recto.secrets.EnvSource         — passthrough backend reading os.environ
+    recto.secrets.CredManSource     — Windows Credential Manager backend
+    recto.secrets.register_source   — third-party backend registration
+    recto.launcher.launch           — read config, fetch secrets, spawn child
+
+Higher-level entry points (CLI, healthz probe loop, restart policy, comms
+webhook dispatch) are wired in alongside the launcher in v0.1.
+"""
+
+__version__ = "0.1.0.dev0"
+__all__ = ["__version__"]

recto/__main__.py

@@ -0,0 +1,16 @@
+"""`python -m recto` entry point.
+
+Forwards to recto.cli:main(). The console-script entry registered
+in pyproject.toml (`recto = "recto.cli:main"`) hits the same target,
+so `recto launch ...` and `python -m recto launch ...` are identical.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from recto.cli import main
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

recto/_launcher_run.py

@@ -0,0 +1,151 @@
+"""Restart-loop entry point split out of recto.launcher.
+
+Lives in its own module to keep recto/launcher.py under the
+cross-mount Write-tool truncation threshold encountered during v0.1
+work. Re-exported as `recto.launcher.run` at the bottom of
+recto/launcher.py.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from collections.abc import Callable, Mapping
+
+from recto.adminui import AdminUIServer, EventBuffer
+from recto.config import ServiceConfig
+from recto.healthz import HealthzProbe
+from recto.joblimit import JobLimit
+from recto.restart import MaxAttemptsReachedError, next_delay, should_restart
+from recto.secrets import SecretSource
+from recto.telemetry import TelemetryClient
+
+__all__ = ["run"]
+
+
+def run(
+    config: ServiceConfig,
+    *,
+    sources: Mapping[str, SecretSource] | None = None,
+    popen: Callable[..., "subprocess.Popen"] = subprocess.Popen,
+    base_env: Mapping[str, str] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    probe_factory: Callable[..., HealthzProbe] = HealthzProbe,
+    poll_interval_seconds: float = 0.5,
+    terminate_grace_seconds: float = 5.0,
+    dispatcher_factory: Callable[..., object] | None = None,
+    joblimit_factory: Callable[..., JobLimit] = JobLimit,
+    telemetry_factory: Callable[..., TelemetryClient] = TelemetryClient,
+    buffer_factory: Callable[[], EventBuffer] = EventBuffer,
+    adminui_factory: Callable[..., AdminUIServer] = AdminUIServer,
+) -> int:
+    """Run the supervised child with the configured restart policy.
+
+    Compared to launch():
+    - launch() is one-shot (single spawn, single bracket).
+    - run() brackets init/teardown ONCE around the whole loop and
+      re-spawns per restart policy. Long-lived backends (Vault session,
+      hardware-enclave handle) stay open across restarts. The
+      TelemetryClient also lives across the whole loop -- one OTel
+      span covers every restart attempt. Likewise the EventBuffer +
+      AdminUIServer cover the whole loop, so /api/events shows the
+      full lifecycle history rather than just the latest spawn.
+
+    Returns the LAST child invocation's exit code, whether the policy
+    decided "no restart" or max_attempts_reached fired.
+    """
+    # Local imports avoid the recto.launcher <-> recto._launcher_run
+    # circular import at module load time.
+    from recto.launcher import (
+        _bracket_lifecycle,
+        _build_dispatcher,
+        _emit_event,
+        _spawn_and_wait,
+        build_child_env,
+        resolve_sources,
+    )
+
+    if sources is None:
+        sources = resolve_sources(config)
+
+    telemetry = telemetry_factory(config.spec.telemetry)
+    telemetry.start_run(
+        config.metadata.name,
+        attributes={
+            "recto.healthz.type": config.spec.healthz.type,
+            "recto.restart.policy": config.spec.restart.policy,
+        },
+    )
+    buffer = buffer_factory()
+    adminui = adminui_factory(
+        config.spec.admin_ui,
+        service_name=config.metadata.name,
+        buffer=buffer,
+        config=config,
+    )
+    adminui.start()
+    last_rc = 0
+    try:
+        with _bracket_lifecycle(
+            config, sources, telemetry=telemetry, buffer=buffer
+        ):
+            env = build_child_env(config.spec, sources, base_env=base_env)
+            dispatcher = _build_dispatcher(config, env, dispatcher_factory)
+            attempt = 0
+            while True:
+                last_rc = _spawn_and_wait(
+                    config,
+                    env,
+                    popen,
+                    probe_factory=probe_factory,
+                    poll_interval_seconds=poll_interval_seconds,
+                    terminate_grace_seconds=terminate_grace_seconds,
+                    dispatcher=dispatcher,
+                    joblimit_factory=joblimit_factory,
+                    telemetry=telemetry,
+                    buffer=buffer,
+                )
+                if not should_restart(last_rc, config.spec.restart):
+                    _emit_event(
+                        config,
+                        "run.final_exit",
+                        {"returncode": last_rc, "restart_attempts": attempt},
+                        dispatcher=dispatcher,
+                        telemetry=telemetry,
+                        buffer=buffer,
+                    )
+                    return last_rc
+                attempt += 1
+                try:
+                    delay = next_delay(attempt, config.spec.restart)
+                except MaxAttemptsReachedError:
+                    _emit_event(
+                        config,
+                        "max_attempts_reached",
+                        {
+                            "max_attempts": config.spec.restart.max_attempts,
+                            "last_returncode": last_rc,
+                        },
+                        dispatcher=dispatcher,
+                        telemetry=telemetry,
+                        buffer=buffer,
+                    )
+                    return last_rc
+                _emit_event(
+                    config,
+                    "restart.attempt",
+                    {
+                        "attempt": attempt,
+                        "delay_seconds": delay,
+                        "previous_returncode": last_rc,
+                        "backoff": config.spec.restart.backoff,
+                    },
+                    dispatcher=dispatcher,
+                    telemetry=telemetry,
+                    buffer=buffer,
+                )
+                sleep(delay)
+    finally:
+        adminui.stop()
+        telemetry.end_run(last_rc)
+        telemetry.shutdown()

recto/_migrate.py

@@ -0,0 +1,167 @@
+"""Helpers for `recto migrate-from-nssm`. Extracted from recto.cli.
+
+These functions are pure (no I/O, no side effects) and small. They
+live in their own module so cli.py stays under the Cowork Write-tool
+size threshold while still being a thin dispatcher rather than a
+1000-line god-module. Same pattern as ``recto._launcher_run`` --
+private (underscore-prefix) module, re-imported by name from
+``recto.cli``.
+
+If you're reading this in v0.3+: feel free to inline these back into
+cli.py once the Cowork sandbox is no longer the operator's primary
+authoring environment.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from recto.nssm import NssmConfig
+
+__all__ = [
+    "build_migration_plan",
+    "escape_yaml",
+    "generate_service_yaml",
+    "partition_env_entries",
+]
+
+
+def partition_env_entries(
+    entries: list[tuple[str, str]],
+    *,
+    keep_as_env: list[str] | None = None,
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]:
+    """Split NSSM AppEnvironmentExtra entries into (secrets, plain_env).
+
+    Operators pass ``--keep-as-env=NAME[,NAME...]`` on the
+    ``migrate-from-nssm`` CLI to route specific keys into the
+    generated YAML's ``spec.env:`` block instead of Credential
+    Manager. The default (``keep_as_env=None`` or empty list) is
+    conservative: every entry goes to CredMan, matching v0.1
+    behavior. No surprise allow-list -- operators opt in
+    per-migration.
+
+    Returns ``(secrets, plain_env)``. Both lists preserve the input
+    order.
+    """
+    keep_set = set(keep_as_env or ())
+    secrets: list[tuple[str, str]] = []
+    plain_env: list[tuple[str, str]] = []
+    for k, v in entries:
+        if k in keep_set:
+            plain_env.append((k, v))
+        else:
+            secrets.append((k, v))
+    return secrets, plain_env
+
+
+def build_migration_plan(
+    *,
+    nssm_cfg: NssmConfig,
+    secrets: list[tuple[str, str]],
+    yaml_out: Path,
+    python_exe: str,
+    plain_env: list[tuple[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Build a dict describing what migrate-from-nssm WOULD do.
+
+    Secret VALUES are masked (replaced with '<redacted>') so the plan
+    can be JSON-printed without leaking. Plain-env values (from
+    ``--keep-as-env``) are NOT masked since they're explicitly
+    operator-tagged as non-secret.
+    """
+    plain_env = plain_env or []
+    return {
+        "service": nssm_cfg.service,
+        "current_app_path": nssm_cfg.app_path,
+        "current_app_parameters": nssm_cfg.app_parameters,
+        "current_app_directory": nssm_cfg.app_directory,
+        "current_environment_extra_count": len(secrets) + len(plain_env),
+        "secrets_to_install": [
+            {"name": k, "value": "<redacted>"} for k, _ in secrets
+        ],
+        "plain_env_to_yaml": [
+            {"name": k, "value": v} for k, v in plain_env
+        ],
+        "yaml_out": str(yaml_out),
+        "new_app_path": python_exe,
+        "new_app_parameters": f"-m recto launch {yaml_out}",
+    }
+
+
+def generate_service_yaml(
+    *,
+    service: str,
+    nssm_cfg: NssmConfig,
+    secret_keys: list[str],
+    plain_env: list[tuple[str, str]] | None = None,
+    secret_backend: str = "credman",
+) -> str:
+    """Produce the generated service.yaml text.
+
+    Hand-rolled (not via PyYAML's dump) so we control formatting:
+    fields appear in a stable order, comments are preserved, and the
+    output is human-reviewable. PyYAML's default style would munge
+    quoting on values with `:` or `#` and lose readability.
+
+    ``plain_env`` (from ``--keep-as-env``) is rendered into the
+    YAML's ``spec.env:`` block. ``secret_keys`` becomes the
+    ``spec.secrets:`` block.
+    """
+    plain_env = plain_env or []
+    lines: list[str] = []
+    a = lines.append
+    a("# Generated by `recto migrate-from-nssm`.")
+    a(f"# Source NSSM service: {nssm_cfg.service}")
+    a("# Review and edit before relying on this in production.")
+    a("apiVersion: recto/v1")
+    a("kind: Service")
+    a("metadata:")
+    a(f"  name: {service}")
+    # Map NSSM's DisplayName -> YAML metadata.display_name (Papercut #3
+    # additive field, v0.2.x+) and NSSM's Description -> YAML
+    # metadata.description independently. Pre-Papercut-#3 behavior
+    # collapsed NSSM DisplayName into a single YAML `description`
+    # field, which on round-trip through `recto apply` then wrote the
+    # same string back into both NSSM registry parameters -- lossy. New
+    # migrations produce two distinct fields when both are set on the
+    # source NSSM service. If only DisplayName is set, only display_name
+    # is emitted (so `recto apply` won't pollute NSSM's Description from
+    # "" to the DisplayName string on round-trip).
+    if nssm_cfg.display_name:
+        a(f"  display_name: \"{escape_yaml(nssm_cfg.display_name)}\"")
+    if nssm_cfg.description:
+        a(f"  description: \"{escape_yaml(nssm_cfg.description)}\"")
+    a("spec:")
+    a(f"  exec: \"{escape_yaml(nssm_cfg.app_path)}\"")
+    if nssm_cfg.app_parameters:
+        a("  args:")
+        for w in nssm_cfg.app_parameters.split():
+            a(f"    - \"{escape_yaml(w)}\"")
+    if nssm_cfg.app_directory:
+        a(f"  working_dir: \"{escape_yaml(nssm_cfg.app_directory)}\"")
+    if secret_keys:
+        a("  secrets:")
+        for key in secret_keys:
+            a(f"    - name: {key}")
+            a(f"      source: {secret_backend}")
+            a(f"      target_env: {key}")
+            a("      required: true")
+    if plain_env:
+        a("  env:")
+        for k, v in plain_env:
+            a(f"    {k}: \"{escape_yaml(v)}\"")
+    a("  restart:")
+    a("    policy: always")
+    a("    backoff: exponential")
+    a("    initial_delay_seconds: 1")
+    a("    max_delay_seconds: 60")
+    a("    max_attempts: 10")
+    a("")
+    return "\n".join(lines)
+
+
+def escape_yaml(s: str) -> str:
+    """Escape backslashes and double-quotes for YAML double-quoted strings."""
+    return s.replace("\\", "\\\\").replace("\"", "\\\"")