Repository navigation
Description
User Story
As an OpenShell Maintainer I want the desktop drivers to exist in their own repository so that their ownership and maintenance can be considered separately to core OpenShell. The gateway needs a generic way to start them.
Problem Statement
The only gateway-launched driver is the VM driver, through VM-specific code. Docker and Podman cannot be launched at all.
Impact / Why This Matters
A generic launcher is the mechanism that lets any driver binary, including ones that live in other repositories, run under the gateway.
Proposed Design
The launcher resolves a driver name to a binary (an explicit path in gateway configuration, then a driver directory beside the gateway binary), refuses a binary or directory not owned by the gateway's effective user or root or that is group- or world-writable, writes the startup document, spawns the process, waits for its Unix socket, and negotiates protocol over GetCapabilities. Shutdown reuses ManagedDriverProcess (SIGTERM, bounded wait, kill, socket cleanup).
Decisions needed (before implementation)
Do not implement until these are resolved. The recommendations are proposals; reviewers can override them.
- What happens when a launched driver exits after it was ready?
- Current VM behavior:
spawndetects an exit only while waiting for the socket (try_wait, "exited before becoming ready"). After that,ManagedDriverProcessis used only for shutdown. Nothing callstry_waitorwaiton the child while the gateway runs. The compute-driver watch loop logs "watch stream ended unexpectedly" and retries after 2 seconds, so the gateway appears to keep running against a dead driver. This is from code reading and has not been confirmed by running it. - Options: (a) fail fast for all launched drivers, so the gateway exits and the init system restarts it; (b) keep current behavior for VM and fail fast only for newly launched drivers; (c) restart and reconnect.
- Recommendation: (a), including VM. It is a behavior change for VM, so call it out in release notes. Restart and reconnect is a follow-up.
- Current VM behavior:
- How does the gateway trust the binary it executes?
- Current VM behavior: the VM driver path is configured explicitly.
vm.rschecks owner (euid) and mode (0700) of the state and socket directories, but not of the binary. - Options: (a) ownership and permission checks only; (b) additionally pin driver digests in the
packagesbundle manifest and verify before executing; and, separately, whether a system driver directory is searched. - Recommendation: (a) now. Defer digest pinning until
packagesproduces the manifest that would hold the digests. Search a system driver directory, since DEB, RPM, and snap installs do not place the driver beside the gateway binary. The exact paths depend on the install layout, which has not been checked.
- Current VM behavior: the VM driver path is configured explicitly.
Acceptance Criteria
- The decisions above are recorded in this issue.
- The gateway launches a driver by name from an explicit path or the driver directory, with the ownership and permission checks.
- A test refuses a binary or directory that is group- or world-writable or not owned by the gateway's effective user or root.
- If a launched driver exits after it was ready, the gateway behaves as decided; for fail-fast, a test kills the driver and checks that the gateway exits with an error naming the driver.
- Shutdown sends SIGTERM, waits a bounded time, then kills, and removes the socket.
Alternatives Considered
- Keep per-driver launch code. Works for one driver, but every new driver repeats the same checks.
- Require operators to start drivers themselves. Already possible, but it does not give a default install a working driver.
Activity