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/web/app/Services/Cloud/CloudInstanceRuntimeService...

500 lines
20 KiB
PHP

<?php
namespace App\Services\Cloud;
use App\Models\CloudInstance;
use App\Models\CloudInstanceRuntime;
/**
* Database-backed last-known VM power observations.
*
* This service is deliberately independent of the engine client. A worker
* records a successful batch observation with markObserved(), or records a
* host-level failure with markUnavailable(). Page services can then render a
* bounded first paint from forIds() without treating a stale value as live.
*/
final class CloudInstanceRuntimeService
{
public const FRESHNESS_SECONDS = 30;
private const ERROR_CODES = [
'host_unavailable', 'engine_timeout', 'engine_error', 'invalid_response',
];
/** Create the initial observation row after provisioning succeeds. */
public static function seed(int $instanceId, int $hostId, string $uuid,
?int $now = null): CloudInstanceRuntime
{
$now = self::now($now);
[$instanceId, $hostId, $uuid] = self::identity($instanceId, $hostId, $uuid);
$runtime = CloudInstanceRuntime::where('instance_id', $instanceId)->first();
if ($runtime === null) {
$runtime = new CloudInstanceRuntime();
$runtime->instance_id = $instanceId;
$runtime->host_id = $hostId;
$runtime->uuid = $uuid;
$runtime->power_state = 'unknown';
$runtime->sync_state = 'never';
$runtime->last_success_at = 0;
$runtime->last_attempt_at = 0;
$runtime->revision = 0;
$runtime->last_error_code = '';
$runtime->created_at = $now;
$runtime->updated_at = $now;
$runtime->save();
return $runtime;
}
if (!self::sameIdentity($runtime, $hostId, $uuid)) {
self::reset($runtime, $hostId, $uuid, $now);
$runtime->save();
return $runtime;
}
return $runtime;
}
/**
* Save one trusted engine observation. Unknown engine states are never
* promoted to running or stopped; they leave the cached state unchanged.
*/
public static function markObserved(int $instanceId, int $hostId, string $uuid,
$powerState, ?int $now = null, ?int $revision = null): CloudInstanceRuntime
{
$now = self::now($now);
[$instanceId, $hostId, $uuid] = self::identity($instanceId, $hostId, $uuid);
$state = self::normalizeState($powerState);
// Resolve the identity before writing, but apply the write through a
// conditional revision update. A worker write (which omits the
// token) advances the revision and therefore invalidates any in-flight
// background poll carrying an older token.
// A tokenized background response must never recreate a row that a
// completed delete already removed. Immediate worker writes may seed
// a legacy/missing row, but only when no batch token is present.
self::identityRow($instanceId, $hostId, $uuid, $now, $revision === null);
$values = [
'last_attempt_at' => $now,
'updated_at' => $now,
];
if ($state !== 'unknown') {
$values += [
'power_state' => $state,
'last_success_at' => $now,
'sync_state' => 'ok',
'last_error_code' => '',
];
} else {
// A malformed or unsupported engine item is a failed observation;
// retaining the previous state avoids falsely reporting shutdown.
$values += [
'sync_state' => 'unavailable',
'last_error_code' => 'invalid_response',
];
}
return self::writeObservation(
$instanceId, $hostId, $uuid, $values, $revision
);
}
/**
* Claim one host-batch item before issuing vm-states. The returned token
* is valid only until another writer advances the row revision.
*/
public static function beginObservation(int $instanceId, int $hostId, string $uuid,
?int $now = null): int
{
$now = self::now($now);
[$instanceId, $hostId, $uuid] = self::identity($instanceId, $hostId, $uuid);
for ($attempt = 0; $attempt < 3; $attempt++) {
// The sync pass seeds rows before claiming them. Do not recreate
// one that a concurrent delete has already forgotten.
$runtime = self::identityRow($instanceId, $hostId, $uuid, $now, false);
$current = max(0, (int) $runtime->revision);
$next = $current + 1;
$updated = CloudInstanceRuntime::where('instance_id', $instanceId)
->where('host_id', $hostId)
->where('uuid', $uuid)
->where('revision', $current)
->increment('revision', 1, [
'last_attempt_at' => $now,
'updated_at' => $now,
]);
if ((int) $updated === 1) {
return $next;
}
}
throw new \RuntimeException('Runtime observation token unavailable');
}
/**
* Seed and claim an observation only while the requested identity is still
* the current, non-deleted instance row. The row lock closes the window in
* which an old page request could recreate cache after delete or migration.
*/
public static function beginCurrentObservation(int $instanceId, int $hostId,
string $uuid, ?int $now = null): ?int
{
$now = self::now($now);
[$instanceId, $hostId, $uuid] = self::identity($instanceId, $hostId, $uuid);
return (new CloudInstance())->getConnection()->transaction(
static function () use ($instanceId, $hostId, $uuid, $now): ?int {
$instance = CloudInstance::where('id', $instanceId)
->lockForUpdate()->first(['id', 'host_id', 'uuid', 'status']);
if ($instance === null || (string) $instance->status === 'deleted'
|| (int) $instance->host_id !== $hostId
|| !hash_equals(strtolower(trim((string) $instance->uuid)), $uuid)) {
return null;
}
self::seed($instanceId, $hostId, $uuid, $now);
return self::beginObservation($instanceId, $hostId, $uuid, $now);
},
3
);
}
/** Mark a host batch unavailable while preserving its last good state. */
public static function markUnavailable(array $instanceIds, ?int $hostId = null,
?int $now = null, string $errorCode = 'host_unavailable', array $revisions = []): int
{
$now = self::now($now);
$ids = self::ids($instanceIds);
if ($ids === []) {
return 0;
}
$errorCode = self::errorCode($errorCode);
if ($hostId !== null) {
if ($hostId < 1) {
throw new \InvalidArgumentException('Host ID must be positive');
}
}
$values = [
'sync_state' => 'unavailable',
'last_attempt_at' => $now,
'last_error_code' => $errorCode,
'updated_at' => $now,
];
// Tokenized writes are intentionally per-row: each row may have a
// different claim revision. A stale token simply affects zero rows.
if ($revisions !== []) {
$updated = 0;
foreach ($ids as $id) {
if (!array_key_exists($id, $revisions)) {
continue;
}
$query = CloudInstanceRuntime::where('instance_id', $id);
if ($hostId !== null) {
$query->where('host_id', $hostId);
}
$query->where('revision', (int) $revisions[$id]);
$updated += (int) $query->increment('revision', 1, $values);
}
return $updated;
}
$query = CloudInstanceRuntime::whereIn('instance_id', $ids);
if ($hostId !== null) {
$query->where('host_id', $hostId);
}
return (int) $query->increment('revision', 1, $values);
}
/** Remove an observation when its panel instance is irreversibly deleted. */
public static function forget(int $instanceId): int
{
if ($instanceId < 1) {
return 0;
}
return (int) CloudInstanceRuntime::where('instance_id', $instanceId)->delete();
}
/**
* Return rows keyed by instance ID. Missing rows are represented as a
* pending observation, allowing callers to render deployment/syncing
* without inventing a power state.
*/
public static function forIds(array $instanceIds, ?int $now = null): array
{
$now = self::now($now);
$ids = self::ids($instanceIds);
if ($ids === []) {
return [];
}
$rows = [];
foreach (CloudInstanceRuntime::whereIn('instance_id', $ids)->get() as $runtime) {
$rows[(int) $runtime->instance_id] = self::view($runtime, $now);
}
foreach ($ids as $id) {
if (!isset($rows[$id])) {
$rows[$id] = self::pendingView($id, $now);
}
}
// Preserve the caller's de-duplicated ID order for predictable JSON.
$ordered = [];
foreach ($ids as $id) {
$ordered[(string) $id] = $rows[$id];
}
return $ordered;
}
/** Return observations for an iterable of CloudInstance-like records. */
public static function forInstances(iterable $instances, ?int $now = null): array
{
$items = [];
foreach ($instances as $instance) {
$id = self::value($instance, 'id');
if ($id === null) {
$id = self::value($instance, 'instance_id');
}
$id = filter_var($id, FILTER_VALIDATE_INT,
['options' => ['min_range' => 1]]);
if ($id === false) {
continue;
}
$items[(int) $id] = [
'host_id' => self::value($instance, 'host_id'),
'uuid' => self::value($instance, 'uuid'),
];
}
$views = self::forIds(array_keys($items), $now);
foreach ($items as $id => $identity) {
$currentHost = max(0, (int) $identity['host_id']);
$currentUuid = is_string($identity['uuid'])
? strtolower(trim($identity['uuid'])) : '';
$cachedHost = (int) ($views[(string) $id]['host_id'] ?? 0);
$cachedUuid = strtolower(trim((string) ($views[(string) $id]['uuid'] ?? '')));
// A reused instance row must never inherit the previous VM's
// power state. Treat a partial or mismatched identity as a fresh
// pending observation and expose only the current DB identity.
$identityMismatch = ($cachedHost !== 0 || $cachedUuid !== '')
&& ($cachedHost !== $currentHost || $cachedUuid !== $currentUuid);
if ($identityMismatch || $currentHost < 1 || !self::isUuid($currentUuid)) {
$views[(string) $id] = self::pendingView((int) $id, self::now($now));
}
$views[(string) $id]['host_id'] = $currentHost;
$views[(string) $id]['uuid'] = $currentUuid;
}
return $views;
}
/** Normalize engine values to the panel's bounded state vocabulary. */
public static function normalizeState($value): string
{
$state = CloudInstanceMetadata::state($value);
return match ($state) {
'shutoff', 'shut_off', 'stopped' => 'stopped',
'running' => 'running',
// libvirt reports shutdown while a graceful ACPI request is still
// converging. It is neither running nor a confirmed shutoff.
'shutdown' => 'shutdown',
'paused' => 'paused',
'crashed' => 'crashed',
'pmsuspended' => 'pmsuspended',
'blocked' => 'blocked',
default => 'unknown',
};
}
/** Resolve only the immediate cache state of a successful power action. */
public static function stateAfterSuccessfulAction($observedState,
?string $action): string
{
$state = self::normalizeState($observedState);
if ($action === 'shutdown'
&& in_array($state, ['unknown', 'running', 'blocked', 'shutdown'], true)) {
// Graceful shutdown success means accepted, not powered off. The
// next live observation is responsible for confirming stopped.
return 'shutdown';
}
if ($state !== 'unknown') {
return $state;
}
return match ($action) {
'start', 'reboot', 'reset' => 'running',
'shutdown' => 'shutdown',
'poweroff' => 'stopped',
default => 'unknown',
};
}
/**
* Apply a cache write while atomically advancing its revision. When a
* token is supplied, the row must still carry exactly that revision;
* otherwise this is a worker/immediate write that supersedes any poll.
*/
private static function writeObservation(int $instanceId, int $hostId, string $uuid,
array $values, ?int $revision): CloudInstanceRuntime
{
$query = CloudInstanceRuntime::where('instance_id', $instanceId)
->where('host_id', $hostId)
->where('uuid', $uuid);
if ($revision !== null) {
$query->where('revision', max(0, $revision));
}
$updated = $query->increment('revision', 1, $values);
$runtime = CloudInstanceRuntime::where('instance_id', $instanceId)->first();
if ($runtime !== null) {
// A zero-row conditional update means a newer writer won the
// race. Return that current row without overwriting it.
return $runtime;
}
// The row can disappear during an irreversible delete race. Do not
// recreate a cache row for a VM that was just forgotten; return an
// ephemeral identity-only value to preserve the historical contract.
$runtime = new CloudInstanceRuntime();
$runtime->instance_id = $instanceId;
$runtime->host_id = $hostId;
$runtime->uuid = $uuid;
return $runtime;
}
private static function identityRow(int $instanceId, int $hostId, string $uuid,
int $now, bool $create = true): CloudInstanceRuntime
{
$runtime = CloudInstanceRuntime::where('instance_id', $instanceId)->first();
if ($runtime === null) {
if (!$create) {
throw new \RuntimeException('Runtime observation was removed');
}
return self::seed($instanceId, $hostId, $uuid, $now);
}
if (!self::sameIdentity($runtime, $hostId, $uuid)) {
throw new \RuntimeException('Runtime observation identity mismatch');
}
return $runtime;
}
private static function reset(CloudInstanceRuntime $runtime, int $hostId,
string $uuid, int $now): void
{
$runtime->host_id = $hostId;
$runtime->uuid = $uuid;
$runtime->power_state = 'unknown';
$runtime->sync_state = 'never';
$runtime->last_success_at = 0;
$runtime->last_attempt_at = 0;
// Bump the generation when an instance ID is reused, invalidating any
// response still in flight for the previous host/UUID identity.
$runtime->revision = max(0, (int) $runtime->revision) + 1;
$runtime->last_error_code = '';
$runtime->updated_at = $now;
}
private static function view(CloudInstanceRuntime $runtime, int $now): array
{
$success = max(0, (int) $runtime->last_success_at);
$age = $success > 0 ? max(0, $now - $success) : null;
$future = $success > $now;
$fresh = !$future && $success > 0 && $age !== null && $age <= self::FRESHNESS_SECONDS
&& (string) $runtime->sync_state === 'ok';
$sync = match ((string) $runtime->sync_state) {
'unavailable' => 'unavailable',
'never' => 'pending',
default => $success === 0 || $future ? 'pending' : ($fresh ? 'fresh' : 'syncing'),
};
$state = self::normalizeState($runtime->power_state);
$transition = $state === 'shutdown' ? 'shutdown' : null;
return [
'instance_id' => (string) $runtime->instance_id,
'host_id' => (int) $runtime->host_id,
'uuid' => (string) $runtime->uuid,
'state' => $state,
'power_state' => $state,
'state_transitioning' => $transition !== null,
'state_transition' => $transition,
'fresh' => $fresh,
'state_fresh' => $fresh,
'freshness' => $success === 0 || $future ? 'never' : ($fresh ? 'fresh' : 'stale'),
'sync_status' => $sync,
'state_sync_status' => $sync === 'unavailable' ? 'offline' : $sync,
'last_success_at' => $success > 0 ? $success : null,
'state_observed_at' => $success > 0 && !$future ? $success : null,
'last_attempt_at' => max(0, (int) $runtime->last_attempt_at) ?: null,
'age_seconds' => $age,
'state_label_hint' => $sync === 'unavailable'
? '暂时无法同步' : ($success === 0 || $future ? '等待宿主机同步' : ''),
];
}
private static function pendingView(int $instanceId, int $now): array
{
return [
'instance_id' => (string) $instanceId,
'host_id' => 0,
'uuid' => '',
'state' => 'unknown',
'power_state' => 'unknown',
'state_transitioning' => false,
'state_transition' => null,
'fresh' => false,
'state_fresh' => false,
'freshness' => 'never',
'sync_status' => 'pending',
'state_sync_status' => 'pending',
'last_success_at' => null,
'state_observed_at' => null,
'last_attempt_at' => null,
'age_seconds' => null,
'state_label_hint' => '等待宿主机同步',
];
}
private static function sameIdentity(CloudInstanceRuntime $runtime, int $hostId,
string $uuid): bool
{
return (int) $runtime->host_id === $hostId
&& hash_equals(strtolower((string) $runtime->uuid), $uuid);
}
private static function identity(int $instanceId, int $hostId, string $uuid): array
{
if ($instanceId < 1 || $hostId < 1) {
throw new \InvalidArgumentException('Instance and host IDs must be positive');
}
$uuid = strtolower(trim($uuid));
// Libvirt accepts operator-supplied UUIDs whose version/variant
// nibbles are not RFC 4122 values. Match the existing panel identity
// boundary and require only the canonical five-group shape.
if (!self::isUuid($uuid)) {
throw new \InvalidArgumentException('Invalid runtime UUID');
}
return [$instanceId, $hostId, $uuid];
}
private static function isUuid(string $uuid): bool
{
return preg_match(
'/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/D',
strtolower(trim($uuid))
) === 1;
}
private static function ids(array $values): array
{
$ids = [];
foreach ($values as $value) {
$id = filter_var($value, FILTER_VALIDATE_INT,
['options' => ['min_range' => 1]]);
if ($id !== false) {
$ids[(int) $id] = true;
}
}
return array_keys($ids);
}
private static function value($instance, string $key)
{
if (is_array($instance)) {
return $instance[$key] ?? null;
}
return is_object($instance) ? ($instance->{$key} ?? null) : null;
}
private static function errorCode(string $value): string
{
return in_array($value, self::ERROR_CODES, true) ? $value : 'host_unavailable';
}
private static function now(?int $now): int
{
return max(1, $now ?? time());
}
}