|
|
3 weeks ago | |
|---|---|---|
| .. | ||
| agent | 3 weeks ago | |
| cmd/virt-cloud-agent-gateway | 1 month ago | |
| console | 1 month ago | |
| internal/protocol | 1 month ago | |
| README.md | 4 weeks ago | |
| go.mod | 1 month ago | |
| go.sum | 1 month ago | |
README.md
Virt Cloud panel-side Agent gateway
gateway is an independent Go module containing virt-cloud-agent-gateway.
The service keeps Agent-initiated control WebSockets, accepts
authenticated dispatches from local PHP, and pairs reverse console streams
with the existing browser console URL.
It is not a compatibility layer for the retired Python engine.
Build and test
cd gateway
go test ./...
go build ./cmd/virt-cloud-agent-gateway
The executable requires an absolute --config path. The JSON decoder rejects
unknown fields and trailing values. Configuration loading deliberately does
not reject a readable configuration because of its owner, group, or mode;
missing, unreadable, malformed, or unsafe configuration still fails startup.
The Agent request deadline is deliberately fixed at 870 seconds in the Gateway configuration. The host Agent API caps operations at 840 seconds, its WSS control envelope waits 855 seconds, PHP waits up to 900 seconds, and the worker lease lasts 930 seconds. These margins let each outer layer receive and durably classify the inner layer's result instead of timing out first.
Authentication
Gateway-to-PHP requests use the shared X-Virt-* contract:
METHOD\n
escaped-path-and-query\n
lowercase-sha256-of-exact-body\n
unix-timestamp\n
nonce\n
base64url-json-actor
The signature is lowercase HMAC-SHA256. The Agent gateway signs PHP
authentication and console introspection requests with
{"service":"agent-gateway"} and accepts local PHP dispatches only with
{"service":"php-panel"}.
Agent gateway contract
The gateway listens only on 127.0.0.1:8001. The public reverse proxy exposes
GET /agent/connect, GET /agent/console, and GET /engine-console; it must
not expose POST /internal/agent/request.
An Agent opens /agent/connect with X-Virt-Agent-ID, Authorization: Bearer <per-host-secret>, and the exact virt-agent-control.v3 subprotocol. The
gateway validates those credentials through the fixed loopback PHP endpoint
/api/internal/cloud/agent-auth. It retains the presented secret only in that
live session's memory and revalidates it before every ordinary dispatch or
console open; rejection unregisters and closes the session. PHP dispatches one
signed request envelope to the loopback-only /internal/agent/request; the
gateway sends it to the live Agent and returns the Agent's exact HTTP status and
JSON body. Control frames are bounded JSON text frames:
The v3 subprotocol is a clean break that includes immutable completion frames. There is no v1 or v2 negotiation or compatibility mode: an old Agent or Gateway must fail the WebSocket handshake instead of appearing healthy while dropping a terminal receipt. Deploy the Agent and Gateway binaries from the same release.
{"type":"request","id":"...","method":"POST","request_target":"/v1/...","body":"{...}","headers":{"X-Virt-Actor":"..."}}
{"type":"response","id":"...","status":200,"body":"{...}"}
Failures proven to occur before the host's durable operation journal carry the
exact error field "dispatch_state":"not_dispatched". Mutation requests are
never automatically requeued, including when that marker is present; callers
must create a new operation explicitly. Terminal completion receipts use a
separate durable delivery outbox and an eight-event ACK-driven window. The
Gateway stops reading additional completion events while that window is full;
it never silently drops an event. It returns completion_ack only after PHP
responds with strict JSON {"accepted":true,"disposition":"applied|late|rejected"}.
received, malformed JSON, unknown fields, trailing data, a non-JSON content
type, or a delivery error produces completion_retry instead, leaving the
durable event pending for a later retry. Delivery age and attempt count never
discard a completion event: the Agent keeps retransmitting it at a bounded
rate until PHP returns an exact terminal ACK. Gateway or Agent nonce replay
errors deliberately omit the marker because the first
request may already have been dispatched.
PHP also recognizes a proven failure to connect to the fixed local Gateway: libcurl must report a failed connect or connect-phase timeout with complete zero request/transfer counters, no established connection, response or redirect, and no earlier possibly-sent transfer. Such a task terminates as not applied and its PHP ledgers settle normally; it is never requeued. A response timeout, an empty response, missing transport statistics, or an operation missing from the Agent is not this proof and remains ambiguous.
Resolving an effect fence is a separate, explicit super-administrator action:
POST /v1/operations/{operation_id}/resolve-fence records immutable Journal
audit metadata and releases only the local admission blocker. It never invokes
libvirt or replays the original mutation. GET /v1/operations/{operation_id}/fence-resolution is the read-only lost-response
check. Neither request is automatically retried by the Gateway or Agent.
For a browser console, /engine-console requires a same-origin Origin, the
trusted proxy's single X-Forwarded-Proto, and exactly one browser subprotocol:
cloud-ticket.<opaque-one-time-ticket>
Before accepting the browser WebSocket it signs this PHP introspection body:
{"ticket":"...","consume":true}
PHP must atomically consume that ticket and return:
{
"active": true,
"connection_id": "<opaque-connection-id>",
"agent_id": "<numeric-host-id>",
"agent_ticket": "<short-lived-agent-ticket>",
"agent_expires_at": "2026-10-15T12:00:00Z"
}
The gateway sends the authenticated control session a one-use console_open
message containing PHP's Agent ticket and a gateway-only session token:
{"type":"console_open","id":"...","ticket":"...","session_id":"...","session_token":"..."}
The Agent consumes the ticket locally, then connects outward to
/agent/console with its ID and the returned one-use subprotocol:
virt-agent-console.<session-token>
Only binary WebSocket messages are copied. The gateway sends a WebSocket Ping control frame every 25 seconds on both the browser and reverse-Agent legs and requires a Pong within 10 seconds; these control frames never enter the VNC byte stream. Every 15 seconds the gateway signs a second introspection request:
{"ticket":"...","connection_id":"...","consume":false}
PHP returns exactly {"active":true} while the browser session, user, VM
ownership, and service remain valid. A denial, malformed response, timeout, or
active:false immediately tears down both sides. The gateway never accepts an
Agent endpoint from the browser and never persists a host Agent secret.
PHP implements the browser-ticket and connection lifecycle in
CloudConsoleTicketService. The Agent never listens for a console connection;
it opens the short-lived reverse stream only after console_open. If any
validation or periodic session recheck fails, the gateway closes both
WebSocket sides.
Cloud-image bytes never cross the control WebSocket. PHP persists a staged object and issues a short-lived HTTPS URL plus bearer token; the control request carries only that URL, token, and optional digest, and the Agent downloads the image over HTTPS while enforcing the response length, type-specific size limit, and computed SHA-256.