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

538 lines
20 KiB
PHP

<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
/** The one executable definition for cloud-template import intents. */
final class CloudTemplateImportStateMachine
{
public const SOURCE_UPLOAD = 'upload';
public const SOURCE_REMOTE = 'remote';
public const ACTION_START_UPLOAD = 'start_upload';
public const ACTION_RECONCILE_MULTIPART_START =
'reconcile_multipart_start';
public const ACTION_RECORD_PART = 'record_part';
public const ACTION_COMPLETE_UPLOAD = 'complete_upload';
public const ACTION_RESUME_REMOTE = 'resume_remote';
public const ACTION_CANCEL = 'cancel';
/**
* Every state owns its source compatibility, public actions and lifecycle
* policies. Callers must not maintain parallel state lists.
*
* @var array<string,array{
* resume_step:string,transitions:list<string>,sources:list<string>,
* actions:array<string,list<string>>,resumable:list<string>,
* cancellable:list<string>,cleanup:list<string>,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<string,array<string,mixed>> */
public static function definitions(): array
{
self::assertIntegrity();
return self::DEFINITIONS;
}
/** @return list<string> */
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<string> */
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<string,array<string,mixed>> $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);
}
}
}