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/CloudRescueCatalogStateMach...

360 lines
13 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* The one executable state definition for the global rescue ISO catalog.
*
* Catalog availability, immutable object publication, and disposable host
* replicas intentionally have separate state machines. A transport failure
* may never be translated into a safe retry unless the corresponding state
* exposes an explicit recovery action here.
*/
final class CloudRescueCatalogStateMachine
{
/** @return array<string,array<string,array<string,mixed>>> */
private static function rawDefinition(): array
{
return [
'catalog' => [
'preparing' => self::state(
['validating', 'source_failed', 'source_unknown', 'retiring']
),
'source_failed' => self::state(
['retiring'],
['retire'],
['retire']
),
'source_unknown' => self::state(
['preparing', 'retiring'],
['reconcile_source', 'retire'],
['reconcile_source']
),
'validating' => self::state(
['distributing', 'error', 'retiring']
),
'distributing' => self::state(
['active', 'degraded', 'error', 'retiring']
),
'active' => self::state(
['active', 'degraded', 'error', 'retiring']
),
'degraded' => self::state(
['active', 'degraded', 'error', 'retiring'],
['repair_replicas', 'retire'],
['repair_replicas']
),
'error' => self::state(
['active', 'degraded', 'error', 'retiring'],
['repair_replicas', 'retire'],
['repair_replicas']
),
'retiring' => self::state(
['retired'],
['reconcile_cleanup'],
['reconcile_cleanup']
),
'retired' => self::state([], [], [], true),
],
'artifact' => [
'reserved' => self::state(
['publishing', 'deleted']
),
'publishing' => self::state(
[
'validating', 'publish_failed', 'publish_unknown',
'delete_pending',
]
),
'publish_failed' => self::state(
['delete_pending'],
['delete_artifact'],
['delete_artifact']
),
'publish_unknown' => self::state(
['validating', 'publish_failed', 'delete_pending'],
['reconcile_publish'],
['reconcile_publish']
),
'validating' => self::state(
['ready', 'validation_failed', 'delete_pending']
),
'validation_failed' => self::state(
['delete_pending'],
['delete_artifact'],
['delete_artifact']
),
'ready' => self::state(
['ready', 'delete_pending']
),
'delete_pending' => self::state(
['deleted', 'delete_failed', 'delete_unknown']
),
'delete_failed' => self::state(
['delete_pending'],
['retry_delete'],
['retry_delete']
),
'delete_unknown' => self::state(
['deleted', 'delete_failed'],
['reconcile_delete'],
['reconcile_delete']
),
'deleted' => self::state([], [], [], true),
],
'replica' => [
'pending' => self::state(['importing', 'deleting', 'deleted']),
'importing' => self::state(
['active', 'failed', 'import_unknown']
),
'failed' => self::state(
['importing', 'deleting', 'deleted'],
['retry_import', 'delete_replica'],
['retry_import']
),
'import_unknown' => self::state(
['active', 'missing', 'failed', 'deleting'],
['reconcile_import'],
['reconcile_import']
),
'active' => self::state(
['active', 'stale', 'missing', 'failed', 'deleting', 'deleted']
),
'stale' => self::state(
['active', 'importing', 'deleting', 'deleted'],
['repair_replica'],
['repair_replica']
),
'missing' => self::state(
['active', 'importing', 'deleting', 'deleted'],
['retry_import'],
['retry_import']
),
'deleting' => self::state(
['deleted', 'delete_failed', 'delete_unknown']
),
'delete_failed' => self::state(
['active', 'stale', 'missing', 'deleting', 'deleted'],
['retry_delete'],
['retry_delete']
),
'delete_unknown' => self::state(
['active', 'missing', 'deleted', 'delete_failed'],
['reconcile_delete'],
['reconcile_delete']
),
'deleted' => self::state([], [], [], true),
],
];
}
/**
* @return array{transitions:list<string>,recovery_actions:list<string>,
* required_recovery_actions:list<string>,terminal:bool}
*/
private static function state(
array $transitions,
array $recoveryActions = [],
array $requiredRecoveryActions = [],
bool $terminal = false
): array {
return [
'transitions' => $transitions,
'recovery_actions' => $recoveryActions,
'required_recovery_actions' => $requiredRecoveryActions,
'terminal' => $terminal,
];
}
/** @return array<string,array<string,array<string,mixed>>> */
public static function definition(): array
{
self::assertIntegrity();
return self::rawDefinition();
}
/**
* Verify that every transition is resolvable and every required recovery
* exit is executable. Tests may provide a mutated definition to prove
* that future omissions fail closed.
*
* @param null|array<string,array<string,array<string,mixed>>> $definition
*/
public static function assertIntegrity(?array $definition = null): void
{
$definition ??= self::rawDefinition();
foreach (['catalog', 'artifact', 'replica'] as $layer) {
$states = $definition[$layer] ?? null;
if (!is_array($states) || $states === []) {
throw new \LogicException(
'Rescue catalog state layer is missing: ' . $layer
);
}
foreach ($states as $state => $config) {
if (!is_string($state) || $state === '' || !is_array($config)
|| array_keys($config) !== [
'transitions', 'recovery_actions',
'required_recovery_actions', 'terminal',
]
|| !is_array($config['transitions'])
|| !array_is_list($config['transitions'])
|| !is_array($config['recovery_actions'])
|| !array_is_list($config['recovery_actions'])
|| !is_array($config['required_recovery_actions'])
|| !array_is_list($config['required_recovery_actions'])
|| !is_bool($config['terminal'])) {
throw new \LogicException(sprintf(
'Invalid rescue catalog state definition: %s.%s',
$layer,
(string) $state
));
}
self::assertUniqueNames(
$config['transitions'], $layer . '.' . $state . '.transitions'
);
self::assertUniqueNames(
$config['recovery_actions'],
$layer . '.' . $state . '.recovery_actions'
);
self::assertUniqueNames(
$config['required_recovery_actions'],
$layer . '.' . $state . '.required_recovery_actions'
);
foreach ($config['transitions'] as $next) {
if (!array_key_exists($next, $states)) {
throw new \LogicException(sprintf(
'Unknown rescue state transition: %s.%s -> %s',
$layer,
$state,
$next
));
}
}
foreach ($config['required_recovery_actions'] as $action) {
if (!in_array(
$action,
$config['recovery_actions'],
true
)) {
throw new \LogicException(sprintf(
'Missing required rescue recovery action: %s.%s.%s',
$layer,
$state,
$action
));
}
}
if ($config['terminal']
&& ($config['transitions'] !== []
|| $config['recovery_actions'] !== []
|| $config['required_recovery_actions'] !== [])) {
throw new \LogicException(sprintf(
'Terminal rescue state exposes an exit: %s.%s',
$layer,
$state
));
}
}
}
}
/** @return list<string> */
public static function recoveryActions(string $layer, string $state): array
{
self::assertIntegrity();
return self::stateConfig($layer, $state)['recovery_actions'];
}
public static function assertTransition(
string $layer,
string $current,
string $next
): void {
self::assertIntegrity();
$config = self::stateConfig($layer, $current);
if (!in_array($next, $config['transitions'], true)) {
throw new CloudError(sprintf(
'救援 ISO %s 状态不能从 %s 变更为 %s',
$layer,
$current === '' ? '(empty)' : $current,
$next === '' ? '(empty)' : $next
), 409);
}
}
/**
* Project global availability from exact replicas on enabled hosts.
*
* @param array{revision:int,generation_token:string,size_bytes:int,
* sha256:string} $catalog
* @param iterable<array<string,mixed>|object> $replicas
* @param list<int> $eligibleHostIds
*/
public static function availability(
array $catalog,
iterable $replicas,
array $eligibleHostIds
): string {
$eligible = [];
foreach ($eligibleHostIds as $hostId) {
$hostId = (int) $hostId;
if ($hostId > 0) {
$eligible[$hostId] = true;
}
}
if ($eligible === []) {
return 'error';
}
$exact = [];
foreach ($replicas as $replica) {
$value = static fn (string $key) => is_array($replica)
? ($replica[$key] ?? null)
: ($replica->{$key} ?? null);
$hostId = (int) $value('host_id');
if (!isset($eligible[$hostId])
|| (string) $value('state') !== 'active'
|| (int) $value('revision') !== (int) $catalog['revision']
|| !hash_equals(
(string) $catalog['generation_token'],
(string) $value('generation_token')
)
|| (int) $value('size_bytes') !== (int) $catalog['size_bytes']
|| !hash_equals(
(string) $catalog['sha256'],
(string) $value('sha256')
)) {
continue;
}
$exact[$hostId] = true;
}
if ($exact === []) {
return 'error';
}
return count($exact) === count($eligible) ? 'active' : 'degraded';
}
/** @param list<mixed> $values */
private static function assertUniqueNames(array $values, string $label): void
{
foreach ($values as $value) {
if (!is_string($value)
|| preg_match('/^[a-z][a-z0-9_]*$/D', $value) !== 1) {
throw new \LogicException('Invalid rescue state name: ' . $label);
}
}
if (count($values) !== count(array_unique($values))) {
throw new \LogicException('Duplicate rescue state name: ' . $label);
}
}
/** @return array<string,mixed> */
private static function stateConfig(string $layer, string $state): array
{
$config = self::rawDefinition()[$layer][$state] ?? null;
if (!is_array($config)) {
throw new CloudError('救援 ISO 状态不存在', 409);
}
return $config;
}
}