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()); } }