,sources:list, * actions:array>,resumable:list, * cancellable:list,cleanup:list,terminal:bool}> */ private const DEFINITIONS = [ 'prepared' => [ 'resume_step' => 'acquire', 'transitions' => ['uploading', 'fetching', 'cancelled'], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['start_upload', 'cancel'], 'remote' => ['resume_remote', 'cancel'], ], 'resumable' => ['upload', 'remote'], 'cancellable' => ['upload', 'remote'], 'cleanup' => ['upload', 'remote'], 'terminal' => false, ], 'uploading' => [ 'resume_step' => 'acquire', 'transitions' => [ 'source_verifying', 'upload_failed', 'source_unknown', 'cancel_pending', ], 'sources' => ['upload'], 'actions' => [ 'upload' => [ 'start_upload', 'record_part', 'complete_upload', 'cancel', ], ], 'resumable' => ['upload'], 'cancellable' => ['upload'], 'cleanup' => ['upload'], 'terminal' => false, ], 'fetching' => [ 'resume_step' => 'acquire', 'transitions' => [ 'source_verifying', 'source_failed', 'source_unknown', 'cancelled', ], 'sources' => ['remote'], 'actions' => ['remote' => ['resume_remote', 'cancel']], 'resumable' => ['remote'], 'cancellable' => ['remote'], 'cleanup' => ['remote'], 'terminal' => false, ], 'source_verifying' => [ 'resume_step' => 'verify', 'transitions' => [ 'source_ready', 'upload_failed', 'source_failed', 'source_unknown', ], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['complete_upload'], 'remote' => ['resume_remote'], ], 'resumable' => ['upload', 'remote'], 'cancellable' => [], 'cleanup' => [], 'terminal' => false, ], 'source_ready' => [ 'resume_step' => 'publish', 'transitions' => ['distributing', 'cancel_pending'], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['complete_upload'], 'remote' => ['resume_remote'], ], 'resumable' => ['upload', 'remote'], 'cancellable' => [], 'cleanup' => [], 'terminal' => false, ], 'distributing' => [ 'resume_step' => 'published', 'transitions' => ['ready', 'distribution_failed'], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['complete_upload'], 'remote' => ['resume_remote'], ], 'resumable' => [], 'cancellable' => [], 'cleanup' => [], 'terminal' => false, ], 'ready' => [ 'resume_step' => 'published', 'transitions' => [], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['complete_upload'], 'remote' => ['resume_remote'], ], 'resumable' => [], 'cancellable' => [], 'cleanup' => [], 'terminal' => true, ], 'upload_failed' => [ 'resume_step' => 'acquire', 'transitions' => ['uploading', 'cancel_pending', 'cancelled'], 'sources' => ['upload'], 'actions' => [ 'upload' => ['start_upload', 'complete_upload', 'cancel'], ], 'resumable' => ['upload'], 'cancellable' => ['upload'], 'cleanup' => ['upload'], 'terminal' => false, ], 'source_failed' => [ 'resume_step' => 'acquire', 'transitions' => ['fetching', 'cancelled'], 'sources' => ['remote'], 'actions' => ['remote' => ['resume_remote', 'cancel']], 'resumable' => ['remote'], 'cancellable' => ['remote'], 'cleanup' => ['remote'], 'terminal' => false, ], 'source_unknown' => [ 'resume_step' => 'verify', 'transitions' => [ 'uploading', 'source_verifying', 'cancel_pending', ], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => [ 'reconcile_multipart_start', 'complete_upload', 'cancel', ], 'remote' => ['resume_remote'], ], 'resumable' => ['upload', 'remote'], 'cancellable' => ['upload'], 'cleanup' => ['upload'], 'terminal' => false, ], 'distribution_failed' => [ 'resume_step' => 'published', 'transitions' => ['distributing', 'cancel_pending'], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['complete_upload'], 'remote' => ['resume_remote'], ], 'resumable' => [], 'cancellable' => [], 'cleanup' => [], 'terminal' => false, ], 'cancel_pending' => [ 'resume_step' => 'cancel', 'transitions' => ['cancelled', 'source_unknown'], 'sources' => ['upload'], 'actions' => ['upload' => ['cancel']], 'resumable' => [], 'cancellable' => [], 'cleanup' => ['upload'], 'terminal' => false, ], 'cancelled' => [ 'resume_step' => 'cancel', 'transitions' => [], 'sources' => ['upload', 'remote'], 'actions' => [ 'upload' => ['cancel'], 'remote' => ['cancel'], ], 'resumable' => [], 'cancellable' => [], 'cleanup' => [], 'terminal' => true, ], ]; /** @return array> */ public static function definitions(): array { self::assertIntegrity(); return self::DEFINITIONS; } /** @return list */ public static function states(): array { return array_keys(self::definitions()); } public static function move( CloudTemplateImportIntent $intent, string $next ): void { $source = (string) $intent->source_kind; $current = (string) $intent->state; self::assertSourceState($source, $current); self::assertTransition($current, $next); self::assertSourceState($source, $next); $intent->state = $next; $intent->completed_at = self::terminal($next) ? time() : null; } public static function assertTransition(string $current, string $next): void { self::assertIntegrity(); if ($current === $next && isset(self::DEFINITIONS[$current])) { return; } if (!isset(self::DEFINITIONS[$current]) || !in_array($next, self::DEFINITIONS[$current]['transitions'], true)) { throw new CloudError(sprintf( '云镜像导入状态不能从 %s 变更为 %s', $current === '' ? '(empty)' : $current, $next === '' ? '(empty)' : $next ), 409); } } public static function assertAction( CloudTemplateImportIntent $intent, string $action ): void { $source = (string) $intent->source_kind; $state = (string) $intent->state; self::assertSourceState($source, $state); $actions = self::DEFINITIONS[$state]['actions'][$source] ?? []; if (!in_array($action, $actions, true)) { throw new CloudError('当前导入状态不能执行该操作', 409); } if ($action === self::ACTION_CANCEL && $state === 'source_unknown' && !self::capabilities($intent)['can_cancel']) { throw new CloudError('当前上传结果尚未确认,不能终止原分段上传', 409); } if ($action === self::ACTION_RECONCILE_MULTIPART_START && (string) $intent->multipart_upload_id !== '') { throw new CloudError('原分段上传身份已存在,不能重新创建会话', 409); } } public static function resumeStep(CloudTemplateImportIntent $intent): string { self::assertSourceState((string) $intent->source_kind, (string) $intent->state); return self::DEFINITIONS[(string) $intent->state]['resume_step']; } /** Provider proof that a previous abort was not applied. */ public static function retryableAbortCodes(): array { return ['multipart_abort_rejected', 'multipart_abort_not_applied']; } /** @return array{can_resume:bool,can_cancel:bool} */ public static function capabilities( CloudTemplateImportIntent $intent ): array { $source = (string) $intent->source_kind; $state = (string) $intent->state; self::assertSourceState($source, $state); $definition = self::DEFINITIONS[$state]; $canCancel = in_array($source, $definition['cancellable'], true); if ($canCancel && $source === self::SOURCE_UPLOAD && $state === 'source_unknown') { $canCancel = (string) $intent->multipart_upload_id === '' || in_array((string) $intent->error_code, self::retryableAbortCodes(), true); } return [ 'can_resume' => in_array( $source, $definition['resumable'], true ), 'can_cancel' => $canCancel, ]; } /** @return list */ public static function cleanupStates(string $source): array { self::assertSource($source); $states = []; foreach (self::definitions() as $state => $definition) { if (in_array($source, $definition['cleanup'], true)) { $states[] = $state; } } return $states; } public static function terminal(string $state): bool { self::assertIntegrity(); return (self::DEFINITIONS[$state]['terminal'] ?? false) === true; } public static function assertIntegrity(): void { self::assertDefinitions(self::DEFINITIONS); } /** @param array> $definitions */ public static function assertDefinitions(array $definitions): void { $sources = [self::SOURCE_UPLOAD, self::SOURCE_REMOTE]; $actions = [ self::ACTION_START_UPLOAD, self::ACTION_RECONCILE_MULTIPART_START, self::ACTION_RECORD_PART, self::ACTION_COMPLETE_UPLOAD, self::ACTION_RESUME_REMOTE, self::ACTION_CANCEL, ]; foreach ($definitions as $state => $definition) { if ($state === '' || array_keys($definition) !== [ 'resume_step', 'transitions', 'sources', 'actions', 'resumable', 'cancellable', 'cleanup', 'terminal', ]) { throw new \LogicException( 'Cloud-template import definition is incomplete' ); } foreach (['transitions', 'sources', 'resumable', 'cancellable', 'cleanup'] as $list) { if (!is_array($definition[$list]) || !array_is_list($definition[$list]) || count($definition[$list]) !== count(array_unique($definition[$list]))) { throw new \LogicException( 'Cloud-template import definition list is invalid' ); } } if (!in_array($definition['resume_step'], ['acquire', 'verify', 'publish', 'published', 'cancel'], true) || $definition['sources'] === [] || array_diff($definition['sources'], $sources) !== [] || array_diff($definition['resumable'], $definition['sources']) !== [] || array_diff($definition['cancellable'], $definition['sources']) !== [] || array_diff($definition['cleanup'], $definition['sources']) !== [] || !is_bool($definition['terminal']) || !is_array($definition['actions'])) { throw new \LogicException( 'Cloud-template import source policy is invalid' ); } foreach ($definition['actions'] as $source => $stateActions) { if (!in_array($source, $definition['sources'], true) || !is_array($stateActions) || !array_is_list($stateActions) || count($stateActions) !== count(array_unique($stateActions)) || array_diff($stateActions, $actions) !== []) { throw new \LogicException( 'Cloud-template import action policy is invalid' ); } } foreach ($definition['sources'] as $source) { $stateActions = $definition['actions'][$source] ?? null; if (!is_array($stateActions) || $stateActions === []) { throw new \LogicException( 'Cloud-template import source has no action definition' ); } $step = $definition['resume_step']; if ($step === 'cancel') { if ($stateActions !== [self::ACTION_CANCEL] || $definition['resumable'] !== []) { throw new \LogicException('Cloud-template cancellation step has an incompatible action'); } } else { $resumeAction = $source === self::SOURCE_REMOTE ? self::ACTION_RESUME_REMOTE : ($step === 'acquire' ? self::ACTION_START_UPLOAD : self::ACTION_COMPLETE_UPLOAD); if (!in_array($resumeAction, $stateActions, true) || ($source === self::SOURCE_UPLOAD && $step !== 'acquire' && array_intersect($stateActions, [self::ACTION_START_UPLOAD, self::ACTION_RECORD_PART]) !== [])) { throw new \LogicException('Cloud-template resume step has no compatible execution action'); } } if ((in_array($source, $definition['cancellable'], true) || in_array($source, $definition['cleanup'], true)) && !in_array(self::ACTION_CANCEL, $stateActions, true)) { throw new \LogicException( 'Cloud-template import cancellation outlet is missing' ); } if (in_array($source, $definition['resumable'], true)) { $resumeActions = $source === self::SOURCE_REMOTE ? [self::ACTION_RESUME_REMOTE] : [self::ACTION_START_UPLOAD, self::ACTION_COMPLETE_UPLOAD]; if (array_intersect($resumeActions, $stateActions) === []) { throw new \LogicException( 'Cloud-template import resume outlet is missing' ); } } } if ($state === 'uploading' && !in_array(self::ACTION_RECORD_PART, $definition['actions']['upload'] ?? [], true)) { throw new \LogicException( 'Cloud-template import part receipt outlet is missing' ); } foreach ($definition['transitions'] as $target) { if (!isset($definitions[$target])) { throw new \LogicException(sprintf( 'Cloud-template import state %s references unknown state %s', $state, $target )); } if (array_intersect( $definition['sources'], $definitions[$target]['sources'] ?? [] ) === []) { throw new \LogicException( 'Cloud-template import transition has no compatible source' ); } } if ($definition['terminal'] === true && ($definition['transitions'] !== [] || $definition['resumable'] !== [] || $definition['cancellable'] !== [] || $definition['cleanup'] !== [])) { throw new \LogicException( 'Cloud-template import terminal policy is invalid' ); } } foreach (['ready', 'cancelled'] as $terminal) { if (($definitions[$terminal]['terminal'] ?? null) !== true) { throw new \LogicException( 'Cloud-template import terminal state is missing' ); } } foreach ($definitions as $state => $definition) { foreach ($definition['sources'] as $source) { if ($definition['resume_step'] !== 'cancel' && !self::canReach($definitions, $state, 'ready', $source)) { throw new \LogicException('Cloud-template import has no successful publication path'); } if ((in_array($source, $definition['cancellable'], true) || in_array($source, $definition['cleanup'], true)) && !self::canReach($definitions, $state, 'cancelled', $source)) { throw new \LogicException('Cloud-template import has no cancellation path'); } } } } private static function canReach(array $definitions, string $from, string $target, string $source): bool { $pending = [$from]; $visited = []; while ($pending !== []) { $state = array_pop($pending); if (isset($visited[$state]) || !in_array($source, $definitions[$state]['sources'], true)) { continue; } if ($state === $target) { return true; } $visited[$state] = true; array_push($pending, ...$definitions[$state]['transitions']); } return false; } private static function assertSourceState( string $source, string $state ): void { self::assertSource($source); self::assertIntegrity(); if (!isset(self::DEFINITIONS[$state]) || !in_array($source, self::DEFINITIONS[$state]['sources'], true)) { throw new CloudError( '云镜像导入来源与状态不一致', 409 ); } } private static function assertSource(string $source): void { if (!in_array($source, [self::SOURCE_UPLOAD, self::SOURCE_REMOTE], true)) { throw new CloudError('云镜像导入来源无效', 409); } } }