test(runner): KVM-gated end-to-end AgentGateway-over-vsock suite (RIG-3092) - #822
Merged
mattwilkinsonn merged 2 commits intoSep 1, 2026
Merged
Conversation
|
Compass engineering docs preview: https://compass-runner-rig-3092-kvm.compass-eng-docs.pages.dev Deployed from |
…-3092) W3 of the frozen microVM Runner V4 design record (microVM AgentGateway over host-side vsock). The milestone acceptance gate: a `//go:build microvm && unix` suite driving a real agentHost over a real MicroVMRuntime on live KVM, proving W1 (guestd's in-guest unix->vsock forwarder) and W2 (the host serving the same generated handler over the per-session suffixed AF_UNIX path, probe-gated in Provision) meet over a real cloud-hypervisor hybrid-vsock channel. Test-only — no production code changes. The record's W3 test cycle, all five checks: - Host serves over the real suffixed socket (<runtimeDir>/vsock.sock_1025, 0600) and a host-side Connect client round-trips a Comms call under the bound session. - The vsock leg in-guest: an agent-uid exec runs a bun probe dialing /run/compass/agent.sock, which bridges to the host Gateway over AF_VSOCK, driving a real Comms round-trip that reaches the fake Server relay and back carrying the bound session id. - Fail-closed: a Comms call before Start binds the session is refused CodePermissionDenied over the vsock serve path, never forwarded. - vsock-is-not-IP non-goal: the vsock gateway works while a raw-IP egress attempt is blocked by the always-armed default-deny firewall — the vsock path is orthogonal to the egress seal. - Teardown symmetry: Remove closes the suffixed listener and removes the socket file. Notes for the reader: - The probe vehicle (OQ-5) is a bun one-liner: the guest rootfs ships bun as its only Connect-capable runtime (no node/curl/socat), and the gateway serves HTTP/1.1, so a unix-socket fetch POST is a valid Connect unary. - The suite overrides agentCommand to an inert in-guest keep-alive so the only traffic the fake relay sees is the test's own probe — a call count is then an exact assertion, not a race against a live agent. - The fake Server answers FetchSecrets with CodeFailedPrecondition (the no-secrets-surface posture Start tolerates by skipping the secret materialize): the guest rootfs has no writable filesystem for the agent uid, so the materialize's mkdir $HOME/.compass cannot run and is not part of the transport contract under test. - KVM ctx-lifetime discipline: Provision/Start take t.Context() (the VM lifetime), never a WithTimeout+defer-cancel ctx; per-call deadlines are separate short-lived contexts. Refs RIG-3092, RIG-2495, RIG-2394. Co-authored-by: Matt Wilkinson <matt@rigel.build>
Review round 1 (skill://review, single agent) returned a clean gating floor
(0 high, 0 medium) and 6 lows on the W3 KVM-gated gateway-over-vsock suite.
This additive commit dispositions the five mechanical/clarity lows; the sixth
(a frozen-record §W3(2)/(3) reconciliation) is a design decision parked with
Matt, not a code fix.
- Remove dead `_ = filepath.Dir(path)` in assertSocket0600 and drop the
now-unused `path/filepath` import (the no-op line was the import's sole
consumer — real dead code masking an unused import).
- Extract the in-guest /dev/tcp probe's `timeout 10` magic literal to a named
`guestConnectTimeoutSecs` const with the ordering invariant documented (guest
timeout MUST stay under the host-side inGuestProbeTimeout so a dropped SYN
fails as exit 124, not a host-ctx DeadlineExceeded read as a harness fault).
- Make the vsock-is-not-IP firewall attribution explicit: the raw-IP block is
the firewall (not dead networking) because the exec is past Start's
net_provisioned gate and the default-deny is proven by the egress suite.
- Add a defensive `t.Cleanup(Remove)` to TestVsockGateway_TeardownRemovesSuffixedSocket
so teardown runs even on an early t.Fatalf (Remove is idempotent, so the
in-body Remove + cleanup double-call is harmless), matching the other four
tests and the egress precedent.
- Document the in-guest probe script's template-literal splice invariant
(reqJSON must stay backtick/${-free; a future dynamic payload must
JSON.stringify/parse rather than embed raw JSON).
Test-only; no production code touched. Re-verified on live KVM: all 5
TestVsockGateway_* pass under -race (round-trip intact, IP egress blocked exit
124); gofmt/vet clean; golangci-lint --build-tags microvm 0 issues.
Refs RIG-3092
Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-3092-kvm-e2e-vsock-gateway
branch
from
September 1, 2026 00:36
1934f7f to
08acab5
Compare
mattwilkinsonn
approved these changes
Sep 1, 2026
mattwilkinsonn
deleted the
compass-runner/rig-3092-kvm-e2e-vsock-gateway
branch
September 1, 2026 01:29
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
2 participants
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.
W3 of the frozen microVM Runner V4 design record (microVM AgentGateway over
host-side vsock). The milestone acceptance gate: a
//go:build microvm && unixsuite driving a real agentHost over a real MicroVMRuntime on live KVM, proving
W1 (guestd's in-guest unix->vsock forwarder) and W2 (the host serving the same
generated handler over the per-session suffixed AF_UNIX path, probe-gated in
Provision) meet over a real cloud-hypervisor hybrid-vsock channel. Test-only —
no production code changes.
The record's W3 test cycle, all five checks:
and a host-side Connect client round-trips a Comms call under the bound
session.
/run/compass/agent.sock, which bridges to the host Gateway over AF_VSOCK,
driving a real Comms round-trip that reaches the fake Server relay and back
carrying the bound session id.
CodePermissionDenied over the vsock serve path, never forwarded.
attempt is blocked by the always-armed default-deny firewall — the vsock path
is orthogonal to the egress seal.
file.
Notes for the reader:
only Connect-capable runtime (no node/curl/socat), and the gateway serves
HTTP/1.1, so a unix-socket fetch POST is a valid Connect unary.
traffic the fake relay sees is the test's own probe — a call count is then an
exact assertion, not a race against a live agent.
no-secrets-surface posture Start tolerates by skipping the secret
materialize): the guest rootfs has no writable filesystem for the agent uid,
so the materialize's mkdir $HOME/.compass cannot run and is not part of the
transport contract under test.
lifetime), never a WithTimeout+defer-cancel ctx; per-call deadlines are
separate short-lived contexts.
Refs RIG-3092, RIG-2495, RIG-2394.
Co-authored-by: Matt Wilkinson matt@rigel.build