pycarta-service-agent 0.2.0.dev1__py3-none-win_amd64.whl

pycarta_service_agent/__init__.py

@@ -0,0 +1,42 @@
+"""The carta-service-agent binary, plus the Python contract for talking to it.
+
+This package delivers the platform-specific carta-service-agent executable and
+everything describing the seam between it and the Python that drives it. Those
+facts change when the Go code changes, so they ship in the same artifact as the
+binary and cannot drift out of step with it.
+
+Not here: the seam between Carta and service authors. The register decorator,
+execution-event access, request routing, and the loop that drives user handlers
+all belong to pycarta.services. That is what a service author imports.
+
+find_binary is the only name exported at the top level. Everything else is in a
+submodule, imported directly so using one does not drag in the others:
+
+===============  =============================================================
+Module           Holds
+===============  =============================================================
+``command``      argv builders, environment variable names, exit codes
+``config``       the carta.service.json shape
+``errors``       the exception hierarchy
+``ipc``          stdio JSON framing and the supervised subprocess
+``messages``     IPC message type names and PROTOCOL_VERSION
+===============  =============================================================
+
+pycarta is the only intended consumer, but it is a real one. Treat a change to
+any name these modules export as a breaking change.
+
+Example:
+    Running a fully enrolled service, one execution at a time::
+
+        from pycarta_service_agent import command, config, ipc
+
+        cfg = config.ServiceConfig.load(project_dir)
+        client = ipc.connect(
+            command.run_argv(cfg, once=True),
+            classify_exit=command.classify_exit,
+        )
+"""
+
+from ._locate import find_binary
+
+__all__ = ["find_binary"]

pycarta_service_agent/_locate.py

