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 59dff01535 fix: preserve VM creation failure cause 1 month ago
..
agent fix: preserve VM creation failure cause 1 month ago
cmd feat: adopt outbound agent gateway 1 month ago
console fix: harden agent dispatch and reconciliation 1 month ago
internal/protocol feat: adopt outbound agent gateway 1 month ago
update feat: adopt outbound agent gateway 1 month ago
README.md fix: harden agent dispatch and reconciliation 1 month 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 Go helpers

gateway is an independent Go module containing the two services that cannot safely run inside PHP-FPM:

  • virt-cloud-update is the privileged, Unix-socket-only update coordinator.
  • virt-cloud-agent-gateway keeps Agent-initiated control WebSockets, accepts authenticated dispatches from local PHP, and pairs reverse console streams with the existing browser console URL.

Neither service is a compatibility layer for the retired Python engine.

Build and test

cd gateway
go test ./...
go build ./cmd/virt-cloud-update ./cmd/virt-cloud-agent-gateway

Both commands require an absolute --config path. The JSON decoders reject unknown fields and trailing values. They deliberately do 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

The update API and 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 update helper persists nonce expiry state, accepts a 60-second clock window, and requires a managing super administrator actor. The Agent gateway signs PHP authentication and console introspection requests with {"service":"agent-gateway"} and accepts local PHP dispatches only with {"service":"php-panel"}.

Update API

The helper listens only on /run/virt-cloud/update.sock. Its repository and branch are pinned to https://g.luoli.live/root/virt.git and go. Its state path is fixed below the configured checkout at runtime/update/state.json; startup rejects a runtime symlink that escapes the checkout, without auditing owner/group/mode.

Method Path Purpose
GET /v1/health Helper health and maintenance-lock state
GET /v1/settings Fixed repository, checkout state, job pointers, and token_configured
PUT /v1/settings Saves {"access_token":"..."}, preserves an empty value, or clears with {"clear_token":true}
DELETE /v1/settings/token Clears the saved token
POST /v1/check Read-only ls-remote check; body is empty or {}
POST /v1/apply Starts a pinned update transaction
GET /v1/jobs Lists durable jobs and lock state
GET /v1/jobs/{id} Reads one durable job
POST /v1/jobs/{id}/resolve Records an operator-confirmed reconciliation

Apply requires the exact commits returned by check:

{
  "expected_current_commit": "<full lowercase object id>",
  "expected_remote_commit": "<full lowercase object id>"
}

The helper verifies the Git root, clean worktree, literal origin, go branch, fetched object, and fast-forward relationship. It rejects updates touching deploy/**, Go modules, Composer manifests/lock files, JavaScript dependency manifests/lock files, Cargo manifests/lock files, or Python requirement files. Those changes require a manual maintenance window.

Before the first host mutation it verifies that PHP is runnable, the current and target web/xcat are regular files, and every configured unit is loaded and active. Before each mutation it atomically persists a checkpoint. The sequence is stop application services, stop PHP-FPM, fast-forward source, run php xcat cloudInit with web/ as its working directory, start PHP-FPM and wait for it before starting application services, then wait up to 60 seconds for every unit to become active. A crash or error at or after the stop checkpoint becomes manual_intervention; it does not replay schema initialization, reset source, or claim a rollback. An operator can release that lock only after SSH reconciliation:

{"resolution":"completed","evidence":"ssh: verified schema and all units"}

rolled_back is also accepted when the operator has independently verified a safe rollback. Access tokens are stored only in the private state file, passed to Git through a temporary askpass environment, omitted from command arguments, responses, jobs, and logs, and can be explicitly cleared.

The settings, check, apply, and job responses retain the existing Venix admin page DTO names. In particular, an internal manual_intervention state is exposed as terminal blocked, checkpoint as phase, the applied commit as new_commit, and the pre-update commit as an informational rollback_ref. That reference never triggers an automatic rollback.

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.v1 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:

{"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". The PHP worker may requeue only retryable 5xx responses with that strict marker; terminal authentication, route, and validation errors fail the job without polling a record that cannot exist. Gateway or Agent nonce replay errors deliberately omit the marker because the first request may already have been dispatched.

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.