From d27dbb6c1dc9dfcda7ee3b9e0f9865d77181847a Mon Sep 17 00:00:00 2001 From: Microck Date: Thu, 5 Nov 2026 10:15:39 +0100 Subject: [PATCH 01/14] feat: let users bring their own sandbox plugins Register trusted executable location backends with a versioned capability handshake. Keep provider dependencies outside core and include a runnable sandbox-sdk adapter, isolated workflow checks and operator documentation. Shipped skill size: skills/raft-cli/SKILL.md 5024 -> 4972 bytes. --- .github/workflows/check.yml | 13 +- README.md | 14 + deploy/deploy.py | 2 +- deploy/verify-plugins.py | 417 ++++++++++++++++++++++++ deploy/verify-release.py | 21 +- deploy/verify-run.py | 3 + docs/contract.md | 21 ++ docs/guides/meta.json | 1 + docs/guides/plugins.mdx | 154 +++++++++ docs/reference/cli.md | 22 +- docs/verification.mdx | 7 + examples/sandbox-sdk/.gitignore | 1 + examples/sandbox-sdk/README.md | 153 +++++++++ examples/sandbox-sdk/adapter.mjs | 231 +++++++++++++ examples/sandbox-sdk/package.json | 9 + examples/sandbox-sdk/pnpm-lock.yaml | 58 ++++ examples/sandbox-sdk/smoke-provider.mjs | 126 +++++++ examples/sandbox-sdk/smoke.mjs | 177 ++++++++++ package.json | 1 + pyproject.toml | 6 +- raft.py | 140 +++++++- raft_plugins.py | 102 ++++++ raft_run.py | 4 + skills/raft-cli/SKILL.md | 5 +- website/scripts/verify-site.mjs | 1 + 25 files changed, 1666 insertions(+), 23 deletions(-) create mode 100644 deploy/verify-plugins.py create mode 100644 docs/guides/plugins.mdx create mode 100644 examples/sandbox-sdk/.gitignore create mode 100644 examples/sandbox-sdk/README.md create mode 100644 examples/sandbox-sdk/adapter.mjs create mode 100644 examples/sandbox-sdk/package.json create mode 100644 examples/sandbox-sdk/pnpm-lock.yaml create mode 100644 examples/sandbox-sdk/smoke-provider.mjs create mode 100644 examples/sandbox-sdk/smoke.mjs create mode 100644 raft_plugins.py diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 98be130..84b76ae 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -23,9 +23,9 @@ jobs: with: node-version: '24' - run: uv sync --locked - - run: uvx ruff check raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py deploy/*.py - - run: uvx ruff format --check raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py deploy/*.py - - run: uv run python -m compileall -q raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py deploy + - run: uvx ruff check raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py raft_plugins.py deploy/*.py + - run: uvx ruff format --check raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py raft_plugins.py deploy/*.py + - run: uv run python -m compileall -q raft.py raft_files.py raft_run.py raft_jobs.py raft_output.py raft_plugins.py deploy - run: uv run python deploy/verify-limits.py - run: uv run python deploy/verify-image-tests.py - run: uv run python deploy/verify-run.py @@ -33,5 +33,12 @@ jobs: - run: uv run python deploy/verify-output.py - run: uv run python deploy/verify-features.py - run: uv run python deploy/verify-self-update.py + - run: uv run python deploy/verify-plugins.py + - name: Exercise optional sandbox-sdk plugin + if: matrix.python == '3.14' + run: | + corepack enable + pnpm --dir examples/sandbox-sdk install --frozen-lockfile + pnpm --dir examples/sandbox-sdk smoke - run: uv build - run: uv run python deploy/verify-release.py diff --git a/README.md b/README.md index 449ba11..a5ccfbe 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,20 @@ raft ssh "$box" raft stop "$box" ``` +## use your own sandbox backend + +register a trusted executable plugin as a location, then use the same commands: + +```sh +raft plugin add cloud -- node /absolute/path/to/plugin.mjs +raft plugin info cloud +raft new --location cloud --disposable +``` + +plugins own their dependencies and provider guarantees. the core CLI still needs +only Python. see [user plugins](docs/guides/plugins.mdx) and the runnable +[sandbox-sdk adapter](examples/sandbox-sdk/README.md). + ## image and workspace control the image builder starts with Debian 13 and installs language runtimes, diff --git a/deploy/deploy.py b/deploy/deploy.py index 291431d..042cb09 100644 --- a/deploy/deploy.py +++ b/deploy/deploy.py @@ -59,7 +59,7 @@ def hosts(): # Read at call time: onboarding imports this module before its location exists. - return {name: entry["ssh"] for name, entry in configuration().items()} + return {name: entry["ssh"] for name, entry in configuration().items() if "ssh" in entry} def remote(host, command): diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py new file mode 100644 index 0000000..dc13557 --- /dev/null +++ b/deploy/verify-plugins.py @@ -0,0 +1,417 @@ +"""Verify executable plugins through real CLI processes, without hosts or credentials. + +Run with python3 deploy/verify-plugins.py. The provider and guest files live only +under a temporary directory; PATH deliberately contains no SSH or Incus client. +""" + +import json +import base64 +from pathlib import Path +import re +import signal +import subprocess +import sys +import tempfile +import time + +ROOT = Path(__file__).resolve().parent.parent + +# This is a real, deliberately small provider, not an interception of Raft internals. +# Its state survives invocations so CLI routing errors affect observable box state. +PROVIDER = r""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import time + +store = Path(sys.argv[1]) +mode = sys.argv[2] +action = sys.argv[3] +request = json.loads(os.environ["RAFT_PLUGIN_REQUEST"]) +assert request["protocol"] == 1 +assert isinstance(request["location"], str) and request["location"] +assert isinstance(request["options"], dict) +commands = ["new", "list", "info", "exec", "upload", "download", "note", "destroy"] +if action == "describe": + assert request["args"] == {} + assert sys.stdin.read() == "" + replies = { + "good": {"protocol": 1, "commands": commands}, + "version": {"protocol": 2, "commands": commands}, + "array": [], + "missing": {"protocol": 1}, + "string-commands": {"protocol": 1, "commands": "new"}, + "nonstring-command": {"protocol": 1, "commands": [42]}, + "management-command": {"protocol": 1, "commands": ["host"]}, + } + print("not JSON" if mode == "malformed" else json.dumps(replies[mode])) + sys.exit(0) + +args = request["args"] +assert args["action"] == action and args["location"] == request["location"] +store.mkdir(parents=True, exist_ok=True) +with (store / "actions.jsonl").open("a") as journal: + journal.write(json.dumps({"action": action, "location": request["location"]}) + "\n") +if action not in commands: + raise SystemExit("unsupported action reached provider") + +def write_record(directory, record): + (directory / "info.json").write_text(json.dumps(record)) + +if action == "new": + # This provider has a fixed template. Native sizing defaults would break it. + if args["cpu"] is not None or args["memory"] is not None: + raise SystemExit("fixed-template provider rejects explicit sizing") + if args["template"] is not None: + raise SystemExit("fixture has no snapshot support") + sequence = store / "sequence" + number = int(sequence.read_text()) + 1 if sequence.exists() else 1 + sequence.write_text(str(number)) + directory = store / ("box-" + str(number)) + (directory / "workspace").mkdir(parents=True) + handle = request["location"] + ":job-" + str(number) + ":opaque+β" + note = {key: args[key] for key in ("purpose", "owner", "next") if args[key] is not None} + record = {"box": handle, "state": "Running", "stopAt": str(int(time.time()) + args["ttl"]), + "note": note or None} + write_record(directory, record) + print(handle) +elif action == "list": + for filename in sorted(store.glob("box-*/info.json")): + print(filename.read_text()) +else: + handle = args["target"] if action == "note" else args["box"] + for filename in store.glob("box-*/info.json"): + record = json.loads(filename.read_text()) + if record["box"] == handle: + directory = filename.parent + break + else: + raise SystemExit("box not found: " + handle) + workspace = directory / "workspace" + if action == "info": + print(json.dumps(record)) + elif action == "destroy": + shutil.rmtree(directory) + elif action == "note": + record["note"] = None if args["clear"] else { + key: args[key] for key in ("purpose", "owner", "next") if args[key] is not None + } + write_record(directory, record) + elif action == "exec": + assert not args["detach"] + result = subprocess.run(args["command"], cwd=workspace) + if result.returncode < 0: + os.kill(os.getpid(), -result.returncode) + sys.exit(result.returncode) + else: + if args["recursive"]: + raise SystemExit("fixture supports single files only") + remote = args["destination"] if action == "upload" else args["source"] + remote = Path(remote) + if not remote.is_absolute() or ".." in remote.parts or remote.parts[1] != "workspace": + raise SystemExit("fixture files must be below /workspace") + guest = workspace.joinpath(*remote.parts[2:]) + if action == "upload": + shutil.copyfile(args["source"], guest) + else: + shutil.copyfile(guest, args["destination"]) +""" + + +class Controller: + def __init__(self, directory): + self.directory = directory + self.home = directory / "home" + self.config = self.home / ".config/raft/incus.json" + self.store = directory / "provider-state" + self.script = directory / "provider script.py" + self.script.write_text(PROVIDER) + binary = directory / "bin" + binary.mkdir() + (binary / "provider-python").symlink_to(sys.executable) + # An allowlist avoids inherited Raft overrides, SSH agents and credentials. + self.env = { + "HOME": str(self.home), + "PATH": str(binary), + "TMPDIR": str(directory), + "XDG_CONFIG_HOME": str(self.home / ".config"), + "XDG_DATA_HOME": str(self.home / ".local/share"), + "XDG_CACHE_HOME": str(self.home / ".cache"), + "XDG_STATE_HOME": str(self.home / ".local/state"), + "PYTHONDONTWRITEBYTECODE": "1", + "PYTHONUTF8": "1", + "LC_ALL": "C.UTF-8", + "RAFT_NO_UPDATE_CHECK": "1", + } + + def raft(self, *arguments, code=0, env=None, input=""): + result = subprocess.run( + [sys.executable, str(ROOT / "raft.py"), *map(str, arguments)], + cwd=self.directory, + env=self.env if env is None else env, + input=input, + capture_output=True, + text=True, + timeout=20, + ) + if code is None: + assert result.returncode != 0, (arguments, result.stdout, result.stderr) + else: + assert result.returncode == code, ( + arguments, + result.returncode, + result.stdout, + result.stderr, + ) + return result + + def command(self, mode="good"): + return ["provider-python", str(self.script), str(self.store), mode] + + def add(self, location="cloud", mode="good", code=0): + return self.raft("plugin", "add", location, "--", *self.command(mode), code=code) + + def rows(self): + return [ + json.loads(line) + for line in self.raft("list", "--location", "cloud").stdout.splitlines() + ] + + def info(self, box): + return json.loads(self.raft("info", box).stdout) + + def actions(self): + journal = self.store / "actions.jsonl" + return journal.read_bytes() if journal.exists() else b"" + + def configure(self, inventory): + self.config.parent.mkdir(parents=True, exist_ok=True) + self.config.write_text(json.dumps(inventory)) + + +def verify_registration(controller): + for arguments in [("--version",), ("--help",), ("plugin", "--help")]: + controller.raft(*arguments) + assert not controller.config.exists() + controller.add() + assert controller.config.stat().st_mode & 0o777 == 0o600 + saved = controller.config.read_bytes() + replacement = controller.command() + replacement[2] = str(controller.directory / "replacement-state") + controller.raft("plugin", "add", "cloud", "--", *replacement, code=None) + assert controller.config.read_bytes() == saved, "duplicate registration changed config" + # Removal and introspection are controller operations, not remote deletion. + described = json.loads(controller.raft("plugin", "info", "cloud").stdout) + assert described["protocol"] == 1 and "destroy" in described["commands"] + assert controller.actions() == b"" + # Resolution at registration must survive a later PATH without that executable. + no_path = {**controller.env, "PATH": str(controller.directory / "absent")} + controller.raft("plugin", "info", "cloud", env=no_path) + print("registration: private clean-HOME config, duplicate protection, resolved executable") + + +def verify_lifecycle(controller): + created = controller.raft("new", "--disposable") + box = created.stdout.strip() + location, identifier = box.split(":", 1) + assert location == "cloud" and not re.fullmatch(r"rf-[a-f0-9]{16}", identifier) + record = controller.info(box) + assert record["box"] == box and record["state"] == "Running" + assert controller.rows() == [record] + # A full minute window avoids scheduler-sensitive timestamp assertions. + assert 540 <= int(record["stopAt"]) - int(time.time()) <= 600 + + literal = [ + "a b", + "", + "$HOME", + "$(touch controller-expanded)", + "; touch controller-expanded", + "*", + "|", + ">", + "'quoted'", + "β", + ] + (controller.directory / "glob-match").write_text("must not expand") + echo = "import json,sys; print(json.dumps(sys.argv[1:]))" + output = controller.raft("exec", box, "--", sys.executable, "-c", echo, *literal) + assert json.loads(output.stdout) == literal + assert not (controller.directory / "controller-expanded").exists() + + # A real guest process changes state before failing. Retrying would duplicate it. + program = ( + "from pathlib import Path; import sys; " + "f=Path('attempts').open('a'); f.write('once\\n'); f.close(); " + "sys.stdout.write('guest stdout\\n'); sys.stderr.write('guest stderr\\n'); sys.exit(37)" + ) + failed = controller.raft("exec", box, "--", sys.executable, "-c", program, code=37) + assert failed.stdout == "guest stdout\n" and failed.stderr == "guest stderr\n" + attempts = controller.directory / "attempts" + controller.raft("download", box, "/workspace/attempts", attempts) + assert attempts.read_bytes() == b"once\n", "uncertain exec was retried" + controller.raft( + "exec", + box, + "--", + sys.executable, + "-c", + "import os,signal; os.kill(os.getpid(), signal.SIGTERM)", + code=128 + signal.SIGTERM, + ) + + payload = b"\x00plugin file\xff\n" + source = controller.directory / "upload source" + destination = controller.directory / "download destination" + source.write_bytes(payload) + controller.raft("upload", box, source, "/workspace/payload") + source.unlink() + controller.raft("download", box, "/workspace/payload", destination) + assert destination.read_bytes() == payload + + actions = controller.actions() + controller.raft("stop", box, code=None) + assert controller.actions() == actions, "unsupported command reached provider" + assert controller.info(box) == record, "unsupported stop changed remote state" + actions = controller.actions() + for arguments in [ + ["sync", box, ".", "/workspace/source"], + ["status", box, "provider-job"], + ["policy", "cloud", "--require", "purpose"], + ["run", "--location", "cloud", "--", "true"], + ]: + controller.raft(*arguments, code=None) + assert controller.actions() == actions, "unsupported command reached provider" + report = json.loads(controller.raft("config", "--location", "cloud").stdout) + assert report["policy"] == {"cloud": None} + + # The describe preflight must not consume stdin intended for the guest command. + echoed = controller.raft( + "exec", + box, + "--", + sys.executable, + "-c", + "import sys; sys.stdout.write(sys.stdin.read())", + input="piped payload\n", + ) + assert echoed.stdout == "piped payload\n" + structured = controller.raft( + "--json", + "exec", + box, + "--", + sys.executable, + "-c", + "import os,sys; os.write(1, bytes(range(256))); os.write(2, b'failure'); sys.exit(23)", + code=23, + ) + events = [json.loads(line) for line in structured.stdout.splitlines()] + assert not structured.stderr and events[-1] == {"type": "exit", "code": 23} + for stream, expected in [("stdout", bytes(range(256))), ("stderr", b"failure")]: + assert ( + b"".join(base64.b64decode(row["data"]) for row in events if row["type"] == stream) + == expected + ) + + # Configured sizing must reach a fixed-template provider instead of being silently ignored. + controller.raft("config", "set", "cpu", "3") + controller.raft("new", "--location", "cloud", "--disposable", code=None) + assert controller.rows() == [record] + controller.raft("config", "unset", "cpu") + actions = controller.actions() + controller.raft("note", "cloud", "controller guidance") + locations = [json.loads(line) for line in controller.raft("locations").stdout.splitlines()] + assert locations[0]["note"] == "controller guidance" + controller.raft("note", "cloud", "--clear") + locations = [json.loads(line) for line in controller.raft("locations").stdout.splitlines()] + assert locations[0]["note"] == "" + assert controller.actions() == actions, "location note reached provider" + controller.raft( + "note", box, "--purpose", "regression", "--owner", "verifier", "--next", "destroy" + ) + assert controller.info(box)["note"] == { + "purpose": "regression", + "owner": "verifier", + "next": "destroy", + } + controller.raft("note", box, "--clear") + assert controller.info(box)["note"] is None + + controller.add("other") + actions = controller.actions() + controller.raft("new", "--location", "other", "--from", box + "/snapshot", code=None) + assert controller.actions() == actions, "cross-location template reached provider" + assert len(controller.rows()) == 1 + controller.raft("plugin", "remove", "other") + + # Selecting the plugin must not attempt native SSH, even when native is default. + inventory = json.loads(controller.config.read_text()) + controller.configure({"unusable": {"ssh": "must-not-contact.invalid"}, **inventory}) + assert controller.rows() == [record] + actions = controller.actions() + controller.raft("plugin", "info", "cloud") + assert controller.actions() == actions + controller.raft("plugin", "remove", "cloud") + assert controller.actions() == actions, "removing registration executed a provider action" + controller.add() + assert controller.info(box) == record, "registration removal deleted remote box" + controller.raft("destroy", box) + assert controller.rows() == [] + controller.raft("info", box, code=None) + print( + "lifecycle: opaque handles, argv/stdio/exits, files, notes, capability and location isolation" + ) + + +def verify_rejections(directory): + modes = [ + "version", + "array", + "missing", + "string-commands", + "nonstring-command", + "management-command", + "malformed", + ] + for mode in modes: + work = directory / mode + work.mkdir() + controller = Controller(work) + controller.add(mode=mode, code=None) + assert not controller.config.exists(), "invalid handshake persisted registration: " + mode + assert controller.actions() == b"" + work = directory / "invalid-config" + work.mkdir() + controller = Controller(work) + resolved = [sys.executable, str(controller.script), str(controller.store), "good"] + entries = [ + {"plugin": "not-an-argv"}, + {"plugin": []}, + {"plugin": [sys.executable, 42]}, + {"plugin": resolved, "ssh": "must-not-contact.invalid"}, + ] + for entry in entries: + controller.configure({"cloud": entry}) + before = controller.config.read_bytes() + controller.raft("list", "--location", "cloud", code=None) + assert controller.config.read_bytes() == before + assert controller.actions() == b"", "invalid config reached provider" + print("rejections: invalid protocol/JSON/capabilities and malformed or mixed location config") + + +def main(): + with tempfile.TemporaryDirectory(prefix="raft-plugin-verification-") as temporary: + directory = Path(temporary) + controller = Controller(directory) + verify_registration(controller) + verify_lifecycle(controller) + verify_rejections(directory) + print("Executable plugin verification passed; no live hosts or operator state used") + + +if __name__ == "__main__": + main() diff --git a/deploy/verify-release.py b/deploy/verify-release.py index db45899..5ec55a0 100644 --- a/deploy/verify-release.py +++ b/deploy/verify-release.py @@ -74,6 +74,7 @@ def verify_npm(): "package/raft_run.py", "package/raft_jobs.py", "package/raft_output.py", + "package/raft_plugins.py", }: if content != (ROOT / PurePosixPath(member.name).name).read_bytes(): raise ValueError("npm runtime differs from canonical Python source") @@ -83,6 +84,7 @@ def verify_npm(): "package/raft_run.py", "package/raft_jobs.py", "package/raft_output.py", + "package/raft_plugins.py", "package/LICENSE", "package/deploy/deploy.py", "package/images/incus/build.sh", @@ -121,6 +123,7 @@ def main(): "raft_run.py", "raft_jobs.py", "raft_output.py", + "raft_plugins.py", "deploy", "docs", "images", @@ -133,9 +136,14 @@ def main(): with zipfile.ZipFile(wheels[0]) as archive: for name in archive.namelist(): inspect(name, archive.read(name)) - if not {"raft.py", "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py"} <= set( - archive.namelist() - ): + if not { + "raft.py", + "raft_files.py", + "raft_run.py", + "raft_jobs.py", + "raft_output.py", + "raft_plugins.py", + } <= set(archive.namelist()): raise ValueError("Wheel missing CLI module") # A new environment avoids both editable checkouts and uv's cached same-version # tool environments. Run the installed entry point outside the source tree. @@ -149,7 +157,12 @@ def main(): ) verify_cli(environment / "bin/raft", work) subprocess.run( - [str(python), "-I", "-c", "import raft, raft_files, raft_run, raft_jobs, raft_output"], + [ + str(python), + "-I", + "-c", + "import raft, raft_files, raft_run, raft_jobs, raft_output, raft_plugins", + ], cwd=work, check=True, ) diff --git a/deploy/verify-run.py b/deploy/verify-run.py index 04ad3ee..874618e 100644 --- a/deploy/verify-run.py +++ b/deploy/verify-run.py @@ -34,6 +34,9 @@ def __init__(self, fault="", status=0): self.fault, self.status = fault, status self.events = [] + def creation_location(self, args): + return "lab", {"ssh": "fixture"} + def new(self, args, *, run_id, on_allocate): self.events.append("allocate") assert args.disposable is True and args.ttl == args.timeout + 120 diff --git a/docs/contract.md b/docs/contract.md index d25a8c6..0a12ace 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -10,6 +10,27 @@ For a first run, use [host setup](./operations.mdx) and [your first box](./first Raft manages persistent unprivileged native-architecture Incus system containers on configured ARM64 or AMD64 Linux hosts. Containers share the host kernel. Images must match host CPU architecture; foreign-architecture emulation and VM workflows are not implemented. +## Executable location plugins + +Users can register trusted controller executables as locations with `raft plugin +add LOCATION -- COMMAND ...`. `plugin info` inspects their versioned capability +handshake; `plugin remove` unregisters them without changing provider resources. +Plugins own their dependencies and provider guarantees. The dependency-free +Python CLI keeps Incus as its built-in backend. + +Plugin entries use `plugin` argv and optional `options`, not `ssh`. Selected +commands negotiate protocol 1 before invoking a declared action with inherited +stdio and a JSON `RAFT_PLUGIN_REQUEST` environment value. Unsupported commands +fail without invoking the action; uncertain actions are never retried. Plugin box +IDs are opaque after the location separator. Explicit and configured `new` +defaults apply; omitted built-in Incus sizing does not. `config` reports plugin +host policies as `null`. Incus deployment tools select only SSH locations. + +Incus-specific guarantees in the sections below do not apply to plugins. +Plugins run with the controller user's privileges and inherited credentials; +they are not sandboxed. See [user plugins](./guides/plugins.mdx) for the complete +protocol, output contract and a sandbox-sdk adapter. + ## Image releases - Versioned releases provide clean ARM64 and AMD64 templates with SHA-256 checksums, package inventories, and build provenance. diff --git a/docs/guides/meta.json b/docs/guides/meta.json index 364c1b3..c945f36 100644 --- a/docs/guides/meta.json +++ b/docs/guides/meta.json @@ -18,6 +18,7 @@ "snapshots-forks", "backup-recovery", "config-policy", + "plugins", "upgrades", "troubleshooting" ] diff --git a/docs/guides/plugins.mdx b/docs/guides/plugins.mdx new file mode 100644 index 0000000..da9a001 --- /dev/null +++ b/docs/guides/plugins.mdx @@ -0,0 +1,154 @@ +--- +title: User plugins +description: Register your own sandbox backend without changing Raft or its dependencies. +--- + +# User plugins + +A plugin is a trusted executable on the controller. Register one as a location, +then use Raft's existing commands with its location-qualified handles. Plugins +can use any language and install their own dependencies. Raft itself still needs +only Python. Incus locations keep their existing behavior. + +## Register a plugin + +Install the plugin and its dependencies yourself, then register its command: + +```sh +raft plugin add cloud -- node /absolute/path/to/plugin.mjs +raft plugin info cloud +raft new --location cloud --disposable +raft list --location cloud +raft exec cloud:PROVIDER_ID -- uname -a +raft destroy cloud:PROVIDER_ID +``` + +`add` checks the protocol before saving the location. It refuses an existing +name. Use absolute paths for script arguments; Raft resolves the executable from +PATH at registration but does not resolve its arguments. Commands run in the +caller's working directory, without a shell. `info` prints the current handshake. +`raft plugin remove cloud` removes only the registration, never remote boxes. +Destroy boxes before removing a location if you still need Raft to reach them. + +Registration uses the same private, atomic controller configuration as Incus: + +```json +{ + "lab": {"ssh": "ubuntu@host", "image": "FULL_IMAGE_FINGERPRINT"}, + "cloud": { + "plugin": ["/usr/bin/node", "/absolute/path/to/plugin.mjs"], + "options": {}, + "note": "Provider charges apply" + } +} +``` + +`ssh` and `plugin` are mutually exclusive. `options` is an optional JSON object +passed only to that plugin. Credentials should come from the plugin's own secret +store or inherited environment, not command arguments or checked-in config. +Controller defaults select the location for `new`; without an override, the first +configured location is the default. + +## Trust and provider guarantees + +Plugins have the controller user's filesystem, environment, network and terminal +access. Registration runs their code. Inspect and trust a plugin before adding +it. Raft does not download code, scan PATH for plugins, or install dependencies. +Do not let untrusted projects write the controller configuration or plugin files. + +Incus host locks, the TTL worker, persistent stop, network filtering, +private tunnels and image rules apply only to Incus locations. A plugin owns its +provider's limits, expiry, persistence, isolation, credentials and cleanup. It must +reject unsupported commands and options rather than silently weaken them. In +particular, do not map persistent `stop` to deletion or return a public preview +URL for `forward`, which promises a private loopback tunnel. + +Commands across all locations can partially complete before a later location +fails. Use `--location` on `list`, `capacity`, `doctor`, `gc` and `prune` to select +one location. Raft never retries an uncertain plugin action. `config` reports +`null` for plugin host policies; controller defaults still apply to `new`. + +## Executable protocol, version 1 + +Raft appends one action argument to the registered command. Before an action it +invokes `describe` with closed stdin and a ten-second deadline. This handshake +must be side-effect-free and print exactly one JSON object on stdout: + +```json +{"protocol": 1, "commands": ["new", "list", "info", "exec", "destroy"]} +``` + +Only declared commands run. Supported command names are `new`, `run`, `recover`, +`list`, `capacity`, `doctor`, `gc`, `prune`, `policy`, `note`, `info`, `stop`, +`resume`, `extend`, `destroy`, `ssh`, `exec`, `sync`, `upload`, `download`, +`snapshot`, `snapshots`, `snapshot-delete`, `restore`, `fork`, `forward`, +`desktop`, `logs`, `status`, `cancel`, `backup` and `usage`. Registration, +controller configuration and completion remain Raft commands. + +Each invocation receives `RAFT_PLUGIN_REQUEST` in its environment: + +```json +{ + "protocol": 1, + "location": "cloud", + "options": {}, + "args": { + "action": "exec", + "location": "cloud", + "box": "cloud:PROVIDER_ID", + "detach": false, + "command": ["printf", "%s", "literal argument"] + } +} +``` + +For `describe`, `args` is `{}`. Other actions receive the parsed command arguments, +including defaults, plus the resolved `location`. For `new`, explicit flags beat +controller defaults. Without configured sizing defaults, omitted `--cpu`, +`--memory` and `--disk` are `null`, so fixed-template providers can use their +defaults. Incus image creation still defaults to one CPU, 2 GiB and shared disk. +TTL defaults to 600 seconds. Plugin implementations must define whether and how +their provider enforces that TTL. +Box IDs are opaque nonempty strings after the first colon. Encode IDs if needed +to keep handles on one line. `--from` must stay within its source location. + +Normal actions inherit stdin, stdout and stderr. Preserve literal `exec` arguments +and return the guest exit code. Use stdout for the command result and stderr for +diagnostics. A signal exit becomes `128 + signal`; interruption returns 130. +There is no action deadline imposed by Raft, so plugins must bound their own +network operations and handle cancellation. + +Output follows the existing command contract: `new`, `fork` and `recover` print +one qualified handle; `list` prints JSONL with `box`, `state`, `stopAt`, +`deleteAt`, `disk` and `note`; `info` prints provider metadata as JSON; `exec` +streams guest output. Deadline fields may be empty when unavailable, and `disk` +may be `null` when the provider cannot report its storage. `note` uses Raft's purpose, +owner and next template. File paths and recursive-transfer safeguards follow the +[CLI reference](../reference/cli.md). A plugin can support fewer commands, but +must not advertise semantics it cannot implement. + +Global `raft --json` captures plugin stdout and stderr as base64 byte-stream +events, then emits the plugin exit status. Plugins must write normal output, +not nested Raft event envelopes. Interactive SSH, forwarding and desktop reject +global JSON mode before any plugin runs. + +## sandbox-sdk adapter + +The repository's `examples/sandbox-sdk/` adapter uses +[`@opencoredev/sandbox-sdk`](https://github.com/opencoredev/sandbox-sdk). It keeps +Node.js and provider SDK dependencies outside the Raft installation. Its README +covers provider setup, supported commands and the isolated smoke check. + +## Why an executable protocol + +Python entry points would tie plugins to Raft's Python environment. Embedding +sandbox-sdk would require Node.js for every installation and couple Raft releases +to provider dependencies. Executables keep dependency ownership with the plugin +and preserve interactive stdio without a background RPC service. + +The [Docker plugin API](https://docs.docker.com/engine/extend/plugin_api/) provides +a precedent for out-of-process plugins with a capability handshake. Raft uses +short-lived executables instead of Docker's daemon and HTTP protocol. SDK +[provider capabilities](https://github.com/opencoredev/sandbox-sdk/blob/main/packages/sdk/src/provider.ts) +are optional, and its [lifecycle API](https://github.com/opencoredev/sandbox-sdk/blob/main/packages/sdk/src/types.ts) +does not promise Incus stop and expiry semantics across every provider. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index da16744..7dcbbee 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -9,6 +9,11 @@ Use `raft [--json] COMMAND ...`. `raft --help`, command `--help` and `raft --ver Global `--json` must precede the command. It emits JSONL data, byte-stream, error and exit events, but rejects interactive `ssh`, `forward` and `desktop`. Without it, output is command-specific. See [scripting and exit codes](../guides/scripting-ci.mdx). +Registered [executable plugins](../guides/plugins.mdx) can provide other sandbox +backends. Commands route by location and must appear in the plugin's capability +handshake. The Incus-specific behavior below applies to SSH locations; a plugin +must document its own guarantees and reject options it cannot honor. + ## Check shared arguments - `box` is the exact location-qualified handle returned by creation, not a native Incus name. Inspect `raft list` and its ownership note first. @@ -32,6 +37,17 @@ Create and start a box; stdout is its exact `LOCATION:rf-` handle with 16 lowerc Create a disposable box, wait for command readiness, optionally upload, execute, collect directories and clean up. `--timeout` is 1 to 2,591,880 seconds, default 600, for all setup/upload/execution. Collection and cleanup each get 30 seconds. `--push` selects Git-tracked/unignored files without `.git` and rejects submodules; `--push-all` copies the full inspected tree. `--cwd` defaults to `/workspace/project` with upload or `/workspace` without it. Upload destinations must be new with an existing parent. Repeat `--pull` to collect directories into absent local destinations with existing parents, even after payload failure. See [CI limits and exit codes](../guides/ci-jobs.mdx). +### `plugin` + +`raft plugin add LOCATION -- COMMAND [ARG ...]` +`raft plugin info LOCATION` +`raft plugin remove LOCATION` + +Register a trusted local executable after checking protocol 1, inspect its +capabilities, or remove its registration without touching remote resources. +Existing location names cannot be overwritten. Dependencies are installed by the +user, not Raft. See [registration and trust](../guides/plugins.mdx). + ### `locations` `raft locations [-h]` @@ -44,7 +60,11 @@ Print JSONL `location`, `default` and `note` from controller inventory without c `raft config set [-h] {location,ttl,cpu,memory,disk,disposable} value` `raft config unset [-h] {location,ttl,cpu,memory,disk,disposable}` -Print effective controller defaults with each value's source and host policies. `--location` filters only the policy report; it is rejected with `set` or `unset`. Keys are `location`, `ttl`, `cpu`, `memory`, `disk`, `disposable`; use `true` or `false` for the last. `unset` restores the built-in default. See [configuration](./configuration.mdx). +Print effective controller defaults with each value's source and host policies. +Plugin policies are `null`. `--location` filters only the policy report; it is +rejected with `set` or `unset`. Keys are `location`, `ttl`, `cpu`, `memory`, `disk`, +`disposable`; use `true` or `false` for the last. `unset` restores the built-in +default. See [configuration](./configuration.mdx). ### `policy` diff --git a/docs/verification.mdx b/docs/verification.mdx index 6ab8546..ba09b0c 100644 --- a/docs/verification.mdx +++ b/docs/verification.mdx @@ -32,6 +32,13 @@ Do not use `--restart-incus` unless daemon interruption is approved on a disposa For host-independent checks, omit `--location` from `verify-features.py`, `verify-limits.py` and `verify-run.py`. `python3 deploy/verify-image-tests.py` checks archive safety; `python3 deploy/verify-self-update.py` tests temporary npm/uv installations. Local worker and orchestration fixtures do not establish native-host behavior. +`python3 deploy/verify-plugins.py` exercises executable plugin registration, +capability failures, opaque handles, commands, files and removal through real CLI +processes with a temporary HOME and provider state. It contacts no hosts. The +optional `examples/sandbox-sdk/` smoke exercises the published SDK and a disposable +filesystem provider, not cloud accounts. These checks do not certify a third-party +provider's isolation, billing or expiry guarantees. + ## Read the evidence and its limits [Native ARM64 and AMD64 validation](https://github.com/Microck/raft/actions/runs/37603576786) exercises lifecycle, workspace controls, tool checks, backup/recovery and startup measurements. [Fresh-host validation](https://github.com/Microck/raft/actions/runs/37469540182) covers deployment and reboot on a disposable AMD64 Ubuntu 24 KVM host. See [measured startup results](./boot-performance.mdx) for samples and methodology. diff --git a/examples/sandbox-sdk/.gitignore b/examples/sandbox-sdk/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/examples/sandbox-sdk/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/examples/sandbox-sdk/README.md b/examples/sandbox-sdk/README.md new file mode 100644 index 0000000..c074017 --- /dev/null +++ b/examples/sandbox-sdk/README.md @@ -0,0 +1,153 @@ +# Optional sandbox-sdk plugin + +This executable implements Raft plugin protocol 1 with the published +`@opencoredev/sandbox-sdk` 1.0.3. Node.js and provider dependencies stay in this +directory, outside Raft's Python installation. Requires Node.js 22+ and pnpm +11.25.0. No build step is needed. + +```sh +cd examples/sandbox-sdk +pnpm install --frozen-lockfile +pnpm smoke +``` + +The smoke uses the SDK's real `memory()` provider in one process and a test-only +filesystem Provider across separate adapter processes. It uses a fresh temporary +directory, real shell commands and real file transfers, then deletes only that +directory. It contacts no cloud provider or Docker daemon. The filesystem Provider +is not a security sandbox and must not be used for untrusted code. + +## Choose a provider + +Create an absolute-path ES module whose default export returns a SDK `Provider`. +The export may be async. It receives `options.providerOptions` as its only argument. +Any compatible provider can be selected; there is no adapter allowlist. Install +optional provider packages beside your factory when that provider requires them. +For example, a factory beside this README can select SDK's Docker provider: + +```js +// /absolute/path/to/examples/sandbox-sdk/my-provider.mjs +import { local } from '@opencoredev/sandbox-sdk/local'; +export default function createProvider(options) { + return local(options); +} +``` + +This example does not install, start or configure Docker. Using it requires your +own authorized daemon and image. Other factories can return any SDK Provider. +Factories and their imported modules are trusted executable code. Keep credentials +in the provider's secret store or inherited environment, not in configuration. +Factories must not print logs on stdout, which carries protocol results. + +Register the adapter, then set the registered location's options in Raft's +controller configuration before creating a box: + +```sh +raft plugin add sdk -- node /absolute/path/to/examples/sandbox-sdk/adapter.mjs +``` + +```json +{ + "sdk": { + "plugin": ["/absolute/path/to/node", "/absolute/path/to/examples/sandbox-sdk/adapter.mjs"], + "options": { + "factory": "/absolute/path/to/examples/sandbox-sdk/my-provider.mjs", + "providerOptions": {}, + "operationTimeoutMs": 120000 + } + } +} +``` + +`factory` is required for normal actions and must be an absolute module filename. +`providerOptions` defaults to `{}`. `operationTimeoutMs` defaults to 120000 and +bounds each whole invocation, including factory loading and handle cleanup. +Unknown adapter options fail. `describe` imports neither the factory nor the SDK, +needs no credentials, and only prints the static handshake. + +```sh +box=$(raft new --location sdk --disposable) +raft list --location sdk +raft info "$box" +raft exec "$box" -- printf '%s\n' 'literal $argument' +raft upload "$box" ./input.txt /workspace/input.txt +raft download "$box" /workspace/input.txt ./output.txt +raft destroy "$box" +``` + +## Supported behavior + +- `new` requires explicit `--disposable`. It passes `timeoutMs = ttl * 1000` to + `createSandbox`; TTL defaults to 600 seconds. Omitted CPU and memory leave SDK + defaults untouched. Explicit sizing requires both CPU and memory, maps GiB to + SDK `memoryMb` using 1024 MiB per GiB, and requires the provider's `size` + capability. Disk sizing, snapshot sources and box notes are rejected. +- `list` prints JSONL with `box`, `state`, `stopAt`, `deleteAt`, `disk` and `note`. + Deadlines are empty and disk/note are null because the common SDK contract does + not report authoritative deadlines or storage, or implement Raft's note template. +- `info` prints JSON metadata with the native ID, qualified handle, provider, + labels and capabilities. +- `exec` requires a provider with a POSIX shell and `/workspace` working directory. + It POSIX-shell-quotes every argv element and streams every text chunk from + `Provider.exec` to its corresponding output stream. It returns the guest exit + code. The SDK's higher-level `box.run()` iterator is deliberately not used: + version 1.0.3 drops old chunks when its 1 MiB subscription queue fills. Stdin is + inherited by the adapter, but the SDK's primitive closes guest stdin; interactive + terminals and stdin forwarding are not supported. Detached exec is rejected. +- `upload` and `download` transfer one regular file as bytes, in memory. Guest + paths must be absolute POSIX file paths without NUL or `..` components. Recursive + transfers and directory/symlink downloads are rejected. An upload source must + be a regular file. A download stages bytes in a private sibling directory and + renames only after a successful read and handle close, leaving any existing + destination unchanged on failure. Parent directories must already exist. +- `destroy` deletes only after checking both SDK and Raft location labels in + filtered SDK metadata, then connecting and rechecking the handle. The first + check matters because some providers expire/delete during connect. Every box + operation applies these checks; list requests and independently filters labels. + Labels prevent accidental cross-location access, not hostile access by someone + who controls the provider account or trusted factory. + +IDs are reversible UTF-8 base64url encodings of native provider IDs. Handles stay +on one line, and reconnect in separate CLI processes without a local ID registry. +Native provider state must itself survive processes. SDK's `memory()` does not. +Creation calls `close()` explicitly, not `await using`, which would destroy an +unkeyed sandbox. No persistent stop, resume, SSH, forwarding, snapshots, background +jobs or maintenance commands are advertised. Global `raft --json` is supported by +Raft's byte-stream event wrapper; the adapter ignores `args.json_output` metadata +and always writes normal command output, never nested event envelopes. + +## Expiry and failure limits + +`--disposable` acknowledges that this adapter cannot promise Raft's persistent +stop or Incus expiry worker. It is not proof of provider-side expiry. SDK providers +may enforce, cap, round, ignore or lazily check `timeoutMs`; check the selected +provider's implementation and account policy. Explicitly destroy boxes when done. +Cloud billing and cleanup remain the operator's responsibility. + +In published SDK 1.0.3, Docker's `local()` stores a deadline in Docker labels and +checks it on `connect()`. Its `list()` does not expire containers and there is no +independent expiry worker in that implementation. A short-lived CLI process does +not stay alive to enforce TTL. Other versions or factories may use a client-owned +worker; such a worker dies with the CLI process unless separately supervised. +Do not rely on this example for unattended Docker expiry. + +The invocation deadline and SIGINT/SIGTERM abort SDK create/exec requests, allow +five seconds for cleanup, then exit with 124, 130 or 143. Other SDK operations lack +a common abort signal. A disconnected, interrupted or timed-out mutation may +have completed remotely; this adapter never retries it. Inspect provider state +before retrying. An exec timeout returns 124; a provider's null exit status without +a timeout returns 137. Normal errors return 1. Providers must honor the SDK +contract to kill the whole guest process group on exec timeout/abort. Adapter +cleanup closes handles, not sandboxes. No local timer can guarantee remote cleanup +when a provider stops responding. + +## Primary API sources + +All source links are pinned to the npm 1.0.3 publication's `gitHead`: + +- [Published package metadata](https://registry.npmjs.org/@opencoredev/sandbox-sdk/1.0.3) +- [createSandbox, connectSandbox, listSandboxes](https://github.com/opencoredev/sandbox-sdk/blob/f2e2267751f6cb751ea46b8bffbd09aa238edca1/packages/sdk/src/index.ts) +- [Provider primitives and labels](https://github.com/opencoredev/sandbox-sdk/blob/f2e2267751f6cb751ea46b8bffbd09aa238edca1/packages/sdk/src/provider.ts) +- [RunOptions, close and disposal](https://github.com/opencoredev/sandbox-sdk/blob/f2e2267751f6cb751ea46b8bffbd09aa238edca1/packages/sdk/src/types.ts) +- [Bounded output iterator](https://github.com/opencoredev/sandbox-sdk/blob/f2e2267751f6cb751ea46b8bffbd09aa238edca1/packages/sdk/src/run.ts) +- [Docker lifecycle implementation](https://github.com/opencoredev/sandbox-sdk/blob/f2e2267751f6cb751ea46b8bffbd09aa238edca1/packages/sdk/src/providers/local/index.ts) diff --git a/examples/sandbox-sdk/adapter.mjs b/examples/sandbox-sdk/adapter.mjs new file mode 100644 index 0000000..1825396 --- /dev/null +++ b/examples/sandbox-sdk/adapter.mjs @@ -0,0 +1,231 @@ +import { open, mkdtemp, rename, rm, writeFile } from 'node:fs/promises'; +import { dirname, isAbsolute, join, resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; + +const commands = ['new', 'list', 'info', 'exec', 'upload', 'download', 'destroy']; +const locationLabel = 'raft.location'; +const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`; +const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value); +const fail = (message) => { throw new Error(message); }; +const json = (value) => process.stdout.write(`${JSON.stringify(value)}\n`); + +function guestPath(value) { + if (typeof value !== 'string' || !value.startsWith('/') || value.endsWith('/') || + value.includes('\0') || value.split('/').includes('..')) { + fail('Guest path must be an absolute POSIX file path without NUL or .. components'); + } + return value; +} + +function nativeId(handle, location) { + if (typeof handle !== 'string' || !handle.startsWith(`${location}:`)) { + fail('Box handle must belong to the requested location'); + } + const encoded = handle.slice(location.length + 1); + if (!/^[A-Za-z0-9_-]+$/.test(encoded)) fail('Invalid base64url box ID'); + const id = Buffer.from(encoded, 'base64url').toString('utf8'); + if (!id || Buffer.from(id).toString('base64url') !== encoded) fail('Noncanonical box ID'); + return id; +} + +function qualified(id, location) { + if (typeof id !== 'string' || !id || !id.isWellFormed()) fail('Provider returned an invalid UTF-8 ID'); + return `${location}:${Buffer.from(id).toString('base64url')}`; +} + +function validateArgs(action, args, location) { + if (args.action !== action || args.location !== location) fail('Action or normalized location mismatch'); + const allowed = { + new: ['ttl', 'cpu', 'memory', 'disposable'], + list: [], info: [], destroy: [], + exec: ['command', 'detach'], + upload: ['source', 'destination', 'recursive'], + download: ['source', 'destination', 'recursive'], + }[action]; + for (const [key, value] of Object.entries(args)) { + if (!['action', 'location', 'box', 'json_output', ...allowed].includes(key) && + value !== null && value !== false && value !== undefined) { + fail(`Unsupported argument: ${key}`); + } + } + if (action === 'new') { + if (args.disposable !== true) fail('new requires --disposable; persistent stop is not supported'); + if (!Number.isSafeInteger(args.ttl) || args.ttl < 60 || args.ttl > 2592000) fail('TTL must be 60..2592000 seconds'); + const cpu = args.cpu ?? null; + const memory = args.memory ?? null; + if ((cpu === null) !== (memory === null)) fail('Explicit sizing requires both --cpu and --memory'); + if (cpu !== null && (!Number.isSafeInteger(cpu) || cpu <= 0 || + typeof memory !== 'string' || !/^[1-9][0-9]*GiB$/.test(memory) || + !Number.isSafeInteger(Number.parseInt(memory, 10) * 1024))) { + fail('CPU must be a positive integer and memory must be whole positive GiB'); + } + } + if (action === 'exec') { + if (args.detach) fail('Detached exec is not supported'); + if (!Array.isArray(args.command) || !args.command.length || + args.command.some((arg) => typeof arg !== 'string' || arg.includes('\0'))) { + fail('exec requires nonempty literal argv without NUL'); + } + } + if (action === 'upload' || action === 'download') { + if (args.recursive) fail('Recursive transfers are not supported'); + guestPath(action === 'upload' ? args.destination : args.source); + const localPath = action === 'upload' ? args.source : args.destination; + if (typeof localPath !== 'string' || !localPath || localPath.includes('\0')) fail('Local file path is required'); + } + if (!['new', 'list'].includes(action)) nativeId(args.box, location); +} + +async function atomicDownload(destination, bytes) { + const target = resolve(destination); + const staging = await mkdtemp(join(dirname(target), '.raft-download-')); + try { + const temporary = join(staging, 'file'); + await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 }); + await rename(temporary, target); + } finally { + await rm(staging, { recursive: true, force: true }); + } +} + +async function dispatch({ action, request, signal, timeoutMs }) { + const { args, location, options } = request; + const { createSandbox, connectSandbox, listSandboxes } = await import('@opencoredev/sandbox-sdk'); + const factory = (await import(pathToFileURL(options.factory).href)).default; + if (typeof factory !== 'function') fail('Factory module must default-export a function returning a Provider'); + const provider = await factory(options.providerOptions ?? {}); + const labels = { 'sandbox-sdk': '1', [locationLabel]: location }; + const owns = (box) => Object.entries(labels).every(([key, value]) => box.labels?.[key] === value); + if (signal.aborted) throw signal.reason; + + if (action === 'list') { + for (const box of await listSandboxes(provider, { labels })) { + if (owns(box)) json({ box: qualified(box.id, location), state: box.state, + stopAt: '', deleteAt: '', disk: null, note: null }); + } + return 0; + } + + let box; + let download; + let exitCode = 0; + try { + if (action === 'new') { + const size = args.cpu == null ? {} : { + size: { cpu: args.cpu, memoryMb: Number.parseInt(args.memory, 10) * 1024 }, + }; + box = await createSandbox(provider, { ...size, labels, timeoutMs: args.ttl * 1000, signal }); + } else { + const id = nativeId(args.box, location); + // Some providers expire/delete during connect. Establish ownership before that call. + const candidates = await listSandboxes(provider, { labels }); + if (!candidates.some((candidate) => candidate.id === id && owns(candidate))) { + fail('Sandbox is missing or not owned by this Raft location'); + } + box = await connectSandbox(provider, id, { recoverSecrets: false }); + } + // Check even when the provider ignores list filters or connects an arbitrary native ID. + if (!owns(box)) fail('Sandbox is not owned by this Raft location'); + if (signal.aborted) throw signal.reason; + switch (action) { + case 'new': + // Close successfully before publishing a handle; never auto-dispose an unkeyed sandbox. + await box.close(); + process.stdout.write(`${qualified(box.id, location)}\n`); + break; + case 'info': + json({ box: qualified(box.id, location), id: box.id, provider: box.provider, + labels: box.labels, capabilities: [...box.capabilities] }); + break; + case 'destroy': + await box.destroy(); + break; + case 'exec': { + // RunHandle's OutputBus drops chunks above 1 MiB. Primitive callbacks do not. + const outcome = await provider.exec(box.id, { + command: args.command.map(quote).join(' '), cwd: '/workspace', env: {}, + timeoutMs, signal, streaming: true, + onChunk({ stream, text }) { process[stream].write(text); }, + }); + exitCode = outcome.timedOut ? 124 : (outcome.exitCode ?? 137); + if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) fail('Provider returned an invalid exit code'); + break; + } + case 'upload': { + const source = await open(args.source, 'r'); + try { + if (!(await source.stat()).isFile()) fail('Upload source must be a regular file'); + await box.files.write(args.destination, await source.readFile()); + } finally { await source.close(); } + break; + } + case 'download': + if ((await box.files.stat(args.source)).type !== 'file') fail('Download source must be a regular file'); + download = await box.files.read(args.source, { as: 'bytes' }); + break; + } + } finally { + await box?.close(); + } + // A failed remote read or handle close cannot damage an existing local destination. + if (signal.aborted) throw signal.reason; + if (download !== undefined) await atomicDownload(args.destination, download); + return exitCode; +} + +async function main() { + const action = process.argv.at(-1); + const request = JSON.parse(process.env.RAFT_PLUGIN_REQUEST ?? 'null'); + if (!object(request) || request.protocol !== 1 || !object(request.args) || + !object(request.options) || typeof request.location !== 'string' || + !request.location || /[:\s]/.test(request.location)) fail('Invalid protocol 1 request'); + if (action === 'describe') { + json({ protocol: 1, commands }); + return 0; + } + if (!commands.includes(action)) fail(`Unsupported action: ${action}`); + validateArgs(action, request.args, request.location); + const { options } = request; + for (const key of Object.keys(options)) { + if (!['factory', 'providerOptions', 'operationTimeoutMs'].includes(key)) fail(`Unknown adapter option: ${key}`); + } + if (typeof options.factory !== 'string' || !isAbsolute(options.factory)) fail('options.factory must be an absolute module filename'); + if (options.providerOptions !== undefined && !object(options.providerOptions)) fail('providerOptions must be an object'); + const timeoutMs = options.operationTimeoutMs ?? 120000; + if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) fail('operationTimeoutMs must be 1..2147483647'); + const controller = new AbortController(); + let cancelledCode; + let forced; + const cancel = (code, message) => { + if (cancelledCode !== undefined) return; + cancelledCode = code; + process.stderr.write(`${message}; remote outcome may be uncertain. Inspect before retrying.\n`); + controller.abort(new Error(message)); + forced = setTimeout(() => process.exit(code), 5000); + }; + const interrupt = () => cancel(130, 'Interrupted'); + const terminate = () => cancel(143, 'Terminated'); + process.on('SIGINT', interrupt); + process.on('SIGTERM', terminate); + const deadline = setTimeout(() => cancel(124, 'Adapter operation timed out'), timeoutMs); + try { + return await dispatch({ action, request, signal: controller.signal, timeoutMs }); + } finally { + clearTimeout(deadline); + clearTimeout(forced); + process.off('SIGINT', interrupt); + process.off('SIGTERM', terminate); + if (cancelledCode !== undefined) process.exitCode = cancelledCode; + } +} + +try { + const code = await main(); + process.exitCode ??= code; + // Flush all callback writes, including output larger than the writable high-water mark. + await Promise.all([process.stdout, process.stderr].map((stream) => + new Promise((resolve) => stream.write('', resolve)))); +} catch (error) { + process.stderr.write(`sandbox-sdk adapter: ${error.message}\n`); + process.exitCode ??= 1; +} diff --git a/examples/sandbox-sdk/package.json b/examples/sandbox-sdk/package.json new file mode 100644 index 0000000..1fbc2ff --- /dev/null +++ b/examples/sandbox-sdk/package.json @@ -0,0 +1,9 @@ +{ + "name": "raft-sandbox-sdk-example", + "private": true, + "type": "module", + "engines": { "node": ">=22" }, + "packageManager": "pnpm@11.25.0", + "scripts": { "smoke": "node smoke.mjs" }, + "dependencies": { "@opencoredev/sandbox-sdk": "1.0.3" } +} diff --git a/examples/sandbox-sdk/pnpm-lock.yaml b/examples/sandbox-sdk/pnpm-lock.yaml new file mode 100644 index 0000000..7267b5d --- /dev/null +++ b/examples/sandbox-sdk/pnpm-lock.yaml @@ -0,0 +1,58 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + '@opencoredev/sandbox-sdk': + specifier: 1.0.3 + version: 1.0.3 + +packages: + + '@opencoredev/sandbox-sdk@1.0.3': + resolution: {integrity: sha512-e80FUkMZYBoX9oeZrldLnKwVvYYXXuj8fJbzfboaDfhlOGx1wN/s7ClHNvvTTeFkJwQywtlOJ2FFOO+YeKSoSw==} + engines: {bun: '>=1.3', node: '>=22'} + peerDependencies: + '@boxd-sh/sdk': ^0.2.17 + '@mastra/core': ^1.78.0 + '@openai/agents': ^0.20.0 + '@rivet-dev/agentos-core': 0.4.1 + '@tenkicloud/sandbox': ^1.4.1 + '@upstash/box': ^0.7.9 + '@vercel/sandbox': ^3.8.0 + ai: ^7.0.143 + railway: ^3.16.0 + vitest: '>=3' + zod: ^4.6.7 + peerDependenciesMeta: + '@boxd-sh/sdk': + optional: true + '@mastra/core': + optional: true + '@openai/agents': + optional: true + '@rivet-dev/agentos-core': + optional: true + '@tenkicloud/sandbox': + optional: true + '@upstash/box': + optional: true + '@vercel/sandbox': + optional: true + ai: + optional: true + railway: + optional: true + vitest: + optional: true + zod: + optional: true + +snapshots: + + '@opencoredev/sandbox-sdk@1.0.3': {} diff --git a/examples/sandbox-sdk/smoke-provider.mjs b/examples/sandbox-sdk/smoke-provider.mjs new file mode 100644 index 0000000..4bd2efb --- /dev/null +++ b/examples/sandbox-sdk/smoke-provider.mjs @@ -0,0 +1,126 @@ +// Test-only Provider: real files and host shell processes, not an isolation boundary. +import { spawn } from 'node:child_process'; +import { randomUUID } from 'node:crypto'; +import { constants } from 'node:os'; +import { readFile, writeFile, mkdir, readdir, lstat, rm, access } from 'node:fs/promises'; +import { join, resolve, relative, isAbsolute, dirname } from 'node:path'; +import { StringDecoder } from 'node:string_decoder'; +import { SandboxError } from '@opencoredev/sandbox-sdk'; + +export default async function filesystemProvider({ root }) { + if (typeof root !== 'string' || !isAbsolute(root) || + (await readFile(join(root, '.raft-sdk-smoke'), 'utf8')) !== 'disposable\n') { + throw new Error('Test Provider requires a marked disposable root'); + } + const boxes = join(root, 'boxes'); + await mkdir(boxes, { recursive: true }); + const directory = (id) => join(boxes, Buffer.from(id).toString('base64url')); + const metadata = (id) => join(directory(id), 'info.json'); + const guest = (id, path) => { + const base = join(directory(id), 'files'); + const target = resolve(base, `.${path}`); + const rel = relative(base, target); + if (!path.startsWith('/') || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) { + throw new Error('Path escapes test workspace'); + } + return target; + }; + const connect = async (id) => { + try { return JSON.parse(await readFile(metadata(id), 'utf8')); } + catch (cause) { + if (cause.code === 'ENOENT') throw new SandboxError('Unknown disposable test sandbox', { code: 'not_found' }); + throw cause; + } + }; + const stat = async (id, path) => { + await connect(id); + const value = await lstat(guest(id, path)); + return { path, type: value.isSymbolicLink() ? 'symlink' : value.isDirectory() ? 'directory' : 'file', + size: value.size, modifiedAt: value.mtimeMs }; + }; + return { + name: 'raft-disposable-filesystem', keyMode: 'best-effort', capabilities: new Set(), + async create(input) { + // Exercise IDs that cannot safely be printed raw on one CLI line. + const id = `test/${randomUUID()}:雪\n`; + await mkdir(guest(id, '/workspace'), { recursive: true }); + const info = { id, labels: input.labels, state: 'running', createdAt: Date.now() }; + await writeFile(metadata(id), JSON.stringify(info), { flag: 'wx' }); + await writeFile(join(directory(id), 'creation.json'), JSON.stringify(input)); + return info; + }, + async find(key) { + return (await this.list({})).find((box) => box.key === key); + }, + connect, + async list(labels) { + const entries = await readdir(boxes); + const rows = await Promise.all(entries.map(async (entry) => + JSON.parse(await readFile(join(boxes, entry, 'info.json'), 'utf8')))); + return rows.filter((box) => Object.entries(labels).every(([key, value]) => box.labels[key] === value)); + }, + async destroy(id) { + await connect(id); + await rm(directory(id), { recursive: true }); + }, + async close(id) { await access(metadata(id)); }, + native(id) { return { directory: directory(id) }; }, + async previewUrl() { throw new SandboxError('Test Provider has no network preview', { code: 'unsupported' }); }, + async exec(id, input) { + await connect(id); + if (input.signal?.aborted) return { exitCode: null, timedOut: true }; + return await new Promise((fulfill, reject) => { + // This is the only process group signaled by the smoke. It is newly spawned here. + const child = spawn('/bin/sh', ['-c', input.command], { + cwd: guest(id, input.cwd), env: { ...process.env, ...input.env }, + detached: true, stdio: ['pipe', 'pipe', 'pipe'], + }); + let timedOut = false; + const cancel = () => { + timedOut = true; + try { process.kill(-child.pid, 'SIGKILL'); } + catch (error) { if (error.code !== 'ESRCH') reject(error); } + }; + const timer = setTimeout(cancel, input.timeoutMs); + input.signal?.addEventListener('abort', cancel, { once: true }); + for (const stream of ['stdout', 'stderr']) { + const decoder = new StringDecoder('utf8'); + child[stream].on('data', (bytes) => { + const text = decoder.write(bytes); + if (text) input.onChunk({ stream, text }); + }); + child[stream].on('end', () => { + const text = decoder.end(); + if (text) input.onChunk({ stream, text }); + }); + } + const cleanup = () => { + clearTimeout(timer); + input.signal?.removeEventListener('abort', cancel); + }; + child.once('error', (error) => { cleanup(); reject(error); }); + child.once('close', (code, signal) => { + cleanup(); + fulfill({ exitCode: code ?? (signal ? 128 + constants.signals[signal] : null), timedOut }); + }); + child.stdin.on('error', (error) => { if (error.code !== 'EPIPE') reject(error); }); + child.stdin.end(input.stdin ?? ''); + }); + }, + files: { + writeCreatesParents: true, writeSupportsMode: true, + async read(id, path) { await connect(id); return await readFile(guest(id, path)); }, + async write(id, path, bytes, options) { + await connect(id); + await mkdir(dirname(guest(id, path)), { recursive: true }); + await writeFile(guest(id, path), bytes, options); + }, + stat, + async list(id, path) { + return await Promise.all((await readdir(guest(id, path))).map((name) => stat(id, `${path}/${name}`))); + }, + async mkdir(id, path) { await connect(id); await mkdir(guest(id, path), { recursive: true }); }, + async remove(id, path, options) { await connect(id); await rm(guest(id, path), options); }, + }, + }; +} diff --git a/examples/sandbox-sdk/smoke.mjs b/examples/sandbox-sdk/smoke.mjs new file mode 100644 index 0000000..e6414bf --- /dev/null +++ b/examples/sandbox-sdk/smoke.mjs @@ -0,0 +1,177 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { mkdtemp, writeFile, readFile, readdir, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { createSandbox, connectSandbox, listSandboxes } from '@opencoredev/sandbox-sdk'; +import { memory } from '@opencoredev/sandbox-sdk/memory'; + +const here = dirname(fileURLToPath(import.meta.url)); +const root = await mkdtemp(join(tmpdir(), 'raft-sdk-smoke-')); +const options = { factory: join(here, 'smoke-provider.mjs'), providerOptions: { root } }; +const labels = { 'raft.location': 'sdk' }; + +function invoke(action, args = {}, settings = {}) { + const location = settings.location ?? 'sdk'; + const request = { protocol: 1, location, options: settings.options ?? options, + args: action === 'describe' ? {} : { action, location, json_output: false, ...args } }; + return new Promise((fulfill, reject) => { + const stdout = []; + const stderr = []; + const child = spawn(process.execPath, [join(here, 'adapter.mjs'), action], { + env: { ...process.env, RAFT_PLUGIN_REQUEST: JSON.stringify(request) }, + stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000, + }); + child.stdout.on('data', (chunk) => { + stdout.push(chunk); + settings.onStdout?.(chunk, child); + }); + child.stderr.on('data', (chunk) => stderr.push(chunk)); + child.on('error', reject); + child.on('close', (status, signal) => fulfill({ status, signal, + stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString() })); + }); +} + +async function success(action, args, settings) { + const result = await invoke(action, args, settings); + assert.equal(result.status, 0, `${action}: ${result.stderr}`); + assert.equal(result.stderr, ''); + return result.stdout; +} + +async function rejected(action, args, pattern, settings) { + const result = await invoke(action, args, settings); + assert.equal(result.status, 1, `${action}: ${result.stderr}`); + assert.match(result.stderr, pattern); + assert.equal(result.stdout, ''); +} + +try { + await writeFile(join(root, '.raft-sdk-smoke'), 'disposable\n'); + + // Published SDK lifecycle/files/run, with its built-in in-memory implementation. + const provider = memory(); + const created = await createSandbox(provider, { labels, timeoutMs: 60000 }); + try { + await created.files.write('/workspace/value', new Uint8Array([0, 255, 10])); + await created.close(); + const attached = await connectSandbox(provider, created.id, { recoverSecrets: false }); + try { + assert.deepEqual(await attached.files.read('/workspace/value', { as: 'bytes' }), new Uint8Array([0, 255, 10])); + assert.equal((await attached.run("printf '%s' 'literal $value'")).stdout, 'literal $value'); + assert.deepEqual((await listSandboxes(provider, { labels })).map((box) => box.id), [created.id]); + await attached.destroy(); + } finally { await attached.close(); } + } finally { await provider.destroy(created.id); } + assert.deepEqual(await listSandboxes(provider, { labels }), []); + + // Describe must not load even a factory that would fail or require secrets. + const forbidden = join(root, 'must-not-import.mjs'); + await writeFile(forbidden, "throw new Error('Factory loaded during handshake');\n"); + const handshake = JSON.parse(await success('describe', {}, { options: { factory: forbidden } })); + assert.deepEqual(handshake, { protocol: 1, + commands: ['new', 'list', 'info', 'exec', 'upload', 'download', 'destroy'] }); + assert.deepEqual((await readdir(root)).sort(), ['.raft-sdk-smoke', 'must-not-import.mjs']); + + const creation = { disposable: true, ttl: 600, cpu: null, memory: null, disk: null, + template: null, purpose: null, owner: null, next: null }; + const handle = (await success('new', creation)).trim(); + assert.match(handle, /^sdk:[A-Za-z0-9_-]+$/); + const nativeId = Buffer.from(handle.slice(4), 'base64url').toString(); + assert.match(nativeId, /^test\/.+:雪\n$/); + const storage = join(root, 'boxes', handle.slice(4)); + const input = JSON.parse(await readFile(join(storage, 'creation.json'), 'utf8')); + assert.equal(input.timeoutMs, 600000); + assert.equal(Object.hasOwn(input, 'size'), false); + const metadata = JSON.parse(await success('info', { box: handle })); + assert.equal(metadata.id, nativeId); + assert.equal(metadata.labels['raft.location'], 'sdk'); + assert.equal(metadata.labels['sandbox-sdk'], '1'); + assert.deepEqual(JSON.parse((await success('list')).trim()), + { box: handle, state: 'running', stopAt: '', deleteAt: '', disk: null, note: null }); + + const literals = ['', 'space here', "quote'\"", '$HOME; touch SHOULD_NOT_EXIST', '`echo unsafe`', 'line\nbreak', '雪']; + const literalOutput = await success('exec', { box: handle, detach: false, + command: ['printf', '%s\n', ...literals] }); + assert.equal(literalOutput, literals.join('\n') + '\n'); + assert.equal((await readdir(join(storage, 'files', 'workspace'))).includes('SHOULD_NOT_EXIST'), false); + + const length = 2 * 1024 * 1024 + 31; + const large = await invoke('exec', { box: handle, command: [process.execPath, '-e', + `process.stdout.write('s'.repeat(${length})); process.stderr.write('e'.repeat(${length})); process.exitCode=19;`] }); + assert.equal(large.status, 19); + assert.equal(large.stdout, 's'.repeat(length)); + assert.equal(large.stderr, 'e'.repeat(length)); + + // The guest cannot finish until the controller sees the first streamed chunk. + const release = join(root, 'release'); + let released; + const streaming = await invoke('exec', { box: handle, command: [process.execPath, '-e', + `const fs=require('node:fs'); process.stdout.write('ready\\n'); const t=setInterval(()=>{if(fs.existsSync(${JSON.stringify(release)})){clearInterval(t);process.stdout.write('done\\n')}},10);`] }, + { onStdout(chunk) { if (!released && chunk.toString().includes('ready')) released = writeFile(release, 'go'); } }); + await released; + assert.equal(streaming.status, 0, streaming.stderr); + assert.equal(streaming.stdout, 'ready\ndone\n'); + + const source = join(root, 'source'); + const destination = join(root, 'download'); + const payload = Buffer.from(Array.from({ length: 262144 }, (_, index) => index % 256)); + await writeFile(source, payload); + await success('upload', { box: handle, source, destination: '/workspace/file', recursive: false }); + await success('download', { box: handle, source: '/workspace/file', destination, recursive: false }); + assert.deepEqual(await readFile(destination), payload); + await writeFile(destination, 'keep existing'); + await rejected('download', { box: handle, source: '/workspace/missing', destination }, /ENOENT/); + assert.equal(await readFile(destination, 'utf8'), 'keep existing'); + await rejected('download', { box: handle, source: '/workspace', destination }, /regular file/); + assert.equal(await readFile(destination, 'utf8'), 'keep existing'); + + await rejected('new', { ...creation, disposable: false }, /--disposable/); + await rejected('new', { ...creation, disk: '10GiB' }, /Unsupported argument: disk/); + await rejected('new', { ...creation, purpose: 'test note' }, /Unsupported argument: purpose/); + await rejected('new', { ...creation, template: 'sdk:x/snapshot' }, /Unsupported argument: template/); + await rejected('new', { ...creation, cpu: 1 }, /both --cpu and --memory/); + await rejected('new', { ...creation, cpu: 3, memory: '3GiB' }, /cannot enforce size/); + await rejected('exec', { box: handle, command: ['true'], detach: true }, /Detached exec/); + assert.equal(await success('list', { json_output: true }), await success('list')); + await rejected('upload', { box: handle, source, destination: '/workspace/file', recursive: true }, /Recursive/); + await rejected('download', { box: handle, source: '/workspace/file', destination, recursive: true }, /Recursive/); + for (const path of ['relative', '/workspace/../file', '/workspace/file\0bad', '/workspace/']) { + await rejected('upload', { box: handle, source, destination: path }, /absolute POSIX/); + await rejected('download', { box: handle, source: path, destination }, /absolute POSIX/); + } + + // A forged prefix must not bypass the labels, even for destructive/file actions. + const forged = handle.replace(/^sdk:/, 'other:'); + for (const action of ['info', 'exec', 'upload', 'download', 'destroy']) { + const args = { box: forged }; + if (action === 'exec') args.command = ['true']; + if (action === 'upload') Object.assign(args, { source, destination: '/workspace/file' }); + if (action === 'download') Object.assign(args, { source: '/workspace/file', destination }); + await rejected(action, args, /not owned by this Raft location/, { location: 'other' }); + } + assert.equal(await success('list', {}, { location: 'other' }), ''); + await rejected('info', { box: forged }, /must belong/); + await rejected('info', { box: 'sdk:bad=' }, /Invalid base64url/); + + // Cancellation controls only the disposable exec group created by smoke-provider. + const interrupted = await invoke('exec', { box: handle, command: ['/bin/sh', '-c', + "printf 'interrupt-ready\\n'; sleep 30 & wait"] }, + { onStdout(chunk, child) { if (chunk.toString().includes('interrupt-ready')) child.kill('SIGINT'); } }); + assert.equal(interrupted.status, 130, interrupted.stderr); + assert.match(interrupted.stderr, /Interrupted/); + const timedOut = await invoke('exec', { box: handle, command: ['/bin/sh', '-c', 'sleep 30 & wait'] }, + { options: { ...options, operationTimeoutMs: 300 } }); + assert.equal(timedOut.status, 124, timedOut.stderr); + + await success('destroy', { box: handle }); + assert.equal(await success('list'), ''); + await rejected('info', { box: handle }, /missing or not owned/); + assert.deepEqual(await readdir(join(root, 'boxes')), []); + + console.log('PASS: SDK memory API; cross-process lifecycle, ownership, literal/large/live exec, binary transfers, failure safety, refusals and isolated cancellation'); +} finally { + await rm(root, { recursive: true, force: true }); +} diff --git a/package.json b/package.json index 8673dfb..05d793c 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py", + "raft_plugins.py", "deploy/*.py", "deploy/*.sh", "deploy/*.conf", diff --git a/pyproject.toml b/pyproject.toml index 15448b4..185cbe0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,11 +15,11 @@ requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.build.targets.sdist] -only-include = ["raft.py", "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py", "pyproject.toml", "package.json", ".npmignore", "uv.lock", "README.md", "LICENSE", ".gitignore", "deploy/", "docs/", "images/", "skills/", ".github/"] -exclude = ["/.jj", "/.git", "**/__pycache__", "**/*.pyc"] +only-include = ["raft.py", "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py", "raft_plugins.py", "pyproject.toml", "package.json", ".npmignore", "uv.lock", "README.md", "LICENSE", ".gitignore", "deploy/", "docs/", "images/", "skills/", "examples/sandbox-sdk/", ".github/"] +exclude = ["/.jj", "/.git", "**/__pycache__", "**/*.pyc", "**/node_modules"] [tool.hatch.build.targets.wheel] -include = ["raft.py", "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py"] +include = ["raft.py", "raft_files.py", "raft_run.py", "raft_jobs.py", "raft_output.py", "raft_plugins.py"] [tool.hatch.version] path = "raft.py" diff --git a/raft.py b/raft.py index c6e118e..c5551d5 100755 --- a/raft.py +++ b/raft.py @@ -27,6 +27,7 @@ import raft_run import raft_jobs import raft_output +import raft_plugins __version__ = "0.8.0" @@ -69,12 +70,18 @@ def configuration(): inventory = json.loads(CONFIG.read_text()) if not isinstance(inventory, dict) or not inventory: - raise ValueError("Configure at least one host in ~/.config/raft/incus.json") + raise ValueError("Configure at least one location in ~/.config/raft/incus.json") for location, entry in inventory.items(): if not re.fullmatch(LOCATION_NAME, location): raise ValueError("Location names must use letters, digits, underscores or hyphens") - if not isinstance(entry, dict) or not isinstance(entry.get("ssh"), str) or not entry["ssh"]: - raise ValueError("Each configured location needs a nonempty ssh target") + if not isinstance(entry, dict): + raise ValueError("Each configured location must be a JSON object") + if "plugin" in entry: + raft_plugins.validate(entry) + elif not isinstance(entry.get("ssh"), str) or not entry["ssh"]: + raise ValueError( + "Each configured location needs a nonempty ssh target or plugin command" + ) if not isinstance(entry.get("note", ""), str): raise ValueError("Location notes must be strings") return inventory @@ -403,6 +410,9 @@ def receive(command, destination, *, stdin=None): def remote( location, argv, *, capture=True, stdin=subprocess.DEVNULL, stdout=None, tty=False, locked=False ): + entry = settings(location) + if "plugin" in entry: + raise ValueError(f"{location} is a plugin location; this operation requires Incus") command = ["sudo", "-n"] if locked: command += ["flock", "/run/lock/raft-incus.lock"] @@ -414,7 +424,7 @@ def remote( "BatchMode=yes", "-o", "ConnectTimeout=10", - settings(location)["ssh"], + entry["ssh"], shlex.join(command), ] if stdout is not None: @@ -644,9 +654,11 @@ def register(inventory): def parse_handle(value): location, separator, name = value.partition(":") - if not separator or not re.fullmatch(r"rf-[a-f0-9]{16}", name): + if not separator or not name or any(ord(char) < 32 or ord(char) == 127 for char in value): + raise ValueError("Use the location-qualified handle returned by new") + entry = settings(location) + if "plugin" not in entry and not re.fullmatch(r"rf-[a-f0-9]{16}", name): raise ValueError("Use the location-qualified handle returned by new") - settings(location) return location, name @@ -2024,6 +2036,17 @@ def parser(): note.add_argument("text", nargs="?", help="Location guidance, e.g. 'Preferred for builds'") note.add_argument("--clear", action="store_true", help="Remove the note") note_options(note) + plugin = commands.add_parser("plugin", help="Register trusted executable location plugins") + plugin_commands = plugin.add_subparsers(dest="plugin_action", required=True) + add_plugin = plugin_commands.add_parser("add", help="Check and register a plugin command") + add_plugin.add_argument("location") + add_plugin.add_argument("command", nargs=argparse.REMAINDER, help="-- COMMAND [ARG ...]") + for action in ["info", "remove"]: + management = plugin_commands.add_parser( + action, + help="Inspect the plugin protocol" if action == "info" else "Remove registration only", + ) + management.add_argument("location") host = commands.add_parser("host", help="Onboard workspace hosts") host_commands = host.add_subparsers(dest="host_action", required=True) onboard = host_commands.add_parser( @@ -2167,16 +2190,96 @@ def parser(): return cli +def plugin_management(args): + """Registration never installs dependencies or removes provider resources.""" + location_name(args.location) + if args.plugin_action == "add": + command = args.command[1:] if args.command[:1] == ["--"] else args.command + entry = {"plugin": command} + raft_plugins.validate(entry) + executable = shutil.which(command[0]) + if executable is None: + raise ValueError(f"Plugin executable not found: {command[0]}") + # Preserve virtualenv interpreter symlinks; resolving them drops their dependencies. + entry["plugin"] = [str(Path(executable).absolute()), *command[1:]] + + def register(inventory): + if args.location in inventory: + raise ValueError(f"Location {args.location} is already configured") + raft_plugins.describe(args.location, entry) + inventory[args.location] = entry + + edit_configuration(register) + print(f"Registered plugin location {args.location}") + return 0 + entry = settings(args.location) + if "plugin" not in entry: + raise ValueError(f"{args.location} is not a plugin location") + if args.plugin_action == "info": + raft_output.data(raft_plugins.describe(args.location, entry), indent=2) + else: + + def unregister(inventory): + if "plugin" not in inventory.get(args.location, {}): + raise ValueError(f"{args.location} is no longer a plugin location") + del inventory[args.location] + + edit_configuration(unregister) + print(f"Removed plugin registration {args.location}; provider resources were not changed") + return 0 + + +def creation_location(args): + """Choose the backend before any Incus-specific creation or CI work.""" + location = args.location + template = getattr(args, "template", None) + if template: + handle, separator, snapshot = template.partition("/") + if not separator or not snapshot: + raise ValueError("Use --from LOCATION:BOX/SNAPSHOT") + source, _ = parse_handle(handle) + if location is not None and location != source: + raise ValueError("Snapshot templates must stay on their source location") + location = source + if location is None: + location = configured_defaults().get("location") + if location is None: + location = next(iter(configuration())) + return location, settings(location) + + +def plugin_defaults(args): + """Honor explicit and configured defaults without imposing Incus image sizing.""" + configured = configured_defaults() + for key, (builtin, _) in NEW_DEFAULTS.items(): + if key == "location" or getattr(args, key, None) is not None: + continue + if args.template and key in SIZE_DEFAULTS: + continue + setattr(args, key, configured.get(key, None if key in SIZE_DEFAULTS else builtin)) + + def dispatch(args): if getattr(args, "json_output", False) and args.action in {"ssh", "forward", "desktop"}: raise ValueError("JSON mode does not support interactive shells or foreground tunnels") if args.action == "completions": print(raft_output.completions(args.shell), end="") return 0 - if args.action == "run": - return raft_run.run(args, sys.modules[__name__]) + if args.action == "plugin": + return plugin_management(args) if args.action == "self-update": return self_update(args) + if args.action in ["new", "recover"]: + location, entry = creation_location(args) + if "plugin" in entry: + box_note(args) + if args.action == "new": + plugin_defaults(args) + if entry.get("note"): + print(f"{location} note: {entry['note']}", file=sys.stderr) + return raft_plugins.run(location, entry, args) + if args.action == "run": + return raft_run.run(args, sys.modules[__name__]) if args.action == "recover": recover(args) return 0 @@ -2191,6 +2294,9 @@ def dispatch(args): report = {"file": str(DEFAULTS_CONFIG), "defaults": effective_defaults(), "policy": {}} locations = [args.location] if args.location else configuration() for location in locations: + if "plugin" in settings(location): + report["policy"][location] = None + continue try: report["policy"][location] = host_policy(location) except RuntimeError as error: @@ -2204,6 +2310,9 @@ def dispatch(args): set_default(args.key, args.value if args.config_action == "set" else None) return 0 if args.action == "policy": + entry = settings(args.location) + if "plugin" in entry: + return raft_plugins.run(args.location, entry, args) change_policy(args) return 0 if args.action == "note": @@ -2221,6 +2330,9 @@ def dispatch(args): if args.clear == (fields is not None): raise ValueError("Give --purpose (with optional --owner and --next) or --clear") location, name = parse_handle(args.target) + entry = settings(location) + if "plugin" in entry: + return raft_plugins.run(location, entry, args) instance(location, name) require_note( location, @@ -2251,6 +2363,12 @@ def dispatch(args): if getattr(args, "location", None): locations = [args.location] for location in locations: + entry = settings(location) + if "plugin" in entry: + result = raft_plugins.run(location, entry, args) + if result: + return result + continue if args.action == "capacity": report = host_capacity(location) if args.json or args.json_output: @@ -2311,6 +2429,9 @@ def dispatch(args): return 0 if args.action in {"logs", "status", "cancel"}: location, name = parse_handle(args.box) + entry = settings(location) + if "plugin" in entry: + return raft_plugins.run(location, entry, args) if not re.fullmatch(r"rfcmd-[a-f0-9]{32}", args.job): raise ValueError("Use the job ID returned by exec --detach") command = shlex.join( @@ -2350,6 +2471,9 @@ def dispatch(args): # Only fork accepts note flags here; check them before contacting the host. fields = box_note(args) location, name = parse_handle(args.box) + entry = settings(location) + if "plugin" in entry: + return raft_plugins.run(location, entry, args) box = instance(location, name) if args.action == "info": raft_output.data(box, indent=2) diff --git a/raft_plugins.py b/raft_plugins.py new file mode 100644 index 0000000..71deaa7 --- /dev/null +++ b/raft_plugins.py @@ -0,0 +1,102 @@ +"""Versioned executable location plugins. No provider dependencies live in Raft.""" + +import json +import os +import signal +import subprocess + +PROTOCOL = 1 +COMMANDS = frozenset( + "new run recover list capacity doctor gc prune policy note info stop resume extend destroy ssh exec " + "upload download snapshot snapshots snapshot-delete restore fork forward desktop logs " + "status cancel backup usage sync".split() +) + + +def validate(entry): + """Validate the controller boundary before launching any plugin code.""" + command = entry["plugin"] + if ( + not isinstance(command, list) + or not command + or any(not isinstance(part, str) or not part or "\0" in part for part in command) + ): + raise ValueError("Plugin command must be a nonempty array of nonempty strings") + if "ssh" in entry: + raise ValueError("A location cannot configure both ssh and plugin") + if not isinstance(entry.get("options", {}), dict): + raise ValueError("Plugin options must be a JSON object") + + +def environment(location, entry, arguments): + return { + **os.environ, + "RAFT_PLUGIN_REQUEST": json.dumps( + { + "protocol": PROTOCOL, + "location": location, + "options": entry.get("options", {}), + "args": arguments, + } + ), + } + + +def describe(location, entry): + """Negotiate afresh so upgrades cannot run stale, unsupported commands.""" + with subprocess.Popen( + [*entry["plugin"], "describe"], + env=environment(location, entry, {}), + stdin=subprocess.DEVNULL, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + start_new_session=True, + ) as process: + try: + output, errors = process.communicate(timeout=10) + except BaseException as error: + # A helper inheriting the pipes must not outlive a timed-out handshake. + try: + os.killpg(process.pid, signal.SIGKILL) + except ProcessLookupError: + pass + process.communicate() + if isinstance(error, subprocess.TimeoutExpired): + raise RuntimeError( + f"Plugin {location} describe timed out after 10 seconds" + ) from None + raise + if process.returncode: + raise RuntimeError(f"Plugin {location} describe failed: {errors.strip()}") + try: + manifest = json.loads(output) + except ValueError as error: + raise ValueError(f"Plugin {location} describe must return one JSON object") from error + if ( + not isinstance(manifest, dict) + or type(manifest.get("protocol")) is not int + or manifest["protocol"] != PROTOCOL + ): + raise ValueError(f"Plugin {location} must implement protocol {PROTOCOL}") + commands = manifest.get("commands") + if ( + not isinstance(commands, list) + or not commands + or any(not isinstance(action, str) or action not in COMMANDS for action in commands) + or len(set(commands)) != len(commands) + ): + raise ValueError(f"Plugin {location} commands must be a nonempty list of Raft actions") + return manifest + + +def run(location, entry, args): + manifest = describe(location, entry) + if args.action not in manifest["commands"]: + raise ValueError(f"Plugin {location} does not support {args.action}") + result = subprocess.run( + [*entry["plugin"], args.action], + env=environment(location, entry, {**vars(args), "location": location}), + check=False, + ) + return result.returncode if result.returncode >= 0 else 128 - result.returncode diff --git a/raft_run.py b/raft_run.py index 4efc07d..c2b5d2f 100644 --- a/raft_run.py +++ b/raft_run.py @@ -245,6 +245,10 @@ def issue(error): signal.signal(number, stop) signal.setitimer(signal.ITIMER_REAL, args.timeout) try: + # A plugin owns its run lifecycle; never send it through Incus creation/cleanup. + location, entry = api.creation_location(args) + if "plugin" in entry: + return api.raft_plugins.run(location, entry, args) include = git_files(source) if args.push else None api.new(args, run_id=token, on_allocate=record) creation_acknowledged = True diff --git a/skills/raft-cli/SKILL.md b/skills/raft-cli/SKILL.md index fa0b8cb..e0f836d 100644 --- a/skills/raft-cli/SKILL.md +++ b/skills/raft-cli/SKILL.md @@ -65,9 +65,8 @@ supply the changing feature set, sizes, limits and software inventory. ## Preserve the boundaries -Raft workspaces are native-architecture containers sharing the host kernel. -Do not promise VM isolation or cross-architecture execution. Inspect the actual -runtime before claiming any isolation or resource limit. +Incus boxes share the host kernel. For plugin locations, read `raft plugin info` +and that plugin's guarantees; Incus lifecycle and isolation rules do not apply. Host onboarding, deployment, upgrades and global cleanup affect more than a single workspace. Perform them only within explicit authorization; inspect a diff --git a/website/scripts/verify-site.mjs b/website/scripts/verify-site.mjs index 6ec31f3..249d550 100644 --- a/website/scripts/verify-site.mjs +++ b/website/scripts/verify-site.mjs @@ -47,6 +47,7 @@ try { '/docs/guides/scripting-ci', '/docs/guides/ci-jobs', '/docs/guides/config-policy', + '/docs/guides/plugins', '/docs/guides/desktop-services', '/docs/guides/snapshots-forks', '/docs/guides/backup-recovery', From 9a2a7c96183cf4cc646f24987b018e55a704a802 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 22:43:57 +0000 Subject: [PATCH 02/14] fix: preserve default-location recovery diagnostics --- raft.py | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/raft.py b/raft.py index c5551d5..6dd9502 100755 --- a/raft.py +++ b/raft.py @@ -1600,6 +1600,19 @@ def configured_defaults(unchecked=None): } +def default_location(configured): + """Resolve the configured default with the same recovery advice for every backend.""" + if "location" not in configured: + return next(iter(configuration())) + if configured["location"] in configuration(): + return configured["location"] + raise ValueError( + f"{DEFAULTS_CONFIG}: defaults.location names unknown location " + f"{configured['location']}; run raft config set location NAME or " + "raft config unset location" + ) + + def apply_new_defaults(args): """Fill omitted new options: explicit flag, then config.json, then the built-in default. @@ -1627,17 +1640,9 @@ def apply_new_defaults(args): args.disk = None # A --from template fixes the location, so only plain creation takes a default. if args.location is None and not args.template: - if "location" not in configured: - args.location = next(iter(configuration())) - elif configured["location"] in configuration(): - args.location = configured["location"] + args.location = default_location(configured) + if "location" in configured: used.add("location") - else: - raise ValueError( - f"{DEFAULTS_CONFIG}: defaults.location names unknown location " - f"{configured['location']}; run raft config set location NAME or " - "raft config unset location" - ) return used @@ -2242,9 +2247,7 @@ def creation_location(args): raise ValueError("Snapshot templates must stay on their source location") location = source if location is None: - location = configured_defaults().get("location") - if location is None: - location = next(iter(configuration())) + location = default_location(configured_defaults()) return location, settings(location) From c4d4bf6b4a15b0fdfdf18c94740999098285a772 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 22:46:11 +0000 Subject: [PATCH 03/14] test: include plugin runtime in self-update fixtures --- deploy/verify-self-update.py | 1 + 1 file changed, 1 insertion(+) diff --git a/deploy/verify-self-update.py b/deploy/verify-self-update.py index fba85bd..27b45a6 100644 --- a/deploy/verify-self-update.py +++ b/deploy/verify-self-update.py @@ -95,6 +95,7 @@ def next_release(work): "raft_run.py", "raft_jobs.py", "raft_output.py", + "raft_plugins.py", "pyproject.toml", "README.md", "LICENSE", From 7ffbfa0386ba5d2cdb3851623156fe88729a0d6d Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 22:48:03 +0000 Subject: [PATCH 04/14] ci: select the SDK example pinned pnpm from its directory --- .github/workflows/check.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 84b76ae..2f3f0ad 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -36,9 +36,10 @@ jobs: - run: uv run python deploy/verify-plugins.py - name: Exercise optional sandbox-sdk plugin if: matrix.python == '3.14' + working-directory: examples/sandbox-sdk run: | corepack enable - pnpm --dir examples/sandbox-sdk install --frozen-lockfile - pnpm --dir examples/sandbox-sdk smoke + pnpm install --frozen-lockfile + pnpm smoke - run: uv build - run: uv run python deploy/verify-release.py From 3d6d68009b75bdae9c824efc4ab29aa2123fc6a0 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 22:50:51 +0000 Subject: [PATCH 05/14] fix: preserve plugin cancellation cleanup and run defaults --- docs/guides/plugins.mdx | 7 +++++-- examples/sandbox-sdk/adapter.mjs | 3 ++- raft_plugins.py | 22 ++++++++++++++++++---- raft_run.py | 1 + 4 files changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/guides/plugins.mdx b/docs/guides/plugins.mdx index da9a001..6971125 100644 --- a/docs/guides/plugins.mdx +++ b/docs/guides/plugins.mdx @@ -115,8 +115,11 @@ to keep handles on one line. `--from` must stay within its source location. Normal actions inherit stdin, stdout and stderr. Preserve literal `exec` arguments and return the guest exit code. Use stdout for the command result and stderr for diagnostics. A signal exit becomes `128 + signal`; interruption returns 130. -There is no action deadline imposed by Raft, so plugins must bound their own -network operations and handle cancellation. +Plugins must bound their own network operations. `run` retains its controller +deadline. On controller cancellation, Raft sends SIGTERM to the plugin's isolated +process group and allows six seconds for remote cleanup before SIGKILL. Other +actions have no controller deadline. Configured sizing defaults apply to `run` +as well as `new`; snapshot sources retain their sizing unless explicitly overridden. Output follows the existing command contract: `new`, `fork` and `recover` print one qualified handle; `list` prints JSONL with `box`, `state`, `stopAt`, diff --git a/examples/sandbox-sdk/adapter.mjs b/examples/sandbox-sdk/adapter.mjs index 1825396..05cae3c 100644 --- a/examples/sandbox-sdk/adapter.mjs +++ b/examples/sandbox-sdk/adapter.mjs @@ -202,6 +202,7 @@ async function main() { process.stderr.write(`${message}; remote outcome may be uncertain. Inspect before retrying.\n`); controller.abort(new Error(message)); forced = setTimeout(() => process.exit(code), 5000); + forced.unref(); }; const interrupt = () => cancel(130, 'Interrupted'); const terminate = () => cancel(143, 'Terminated'); @@ -212,7 +213,7 @@ async function main() { return await dispatch({ action, request, signal: controller.signal, timeoutMs }); } finally { clearTimeout(deadline); - clearTimeout(forced); + if (cancelledCode === undefined) clearTimeout(forced); process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); if (cancelledCode !== undefined) process.exitCode = cancelledCode; diff --git a/raft_plugins.py b/raft_plugins.py index 71deaa7..98590b6 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -94,9 +94,23 @@ def run(location, entry, args): manifest = describe(location, entry) if args.action not in manifest["commands"]: raise ValueError(f"Plugin {location} does not support {args.action}") - result = subprocess.run( + with subprocess.Popen( [*entry["plugin"], args.action], env=environment(location, entry, {**vars(args), "location": location}), - check=False, - ) - return result.returncode if result.returncode >= 0 else 128 - result.returncode + start_new_session=True, + ) as process: + try: + returncode = process.wait() + except BaseException: + # Give the isolated plugin group time to cancel remote work before escalation. + try: + os.killpg(process.pid, signal.SIGTERM) + except ProcessLookupError: + pass + try: + process.wait(timeout=6) + except subprocess.TimeoutExpired: + os.killpg(process.pid, signal.SIGKILL) + process.wait() + raise + return returncode if returncode >= 0 else 128 - returncode diff --git a/raft_run.py b/raft_run.py index c2b5d2f..6fbbccb 100644 --- a/raft_run.py +++ b/raft_run.py @@ -248,6 +248,7 @@ def issue(error): # A plugin owns its run lifecycle; never send it through Incus creation/cleanup. location, entry = api.creation_location(args) if "plugin" in entry: + api.plugin_defaults(args) return api.raft_plugins.run(location, entry, args) include = git_files(source) if args.push else None api.new(args, run_id=token, on_allocate=record) From 4a9524aac1f6a4220830353751243e07785562e2 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:07:26 +0000 Subject: [PATCH 06/14] fix: keep plugin cancellation bounded across repeated interrupts --- deploy/verify-plugins.py | 46 ++++++++++++++++++++++++++++++++++++++++ raft_plugins.py | 25 +++++++++++++++------- 2 files changed, 63 insertions(+), 8 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index dc13557..edbfe09 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -403,6 +403,51 @@ def verify_rejections(directory): print("rejections: invalid protocol/JSON/capabilities and malformed or mixed location config") +def verify_repeated_cancellation(directory): + """Only this disposable plugin group receives lifecycle signals.""" + marker = directory / "termination-ready" + script = directory / "stubborn-plugin.py" + script.write_text( + "import json,sys,signal,time,pathlib\n" + "if sys.argv[-1]=='describe':\n" + " print(json.dumps({'protocol':1,'commands':['run']}));sys.exit()\n" + "def terminate(*_): pathlib.Path(sys.argv[1]).write_text('ready')\n" + "signal.signal(signal.SIGTERM,terminate)\n" + "while True: time.sleep(1)\n" + ) + home = directory / "cancel-home" + config = home / ".config/raft" + config.mkdir(parents=True) + (config / "incus.json").write_text( + json.dumps({"cancel": {"plugin": [sys.executable, str(script), str(marker)]}}) + ) + with subprocess.Popen( + [ + sys.executable, + str(ROOT / "raft.py"), + "run", + "--location", + "cancel", + "--timeout", + "1", + "--", + "true", + ], + env={"HOME": str(home), "RAFT_NO_UPDATE_CHECK": "1"}, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) as process: + deadline = time.monotonic() + 5 + while not marker.exists() and time.monotonic() < deadline: + time.sleep(0.01) + assert marker.exists(), "plugin did not receive cancellation" + process.send_signal(signal.SIGINT) + process.send_signal(signal.SIGTERM) + stdout, stderr = process.communicate(timeout=10) + assert process.returncode == 124, (process.returncode, stdout, stderr) + print("cancellation: repeated interrupts preserve bounded plugin escalation") + + def main(): with tempfile.TemporaryDirectory(prefix="raft-plugin-verification-") as temporary: directory = Path(temporary) @@ -410,6 +455,7 @@ def main(): verify_registration(controller) verify_lifecycle(controller) verify_rejections(directory) + verify_repeated_cancellation(directory) print("Executable plugin verification passed; no live hosts or operator state used") diff --git a/raft_plugins.py b/raft_plugins.py index 98590b6..248aefc 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -102,15 +102,24 @@ def run(location, entry, args): try: returncode = process.wait() except BaseException: - # Give the isolated plugin group time to cancel remote work before escalation. + # Repeated cancellation must not interrupt the bounded cleanup window. + signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) + previous = {number: signal.signal(number, signal.SIG_IGN) for number in signals} try: - os.killpg(process.pid, signal.SIGTERM) - except ProcessLookupError: - pass - try: - process.wait(timeout=6) + try: + os.killpg(process.pid, signal.SIGTERM) + except ProcessLookupError: + pass + try: + process.wait(timeout=6) + finally: + if process.poll() is None: + os.killpg(process.pid, signal.SIGKILL) + process.wait() except subprocess.TimeoutExpired: - os.killpg(process.pid, signal.SIGKILL) - process.wait() + pass + finally: + for number, handler in previous.items(): + signal.signal(number, handler) raise return returncode if returncode >= 0 else 128 - returncode From 2f4e3798950aee194bd0a7dc90380c0276707937 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:11:21 +0000 Subject: [PATCH 07/14] fix: block repeated cancellation before unwinding into cleanup --- deploy/verify-plugins.py | 15 +++++++++++++++ raft_run.py | 7 ++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index edbfe09..8c6001c 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -421,9 +421,24 @@ def verify_repeated_cancellation(directory): (config / "incus.json").write_text( json.dumps({"cancel": {"plugin": [sys.executable, str(script), str(marker)]}}) ) + # Trace schedules a real signal at the transition without replacing handlers. + launcher = ( + "import os,signal,sys,runpy\n" + "def trace(frame,event,arg):\n" + " if event=='line' and frame.f_code.co_filename.endswith('raft_plugins.py') " + "and frame.f_code.co_name=='run' and 'signals' in frame.f_locals " + "and 'previous' not in frame.f_locals:\n" + " sys.settrace(None);os.kill(os.getpid(),signal.SIGINT)\n" + " return trace\n" + "sys.settrace(trace);sys.argv=sys.argv[1:];" + "sys.path.insert(0,os.path.dirname(sys.argv[0]));" + "runpy.run_path(sys.argv[0],run_name='__main__')\n" + ) with subprocess.Popen( [ sys.executable, + "-c", + launcher, str(ROOT / "raft.py"), "run", "--location", diff --git a/raft_run.py b/raft_run.py index 6fbbccb..41609b6 100644 --- a/raft_run.py +++ b/raft_run.py @@ -220,11 +220,14 @@ def run(args, api): began = time.monotonic() signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) previous = {number: signal.getsignal(number) for number in signals} + previous_mask = signal.pthread_sigmask(signal.SIG_BLOCK, set()) old_timer = signal.getitimer(signal.ITIMER_REAL) if old_timer[0]: raise RuntimeError("run cannot replace an existing process alarm") def stop(number, _frame): + # Block atomically before raising: cleanup has not installed its handlers yet. + signal.pthread_sigmask(signal.SIG_BLOCK, signals) if number == signal.SIGALRM: raise Stopped(124, f"{phase} deadline exceeded") raise Stopped(128 + number, f"interrupted by signal {number}") @@ -278,9 +281,10 @@ def issue(error): issue(error) finally: signal.setitimer(signal.ITIMER_REAL, 0) - # A repeated cancellation cannot interrupt the bounded cleanup grace. + # Discard repeated interrupts before restoring delivery for cleanup deadlines. signal.signal(signal.SIGINT, signal.SIG_IGN) signal.signal(signal.SIGTERM, signal.SIG_IGN) + signal.pthread_sigmask(signal.SIG_SETMASK, previous_mask) if allocated is not None: location, name = allocated try: @@ -330,6 +334,7 @@ def issue(error): for number, handler in previous.items(): signal.signal(number, handler) signal.setitimer(signal.ITIMER_REAL, *old_timer) + signal.pthread_sigmask(signal.SIG_SETMASK, previous_mask) print( f"raft run: finished in {time.monotonic() - began:.1f}s (status {status})", file=sys.stderr ) From dee3d9025037fe9025d938ba181d4a4b1ef88590 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:16:07 +0000 Subject: [PATCH 08/14] fix: preserve independent native cleanup alarms after plugin cancellation --- deploy/verify-plugins.py | 9 ++++++++- deploy/verify-run.py | 13 +++++++++++++ raft_run.py | 10 ++++++++-- 3 files changed, 29 insertions(+), 3 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index 8c6001c..b41c978 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -413,6 +413,7 @@ def verify_repeated_cancellation(directory): " print(json.dumps({'protocol':1,'commands':['run']}));sys.exit()\n" "def terminate(*_): pathlib.Path(sys.argv[1]).write_text('ready')\n" "signal.signal(signal.SIGTERM,terminate)\n" + "pathlib.Path(sys.argv[1]+'.started').write_text('started')\n" "while True: time.sleep(1)\n" ) home = directory / "cancel-home" @@ -452,6 +453,12 @@ def verify_repeated_cancellation(directory): stdout=subprocess.PIPE, stderr=subprocess.PIPE, ) as process: + started = Path(str(marker) + ".started") + deadline = time.monotonic() + 5 + while not started.exists() and time.monotonic() < deadline: + time.sleep(0.01) + assert started.exists(), "plugin did not start" + process.send_signal(signal.SIGINT) deadline = time.monotonic() + 5 while not marker.exists() and time.monotonic() < deadline: time.sleep(0.01) @@ -459,7 +466,7 @@ def verify_repeated_cancellation(directory): process.send_signal(signal.SIGINT) process.send_signal(signal.SIGTERM) stdout, stderr = process.communicate(timeout=10) - assert process.returncode == 124, (process.returncode, stdout, stderr) + assert process.returncode == 130, (process.returncode, stdout, stderr) print("cancellation: repeated interrupts preserve bounded plugin escalation") diff --git a/deploy/verify-run.py b/deploy/verify-run.py index 874618e..1b40ee5 100644 --- a/deploy/verify-run.py +++ b/deploy/verify-run.py @@ -169,6 +169,19 @@ def test_artifacts_and_error_precedence(self): if failure == "first-pull": self.assertIn("download:/second", api.events) + def test_collection_timeout_then_cleanup_timeout(self): + class StalledCollectionAndCleanup(Transport): + def wait(self, phase): + if phase in {"download", "cleanup"}: + time.sleep(2) + + with tempfile.TemporaryDirectory() as directory: + transport = StalledCollectionAndCleanup() + began = time.monotonic() + self.assertEqual(self.invoke(transport, "--pull", "/first", directory + "/one"), 1) + self.assertEqual(transport.events[-1], "cleanup") + self.assertLess(time.monotonic() - began, 1) + def test_invalid_paths_and_command_do_not_allocate(self): with tempfile.TemporaryDirectory() as directory: for extra in [ diff --git a/raft_run.py b/raft_run.py index 41609b6..dfbecc3 100644 --- a/raft_run.py +++ b/raft_run.py @@ -218,6 +218,7 @@ def run(args, api): status = 1 phase = "job" began = time.monotonic() + plugin_active = False signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) previous = {number: signal.getsignal(number) for number in signals} previous_mask = signal.pthread_sigmask(signal.SIG_BLOCK, set()) @@ -226,8 +227,9 @@ def run(args, api): raise RuntimeError("run cannot replace an existing process alarm") def stop(number, _frame): - # Block atomically before raising: cleanup has not installed its handlers yet. - signal.pthread_sigmask(signal.SIG_BLOCK, signals) + # Plugin cancellation unwinds before its cleanup handlers are installed. + if plugin_active: + signal.pthread_sigmask(signal.SIG_BLOCK, signals) if number == signal.SIGALRM: raise Stopped(124, f"{phase} deadline exceeded") raise Stopped(128 + number, f"interrupted by signal {number}") @@ -252,6 +254,7 @@ def issue(error): location, entry = api.creation_location(args) if "plugin" in entry: api.plugin_defaults(args) + plugin_active = True return api.raft_plugins.run(location, entry, args) include = git_files(source) if args.push else None api.new(args, run_id=token, on_allocate=record) @@ -284,7 +287,10 @@ def issue(error): # Discard repeated interrupts before restoring delivery for cleanup deadlines. signal.signal(signal.SIGINT, signal.SIG_IGN) signal.signal(signal.SIGTERM, signal.SIG_IGN) + # A run alarm that expired during plugin grace must not escape this handler. + signal.signal(signal.SIGALRM, signal.SIG_IGN) signal.pthread_sigmask(signal.SIG_SETMASK, previous_mask) + signal.signal(signal.SIGALRM, stop) if allocated is not None: location, name = allocated try: From cc69648a61cc25b948ad0d8713bf4d8953d24516 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:19:51 +0000 Subject: [PATCH 09/14] fix: give direct plugin actions bounded signal cleanup --- deploy/verify-plugins.py | 28 ++++++++++--------- raft_plugins.py | 58 +++++++++++++++++++++++++++------------- 2 files changed, 55 insertions(+), 31 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index b41c978..775ff1d 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -403,14 +403,14 @@ def verify_rejections(directory): print("rejections: invalid protocol/JSON/capabilities and malformed or mixed location config") -def verify_repeated_cancellation(directory): +def verify_repeated_cancellation(directory, action="run", first_signal=signal.SIGINT): """Only this disposable plugin group receives lifecycle signals.""" marker = directory / "termination-ready" script = directory / "stubborn-plugin.py" script.write_text( "import json,sys,signal,time,pathlib\n" "if sys.argv[-1]=='describe':\n" - " print(json.dumps({'protocol':1,'commands':['run']}));sys.exit()\n" + " print(json.dumps({'protocol':1,'commands':['run','exec']}));sys.exit()\n" "def terminate(*_): pathlib.Path(sys.argv[1]).write_text('ready')\n" "signal.signal(signal.SIGTERM,terminate)\n" "pathlib.Path(sys.argv[1]+'.started').write_text('started')\n" @@ -427,27 +427,25 @@ def verify_repeated_cancellation(directory): "import os,signal,sys,runpy\n" "def trace(frame,event,arg):\n" " if event=='line' and frame.f_code.co_filename.endswith('raft_plugins.py') " - "and frame.f_code.co_name=='run' and 'signals' in frame.f_locals " - "and 'previous' not in frame.f_locals:\n" + "and frame.f_code.co_name=='run' and 'error' in frame.f_locals:\n" " sys.settrace(None);os.kill(os.getpid(),signal.SIGINT)\n" " return trace\n" "sys.settrace(trace);sys.argv=sys.argv[1:];" "sys.path.insert(0,os.path.dirname(sys.argv[0]));" "runpy.run_path(sys.argv[0],run_name='__main__')\n" ) + arguments = ( + ["run", "--location", "cancel", "--timeout", "1", "--", "true"] + if action == "run" + else ["exec", "cancel:opaque", "--", "true"] + ) with subprocess.Popen( [ sys.executable, "-c", launcher, str(ROOT / "raft.py"), - "run", - "--location", - "cancel", - "--timeout", - "1", - "--", - "true", + *arguments, ], env={"HOME": str(home), "RAFT_NO_UPDATE_CHECK": "1"}, stdout=subprocess.PIPE, @@ -458,7 +456,7 @@ def verify_repeated_cancellation(directory): while not started.exists() and time.monotonic() < deadline: time.sleep(0.01) assert started.exists(), "plugin did not start" - process.send_signal(signal.SIGINT) + process.send_signal(first_signal) deadline = time.monotonic() + 5 while not marker.exists() and time.monotonic() < deadline: time.sleep(0.01) @@ -466,7 +464,7 @@ def verify_repeated_cancellation(directory): process.send_signal(signal.SIGINT) process.send_signal(signal.SIGTERM) stdout, stderr = process.communicate(timeout=10) - assert process.returncode == 130, (process.returncode, stdout, stderr) + assert process.returncode == 128 + first_signal, (process.returncode, stdout, stderr) print("cancellation: repeated interrupts preserve bounded plugin escalation") @@ -478,6 +476,10 @@ def main(): verify_lifecycle(controller) verify_rejections(directory) verify_repeated_cancellation(directory) + for number in (signal.SIGINT, signal.SIGTERM): + direct = directory / ("direct-" + str(number)) + direct.mkdir() + verify_repeated_cancellation(direct, "exec", number) print("Executable plugin verification passed; no live hosts or operator state used") diff --git a/raft_plugins.py b/raft_plugins.py index 248aefc..46b5747 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -94,32 +94,54 @@ def run(location, entry, args): manifest = describe(location, entry) if args.action not in manifest["commands"]: raise ValueError(f"Plugin {location} does not support {args.action}") - with subprocess.Popen( - [*entry["plugin"], args.action], - env=environment(location, entry, {**vars(args), "location": location}), - start_new_session=True, - ) as process: - try: - returncode = process.wait() - except BaseException: - # Repeated cancellation must not interrupt the bounded cleanup window. - signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) - previous = {number: signal.signal(number, signal.SIG_IGN) for number in signals} + + class Cancelled(BaseException): + def __init__(self, number): + self.number = number + + signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) + mask = signal.pthread_sigmask(signal.SIG_BLOCK, signals) + handlers = {number: signal.getsignal(number) for number in signals} + + def cancel(number, _frame): + signal.pthread_sigmask(signal.SIG_BLOCK, signals) + raise Cancelled(number) + + try: + # Install before unmasking, so direct CLI actions cannot die without cleanup. + for number in (signal.SIGINT, signal.SIGTERM): + if handlers[number] in (signal.SIG_DFL, signal.default_int_handler): + signal.signal(number, cancel) + signal.pthread_sigmask(signal.SIG_SETMASK, mask) + with subprocess.Popen( + [*entry["plugin"], args.action], + env=environment(location, entry, {**vars(args), "location": location}), + start_new_session=True, + restore_signals=True, + ) as process: try: + returncode = process.wait() + except BaseException as error: try: os.killpg(process.pid, signal.SIGTERM) except ProcessLookupError: pass try: process.wait(timeout=6) + except subprocess.TimeoutExpired: + pass finally: if process.poll() is None: os.killpg(process.pid, signal.SIGKILL) process.wait() - except subprocess.TimeoutExpired: - pass - finally: - for number, handler in previous.items(): - signal.signal(number, handler) - raise - return returncode if returncode >= 0 else 128 - returncode + if isinstance(error, Cancelled): + return 128 + error.number + raise + return returncode if returncode >= 0 else 128 - returncode + finally: + # Discard queued cancellation before restoring the caller's signal state. + for number in signals: + signal.signal(number, signal.SIG_IGN) + signal.pthread_sigmask(signal.SIG_SETMASK, mask) + for number, handler in handlers.items(): + signal.signal(number, handler) From ce45d338fed80a3bd81a60f4df554d786e834fc2 Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:25:28 +0000 Subject: [PATCH 10/14] fix: cover plugin child publication with cancellation cleanup --- deploy/verify-plugins.py | 17 +++++++++-- raft_plugins.py | 61 ++++++++++++++++++++++++---------------- 2 files changed, 51 insertions(+), 27 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index 775ff1d..5fdef61 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -403,7 +403,7 @@ def verify_rejections(directory): print("rejections: invalid protocol/JSON/capabilities and malformed or mixed location config") -def verify_repeated_cancellation(directory, action="run", first_signal=signal.SIGINT): +def verify_repeated_cancellation(directory, action="run", first_signal=signal.SIGINT, launch=False): """Only this disposable plugin group receives lifecycle signals.""" marker = directory / "termination-ready" script = directory / "stubborn-plugin.py" @@ -423,11 +423,16 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI json.dumps({"cancel": {"plugin": [sys.executable, str(script), str(marker)]}}) ) # Trace schedules a real signal at the transition without replacing handlers. + transition = ( + "frame.f_locals.get('process') is not None and 'pending' in frame.f_locals" + if launch + else "'error' in frame.f_locals" + ) launcher = ( "import os,signal,sys,runpy\n" "def trace(frame,event,arg):\n" " if event=='line' and frame.f_code.co_filename.endswith('raft_plugins.py') " - "and frame.f_code.co_name=='run' and 'error' in frame.f_locals:\n" + f"and frame.f_code.co_name=='run' and ({transition}):\n" " sys.settrace(None);os.kill(os.getpid(),signal.SIGINT)\n" " return trace\n" "sys.settrace(trace);sys.argv=sys.argv[1:];" @@ -451,6 +456,11 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI stdout=subprocess.PIPE, stderr=subprocess.PIPE, ) as process: + if launch: + stdout, stderr = process.communicate(timeout=10) + assert process.returncode == 130, (process.returncode, stdout, stderr) + print("cancellation: first signal immediately after launch remains bounded") + return started = Path(str(marker) + ".started") deadline = time.monotonic() + 5 while not started.exists() and time.monotonic() < deadline: @@ -480,6 +490,9 @@ def main(): direct = directory / ("direct-" + str(number)) direct.mkdir() verify_repeated_cancellation(direct, "exec", number) + launch = directory / "launch-transition" + launch.mkdir() + verify_repeated_cancellation(launch, "exec", launch=True) print("Executable plugin verification passed; no live hosts or operator state used") diff --git a/raft_plugins.py b/raft_plugins.py index 46b5747..375995e 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -102,42 +102,53 @@ def __init__(self, number): signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM) mask = signal.pthread_sigmask(signal.SIG_BLOCK, signals) handlers = {number: signal.getsignal(number) for number in signals} + process = None + pending = None def cancel(number, _frame): + nonlocal pending signal.pthread_sigmask(signal.SIG_BLOCK, signals) - raise Cancelled(number) + pending = number + # Popen must finish publishing the child handle before cancellation unwinds. + if process is not None: + raise Cancelled(number) try: - # Install before unmasking, so direct CLI actions cannot die without cleanup. - for number in (signal.SIGINT, signal.SIGTERM): - if handlers[number] in (signal.SIG_DFL, signal.default_int_handler): + for number in signals: + if handlers[number] != signal.SIG_IGN and ( + number != signal.SIGALRM or callable(handlers[number]) + ): signal.signal(number, cancel) signal.pthread_sigmask(signal.SIG_SETMASK, mask) - with subprocess.Popen( + process = subprocess.Popen( [*entry["plugin"], args.action], env=environment(location, entry, {**vars(args), "location": location}), start_new_session=True, - restore_signals=True, - ) as process: - try: - returncode = process.wait() - except BaseException as error: - try: - os.killpg(process.pid, signal.SIGTERM) - except ProcessLookupError: - pass - try: - process.wait(timeout=6) - except subprocess.TimeoutExpired: - pass - finally: - if process.poll() is None: - os.killpg(process.pid, signal.SIGKILL) - process.wait() - if isinstance(error, Cancelled): - return 128 + error.number - raise + ) + if pending is not None: + raise Cancelled(pending) + returncode = process.wait() return returncode if returncode >= 0 else 128 - returncode + except BaseException as error: + if process is not None: + try: + os.killpg(process.pid, signal.SIGTERM) + except ProcessLookupError: + pass + try: + process.wait(timeout=6) + except subprocess.TimeoutExpired: + pass + finally: + if process.poll() is None: + os.killpg(process.pid, signal.SIGKILL) + process.wait() + if isinstance(error, Cancelled): + handler = handlers[error.number] + if callable(handler) and handler != signal.default_int_handler: + handler(error.number, None) + return 128 + error.number + raise finally: # Discard queued cancellation before restoring the caller's signal state. for number in signals: From e7c6ce705f7745414180732cb965413d08093b8c Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:30:14 +0000 Subject: [PATCH 11/14] fix: keep child signals unblocked during deferred cancellation --- deploy/verify-plugins.py | 12 ++++++++++++ raft_plugins.py | 3 ++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index 5fdef61..7a06afe 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -428,6 +428,12 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI if launch else "'error' in frame.f_locals" ) + if launch == "before": + transition = ( + "'pending' in frame.f_locals and frame.f_locals.get('process') is None " + "and 'cancel' in frame.f_locals " + "and signal.getsignal(signal.SIGTERM) is frame.f_locals['cancel']" + ) launcher = ( "import os,signal,sys,runpy\n" "def trace(frame,event,arg):\n" @@ -444,6 +450,7 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI if action == "run" else ["exec", "cancel:opaque", "--", "true"] ) + began = time.monotonic() with subprocess.Popen( [ sys.executable, @@ -459,6 +466,8 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI if launch: stdout, stderr = process.communicate(timeout=10) assert process.returncode == 130, (process.returncode, stdout, stderr) + if launch == "before": + assert time.monotonic() - began < 3, "child inherited blocked SIGTERM" print("cancellation: first signal immediately after launch remains bounded") return started = Path(str(marker) + ".started") @@ -493,6 +502,9 @@ def main(): launch = directory / "launch-transition" launch.mkdir() verify_repeated_cancellation(launch, "exec", launch=True) + before = directory / "before-launch" + before.mkdir() + verify_repeated_cancellation(before, "exec", launch="before") print("Executable plugin verification passed; no live hosts or operator state used") diff --git a/raft_plugins.py b/raft_plugins.py index 375995e..6b185e5 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -107,10 +107,10 @@ def __init__(self, number): def cancel(number, _frame): nonlocal pending - signal.pthread_sigmask(signal.SIG_BLOCK, signals) pending = number # Popen must finish publishing the child handle before cancellation unwinds. if process is not None: + signal.pthread_sigmask(signal.SIG_BLOCK, signals) raise Cancelled(number) try: @@ -126,6 +126,7 @@ def cancel(number, _frame): start_new_session=True, ) if pending is not None: + signal.pthread_sigmask(signal.SIG_BLOCK, signals) raise Cancelled(pending) returncode = process.wait() return returncode if returncode >= 0 else 128 - returncode From 6a88958fe2df00118490357913b0d97d84a9223d Mon Sep 17 00:00:00 2001 From: Microck Date: Fri, 13 Nov 2026 23:33:57 +0000 Subject: [PATCH 12/14] release: prepare v0.9.0 user plugins --- docs/releases/0.9.0.md | 47 +++++++++++++++++++++++++++++++++ docs/releases/meta.json | 1 + package.json | 2 +- raft.py | 2 +- website/scripts/verify-site.mjs | 1 + 5 files changed, 51 insertions(+), 2 deletions(-) create mode 100644 docs/releases/0.9.0.md diff --git a/docs/releases/0.9.0.md b/docs/releases/0.9.0.md new file mode 100644 index 0000000..77c479c --- /dev/null +++ b/docs/releases/0.9.0.md @@ -0,0 +1,47 @@ +--- +title: Raft 0.9.0 +description: Bring your own sandbox backend with executable location plugins. +--- + +# Raft 0.9.0 + +## User-installed sandbox plugins + +Register a trusted executable as a location without changing Raft or installing +provider dependencies into its Python environment: + +```sh +raft plugin add cloud -- node /absolute/path/to/plugin.mjs +raft plugin info cloud +raft new --location cloud --disposable +``` + +Existing commands route by location. Plugins declare the commands they support +through a versioned handshake; unsupported commands fail before the action runs. +`raft plugin remove cloud` removes only the registration, not remote resources. +Registered Python virtualenv interpreters retain their dependencies. + +The repository includes a runnable sandbox-sdk adapter for creating, inspecting +and deleting sandboxes, executing commands, and transferring single files. A +provider factory selects any compatible SDK provider. See +[user plugins](../guides/plugins.mdx) for installation, the protocol and trust +boundaries. + +## Cancellation and provider guarantees + +Plugin actions get a bounded cleanup window on cancellation. Repeated signals, +launch-time cancellation and expired run alarms cannot bypass that cleanup. +Configured sizing defaults apply to plugin-backed `run` as well as `new`. + +Plugins run with the controller user's privileges. They own their provider's +expiry, persistence, networking and isolation guarantees; Incus guarantees do not +transfer to other backends. The sandbox-sdk example requires disposable creation +and documents provider-specific TTL limits. Explicitly destroy resources when +done. + +## Upgrade + +Update the CLI through your existing installation channel. Incus locations keep +their behavior. Plugins are opt-in and have no effect until registered. Install +plugin dependencies separately; updating Raft does not update plugins or live +hosts. diff --git a/docs/releases/meta.json b/docs/releases/meta.json index fa64a99..094415c 100644 --- a/docs/releases/meta.json +++ b/docs/releases/meta.json @@ -4,6 +4,7 @@ "defaultOpen": false, "pages": [ "index", + "0.9.0", "0.8.0", "0.7.1", "0.7.0", diff --git a/package.json b/package.json index 05d793c..36a57e1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@microck/raft", - "version": "0.8.0", + "version": "0.9.0", "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev", "license": "MIT", "repository": { diff --git a/raft.py b/raft.py index 6dd9502..b2b8eac 100755 --- a/raft.py +++ b/raft.py @@ -29,7 +29,7 @@ import raft_output import raft_plugins -__version__ = "0.8.0" +__version__ = "0.9.0" CONFIG = Path.home() / ".config/raft/incus.json" # Controller defaults for new live apart from the location inventory, so location diff --git a/website/scripts/verify-site.mjs b/website/scripts/verify-site.mjs index 249d550..bef3792 100644 --- a/website/scripts/verify-site.mjs +++ b/website/scripts/verify-site.mjs @@ -72,6 +72,7 @@ try { '/docs/releases/0.7.0', '/docs/releases/0.7.1', '/docs/releases/0.8.0', + '/docs/releases/0.9.0', ]; const targets = new Set(); const fragments = new Map(); From 7821408fd9443205e6cee62da1c74aa2107a7ea5 Mon Sep 17 00:00:00 2001 From: Microck Date: Sat, 14 Nov 2026 00:06:49 +0000 Subject: [PATCH 13/14] fix: clean up plugin helpers after leader exit --- deploy/verify-plugins.py | 61 ++++++++++++++++++++++++++++++++++------ docs/guides/plugins.mdx | 3 +- raft_plugins.py | 20 +++++++++---- 3 files changed, 68 insertions(+), 16 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index 7a06afe..b21cf93 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -6,6 +6,7 @@ import json import base64 +import os from pathlib import Path import re import signal @@ -403,17 +404,29 @@ def verify_rejections(directory): print("rejections: invalid protocol/JSON/capabilities and malformed or mixed location config") -def verify_repeated_cancellation(directory, action="run", first_signal=signal.SIGINT, launch=False): +def verify_repeated_cancellation( + directory, action="run", first_signal=signal.SIGINT, launch=False, helper=False +): """Only this disposable plugin group receives lifecycle signals.""" marker = directory / "termination-ready" script = directory / "stubborn-plugin.py" script.write_text( - "import json,sys,signal,time,pathlib\n" + "import json,sys,signal,time,pathlib,os,subprocess\n" "if sys.argv[-1]=='describe':\n" " print(json.dumps({'protocol':1,'commands':['run','exec']}));sys.exit()\n" - "def terminate(*_): pathlib.Path(sys.argv[1]).write_text('ready')\n" - "signal.signal(signal.SIGTERM,terminate)\n" - "pathlib.Path(sys.argv[1]+'.started').write_text('started')\n" + + ( + "if os.fork()==0:\n" + " signal.signal(signal.SIGTERM,signal.SIG_IGN)\n" + " pathlib.Path(sys.argv[1]+'.helper').write_text(str(os.getpid()))\n" + " while True: time.sleep(1)\n" + if helper + else "" + ) + + "def terminate(*_):\n" + " pathlib.Path(sys.argv[1]).write_text('ready')\n" + + (" sys.exit(0)\n" if helper else "") + + "signal.signal(signal.SIGTERM,terminate)\n" + "pathlib.Path(sys.argv[1]+'.started').write_text(str(os.getpid()))\n" "while True: time.sleep(1)\n" ) home = directory / "cancel-home" @@ -451,7 +464,7 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI else ["exec", "cancel:opaque", "--", "true"] ) began = time.monotonic() - with subprocess.Popen( + process = subprocess.Popen( [ sys.executable, "-c", @@ -462,7 +475,8 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI env={"HOME": str(home), "RAFT_NO_UPDATE_CHECK": "1"}, stdout=subprocess.PIPE, stderr=subprocess.PIPE, - ) as process: + ) + try: if launch: stdout, stderr = process.communicate(timeout=10) assert process.returncode == 130, (process.returncode, stdout, stderr) @@ -475,15 +489,41 @@ def verify_repeated_cancellation(directory, action="run", first_signal=signal.SI while not started.exists() and time.monotonic() < deadline: time.sleep(0.01) assert started.exists(), "plugin did not start" + helper_marker = Path(str(marker) + ".helper") + if helper: + while not helper_marker.exists() and time.monotonic() < deadline: + time.sleep(0.01) + assert helper_marker.exists(), "plugin helper did not start" + helper_status = Path(f"/proc/{int(helper_marker.read_text())}/stat") process.send_signal(first_signal) deadline = time.monotonic() + 5 while not marker.exists() and time.monotonic() < deadline: time.sleep(0.01) assert marker.exists(), "plugin did not receive cancellation" - process.send_signal(signal.SIGINT) - process.send_signal(signal.SIGTERM) + if not helper: + process.send_signal(signal.SIGINT) + process.send_signal(signal.SIGTERM) stdout, stderr = process.communicate(timeout=10) assert process.returncode == 128 + first_signal, (process.returncode, stdout, stderr) + if helper: + deadline = time.monotonic() + 1 + while helper_status.exists(): + if helper_status.read_text().split(") ", 1)[1].startswith("Z "): + break + assert time.monotonic() < deadline, "plugin helper survived cancellation" + time.sleep(0.01) + finally: + # Only fixture-owned PIDs, never operator sessions or configured hosts. + for suffix in (".started", ".helper"): + pidfile = Path(str(marker) + suffix) + if pidfile.exists(): + try: + os.kill(int(pidfile.read_text()), signal.SIGKILL) + except ProcessLookupError: + pass + if process.poll() is None: + process.kill() + process.communicate(timeout=3) print("cancellation: repeated interrupts preserve bounded plugin escalation") @@ -505,6 +545,9 @@ def main(): before = directory / "before-launch" before.mkdir() verify_repeated_cancellation(before, "exec", launch="before") + helpers = directory / "surviving-helper" + helpers.mkdir() + verify_repeated_cancellation(helpers, "exec", helper=True) print("Executable plugin verification passed; no live hosts or operator state used") diff --git a/docs/guides/plugins.mdx b/docs/guides/plugins.mdx index 6971125..6bc00d3 100644 --- a/docs/guides/plugins.mdx +++ b/docs/guides/plugins.mdx @@ -117,7 +117,8 @@ and return the guest exit code. Use stdout for the command result and stderr for diagnostics. A signal exit becomes `128 + signal`; interruption returns 130. Plugins must bound their own network operations. `run` retains its controller deadline. On controller cancellation, Raft sends SIGTERM to the plugin's isolated -process group and allows six seconds for remote cleanup before SIGKILL. Other +process group and allows six seconds for remote cleanup before SIGKILL. Once the +plugin leader exits, remaining helpers are killed immediately. Other actions have no controller deadline. Configured sizing defaults apply to `run` as well as `new`; snapshot sources retain their sizing unless explicitly overridden. diff --git a/raft_plugins.py b/raft_plugins.py index 6b185e5..8919f75 100644 --- a/raft_plugins.py +++ b/raft_plugins.py @@ -4,6 +4,7 @@ import os import signal import subprocess +import time PROTOCOL = 1 COMMANDS = frozenset( @@ -128,6 +129,8 @@ def cancel(number, _frame): if pending is not None: signal.pthread_sigmask(signal.SIG_BLOCK, signals) raise Cancelled(pending) + os.waitid(os.P_PID, process.pid, os.WEXITED | os.WNOWAIT) + signal.pthread_sigmask(signal.SIG_BLOCK, signals) returncode = process.wait() return returncode if returncode >= 0 else 128 - returncode except BaseException as error: @@ -136,14 +139,19 @@ def cancel(number, _frame): os.killpg(process.pid, signal.SIGTERM) except ProcessLookupError: pass + # Keep the leader unreaped so its PID cannot be reused as another + # process group's ID before the final group signal. Leader exit + # means plugin cleanup is done; remaining helpers must not escape. + deadline = time.monotonic() + 6 + while time.monotonic() < deadline: + if os.waitid(os.P_PID, process.pid, os.WEXITED | os.WNOHANG | os.WNOWAIT): + break + time.sleep(0.01) try: - process.wait(timeout=6) - except subprocess.TimeoutExpired: + os.killpg(process.pid, signal.SIGKILL) + except ProcessLookupError: pass - finally: - if process.poll() is None: - os.killpg(process.pid, signal.SIGKILL) - process.wait() + process.wait() if isinstance(error, Cancelled): handler = handlers[error.number] if callable(handler) and handler != signal.default_int_handler: From ed8f4f99c69c2566e868b76fa4d6cd0d4d0cb76f Mon Sep 17 00:00:00 2001 From: Microck Date: Sat, 14 Nov 2026 00:22:06 +0000 Subject: [PATCH 14/14] test: remove plugin cancellation fixture races --- deploy/verify-plugins.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/deploy/verify-plugins.py b/deploy/verify-plugins.py index b21cf93..a08cbcf 100644 --- a/deploy/verify-plugins.py +++ b/deploy/verify-plugins.py @@ -417,7 +417,8 @@ def verify_repeated_cancellation( + ( "if os.fork()==0:\n" " signal.signal(signal.SIGTERM,signal.SIG_IGN)\n" - " pathlib.Path(sys.argv[1]+'.helper').write_text(str(os.getpid()))\n" + " temporary=pathlib.Path(sys.argv[1]+'.helper.tmp');temporary.write_text(str(os.getpid()))\n" + " os.replace(temporary,sys.argv[1]+'.helper')\n" " while True: time.sleep(1)\n" if helper else "" @@ -426,7 +427,8 @@ def verify_repeated_cancellation( " pathlib.Path(sys.argv[1]).write_text('ready')\n" + (" sys.exit(0)\n" if helper else "") + "signal.signal(signal.SIGTERM,terminate)\n" - "pathlib.Path(sys.argv[1]+'.started').write_text(str(os.getpid()))\n" + "temporary=pathlib.Path(sys.argv[1]+'.started.tmp');temporary.write_text(str(os.getpid()))\n" + "os.replace(temporary,sys.argv[1]+'.started')\n" "while True: time.sleep(1)\n" ) home = directory / "cancel-home" @@ -507,8 +509,11 @@ def verify_repeated_cancellation( assert process.returncode == 128 + first_signal, (process.returncode, stdout, stderr) if helper: deadline = time.monotonic() + 1 - while helper_status.exists(): - if helper_status.read_text().split(") ", 1)[1].startswith("Z "): + while True: + try: + if helper_status.read_text().split(") ", 1)[1].startswith("Z "): + break + except (FileNotFoundError, ProcessLookupError): break assert time.monotonic() < deadline, "plugin helper survived cancellation" time.sleep(0.01)