@@ -0,0 +1,81 @@
+"""Locating the carta-service-agent binary bundled in this wheel.
+
+Also holds the CARTA_SERVICE_AGENT_BIN escape hatch, which points the package at
+a binary elsewhere on disk. That is for developing this package: run a locally
+built Go binary against the Python driving it without rebuilding a wheel first.
+Not part of the contract with consumers, who should always get the binary their
+wheel shipped.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import stat
+from importlib import resources
+
+_BIN_DIR = "_bin"
+_BIN_NAME = (
+    "carta-service-agent.exe"
+    if platform.system() == "Windows"
+    else "carta-service-agent"
+)
+_PKG_NAME = "pycarta-service-agent"
+
+# Development escape hatch, see the module docstring. Private on purpose. For
+# developers of this package, not the consumers it exports to.
+_ENV_OVERRIDE = "CARTA_SERVICE_AGENT_BIN"
+
+
+def find_binary() -> str:
+    """Absolute path to the carta-service-agent binary bundled in this wheel.
+
+    Each wheel carries exactly one binary, built for that wheel's platform tag,
+    so pip installs the one matching the host. Marked executable on first call if
+    it is not already, since a wheel does not reliably preserve the mode bit.
+
+    CARTA_SERVICE_AGENT_BIN, if set to an absolute path, replaces the bundled
+    binary. Escape hatch for developing this package against a locally built
+    binary. Not something a consumer should rely on. Validated the same way the
+    bundled path is, so a stale or misspelled value fails here with a useful
+    message instead of an opaque spawn error later.
+
+    Returns:
+        str: Absolute path to the executable, safe to pass as argv[0].
+
+    Raises:
+        FileNotFoundError: CARTA_SERVICE_AGENT_BIN is set but names nothing, or
+            the package is installed with its bundled binary missing (broken or
+            hand-assembled install).
+    """
+    override = os.environ.get(_ENV_OVERRIDE, "").strip()
+    if override:
+        if not os.path.isfile(override):
+            raise FileNotFoundError(
+                f"{_ENV_OVERRIDE} is set to {override!r}, which is not a file."
+            )
+        _ensure_executable(override)
+        return override
+
+    ref = resources.files(__package__).joinpath(_BIN_DIR, _BIN_NAME)
+    with resources.as_file(ref) as p:
+        path = os.fspath(p)
+
+    if not os.path.isfile(path):
+        raise FileNotFoundError(
+            f"{_PKG_NAME} is installed but its bundled binary is missing at {path!r}."
+        )
+
+    _ensure_executable(path)
+    return path
+
+
+def _ensure_executable(path: str) -> None:
+    if os.name != "nt":
+        mode = os.stat(path).st_mode
+        expected = mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        if mode != expected:
+            try:
+                os.chmod(path, expected)
+            except OSError:
+                pass

pycarta_service_agent/command.py

@@ -0,0 +1,459 @@
+"""Invoking the carta-service-agent binary: flags, env vars, exit codes.
+
+The binary takes all of its config from flags and never reads
+carta.service.json at runtime, so an adapter has to translate Python arguments
+into an argv. The environment supplies credentials only, never config. Those two
+contracts plus the exit-code contract are facts about the binary, so they live
+here next to it rather than in the adapter.
+
+The flag builders are pure. They return argv fragments and touch nothing.
+run_argv and run_subcommand also resolve the binary's path, and run_subcommand
+spawns it.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+from .config import ServiceConfig, SUPPORTED_INVOKER
+from .errors import CommandError
+from .ipc import ExitAction
+from ._locate import find_binary
+
+# -- environment -------------------------------------------------------------
+
+ENV_SESSION_TOKEN: str = "CARTA_SESSION_TOKEN"
+"""Cognito ID token. Lets enroll and init skip the interactive browser login.
+
+Read by enroll and init only. Required when --no-browser is set, since the PKCE
+loopback flow needs a browser and there is not one.
+
+Env var rather than a flag because command lines are visible in ps.
+
+Same token the browser login would have produced. An adapter that already
+authenticated the user can inject it here instead of prompting a second time.
+"""
+
+ENV_API_TOKEN: str = "CARTA_SERVICE_API_TOKEN"
+"""Per-service API token, for a runner that did not enroll itself.
+
+Read by run and export. Takes precedence over both the OS keychain and the
+credentials fallback file. Set this with ENV_RUNNER_ID and run needs no local
+credential storage at all, which is what makes a container or serverless
+deployment work: no keychain available, and nothing should be writing credential
+files.
+
+"carta-service-agent export" prints the value to seed this.
+"""
+
+ENV_RUNNER_ID: str = "CARTA_SERVICE_RUNNER_ID"
+"""Runner identity, for a runner that did not enroll itself.
+
+Read by run and export, same precedence over the keychain and fallback file as
+ENV_API_TOKEN. Normally enroll creates the runner ID and caches it in the
+keychain. This is how a pre-provisioned deployment gets told which runner it is
+instead.
+"""
+
+ENV_SMCP_JWT: str = "CARTA_SERVICE_SMCP_JWT"
+"""Already-exchanged SMCP JWT, for a runner whose deployment shares one.
+
+Read by run. Seeds the agent's session cache so no token exchange with the
+agent gateway is needed while the token remains valid. For short-lived runners
+(a Lambda woken per signal) that would otherwise each perform their own
+exchange, the deployment exchanges once, stashes the JWT, and injects it here.
+
+Supply a token whose remaining validity covers the whole run. The agent
+validates expiry itself and falls back to a normal exchange (via ENV_API_TOKEN)
+when the token is expired, expiring, or malformed.
+"""
+
+
+# -- exit codes --------------------------------------------------------------
+
+EXIT_STOP: int = 0
+"""run shut down cleanly. Stdin closed, or a signal arrived.
+
+Also what run returns after finishing its work under --once or
+--max-executions, and when --exit-when-idle finds an empty queue. Do not
+restart.
+"""
+
+EXIT_RESTART: int = 1
+"""run hit a transient failure. Restart with backoff.
+
+Reserved. run swallows loop errors into its own backoff and emits only
+EXIT_STOP or EXIT_FAIL.
+"""
+
+EXIT_RESTART_NOW: int = 2
+"""run asked to be restarted immediately, no backoff delay.
+
+Reserved for a future config-reload or file-watch mode. Not currently emitted.
+"""
+
+EXIT_FAIL: int = 3
+"""run failed deterministically. Do not restart.
+
+Every setup failure lands here: flag parsing, missing or invalid required flags,
+config validation, logger setup, credential lookup, gateway client, invoker
+startup (including a failed hello handshake or a version mismatch). A restart
+fails the same way.
+"""
+
+
+def classify_exit(returncode: int) -> ExitAction:
+    """Map a run exit code onto the action a supervisor should take.
+
+    Pass this to ipc.connect as classify_exit so the supervisor honors the
+    binary's contract instead of the generic "zero stops, anything else
+    restarts" default.
+
+    Args:
+        returncode: Exit code from "carta-service-agent run".
+
+    Returns:
+        ExitAction: STOP for EXIT_STOP, RESTART_NOW for EXIT_RESTART_NOW, FAIL
+        for EXIT_FAIL, RESTART for anything else. Codes the binary does not
+        define and signal-derived codes fall in that last bucket and are treated
+        as transient.
+    """
+    if returncode == EXIT_STOP:
+        return ExitAction.STOP
+    if returncode == EXIT_RESTART_NOW:
+        return ExitAction.RESTART_NOW
+    if returncode == EXIT_FAIL:
+        return ExitAction.FAIL
+    return ExitAction.RESTART
+
+
+# -- flags -------------------------------------------------------------------
+
+
+def url_flags(
+    carta_url: str = "",
+    control_plane_url: str = "",
+    gateway_url: str = "",
+    platform_env: str = "",
+) -> list[str]:
+    """Build the endpoint flags every subcommand accepts.
+
+    Empty values are omitted rather than passed as empty strings, which lets the
+    binary apply its own defaults. A blank URL gets derived from the platform
+    environment, and a blank platform environment means production.
+
+    Args:
+        carta_url: Override for the Carta API base URL.
+        control_plane_url: Override for the control plane base URL.
+        gateway_url: Override for the agent gateway base URL.
+        platform_env: Platform environment to derive unset URLs from, either
+            "development" or "production". Not validated here. The binary
+            rejects an unrecognized value.
+
+    Returns:
+        list[str]: Flag/value pairs for the non-empty arguments, stable order.
+        Empty list when every argument is empty.
+    """
+    flags: list[str] = []
+    for flag, value in (
+        ("--carta-url", carta_url),
+        ("--control-plane-url", control_plane_url),
+        ("--gateway-url", gateway_url),
+        ("--platform-env", platform_env),
+    ):
+        if value:
+            flags.extend([flag, value])
+    return flags
+
+
+def enroll_flags(
+    carta_url: str = "",
+    control_plane_url: str = "",
+    gateway_url: str = "",
+    platform_env: str = "",
+    namespace: str = "",
+    service_name: str = "",
+    no_auth: bool = False,
+    no_browser: bool = False,
+    no_keychain: bool = False,
+) -> list[str]:
+    """Build the flags for "carta-service-agent enroll".
+
+    Enroll registers the service and this device with the platform. It resolves
+    or creates the runner, creates the service, links them, mints the API token,
+    and writes the resolved service_id back into carta.service.json.
+
+    --invoker is always included, since this package is the Python adapter.
+
+    namespace and service_name are required by the binary but optional here, so
+    a caller can build a partial argv. The binary names the missing flag.
+
+    Args:
+        carta_url: Override for the Carta API base URL.
+        control_plane_url: Override for the control plane base URL.
+        gateway_url: Override for the agent gateway base URL.
+        platform_env: "development" or "production".
+        namespace: Carta namespace to enroll the service into.
+        service_name: Name for the service within the namespace.
+        no_auth: Skip authentication. Only valid when the platform is also
+            running without auth. Enroll does not currently honor it.
+        no_browser: Authenticate from ENV_SESSION_TOKEN only, never open a
+            browser. Fails fast if that variable is unset, malformed, or expired.
+        no_keychain: Skip the OS keychain, use the credentials fallback file. For
+            a host with no keychain, where every keychain call fails and logs a
+            warning first.
+
+    Returns:
+        list[str]: The flags, without the binary path or the "enroll" subcommand
+        name. Pass to run_subcommand.
+    """
+    flags = ["--invoker", SUPPORTED_INVOKER]
+    flags += url_flags(carta_url, control_plane_url, gateway_url, platform_env)
+    if namespace:
+        flags += ["--namespace", namespace]
+    if service_name:
+        flags += ["--name", service_name]
+    if no_auth:
+        flags.append("--no-auth")
+    if no_browser:
+        flags.append("--no-browser")
+    if no_keychain:
+        flags.append("--no-keychain")
+    return flags
+
+
+def init_flags(
+    carta_url: str = "",
+    control_plane_url: str = "",
+    gateway_url: str = "",
+    platform_env: str = "",
+    no_browser: bool = False,
+    no_keychain: bool = False,
+) -> list[str]:
+    """Build the flags for "carta-service-agent init".
+
+    Init is interactive one-time project setup. It authenticates the user, lets
+    them pick or create a namespace, and writes carta.service.json into the
+    current working directory. It does not capture a service name. That arrives
+    at enroll time.
+
+    Args:
+        carta_url: Override for the Carta API base URL.
+        control_plane_url: Override for the control plane base URL.
+        gateway_url: Override for the agent gateway base URL.
+        platform_env: "development" or "production".
+        no_browser: Authenticate from ENV_SESSION_TOKEN only, never open a
+            browser. Init is interactive in other respects, so this suppresses
+            the login prompt only.
+        no_keychain: Skip the OS keychain, use the credentials fallback file.
+
+    Returns:
+        list[str]: The flags, without the binary path or the "init" subcommand
+        name. Pass to run_subcommand.
+    """
+    flags = url_flags(carta_url, control_plane_url, gateway_url, platform_env)
+    if no_browser:
+        flags.append("--no-browser")
+    if no_keychain:
+        flags.append("--no-keychain")
+    return flags
+
+
+def export_flags(
+    service_id: str,
+    namespace: str,
+    service_name: str,
+    carta_url: str = "",
+    control_plane_url: str = "",
+    gateway_url: str = "",
+    platform_env: str = "",
+    no_keychain: bool = False,
+) -> list[str]:
+    """Build the flags for "carta-service-agent export".
+
+    Export is read-only and contacts no platform service. It prints this
+    machine's credentials for one service as JSON on stdout, so a
+    pre-provisioned deployment can be seeded with ENV_API_TOKEN and
+    ENV_RUNNER_ID. It exists because an API token value cannot be recovered from
+    the platform after creation. The machine that enrolled the service holds the
+    only copy.
+
+    The output contains a live credential. Capture stdout rather than letting it
+    reach a terminal or a log.
+
+    Args:
+        service_id: Platform service ID to export credentials for. This is the
+            keychain account holding the API token, so it has to match the
+            service that was enrolled.
+        namespace: Carta namespace owning the service.
+        service_name: Service name within the namespace.
+        carta_url: Override for the Carta API base URL.
+        control_plane_url: Override for the control plane base URL.
+        gateway_url: Override for the agent gateway base URL.
+        platform_env: "development" or "production". Decides which URLs appear
+            in the exported JSON.
+        no_keychain: Skip the OS keychain, read the credentials fallback file.
+
+    Returns:
+        list[str]: The flags, without the binary path or the "export" subcommand
+        name.
+    """
+    flags = [
+        "--id",
+        service_id,
+        "--namespace",
+        namespace,
+        "--name",
+        service_name,
+        "--invoker",
+        SUPPORTED_INVOKER,
+    ]
+    flags += url_flags(carta_url, control_plane_url, gateway_url, platform_env)
+    if no_keychain:
+        flags.append("--no-keychain")
+    return flags
+
+
+def run_argv(
+    cfg: ServiceConfig,
+    *,
+    exit_when_idle: bool = False,
+    log_format: str = "",
+    log_level: str = "",
+    max_executions: int = 0,
+    no_debug_logf: bool = False,
+    no_keychain: bool = False,
+    once: bool = False,
+    quiet: bool = False,
+    verbose: bool = False,
+) -> list[str]:
+    """Build the full argv for "carta-service-agent run", binary path included.
+
+    Unlike the other builders here, the result is ready to hand to ipc.connect.
+    --log-stderr is always appended: the binary's stdout is the IPC channel, so
+    log output there corrupts the message framing.
+
+    The defaults describe a long-lived agent holding a long poll, waiting for
+    work. once and exit_when_idle describe the opposite, a runner started per
+    wake-up that skips the long poll, drains what is queued, and exits.
+
+    Args:
+        cfg: Service configuration. service_id, namespace, and service_name have
+            to be non-blank. The URL fields and platform_env are forwarded when
+            set, omitted when empty.
+        exit_when_idle: Exit as soon as the queue is empty.
+        log_format: Console stream format, "text" or "json". Empty uses the
+            default of "text". The debug log file is always JSON.
+        log_level: Console stream level, one of "debug", "info", "warn", or
+            "error". Empty uses the default of "info". Does not affect the
+            debug log file, which is always at debug.
+        max_executions: Stop after claiming this many executions. 0 means no
+            limit. Counted at claim time, not on success, so a service that
+            fails every execution still terminates. Negative values are rejected
+            by the binary.
+        no_debug_logf: Do not write the debug log file.
+        no_keychain: Skip the OS keychain, read credentials from the fallback
+            file. Unnecessary when ENV_API_TOKEN and ENV_RUNNER_ID are set,
+            since those bypass both.
+        once: Handle at most one execution and exit. This is the shorthand for
+            "--exit-when-idle --max-executions 1". Overrides max_executions.
+        quiet: Log the console stream at error level. Overrides log_level.
+            Incompatible with verbose.
+        verbose: Log the console stream at debug level. Overrides log_level.
+            Incompatible with quiet.
+
+    Returns:
+        list[str]: Full argv, starting with the absolute path to the binary.
+
+    Raises:
+        ValueError: cfg.service_id, cfg.namespace, or cfg.service_name is empty
+            or whitespace.
+        FileNotFoundError: The binary could not be located.
+    """
+    required = {
+        "service_id": cfg.service_id,
+        "namespace": cfg.namespace,
+        "service_name": cfg.service_name,
+    }
+    for name, value in required.items():
+        if not value or not value.strip():
+            raise ValueError(f"{name} is required to launch the agent")
+    argv = [
+        find_binary(),
+        "run",
+        "--id",
+        cfg.service_id,
+        "--namespace",
+        cfg.namespace,
+        "--name",
+        cfg.service_name,
+        "--invoker",
+        SUPPORTED_INVOKER,
+    ]
+    argv += url_flags(
+        cfg.carta_url,
+        cfg.control_plane_url,
+        cfg.gateway_url,
+        cfg.platform_env,
+    )
+
+    if once:
+        argv.append("--once")
+    if exit_when_idle:
+        argv.append("--exit-when-idle")
+    if max_executions:
+        argv += ["--max-executions", str(max_executions)]
+    if no_keychain:
+        argv.append("--no-keychain")
+
+    if log_level:
+        argv += ["--log-level", log_level]
+    if log_format:
+        argv += ["--log-format", log_format]
+    if verbose:
+        argv.append("--verbose")
+    if quiet:
+        argv.append("--quiet")
+    if no_debug_logf:
+        argv.append("--no-debug-logf")
+
+    # log stderr required, the agent's stdout is the IPC channel
+    argv.append("--log-stderr")
+    return argv
+
+
+# -- invocation --------------------------------------------------------------
+
+
+def run_subcommand(
+    subcommand: str,
+    flags: list[str],
+    *,
+    env: dict[str, str] | None = None,
+) -> None:
+    """Run a subcommand to completion with the terminal's stdio.
+
+    The child inherits this process's stdin, stdout, and stderr, so its prompts
+    and diagnostics reach the user directly. Right for init and enroll, which are
+    interactive. Wrong for export, whose stdout is JSON worth capturing.
+
+    Do not use this for run. That subcommand's stdio is the IPC channel. Use
+    run_argv with ipc.connect instead.
+
+    Args:
+        subcommand: Subcommand name, e.g. "enroll" or "init".
+        flags: Flags for it, usually from enroll_flags or init_flags.
+        env: Variables to merge onto this process's environment for the child.
+            The parent environment is otherwise inherited unchanged, so this is
+            additive. Use it to inject ENV_SESSION_TOKEN.
+
+    Raises:
+        CommandError: The subcommand exited non-zero. The child has already
+            written its diagnostics to the inherited stderr.
+        FileNotFoundError: The binary could not be located.
+    """
+    proc_env = {**os.environ, **env} if env else None
+    result = subprocess.run([find_binary(), subcommand, *flags], env=proc_env)
+    if result.returncode != 0:
+        raise CommandError(f"{subcommand} failed (see output above)")