You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/gateway
codex 63f365d847 fix(cloud): repair portable backup preflight 3 weeks ago
..
agent fix(cloud): repair portable backup preflight 3 weeks ago
cmd/virt-cloud-agent-gateway refactor: make cloud tasks single-dispatch 4 weeks ago
console fix: harden agent dispatch and reconciliation 1 month ago
internal/protocol Remove online update subsystem 1 month ago
README.md fix(cloud): close six operation recovery dead ends 4 weeks ago
go.mod feat: replace Python engine with Go host agents 1 month ago
go.sum feat: replace Python engine with Go host agents 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.