feat(guest_control): grow GuestControl with the V2b exec surface (RIG-2493) - #696
Open
rigel-mintaka wants to merge 2 commits into
Open
feat(guest_control): grow GuestControl with the V2b exec surface (RIG-2493)#696rigel-mintaka wants to merge 2 commits into
rigel-mintaka wants to merge 2 commits into
Conversation
|
Compass engineering docs preview: https://compass-runner-rig-2493-u1-g.compass-eng-docs.pages.dev Deployed from |
…-2493) U1 of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U1). Grows `proto/compass/v1/guest_control.proto` additively per §(a) with the four exec-surface RPCs and their messages, plus one additive field on the V2a `HealthResponse`, and regenerates the internal-go lane. ### What - `Exec(ExecRequest) returns (ExecResponse)` — one-shot; a non-zero exit rides `ExecResponse.exit_code`, never a Connect error (the wire mirror of `podman.go:310-313`). - `ExecStream(stream ExecStreamRequest) returns (stream ExecStreamResponse)` — bidi; direction-specific `oneof` frames (`StartExec|stdin|StdinClose` up, `ExecStarted|stdout|stderr|ExecExit` down). Named `ExecStreamRequest`/`ExecStreamResponse` rather than the parent's shared `ExecStreamFrame` sketch, forced by buf's RPC_REQUEST/RESPONSE_STANDARD_NAME (OQ-B, resolved in-record). - `Signal(SignalRequest) returns (SignalResponse)` — kill an exec by `exec_id`; empty `exec_id` targets the guest (Stop, §(d)). - `Provision(ProvisionRequest) returns (ProvisionResponse)` — the `ready -> provisioned` gate transition; carries `default_exec_uid` + `base_env` now, the `nft_script` branch is V3's. - `HealthResponse.boot_nonce` (field 4, additive) — the host-minted cmdline nonce guestd echoes so Start binds the guest to the VM it launched (§(e), OQ-A resolved). - Service-header auth paragraph rewritten to record the (e) structural-identity resolution. Additive-only (new RPCs, new messages, one new field): `buf breaking` is satisfied by construction, and the file stays on the internal-only lane (`go/internal/gen`, no TS, no public `go/gen`). ### Guard for the stacked follow-ups The generated `GuestControlHandler` interface widened to all five RPCs, so the V2a Health-only `healthService` no longer satisfies it. This commit embeds `UnimplementedGuestControlHandler` in `healthService` so the four new RPCs answer `CodeUnimplemented` and the V2a Health path is byte-unchanged; U2 replaces `healthService` with the real supervisor. ### Verification `moon run compass-proto:ci` green (gen-fence, drift, lint, breaking); `go build ./internal/gen/... ./internal/guestd/... ./internal/runtime/...` and `go vet ./internal/guestd/...` clean. Ledger-impact: none Spec-impact: none Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…2493) Address ReviewU1's two low findings on the `Exec` RPC doc-comment (proto + regenerated connect interface): - The `(0/caps)` parenthetical implied capabilities are refusable over this proto; they are not — caps are ignored-and-asserted in the guest, never surfaced as a Connect error. Narrowed to `(0)`, since a refused uid is the only wire-refusable case. - "could not be attempted" excluded the attempted-then-timed-out case. Reworded to "could not be attempted or could not complete" so a spawn failure, a refused uid, a timeout, and an unprovisioned gate all read as covered. Doc-only; the wire surface is byte-identical. `moon run compass-proto:ci` green (drift confirms generated matches source). Ledger-impact: none Spec-impact: none. Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u1-guest-control-exec-proto
branch
from
August 28, 2026 10:06
6410d64 to
1d0d884
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is part of a stack containing 5 PRs:
mainU1 of the frozen microVM Runner V2b plan (
docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, §Plan U1). Growsproto/compass/v1/guest_control.protoadditively per §(a) with the four exec-surface RPCs and their messages, plus one additive field on the V2aHealthResponse, and regenerates the internal-go lane.What
Exec(ExecRequest) returns (ExecResponse)— one-shot; a non-zero exit ridesExecResponse.exit_code, never a Connect error (the wire mirror ofpodman.go:310-313).ExecStream(stream ExecStreamRequest) returns (stream ExecStreamResponse)— bidi; direction-specificoneofframes (StartExec|stdin|StdinCloseup,ExecStarted|stdout|stderr|ExecExitdown). NamedExecStreamRequest/ExecStreamResponserather than the parent's sharedExecStreamFramesketch, forced by buf's RPC_REQUEST/RESPONSE_STANDARD_NAME (OQ-B, resolved in-record).Signal(SignalRequest) returns (SignalResponse)— kill an exec byexec_id; emptyexec_idtargets the guest (Stop, §(d)).Provision(ProvisionRequest) returns (ProvisionResponse)— theready -> provisionedgate transition; carriesdefault_exec_uid+base_envnow, thenft_scriptbranch is V3's.HealthResponse.boot_nonce(field 4, additive) — the host-minted cmdline nonce guestd echoes so Start binds the guest to the VM it launched (§(e), OQ-A resolved).Additive-only (new RPCs, new messages, one new field):
buf breakingis satisfied by construction, and the file stays on the internal-only lane (go/internal/gen, no TS, no publicgo/gen).Guard for the stacked follow-ups
The generated
GuestControlHandlerinterface widened to all five RPCs, so the V2a Health-onlyhealthServiceno longer satisfies it. This commit embedsUnimplementedGuestControlHandlerinhealthServiceso the four new RPCs answerCodeUnimplementedand the V2a Health path is byte-unchanged; U2 replaceshealthServicewith the real supervisor.Verification
moon run compass-proto:cigreen (gen-fence, drift, lint, breaking);go build ./internal/gen/... ./internal/guestd/... ./internal/runtime/...andgo vet ./internal/guestd/...clean.Ledger-impact: none
Spec-impact: none
Refs RIG-2493
Co-authored-by: Matt Wilkinson matt@rigel.build