|
|
1 month ago | |
|---|---|---|
| .. | ||
| agent | 1 month ago | |
| cmd | 1 month ago | |
| console | 1 month ago | |
| internal/protocol | 1 month ago | |
| update | 1 month ago | |
| README.md | 1 month ago | |
| go.mod | 1 month ago | |
| go.sum | 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-updateis the privileged, Unix-socket-only update coordinator.virt-cloud-agent-gatewaykeeps 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.