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.
860 lines
34 KiB
PHP
860 lines
34 KiB
PHP
<?php
|
|
|
|
namespace App\Services\Cloud;
|
|
|
|
use App\Models\CloudInstanceMigration;
|
|
|
|
/**
|
|
* Executable definition of every maintenance-migration stage.
|
|
*
|
|
* Job routing, uncertain-result reconciliation, manual recovery and the
|
|
* administrator progress projection all read this one registry. Adding a
|
|
* stage without its durable job field or recovery contract therefore fails
|
|
* the registry integrity check instead of silently creating a dead end.
|
|
*/
|
|
final class CloudInstanceMigrationWorkflow
|
|
{
|
|
private const STAGES = [
|
|
'prepare' => [
|
|
'position' => 1,
|
|
'label' => '准备源实例',
|
|
'running_state' => 'preparing_source',
|
|
'job_kind' => 'instance_migration_prepare',
|
|
'job_field' => 'source_prepare_job_id',
|
|
'task_key' => 'prepare_task_id',
|
|
'finish_handler' => 'finishPrepareLocked',
|
|
'reconcile_action' => 'reconcile_prepare',
|
|
'failure_policy' => 'conditional_abort',
|
|
'failure_action' => null,
|
|
'required_recovery_actions' => ['abort_prepare'],
|
|
'recovery_actions' => [
|
|
'abort_prepare' => [
|
|
'label' => '中止迁移并恢复源实例',
|
|
'handler' => 'recoverAbortPrepare',
|
|
'destructive' => true,
|
|
'recorded_actions' => [
|
|
'reconcile_prepare', 'abort_prepare',
|
|
],
|
|
'requires_abort_evidence' => true,
|
|
],
|
|
],
|
|
],
|
|
'vpc_target' => [
|
|
'position' => 2,
|
|
'label' => '切换私网路由',
|
|
'running_state' => 'vpc_target_routing',
|
|
'job_kind' => null,
|
|
'job_field' => null,
|
|
'task_key' => null,
|
|
'finish_handler' => null,
|
|
'reconcile_action' => 'reconcile_vpc_target',
|
|
'failure_policy' => 'external_orchestration',
|
|
'failure_action' => 'retry_vpc_target',
|
|
'required_recovery_actions' => [
|
|
'retry_vpc_target', 'abort_vpc_target',
|
|
],
|
|
'recovery_actions' => [
|
|
'retry_vpc_target' => [
|
|
'label' => '重试目标私网路由',
|
|
'handler' => 'recoverRetryVpcTargetLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_vpc_target'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
'abort_vpc_target' => [
|
|
'label' => '恢复源私网并中止迁移',
|
|
'handler' => 'recoverAbortVpcTargetLocked',
|
|
'destructive' => true,
|
|
'recorded_actions' => ['retry_vpc_target'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
'transfer' => [
|
|
'position' => 3,
|
|
'label' => '传输磁盘与快照',
|
|
'running_state' => 'transferring',
|
|
'job_kind' => 'instance_migration_transfer',
|
|
'job_field' => 'target_receive_job_id',
|
|
'task_key' => 'transfer_task_id',
|
|
'finish_handler' => 'finishTransferLocked',
|
|
'reconcile_action' => 'reconcile_transfer',
|
|
'failure_policy' => 'manual_recovery',
|
|
'failure_action' => 'retry_transfer',
|
|
'required_recovery_actions' => [
|
|
'retry_transfer', 'abort_transfer',
|
|
],
|
|
'recovery_actions' => [
|
|
'retry_transfer' => [
|
|
'label' => '继续分块传输',
|
|
'handler' => 'recoverRetryTransferLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_transfer'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
'abort_transfer' => [
|
|
'label' => '中止传输并恢复源实例',
|
|
'handler' => 'recoverAbortTransferLocked',
|
|
'destructive' => true,
|
|
'recorded_actions' => ['retry_transfer'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
'cutover' => [
|
|
'position' => 4,
|
|
'label' => '切换实例账本',
|
|
'running_state' => 'cutover',
|
|
'job_kind' => null,
|
|
'job_field' => null,
|
|
'task_key' => null,
|
|
'finish_handler' => null,
|
|
'reconcile_action' => null,
|
|
'failure_policy' => 'inline_transaction',
|
|
'failure_action' => null,
|
|
'required_recovery_actions' => [],
|
|
'recovery_actions' => [],
|
|
],
|
|
'firewall' => [
|
|
'position' => 5,
|
|
'label' => '恢复目标防火墙',
|
|
'running_state' => 'firewall_running',
|
|
'job_kind' => 'firewall_apply',
|
|
'job_field' => 'firewall_job_id',
|
|
'task_key' => 'firewall_task_id',
|
|
'finish_handler' => 'finishFirewallLocked',
|
|
'reconcile_action' => 'reconcile_firewall',
|
|
'failure_policy' => 'manual_recovery',
|
|
'failure_action' => 'retry_firewall',
|
|
'required_recovery_actions' => ['retry_firewall'],
|
|
'recovery_actions' => [
|
|
'retry_firewall' => [
|
|
'label' => '重试目标防火墙',
|
|
'handler' => 'recoverRetryFirewallLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_firewall'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
'activation' => [
|
|
'position' => 6,
|
|
'label' => '恢复目标电源状态',
|
|
'running_state' => 'activation_running',
|
|
'job_kind' => 'instance_migration_activate',
|
|
'job_field' => 'activate_job_id',
|
|
'task_key' => 'activation_task_id',
|
|
'finish_handler' => 'finishActivationLocked',
|
|
'reconcile_action' => 'reconcile_activation',
|
|
'failure_policy' => 'manual_recovery',
|
|
'failure_action' => 'retry_activation',
|
|
'required_recovery_actions' => ['retry_activation'],
|
|
'recovery_actions' => [
|
|
'retry_activation' => [
|
|
'label' => '重试目标状态恢复',
|
|
'handler' => 'recoverRetryActivationLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_activation'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
'cleanup' => [
|
|
'position' => 7,
|
|
'label' => '清理源副本',
|
|
'running_state' => 'cleanup_running',
|
|
'job_kind' => 'instance_migration_cleanup',
|
|
'job_field' => 'cleanup_job_id',
|
|
'task_key' => 'cleanup_task_id',
|
|
'finish_handler' => 'finishCleanupLocked',
|
|
'reconcile_action' => 'reconcile_cleanup',
|
|
'failure_policy' => 'source_retained',
|
|
'failure_action' => null,
|
|
'required_recovery_actions' => [],
|
|
'recovery_actions' => [],
|
|
],
|
|
'vpc_source' => [
|
|
'position' => null,
|
|
'label' => '恢复源私网路由',
|
|
'running_state' => 'vpc_source_routing',
|
|
'job_kind' => null,
|
|
'job_field' => null,
|
|
'task_key' => null,
|
|
'finish_handler' => null,
|
|
'reconcile_action' => 'reconcile_vpc_source',
|
|
'failure_policy' => 'external_orchestration',
|
|
'failure_action' => 'retry_vpc_source',
|
|
'required_recovery_actions' => ['retry_vpc_source'],
|
|
'recovery_actions' => [
|
|
'retry_vpc_source' => [
|
|
'label' => '重试恢复源私网路由',
|
|
'handler' => 'recoverRetryVpcSourceLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_vpc_source'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
'rollback' => [
|
|
'position' => null,
|
|
'label' => '恢复源实例',
|
|
'running_state' => 'rollback_running',
|
|
'job_kind' => 'instance_migration_rollback',
|
|
'job_field' => 'rollback_job_id',
|
|
'task_key' => 'rollback_task_id',
|
|
'finish_handler' => 'finishRollbackLocked',
|
|
'reconcile_action' => 'reconcile_rollback',
|
|
'failure_policy' => 'manual_recovery',
|
|
'failure_action' => 'retry_rollback',
|
|
'required_recovery_actions' => ['retry_rollback'],
|
|
'recovery_actions' => [
|
|
'retry_rollback' => [
|
|
'label' => '重试恢复源实例',
|
|
'handler' => 'recoverRetryRollbackLocked',
|
|
'destructive' => false,
|
|
'recorded_actions' => ['retry_rollback'],
|
|
'requires_abort_evidence' => false,
|
|
],
|
|
],
|
|
],
|
|
];
|
|
|
|
private const PASSIVE_STATES = [
|
|
'attention_required', 'source_retained', 'completed', 'rolled_back',
|
|
'failed',
|
|
];
|
|
|
|
/** @return array<string,array<string,mixed>> */
|
|
public static function stages(): array
|
|
{
|
|
self::assertIntegrity();
|
|
return self::STAGES;
|
|
}
|
|
|
|
/** @return array<string,mixed>|null */
|
|
public static function job(string $kind): ?array
|
|
{
|
|
self::assertIntegrity();
|
|
foreach (self::STAGES as $key => $stage) {
|
|
if ($stage['job_kind'] === $kind) {
|
|
return ['key' => $key] + $stage;
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** @return list<string> */
|
|
public static function blockingStates(): array
|
|
{
|
|
self::assertIntegrity();
|
|
$states = ['attention_required'];
|
|
foreach (self::STAGES as $stage) {
|
|
$states[] = $stage['running_state'];
|
|
}
|
|
return array_values(array_unique($states));
|
|
}
|
|
|
|
public static function blocksInstance(string $state): bool
|
|
{
|
|
return in_array($state, self::blockingStates(), true);
|
|
}
|
|
|
|
public static function blocksNewMigration(string $state): bool
|
|
{
|
|
return self::blocksInstance($state) || $state === 'source_retained';
|
|
}
|
|
|
|
public static function isRecoveryAction(string $action): bool
|
|
{
|
|
return self::recoveryDefinition($action) !== null;
|
|
}
|
|
|
|
public static function recoveryHandler(string $action): ?string
|
|
{
|
|
$definition = self::recoveryDefinition($action);
|
|
return $definition === null ? null : (string) $definition['handler'];
|
|
}
|
|
|
|
public static function failureAction(string $stageKey): ?string
|
|
{
|
|
self::assertIntegrity();
|
|
if (!isset(self::STAGES[$stageKey])) {
|
|
throw new \LogicException(
|
|
'Unknown maintenance-migration stage: ' . $stageKey
|
|
);
|
|
}
|
|
$action = self::STAGES[$stageKey]['failure_action'];
|
|
return $action === null ? null : (string) $action;
|
|
}
|
|
|
|
/**
|
|
* @return list<array{action:string,label:string,destructive:bool}>
|
|
*/
|
|
public static function recoveryOptions(
|
|
CloudInstanceMigration $migration,
|
|
bool $hasAbortPrepareEvidence
|
|
): array {
|
|
self::assertIntegrity();
|
|
if ((string) $migration->state !== 'attention_required') {
|
|
return [];
|
|
}
|
|
$recorded = (string) $migration->recovery_action;
|
|
$options = [];
|
|
foreach (self::STAGES as $stage) {
|
|
foreach ($stage['recovery_actions'] as $action => $definition) {
|
|
if (!in_array($recorded,
|
|
$definition['recorded_actions'], true)) {
|
|
continue;
|
|
}
|
|
if ($definition['requires_abort_evidence']
|
|
&& !$hasAbortPrepareEvidence) {
|
|
continue;
|
|
}
|
|
$options[] = [
|
|
'action' => $action,
|
|
'label' => (string) $definition['label'],
|
|
'destructive' => (bool) $definition['destructive'],
|
|
];
|
|
}
|
|
}
|
|
return $options;
|
|
}
|
|
|
|
/** @return list<string> */
|
|
public static function recoveryActions(
|
|
CloudInstanceMigration $migration,
|
|
bool $hasAbortPrepareEvidence
|
|
): array {
|
|
return array_map(
|
|
static fn (array $option): string => $option['action'],
|
|
self::recoveryOptions($migration, $hasAbortPrepareEvidence)
|
|
);
|
|
}
|
|
|
|
public static function assertState(
|
|
string $state,
|
|
string $recoveryAction
|
|
): void {
|
|
self::assertIntegrity();
|
|
$knownStates = self::PASSIVE_STATES;
|
|
foreach (self::STAGES as $stage) {
|
|
$knownStates[] = $stage['running_state'];
|
|
}
|
|
if (!in_array($state, $knownStates, true)) {
|
|
throw new \LogicException(
|
|
'Unknown maintenance-migration state: ' . $state
|
|
);
|
|
}
|
|
if ($state === 'attention_required') {
|
|
if (!self::isRecordedRecoveryAction($recoveryAction)) {
|
|
throw new \LogicException(
|
|
'Attention state requires a registered recovery action'
|
|
);
|
|
}
|
|
return;
|
|
}
|
|
if ($state === 'source_retained') {
|
|
if (!in_array($recoveryAction,
|
|
['', 'reconcile_cleanup'], true)) {
|
|
throw new \LogicException(
|
|
'Source-retained state has an invalid recovery action'
|
|
);
|
|
}
|
|
return;
|
|
}
|
|
if ($recoveryAction !== '') {
|
|
throw new \LogicException(
|
|
'Migration state does not accept a recovery action: ' . $state
|
|
);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* A stable, byte-progress-free projection. PeerMigration V3 currently
|
|
* returns no durable transfer telemetry, so the panel reports truthful
|
|
* stage progress instead of inventing a percentage.
|
|
*
|
|
* @return array<string,mixed>
|
|
*/
|
|
public static function progress(
|
|
CloudInstanceMigration $migration
|
|
): array {
|
|
self::assertIntegrity();
|
|
$state = (string) $migration->state;
|
|
$currentKey = self::stageForStateOrRecovery(
|
|
$state,
|
|
(string) $migration->recovery_action
|
|
);
|
|
$mainStages = array_filter(
|
|
self::STAGES,
|
|
static fn (array $stage): bool => is_int($stage['position'])
|
|
);
|
|
uasort($mainStages, static fn (array $left, array $right): int =>
|
|
$left['position'] <=> $right['position']);
|
|
$currentPosition = $currentKey !== null
|
|
&& is_int(self::STAGES[$currentKey]['position'])
|
|
? self::STAGES[$currentKey]['position'] : null;
|
|
$terminalCompleted = $state === 'completed';
|
|
$onRollbackPath = in_array($currentKey, ['vpc_source', 'rollback'], true)
|
|
|| $state === 'rolled_back';
|
|
$steps = [];
|
|
foreach ($mainStages as $key => $stage) {
|
|
$stepStatus = 'pending';
|
|
if ($onRollbackPath) {
|
|
if ($key === 'prepare') {
|
|
// A transfer job can only be queued after source prepare
|
|
// succeeds. Unlike error_code, this durable link is not
|
|
// rewritten when rollback itself fails and is retried.
|
|
$stepStatus = $migration->source_was_running === null
|
|
? 'interrupted' : 'completed';
|
|
} elseif ($key === 'vpc_target') {
|
|
$stepStatus = $migration->vpc_port_id === null
|
|
? 'skipped'
|
|
: ($migration->target_receive_job_id === null
|
|
? 'interrupted' : 'completed');
|
|
} elseif ($key === 'transfer') {
|
|
$stepStatus = $migration->target_receive_job_id === null
|
|
? 'skipped' : 'interrupted';
|
|
}
|
|
} elseif ($terminalCompleted) {
|
|
$stepStatus = self::stageWasSkipped($migration, $key)
|
|
? 'skipped' : 'completed';
|
|
} elseif ($state === 'source_retained') {
|
|
if ($key === 'cleanup') {
|
|
$stepStatus = (string) $migration->recovery_action
|
|
=== 'reconcile_cleanup'
|
|
? 'attention_required' : 'available';
|
|
} else {
|
|
$stepStatus = self::stageWasSkipped($migration, $key)
|
|
? 'skipped' : 'completed';
|
|
}
|
|
} elseif ($currentPosition !== null
|
|
&& $stage['position'] < $currentPosition) {
|
|
$stepStatus = self::stageWasSkipped($migration, $key)
|
|
? 'skipped' : 'completed';
|
|
} elseif ($key === $currentKey) {
|
|
$stepStatus = $state === 'attention_required'
|
|
? 'attention_required' : 'running';
|
|
}
|
|
$steps[] = [
|
|
'key' => $key,
|
|
'label' => (string) $stage['label'],
|
|
'status' => $stepStatus,
|
|
'status_label' => self::stepStatusLabel($stepStatus),
|
|
];
|
|
}
|
|
if ($migration->vpc_port_id !== null
|
|
&& (in_array($currentKey, ['vpc_source', 'rollback'], true)
|
|
|| $state === 'rolled_back')) {
|
|
$sourceRouteStatus = $currentKey === 'vpc_source'
|
|
? ($state === 'attention_required'
|
|
? 'attention_required' : 'running')
|
|
: 'completed';
|
|
$steps[] = [
|
|
'key' => 'vpc_source',
|
|
'label' => (string) self::STAGES['vpc_source']['label'],
|
|
'status' => $sourceRouteStatus,
|
|
'status_label' => self::stepStatusLabel($sourceRouteStatus),
|
|
];
|
|
}
|
|
if ($currentKey === 'rollback' || $state === 'rolled_back') {
|
|
$steps[] = [
|
|
'key' => 'rollback',
|
|
'label' => (string) self::STAGES['rollback']['label'],
|
|
'status' => $state === 'rolled_back' ? 'completed'
|
|
: ($state === 'attention_required'
|
|
? 'attention_required' : 'running'),
|
|
'status_label' => $state === 'rolled_back'
|
|
? self::stepStatusLabel('completed')
|
|
: self::stepStatusLabel(
|
|
$state === 'attention_required'
|
|
? 'attention_required' : 'running'
|
|
),
|
|
];
|
|
}
|
|
$status = match ($state) {
|
|
'completed' => 'completed',
|
|
'rolled_back' => 'rolled_back',
|
|
'source_retained' => (string) $migration->recovery_action
|
|
=== 'reconcile_cleanup'
|
|
? 'attention_required' : 'source_retained',
|
|
'attention_required' => 'attention_required',
|
|
'failed' => 'failed',
|
|
default => 'running',
|
|
};
|
|
$currentStage = $currentKey === null ? null : [
|
|
'key' => $currentKey,
|
|
'label' => (string) self::STAGES[$currentKey]['label'],
|
|
'index' => self::STAGES[$currentKey]['position'],
|
|
];
|
|
return [
|
|
'status' => $status,
|
|
'label' => self::progressLabel($status, $currentStage),
|
|
'blocks_instance' => self::blocksInstance($state),
|
|
'blocks_new_migration' => self::blocksNewMigration($state),
|
|
'current_stage' => $currentStage,
|
|
'stage_count' => count($mainStages),
|
|
'steps' => $steps,
|
|
'byte_progress_available' => false,
|
|
'updated_at' => (int) $migration->updated_at,
|
|
];
|
|
}
|
|
|
|
public static function assertIntegrity(): void
|
|
{
|
|
static $checked = false;
|
|
if ($checked) {
|
|
return;
|
|
}
|
|
self::assertDefinitions(self::STAGES);
|
|
$checked = true;
|
|
}
|
|
|
|
/** @param array<string,array<string,mixed>> $stages */
|
|
public static function assertDefinitions(array $stages): void
|
|
{
|
|
$required = [
|
|
'position', 'label', 'running_state', 'job_kind', 'job_field',
|
|
'task_key', 'finish_handler', 'reconcile_action',
|
|
'failure_policy', 'failure_action',
|
|
'required_recovery_actions', 'recovery_actions',
|
|
];
|
|
$failurePolicies = [
|
|
'conditional_abort', 'manual_recovery', 'inline_transaction',
|
|
'source_retained', 'external_orchestration',
|
|
];
|
|
$positions = [];
|
|
$states = [];
|
|
$jobKinds = [];
|
|
$jobFields = [];
|
|
$taskKeys = [];
|
|
$reconcileActions = [];
|
|
$actions = [];
|
|
if ($stages === []) {
|
|
throw new \LogicException(
|
|
'Maintenance-migration workflow has no stages'
|
|
);
|
|
}
|
|
foreach ($stages as $key => $stage) {
|
|
if (!is_string($key) || $key === '' || !is_array($stage)
|
|
|| array_diff($required, array_keys($stage)) !== []
|
|
|| !is_string($stage['label']) || $stage['label'] === ''
|
|
|| !is_string($stage['running_state'])
|
|
|| $stage['running_state'] === ''
|
|
|| ($stage['position'] !== null
|
|
&& !is_int($stage['position']))
|
|
|| !is_string($stage['failure_policy'])
|
|
|| !in_array(
|
|
$stage['failure_policy'], $failurePolicies, true
|
|
)
|
|
|| ($stage['failure_action'] !== null
|
|
&& (!is_string($stage['failure_action'])
|
|
|| $stage['failure_action'] === ''))
|
|
|| !is_array($stage['required_recovery_actions'])
|
|
|| !array_is_list($stage['required_recovery_actions'])
|
|
|| array_filter(
|
|
$stage['required_recovery_actions'],
|
|
static fn ($action): bool =>
|
|
!is_string($action) || $action === ''
|
|
) !== []
|
|
|| count($stage['required_recovery_actions'])
|
|
!== count(array_unique(
|
|
$stage['required_recovery_actions']
|
|
))
|
|
|| !is_array($stage['recovery_actions'])) {
|
|
throw new \LogicException(
|
|
'Incomplete maintenance-migration stage: ' . $key
|
|
);
|
|
}
|
|
if (isset($states[$stage['running_state']])) {
|
|
throw new \LogicException(
|
|
'Duplicate maintenance-migration running state'
|
|
);
|
|
}
|
|
$states[$stage['running_state']] = true;
|
|
if (is_int($stage['position'])) {
|
|
if (isset($positions[$stage['position']])) {
|
|
throw new \LogicException(
|
|
'Duplicate maintenance-migration stage position'
|
|
);
|
|
}
|
|
$positions[$stage['position']] = true;
|
|
}
|
|
if ($stage['job_kind'] !== null) {
|
|
foreach (['job_kind', 'job_field', 'task_key',
|
|
'finish_handler', 'reconcile_action'] as $field) {
|
|
if (!is_string($stage[$field])
|
|
|| $stage[$field] === '') {
|
|
throw new \LogicException(
|
|
'Executable migration stage is incomplete: ' . $key
|
|
);
|
|
}
|
|
}
|
|
if (isset($jobKinds[$stage['job_kind']])
|
|
|| isset($jobFields[$stage['job_field']])
|
|
|| isset($taskKeys[$stage['task_key']])
|
|
|| isset($reconcileActions[$stage['reconcile_action']])) {
|
|
throw new \LogicException(
|
|
'Duplicate maintenance-migration job definition'
|
|
);
|
|
}
|
|
$jobKinds[$stage['job_kind']] = true;
|
|
$jobFields[$stage['job_field']] = true;
|
|
$taskKeys[$stage['task_key']] = true;
|
|
$reconcileActions[$stage['reconcile_action']] = true;
|
|
} elseif ($stage['failure_policy'] === 'external_orchestration') {
|
|
if ($stage['job_field'] !== null
|
|
|| $stage['task_key'] !== null
|
|
|| $stage['finish_handler'] !== null
|
|
|| !is_string($stage['reconcile_action'])
|
|
|| $stage['reconcile_action'] === ''
|
|
|| isset($reconcileActions[$stage['reconcile_action']])) {
|
|
throw new \LogicException(
|
|
'External migration stage is incomplete: ' . $key
|
|
);
|
|
}
|
|
$reconcileActions[$stage['reconcile_action']] = true;
|
|
} elseif ($stage['job_field'] !== null
|
|
|| $stage['task_key'] !== null
|
|
|| $stage['finish_handler'] !== null
|
|
|| $stage['reconcile_action'] !== null) {
|
|
throw new \LogicException(
|
|
'Non-job migration stage contains partial job metadata'
|
|
);
|
|
}
|
|
foreach ($stage['recovery_actions'] as $action => $definition) {
|
|
if (isset($actions[$action]) || !is_string($action)
|
|
|| $action === '' || !is_array($definition)
|
|
|| !is_string($definition['label'] ?? null)
|
|
|| ($definition['label'] ?? '') === ''
|
|
|| !is_string($definition['handler'] ?? null)
|
|
|| ($definition['handler'] ?? '') === ''
|
|
|| !is_bool($definition['destructive'] ?? null)
|
|
|| !is_array($definition['recorded_actions'] ?? null)
|
|
|| $definition['recorded_actions'] === []
|
|
|| !array_is_list($definition['recorded_actions'])
|
|
|| array_filter(
|
|
$definition['recorded_actions'],
|
|
static fn ($recorded): bool =>
|
|
!is_string($recorded) || $recorded === ''
|
|
) !== []
|
|
|| !is_bool(
|
|
$definition['requires_abort_evidence'] ?? null
|
|
)) {
|
|
throw new \LogicException(
|
|
'Invalid maintenance-migration recovery definition'
|
|
);
|
|
}
|
|
$actions[$action] = true;
|
|
}
|
|
$definedActions = array_keys($stage['recovery_actions']);
|
|
$requiredActions = $stage['required_recovery_actions'];
|
|
sort($definedActions);
|
|
sort($requiredActions);
|
|
if ($definedActions !== $requiredActions) {
|
|
throw new \LogicException(
|
|
'Migration stage recovery exits do not match its contract: '
|
|
. $key
|
|
);
|
|
}
|
|
$failureAction = $stage['failure_action'];
|
|
if ($stage['failure_policy'] === 'manual_recovery') {
|
|
if ($stage['job_kind'] === null || $failureAction === null
|
|
|| !isset($stage['recovery_actions'][$failureAction])) {
|
|
throw new \LogicException(
|
|
'Manual-recovery stage has no failure exit: ' . $key
|
|
);
|
|
}
|
|
foreach ($stage['required_recovery_actions'] as $action) {
|
|
if (!in_array(
|
|
$failureAction,
|
|
$stage['recovery_actions'][$action]['recorded_actions'],
|
|
true
|
|
)) {
|
|
throw new \LogicException(
|
|
'Recovery exit is unreachable from stage failure: '
|
|
. $key
|
|
);
|
|
}
|
|
}
|
|
} elseif ($stage['failure_policy']
|
|
=== 'external_orchestration') {
|
|
if ($stage['job_kind'] !== null
|
|
|| $failureAction === null
|
|
|| !isset($stage['recovery_actions'][$failureAction])) {
|
|
throw new \LogicException(
|
|
'External migration stage has no failure exit: ' . $key
|
|
);
|
|
}
|
|
foreach ($stage['required_recovery_actions'] as $action) {
|
|
if (!in_array(
|
|
$failureAction,
|
|
$stage['recovery_actions'][$action]['recorded_actions'],
|
|
true
|
|
)) {
|
|
throw new \LogicException(
|
|
'External recovery exit is unreachable: ' . $key
|
|
);
|
|
}
|
|
}
|
|
} elseif ($stage['failure_policy'] === 'conditional_abort') {
|
|
if ($stage['job_kind'] === null || $failureAction !== null
|
|
|| $stage['required_recovery_actions'] === []) {
|
|
throw new \LogicException(
|
|
'Conditional-abort stage has an invalid failure contract: '
|
|
. $key
|
|
);
|
|
}
|
|
foreach ($stage['required_recovery_actions'] as $action) {
|
|
$definition = $stage['recovery_actions'][$action];
|
|
if (!$definition['requires_abort_evidence']
|
|
|| !in_array(
|
|
$stage['reconcile_action'],
|
|
$definition['recorded_actions'],
|
|
true
|
|
)) {
|
|
throw new \LogicException(
|
|
'Conditional abort is not evidence-gated: ' . $key
|
|
);
|
|
}
|
|
}
|
|
} elseif ($stage['failure_policy'] === 'inline_transaction') {
|
|
if ($stage['job_kind'] !== null || $failureAction !== null
|
|
|| $stage['required_recovery_actions'] !== []) {
|
|
throw new \LogicException(
|
|
'Inline stage exposes an invalid recovery contract: '
|
|
. $key
|
|
);
|
|
}
|
|
} elseif ($stage['job_kind'] === null || $failureAction !== null
|
|
|| $stage['required_recovery_actions'] !== []) {
|
|
throw new \LogicException(
|
|
'Source-retained stage exposes an invalid recovery contract: '
|
|
. $key
|
|
);
|
|
}
|
|
}
|
|
ksort($positions);
|
|
if (array_keys($positions) !== range(1, count($positions))) {
|
|
throw new \LogicException(
|
|
'Maintenance-migration stage positions are not contiguous'
|
|
);
|
|
}
|
|
foreach ($stages as $stage) {
|
|
foreach ($stage['recovery_actions'] as $definition) {
|
|
foreach ($definition['recorded_actions'] as $recorded) {
|
|
if (!isset($actions[$recorded])
|
|
&& !isset($reconcileActions[$recorded])) {
|
|
throw new \LogicException(
|
|
'Recovery button references an unknown ledger action'
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
/** @return array<string,mixed>|null */
|
|
private static function recoveryDefinition(string $action): ?array
|
|
{
|
|
self::assertIntegrity();
|
|
foreach (self::STAGES as $stageKey => $stage) {
|
|
if (isset($stage['recovery_actions'][$action])) {
|
|
return ['stage_key' => $stageKey]
|
|
+ $stage['recovery_actions'][$action];
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
private static function isRecordedRecoveryAction(string $action): bool
|
|
{
|
|
if ($action === '') {
|
|
return false;
|
|
}
|
|
foreach (self::STAGES as $stage) {
|
|
if ($stage['reconcile_action'] === $action) {
|
|
return true;
|
|
}
|
|
foreach ($stage['recovery_actions'] as $definition) {
|
|
if (in_array($action,
|
|
$definition['recorded_actions'], true)) {
|
|
return true;
|
|
}
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
|
|
private static function stageForStateOrRecovery(
|
|
string $state,
|
|
string $recoveryAction
|
|
): ?string {
|
|
foreach (self::STAGES as $key => $stage) {
|
|
if ($stage['running_state'] === $state) {
|
|
return $key;
|
|
}
|
|
if ($state === 'attention_required') {
|
|
if ($stage['reconcile_action'] === $recoveryAction) {
|
|
return $key;
|
|
}
|
|
foreach ($stage['recovery_actions'] as $definition) {
|
|
if (in_array($recoveryAction,
|
|
$definition['recorded_actions'], true)) {
|
|
return $key;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
if ($state === 'source_retained' || $state === 'completed') {
|
|
return 'cleanup';
|
|
}
|
|
if ($state === 'rolled_back') {
|
|
return 'rollback';
|
|
}
|
|
return null;
|
|
}
|
|
|
|
private static function stageWasSkipped(
|
|
CloudInstanceMigration $migration,
|
|
string $stageKey
|
|
): bool {
|
|
if ($stageKey === 'vpc_target') {
|
|
return $migration->vpc_port_id === null;
|
|
}
|
|
if ($stageKey === 'firewall') {
|
|
return $migration->firewall_job_id === null;
|
|
}
|
|
return false;
|
|
}
|
|
|
|
private static function stepStatusLabel(string $status): string
|
|
{
|
|
return match ($status) {
|
|
'completed' => '已完成',
|
|
'running' => '执行中',
|
|
'skipped' => '已跳过',
|
|
'attention_required' => '需要处理',
|
|
'available' => '可手动清理',
|
|
'interrupted' => '已中止',
|
|
default => '等待中',
|
|
};
|
|
}
|
|
|
|
/** @param array{key:string,label:string,index:int|null}|null $stage */
|
|
private static function progressLabel(
|
|
string $status,
|
|
?array $stage
|
|
): string {
|
|
return match ($status) {
|
|
'completed' => '迁移已完成',
|
|
'rolled_back' => '迁移已中止,源实例已恢复',
|
|
'source_retained' => '目标已切换,源副本已保留',
|
|
'attention_required' => '迁移需要核对或人工处理',
|
|
'failed' => '迁移失败',
|
|
default => $stage === null
|
|
? '迁移进行中' : '正在' . (string) $stage['label'],
|
|
};
|
|
}
|
|
}
|