refactor(template): split import workflow modules

go
codex 2 weeks ago
parent 12b3357048
commit ad68a5bef1

@ -15,7 +15,10 @@ use App\Services\Cloud\CloudRescueCatalogService;
use App\Services\Cloud\CloudRescueTemplateReplicaCoordinator;
use App\Services\Cloud\CloudRescueTemplateRetirementService;
use App\Services\Cloud\CloudTemplateCatalogService;
use App\Services\Cloud\CloudTemplateImportWorkflow;
use App\Services\Cloud\CloudTemplateImportCancellation;
use App\Services\Cloud\CloudTemplateImportReadModel;
use App\Services\Cloud\CloudTemplateMultipartAcquisition;
use App\Services\Cloud\CloudTemplateRemoteAcquisition;
use App\Services\Cloud\CloudTemplateReplicaCoordinator;
use App\Services\Cloud\CloudUserIsoFeature;
@ -375,12 +378,13 @@ final class CloudAdminController
{
$write = $request->getMethod() === 'POST';
$actor = $this->actor($request, $write);
$workflow = new CloudTemplateImportWorkflow();
if (!$write) {
return $response->withJson($workflow->active($actor))
return $response->withJson(
(new CloudTemplateImportReadModel())->active($actor)
)
->withHeader('Cache-Control', 'no-store');
}
$result = $workflow->beginUpload(
$result = (new CloudTemplateMultipartAcquisition())->beginUpload(
CloudInput::object($request),
$actor
);
@ -394,7 +398,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->importRemote(
(new CloudTemplateRemoteAcquisition())->importRemote(
CloudInput::object($request),
$actor
),
@ -406,7 +410,7 @@ final class CloudAdminController
{
$actor = $this->actor($request);
return $response->withJson(
(new CloudTemplateImportWorkflow())->one(
(new CloudTemplateImportReadModel())->one(
(string) ($args['id'] ?? ''),
$actor
)['intent']
@ -417,7 +421,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->resumeRemote(
(new CloudTemplateRemoteAcquisition())->resumeRemote(
(string) ($args['id'] ?? ''),
$actor
),
@ -429,7 +433,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->cancel(
(new CloudTemplateImportCancellation())->cancel(
(string) ($args['id'] ?? ''),
$actor
)
@ -440,7 +444,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->startUpload(
(new CloudTemplateMultipartAcquisition())->startUpload(
(string) ($args['id'] ?? ''),
$actor
)
@ -451,7 +455,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->recordPart(
(new CloudTemplateMultipartAcquisition())->recordPart(
(string) ($args['id'] ?? ''),
(int) ($args['part'] ?? 0),
CloudInput::object($request),
@ -464,7 +468,7 @@ final class CloudAdminController
{
$actor = $this->actor($request, true);
return $response->withJson(
(new CloudTemplateImportWorkflow())->completeUpload(
(new CloudTemplateMultipartAcquisition())->completeUpload(
(string) ($args['id'] ?? ''),
CloudInput::object($request),
$actor

@ -964,7 +964,7 @@ final class CloudTemplateCatalogService
CloudTemplateStateMachine::moveTemplate($template, 'retired');
$template->updated_at = time();
$template->save();
CloudTemplateImportWorkflow::settleDistributionLocked(
CloudTemplateImportPublication::settleDistributionLocked(
$template,
$parent,
false
@ -1117,7 +1117,7 @@ final class CloudTemplateCatalogService
$template->save();
}
if ($success) {
CloudTemplateImportWorkflow::settleDistributionLocked(
CloudTemplateImportPublication::settleDistributionLocked(
$template,
$parent,
true
@ -1126,7 +1126,7 @@ final class CloudTemplateCatalogService
true, false, '', ['template_id' => (string) $template->id]);
return;
}
CloudTemplateImportWorkflow::settleDistributionLocked(
CloudTemplateImportPublication::settleDistributionLocked(
$template,
$parent,
false
@ -1277,7 +1277,7 @@ final class CloudTemplateCatalogService
$template->updated_at = time();
$template->save();
if ((string) $parent->kind === 'template_import') {
CloudTemplateImportWorkflow::settleDistributionLocked(
CloudTemplateImportPublication::settleDistributionLocked(
$template,
$parent,
false

@ -0,0 +1,297 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
/** Cancels imports and performs bounded cleanup of expired intents. */
final class CloudTemplateImportCancellation extends CloudTemplateImportModule
{
public function cancel(
string $id,
array $actor,
?CloudObjectStorageS3Client $client = null
): array {
CloudAccess::manage($actor);
return $this->cancelIntent(
self::intentId($id),
$client ?? new CloudObjectStorageS3Client(),
false
);
}
public function cleanupOneExpired(
?CloudObjectStorageS3Client $client = null
): bool {
$model = new CloudTemplateImportIntent();
$connection = $model->getConnection();
if (!$connection->getSchemaBuilder()->hasTable(
$model->getTable()
)) {
return false;
}
$now = ($this->clock)();
$candidate = CloudTemplateImportIntent::query()
->where('expires_at', '<=', $now)
->where(static function ($query): void {
$query->whereIn('state', [
'prepared', 'fetching', 'uploading', 'upload_failed',
'source_failed', 'cancel_pending',
])->orWhere(static function ($unknown): void {
$unknown->where('source_kind', 'upload')
->where('state', 'source_unknown')
->where(static function ($recoverable): void {
$recoverable->where('multipart_upload_id', '')
->orWhereIn('error_code', [
'multipart_abort_rejected',
'multipart_abort_not_applied',
]);
});
});
})
->orderBy('expires_at')->orderBy('id')->first();
if ($candidate === null) {
return false;
}
$this->cancelIntent(
(string) $candidate->id,
$client ?? new CloudObjectStorageS3Client(),
true
);
return true;
}
private function cancelIntent(
string $id,
CloudObjectStorageS3Client $client,
bool $expiredOnly
): array {
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
$prepared = $connection->transaction(static function () use (
$id,
$expiredOnly,
$now
): array {
$intent = self::lockIntent($id);
if ($expiredOnly && (int) $intent->expires_at > $now) {
return ['done' => true, 'intent' => $intent];
}
$state = (string) $intent->state;
if ($state === 'cancelled') {
return ['done' => true, 'intent' => $intent];
}
if ($state === 'ready') {
throw new CloudError('已发布的云镜像不能作为上传取消', 409);
}
if ((string) $intent->source_kind === 'remote') {
if (!in_array($state, [
'prepared', 'fetching', 'source_failed',
], true)) {
throw new CloudError(
'远程云镜像已进入对象存储核对,不能直接取消',
409
);
}
CloudTemplateImportStateMachine::move(
$intent,
'cancelled'
);
$intent->error_code = '';
$intent->completed_at = $now;
$intent->updated_at = $now;
$intent->save();
return ['done' => true, 'intent' => $intent];
}
if ((string) $intent->source_kind !== 'upload') {
throw new CloudError('云镜像导入来源无效', 409);
}
$uploadId = (string) $intent->multipart_upload_id;
if ($uploadId === '') {
if ($state === 'uploading' && !$expiredOnly
&& (int) $intent->updated_at > $now - 120) {
throw new CloudError(
'对象存储上传会话正在创建,请稍后再取消',
409
);
}
if (!in_array($state, [
'prepared', 'uploading', 'upload_failed',
'source_unknown', 'cancel_pending',
], true)) {
throw new CloudError('当前导入状态不能取消', 409);
}
if (in_array($state, ['prepared', 'upload_failed'], true)) {
CloudTemplateImportStateMachine::move(
$intent,
'cancelled'
);
$intent->error_code = '';
} else {
if ($state !== 'cancel_pending') {
CloudTemplateImportStateMachine::move(
$intent,
'cancel_pending'
);
}
CloudTemplateImportStateMachine::move(
$intent,
'cancelled'
);
$intent->error_code = 'multipart_abandoned_lifecycle';
}
$intent->completed_at = $now;
$intent->updated_at = $now;
$intent->save();
return ['done' => true, 'intent' => $intent];
}
$retryableUnknown = $state === 'source_unknown'
&& in_array((string) $intent->error_code, [
'multipart_abort_rejected',
'multipart_abort_not_applied',
], true);
if (!in_array($state,
['uploading', 'upload_failed', 'cancel_pending'], true)
&& !$retryableUnknown) {
throw new CloudError(
'当前上传结果尚未确认,不能终止原分段上传',
409
);
}
$reconcileFirst = $state === 'cancel_pending';
if (!$reconcileFirst) {
CloudTemplateImportStateMachine::move(
$intent,
'cancel_pending'
);
$intent->error_code = 'multipart_abort_pending';
// If PHP stops after this commit, the worker can immediately
// reconcile the pending cancellation from provider evidence.
$intent->expires_at = $now;
$intent->updated_at = $now;
$intent->save();
}
return [
'done' => false,
'intent' => $intent,
'reconcile_first' => $reconcileFirst,
];
}, 3);
/** @var CloudTemplateImportIntent $intent */
$intent = $prepared['intent'];
if (($prepared['done'] ?? false) === true) {
return self::dto($intent);
}
if (($prepared['reconcile_first'] ?? false) === true) {
$evidence = $this->cancellationEvidence($intent, $client);
if ($evidence === 'absent') {
return self::settleCancelled($id, $now);
}
if ($evidence !== 'active') {
self::settleCancelUnknown($id, $evidence, $now);
throw new CloudError(
'无法确认原分段上传是否已终止,请勿重复取消',
502
);
}
}
$runtime = self::runtime($intent);
try {
$client->abortMultipartUpload(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id
);
return self::settleCancelled($id, $now);
} catch (CloudObjectStorageTransferError $error) {
$evidence = $this->cancellationEvidence($intent, $client);
if ($evidence === 'absent') {
return self::settleCancelled($id, $now);
}
$code = $evidence === 'active'
? 'multipart_abort_not_applied' : $evidence;
self::settleCancelUnknown($id, $code, $now);
throw new CloudError(
$evidence === 'active'
? '对象存储尚未终止分段上传,可以稍后重新取消'
: '无法确认原分段上传是否已终止,请勿重复取消',
$evidence === 'active' ? 409 : 502
);
}
}
private function cancellationEvidence(
CloudTemplateImportIntent $intent,
CloudObjectStorageS3Client $client
): string {
$runtime = self::runtime($intent);
try {
if ($client->inspectObject(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key
) !== null) {
return 'multipart_abort_object_present';
}
} catch (CloudObjectStorageTransferError $error) {
return $error->publicCode;
}
try {
$client->listMultipartParts(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id
);
return 'active';
} catch (CloudObjectStorageTransferError $error) {
return $error->publicCode === 'multipart_upload_absent'
? 'absent' : $error->publicCode;
}
}
private static function settleCancelled(string $id, int $now): array
{
$connection = (new CloudTemplateImportIntent())->getConnection();
return $connection->transaction(static function () use (
$id,
$now
): array {
$intent = self::lockIntent($id);
if ((string) $intent->state !== 'cancelled') {
if ((string) $intent->state !== 'cancel_pending') {
throw new CloudError('上传取消状态已变化,请刷新页面', 409);
}
CloudTemplateImportStateMachine::move($intent, 'cancelled');
}
$intent->error_code = '';
$intent->completed_at = $now;
$intent->updated_at = $now;
$intent->save();
return self::dto($intent);
}, 3);
}
private static function settleCancelUnknown(
string $id,
string $code,
int $now
): void {
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use (
$id,
$code,
$now
): void {
$intent = self::lockIntent($id);
if ((string) $intent->state !== 'cancel_pending') {
return;
}
CloudTemplateImportStateMachine::move($intent, 'source_unknown');
$intent->error_code = substr($code, 0, 128);
$intent->updated_at = $now;
$intent->save();
}, 3);
}
}

@ -0,0 +1,309 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
use App\Models\CloudTemplateImportPart;
/**
* Shared invariant kernel for the cloud-template import modules.
*
* HTTP orchestration stays in the concrete modules. This class only owns the
* frozen storage ledger, identifiers, validation and the public projection.
*/
abstract class CloudTemplateImportModule
{
public const MIN_UPLOAD_BYTES = 1048576;
public const MAX_UPLOAD_BYTES = 4294967296;
protected const INTENT_TTL_SECONDS = 86400;
protected const SOURCE_PURPOSE = 'template-import-source';
protected const RUNTIME_PURPOSE = 'template-import-runtime';
/** @var callable():array<string,mixed> */
protected $runtimeProvider;
/** @var callable():int */
protected $clock;
public function __construct(
?callable $runtimeProvider = null,
?callable $clock = null
) {
$this->runtimeProvider = $runtimeProvider
?? static fn (): array => CloudObjectStorageConfig::runtime(true);
$this->clock = $clock ?? time(...);
}
protected static function lockIntent(string $id): CloudTemplateImportIntent
{
$intent = CloudTemplateImportIntent::query()
->where('id', $id)->lockForUpdate()->first();
if ($intent === null) {
throw new CloudError('云镜像导入记录不存在', 404);
}
return $intent;
}
protected static function runtime(CloudTemplateImportIntent $intent): array
{
$runtime = CloudSecrets::decrypt(
(string) $intent->sealed_storage_runtime,
self::RUNTIME_PURPOSE
);
$config = $runtime['config'] ?? null;
$credentials = $runtime['credentials'] ?? null;
$revision = $runtime['revision'] ?? null;
if (!is_array($config) || array_is_list($config)
|| !is_array($credentials) || array_is_list($credentials)
|| !is_int($revision) || $revision < 1
|| $revision !== (int) $intent->storage_revision) {
throw new CloudError('模板对象存储运行时无效', 503);
}
foreach (['endpoint', 'region', 'bucket', 'prefix'] as $field) {
if (!is_string($config[$field] ?? null)) {
throw new CloudError('模板对象存储运行时无效', 503);
}
}
if (!is_bool($config['path_style'] ?? null)
|| !is_string($credentials['access_key_id'] ?? null)
|| (string) $credentials['access_key_id'] === ''
|| !is_string($credentials['secret_access_key'] ?? null)
|| (string) $credentials['secret_access_key'] === '') {
throw new CloudError('模板对象存储运行时无效', 503);
}
return [
'config' => $config,
'credentials' => $credentials,
'revision' => $revision,
];
}
protected static function dto(CloudTemplateImportIntent $intent): array
{
$parts = CloudTemplateImportPart::query()
->where('intent_id', (string) $intent->id)
->orderBy('part_number')->get()->map(
static fn (CloudTemplateImportPart $part): array => [
'part_number' => (int) $part->part_number,
'size_bytes' => (int) $part->size_bytes,
]
)->all();
$uploadedParts = count($parts);
$uploadedBytes = array_sum(array_column($parts, 'size_bytes'));
$state = (string) $intent->state;
$capabilities = CloudTemplateImportStateMachine::capabilities($intent);
return [
'id' => (string) $intent->id,
'source_kind' => (string) $intent->source_kind,
'name' => (string) $intent->name,
'os_family' => (string) $intent->os_family,
'os_version' => (string) $intent->os_version,
'source_filename' => (string) $intent->source_filename,
'source_size_bytes' => (int) $intent->source_size_bytes,
'source_last_modified' => (int) $intent->source_last_modified,
'source_sha256' => (string) $intent->source_sha256,
'template_id' => (string) $intent->template_id,
'state' => $state,
'uploaded_parts' => $uploadedParts,
'uploaded_bytes' => $uploadedBytes,
'parts' => $parts,
'part_count' => (int) $intent->multipart_part_count,
'part_size_bytes' => (int) $intent->multipart_part_size_bytes,
'can_resume' => $capabilities['can_resume'],
'can_cancel' => $capabilities['can_cancel'],
'task_id' => $intent->active_job_id === null
? null : (int) $intent->active_job_id,
'error_code' => (string) $intent->error_code,
'expires_at' => (int) $intent->expires_at,
'completed_at' => $intent->completed_at === null
? null : (int) $intent->completed_at,
'created_at' => (int) $intent->created_at,
'updated_at' => (int) $intent->updated_at,
];
}
protected static function assertAdministrator(array $actor): void
{
if (($actor['is_admin'] ?? false) !== true) {
throw new CloudError('需要管理员权限', 403);
}
}
protected static function requestKey(array $actor): string
{
$key = $actor['request_idempotency_key'] ?? null;
if (!is_string($key)
|| preg_match('/^[A-Za-z0-9_.-]{16,128}$/D', $key) !== 1) {
throw new CloudError('请求幂等标识无效', 400);
}
return $key;
}
protected static function intentId(string $id): string
{
if (preg_match('/^[a-f0-9]{32}$/D', $id) !== 1) {
throw new CloudError('云镜像导入标识无效', 422);
}
return $id;
}
protected static function fingerprint(array $canonical): string
{
ksort($canonical, SORT_STRING);
return hash('sha256', json_encode(
$canonical,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
| JSON_UNESCAPED_UNICODE
));
}
protected static function remoteSource(
CloudTemplateImportIntent $intent
): array {
$source = CloudSecrets::decrypt(
(string) $intent->sealed_source,
self::SOURCE_PURPOSE
);
if (($source['kind'] ?? null) !== 'remote'
|| !is_string($source['url'] ?? null)
|| !is_string($source['expected_sha256'] ?? null)) {
throw new CloudError('远程云镜像来源账本无效', 503);
}
$url = self::remoteUrl($source['url']);
$sha256 = strtolower(trim($source['expected_sha256']));
if ($sha256 !== ''
&& preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new CloudError('远程云镜像来源账本无效', 503);
}
return ['url' => $url, 'expected_sha256' => $sha256];
}
protected static function remoteUrl($value): string
{
if (!is_string($value) || strlen($value) > 2048
|| preg_match('//u', $value) !== 1) {
throw new CloudError('云镜像地址无效');
}
$value = trim($value);
$parts = parse_url($value);
if (!is_array($parts)
|| strtolower((string) ($parts['scheme'] ?? '')) !== 'https'
|| !is_string($parts['host'] ?? null) || $parts['host'] === ''
|| isset($parts['user']) || isset($parts['pass'])
|| isset($parts['fragment'])
|| (isset($parts['port']) && (int) $parts['port'] !== 443)
|| !str_ends_with(strtolower((string) ($parts['path'] ?? '')),
'.qcow2')) {
throw new CloudError(
'请填写无需账号、使用 443 端口的 HTTPS 镜像直链'
);
}
return $value;
}
protected static function inferRemoteSystem(
string $url,
string $name
): array {
$haystack = strtolower($url . ' ' . $name);
$families = [
'AlmaLinux' => ['almalinux', ['10', '9', '8']],
'Debian' => ['debian', ['13', '12', '11']],
'Ubuntu' => ['ubuntu', ['26.04', '25.10', '25.04', '24.04',
'22.04', '20.04']],
'CentOS Stream' => ['centos', ['10', '9']],
];
foreach ($families as $family => [$needle, $versions]) {
if (!str_contains($haystack, $needle)) {
continue;
}
foreach ($versions as $version) {
if (preg_match('/(?:^|[^0-9])' . preg_quote($version, '/')
. '(?:[^0-9]|$)/', $haystack) === 1) {
return [$family, $version];
}
}
}
throw new CloudError(
'无法从名称或官方地址识别受支持的系统版本'
);
}
protected static function remoteFilename(string $url): string
{
$path = parse_url($url, PHP_URL_PATH);
$filename = is_string($path) ? basename($path) : '';
if ($filename === '' || strlen($filename) > 255
|| preg_match('/\.qcow2$/iD', $filename) !== 1) {
throw new CloudError('官方云镜像文件名无效', 422);
}
return $filename;
}
protected static function filename($value): string
{
if (!is_string($value) || strlen($value) > 255
|| str_contains($value, "\0")
|| preg_match('/\.qcow2$/iD', $value) !== 1) {
throw new CloudError('请选择扩展名为 .qcow2 的云镜像文件');
}
return $value;
}
protected static function label($value, string $label, int $maximum): string
{
if (!is_string($value) || preg_match('//u', $value) !== 1) {
throw new CloudError($label . '无效');
}
$value = trim($value);
if ($value === '' || mb_strlen($value, 'UTF-8') > $maximum
|| preg_match('/[\x00-\x1f\x7f]/u', $value) === 1) {
throw new CloudError($label . '无效');
}
return $value;
}
protected static function integer(
$value,
int $minimum,
int $maximum,
string $message
): int {
$integer = filter_var($value, FILTER_VALIDATE_INT, [
'options' => ['min_range' => $minimum, 'max_range' => $maximum],
]);
if ($integer === false) {
throw new CloudError($message, 422);
}
return (int) $integer;
}
protected static function newTemplateId(string $family,
string $version): string
{
$prefix = strtolower(preg_replace('/[^A-Za-z0-9]+/', '-',
$family . '-' . $version) ?? 'image');
return substr(trim($prefix, '-'), 0, 55) . '-'
. bin2hex(random_bytes(8));
}
protected static function catalogKey(string $family, string $version): string
{
$key = strtolower(preg_replace('/[^A-Za-z0-9]+/', '-',
$family . '-' . $version) ?? 'image');
$key = trim($key, '-');
if ($key === '' || strlen($key) > 80) {
throw new CloudError('云镜像目录标识无效', 422);
}
return $key;
}
protected static function runtimeRevision(array $runtime): int
{
$revision = $runtime['revision'] ?? null;
if (!is_int($revision) || $revision < 1) {
throw new CloudError('模板对象存储运行时无效', 503);
}
return $revision;
}
}

@ -0,0 +1,217 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudJob;
use App\Models\CloudTemplate;
use App\Models\CloudTemplateImportIntent;
/** Publishes a verified object and settles its host-distribution outcome. */
final class CloudTemplateImportPublication extends CloudTemplateImportModule
{
public function acceptCompletedIdentity(string $id, array $identity): void
{
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
$accepted = $connection->transaction(static function () use (
$id,
$identity,
$now
): bool {
$locked = self::lockIntent($id);
if (!in_array((string) $locked->state,
['source_verifying', 'source_unknown'], true)) {
throw new CloudError('上传完成状态已变化,请刷新页面', 409);
}
if ((int) ($identity['size_bytes'] ?? 0)
!== (int) $locked->source_size_bytes
|| !is_string($identity['etag'] ?? null)
|| trim((string) $identity['etag']) === '') {
if ((string) $locked->state === 'source_verifying') {
CloudTemplateImportStateMachine::move(
$locked,
'source_unknown'
);
}
$locked->error_code = 'multipart_object_identity_mismatch';
$locked->updated_at = $now;
$locked->save();
return false;
}
if ((string) $locked->state === 'source_unknown') {
CloudTemplateImportStateMachine::move(
$locked,
'source_verifying'
);
}
$locked->object_version_id =
(string) ($identity['version_id'] ?? '');
$locked->object_etag = (string) $identity['etag'];
CloudTemplateImportStateMachine::move($locked, 'source_ready');
$locked->error_code = '';
$locked->updated_at = $now;
$locked->save();
return true;
}, 3);
if (!$accepted) {
throw new CloudError(
'上传对象身份与导入意图不一致,记录已锁定',
409
);
}
}
public function finalizeReadyIntent(
string $id,
array $actor,
?CloudObjectStorageS3Client $client = null
): array
{
$connection = (new CloudTemplateImportIntent())->getConnection();
$prepared = $connection->transaction(static function () use (
$id
): array {
$intent = self::lockIntent($id);
if (in_array((string) $intent->state,
['distributing', 'ready', 'distribution_failed'], true)) {
$job = $intent->active_job_id === null ? null
: CloudJob::query()
->where('id', (int) $intent->active_job_id)
->lockForUpdate()->first();
if ($job === null || (string) $job->kind !== 'template_import'
|| (int) $job->user_id !== (int) $intent->user_id) {
throw new CloudError('云镜像导入任务账本不完整', 409);
}
return ['ack' => CloudJobService::acknowledgement($job)];
}
if ((string) $intent->state !== 'source_ready'
|| preg_match('/^[a-f0-9]{64}$/D',
(string) $intent->source_sha256) !== 1
|| trim((string) $intent->object_etag) === '') {
throw new CloudError('云镜像导入源尚未就绪', 409);
}
$template = CloudTemplate::query()
->where('id', (string) $intent->template_id)
->lockForUpdate()->first();
if ($template === null) {
$now = time();
$template = new CloudTemplate();
$template->id = (string) $intent->template_id;
$template->catalog_key = (string) $intent->catalog_key;
$template->version_label = (string) $intent->version_label;
$template->is_default = 0;
$template->name = (string) $intent->name;
$template->os_family = (string) $intent->os_family;
$template->os_version = (string) $intent->os_version;
$template->image_bytes = (int) $intent->source_size_bytes;
$template->sha256 = (string) $intent->source_sha256;
$template->startup_script = '';
$template->revision = 1;
$template->generation_token =
(string) $intent->generation_token;
$template->state = 'preparing';
$template->active_job_id = null;
$template->created_at = $template->updated_at = $now;
$template->save();
} elseif ((string) $template->catalog_key
!== (string) $intent->catalog_key
|| (string) $template->generation_token
!== (string) $intent->generation_token
|| (int) $template->image_bytes
!== (int) $intent->source_size_bytes
|| !hash_equals(
(string) $template->sha256,
(string) $intent->source_sha256
)
|| !in_array((string) $template->state,
['preparing', 'importing'], true)) {
throw new CloudError('云镜像导入目录状态不一致', 409);
}
CloudTemplateArtifactManager::adoptImportIntentLocked(
$template,
$intent,
self::runtime($intent)
);
return ['intent' => $intent, 'template' => $template];
}, 3);
if (isset($prepared['ack'])) {
return $prepared['ack'];
}
/** @var CloudTemplateImportIntent $intent */
$intent = $prepared['intent'];
$taskActor = $actor;
$taskActor['user_id'] = (int) $intent->user_id;
$taskActor['request_idempotency_key'] =
'template-import-' . (string) $intent->id;
$ack = CloudTemplateCatalogService::distributePublishedImport(
$intent,
$taskActor,
$client
);
$jobId = filter_var($ack['task_id'] ?? null, FILTER_VALIDATE_INT,
['options' => ['min_range' => 1]]);
if ($jobId === false) {
throw new CloudError('云镜像导入任务回执无效', 502);
}
$connection->transaction(static function () use (
$id,
$jobId
): void {
$locked = self::lockIntent($id);
if ((string) $locked->state === 'source_ready') {
CloudTemplateImportStateMachine::move(
$locked,
'distributing'
);
}
if (!in_array((string) $locked->state,
['distributing', 'ready', 'distribution_failed'], true)
|| ($locked->active_job_id !== null
&& (int) $locked->active_job_id !== (int) $jobId)) {
throw new CloudError('云镜像分发任务状态不一致', 409);
}
$locked->active_job_id = (int) $jobId;
$locked->updated_at = time();
$locked->save();
}, 3);
return $ack;
}
public static function settleDistributionLocked(
CloudTemplate $template,
CloudJob $parent,
bool $success
): void {
$intent = CloudTemplateImportIntent::query()
->where('template_id', (string) $template->id)
->lockForUpdate()->first();
if ($intent === null) {
return;
}
if ($intent->active_job_id !== null
&& (int) $intent->active_job_id !== (int) $parent->id) {
throw new CloudError('云镜像导入任务绑定冲突', 409);
}
if ((string) $intent->state === 'source_ready') {
CloudTemplateImportStateMachine::move($intent, 'distributing');
}
if ((string) $intent->state !== 'distributing') {
if ($success && (string) $intent->state === 'ready') {
return;
}
if (!$success
&& (string) $intent->state === 'distribution_failed') {
return;
}
throw new CloudError('云镜像导入与分发状态不一致', 409);
}
CloudTemplateImportStateMachine::move(
$intent,
$success ? 'ready' : 'distribution_failed'
);
$intent->active_job_id = (int) $parent->id;
$intent->error_code = $success ? '' : 'template_import_failed';
$intent->updated_at = time();
$intent->save();
}
}

@ -0,0 +1,37 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
/** Provides administrator-safe projections of import intent state. */
final class CloudTemplateImportReadModel extends CloudTemplateImportModule
{
public function active(array $actor): array
{
self::assertAdministrator($actor);
$rows = CloudTemplateImportIntent::query()
->whereNotIn('state', ['ready', 'cancelled'])
->orderByDesc('created_at')->limit(50)->get();
return ['intents' => $rows->map(
static fn (CloudTemplateImportIntent $row): array => self::dto($row)
)->all()];
}
public function one(string $id, array $actor): array
{
self::assertAdministrator($actor);
$id = self::intentId($id);
$intent = CloudTemplateImportIntent::find($id);
if ($intent === null) {
throw new CloudError('云镜像导入记录不存在', 404);
}
return ['intent' => self::dto($intent)];
}
/** @return array<string,mixed> */
public static function project(CloudTemplateImportIntent $intent): array
{
return self::dto($intent);
}
}

@ -0,0 +1,299 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
use Illuminate\Database\QueryException;
/** Reserves idempotent local-upload and official-URL import intents. */
final class CloudTemplateImportReservation extends CloudTemplateImportModule
{
public function beginUpload(array $input, array $actor): array
{
CloudAccess::manage($actor);
CloudInput::only($input, [
'name', 'os_family', 'os_version', 'filename', 'size_bytes',
'last_modified',
]);
$userId = (int) ($actor['user_id'] ?? 0);
$requestKey = self::requestKey($actor);
if ($userId < 1) {
throw new CloudError('管理员身份无效', 403);
}
$name = self::label($input['name'] ?? null, '模板名称', 64);
$family = self::label($input['os_family'] ?? null, '系统系列', 32);
$version = self::label($input['os_version'] ?? null, '系统版本', 32);
$filename = self::filename($input['filename'] ?? null);
$size = self::integer(
$input['size_bytes'] ?? null,
self::MIN_UPLOAD_BYTES,
self::MAX_UPLOAD_BYTES,
'云镜像文件大小无效'
);
$lastModified = self::integer(
$input['last_modified'] ?? 0,
0,
PHP_INT_MAX,
'云镜像文件时间无效'
);
$canonical = [
'source_kind' => 'upload',
'name' => $name,
'os_family' => $family,
'os_version' => $version,
'filename' => $filename,
'size_bytes' => $size,
'last_modified' => $lastModified,
];
$fingerprint = self::fingerprint($canonical);
$runtime = ($this->runtimeProvider)();
$now = ($this->clock)();
if (!is_int($now) || $now < 1) {
throw new \LogicException('Template import clock is invalid');
}
try {
return $this->reserveUploadIntent(
$actor,
$userId,
$requestKey,
$fingerprint,
$canonical,
$runtime,
$now
);
} catch (QueryException $error) {
$prior = CloudTemplateImportIntent::query()
->where('user_id', $userId)
->where('request_idempotency_key', $requestKey)->first();
if ($prior === null) {
throw $error;
}
self::assertReplay($prior, $fingerprint);
return ['created' => false, 'intent' => self::dto($prior)];
}
}
public function beginRemote(array $input, array $actor): array
{
CloudAccess::manage($actor);
CloudInput::only($input, ['name', 'url', 'sha256']);
$userId = (int) ($actor['user_id'] ?? 0);
$requestKey = self::requestKey($actor);
if ($userId < 1) {
throw new CloudError('管理员身份无效', 403);
}
$name = self::label($input['name'] ?? null, '模板名称', 64);
$url = self::remoteUrl($input['url'] ?? null);
$expectedSha256 = strtolower(trim(
(string) ($input['sha256'] ?? '')
));
if ($expectedSha256 !== ''
&& preg_match('/^[a-f0-9]{64}$/D', $expectedSha256) !== 1) {
throw new CloudError(
'SHA-256 必须留空或填写 64 位小写十六进制值'
);
}
[$family, $version] = self::inferRemoteSystem($url, $name);
$canonical = [
'source_kind' => 'remote',
'name' => $name,
'url' => $url,
'sha256' => $expectedSha256,
];
$fingerprint = self::fingerprint($canonical);
$runtime = ($this->runtimeProvider)();
$now = ($this->clock)();
if (!is_int($now) || $now < 1) {
throw new \LogicException('Template import clock is invalid');
}
$connection = (new CloudTemplateImportIntent())->getConnection();
try {
return $connection->transaction(static function () use (
$userId,
$requestKey,
$fingerprint,
$name,
$url,
$expectedSha256,
$family,
$version,
$runtime,
$now
): array {
$prior = CloudTemplateImportIntent::query()
->where('user_id', $userId)
->where('request_idempotency_key', $requestKey)
->lockForUpdate()->first();
if ($prior !== null) {
self::assertReplay($prior, $fingerprint);
return [
'created' => false,
'intent' => self::dto($prior),
];
}
$generation = bin2hex(random_bytes(16));
$templateId = self::newTemplateId($family, $version);
$intent = new CloudTemplateImportIntent();
$intent->id = bin2hex(random_bytes(16));
$intent->user_id = $userId;
$intent->request_idempotency_key = $requestKey;
$intent->request_fingerprint = $fingerprint;
$intent->source_kind = 'remote';
$intent->name = $name;
$intent->os_family = $family;
$intent->os_version = $version;
$intent->source_filename = self::remoteFilename($url);
$intent->source_size_bytes = 0;
$intent->source_last_modified = 0;
$intent->source_sha256 = $expectedSha256;
$intent->sealed_source = CloudSecrets::encrypt([
'kind' => 'remote',
'url' => $url,
'expected_sha256' => $expectedSha256,
], self::SOURCE_PURPOSE);
$intent->template_id = $templateId;
$intent->catalog_key = self::catalogKey($family, $version);
$intent->version_label = gmdate('Ymd-His', $now) . '-'
. substr($generation, 0, 8);
$intent->generation_token = $generation;
$intent->storage_revision = self::runtimeRevision($runtime);
$intent->sealed_storage_runtime = CloudSecrets::encrypt(
$runtime,
self::RUNTIME_PURPOSE
);
$intent->object_key =
CloudTemplateArtifactManager::plannedObjectKey(
$runtime,
$templateId,
$generation
);
$intent->multipart_upload_id = '';
$intent->multipart_part_size_bytes = 0;
$intent->multipart_part_count = 0;
$intent->object_version_id = '';
$intent->object_etag = '';
$intent->state = 'prepared';
$intent->active_job_id = null;
$intent->error_code = '';
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->completed_at = null;
$intent->created_at = $intent->updated_at = $now;
$intent->save();
return [
'created' => true,
'intent' => self::dto($intent),
];
}, 3);
} catch (QueryException $error) {
$prior = CloudTemplateImportIntent::query()
->where('user_id', $userId)
->where('request_idempotency_key', $requestKey)->first();
if ($prior === null) {
throw $error;
}
self::assertReplay($prior, $fingerprint);
return ['created' => false, 'intent' => self::dto($prior)];
}
}
private function reserveUploadIntent(
array $actor,
int $userId,
string $requestKey,
string $fingerprint,
array $canonical,
array $runtime,
int $now
): array {
$connection = (new CloudTemplateImportIntent())->getConnection();
return $connection->transaction(static function () use (
$actor,
$userId,
$requestKey,
$fingerprint,
$canonical,
$runtime,
$now
): array {
$prior = CloudTemplateImportIntent::query()
->where('user_id', $userId)
->where('request_idempotency_key', $requestKey)
->lockForUpdate()->first();
if ($prior !== null) {
self::assertReplay($prior, $fingerprint);
return ['created' => false, 'intent' => self::dto($prior)];
}
$generation = bin2hex(random_bytes(16));
$templateId = self::newTemplateId(
(string) $canonical['os_family'],
(string) $canonical['os_version']
);
$intent = new CloudTemplateImportIntent();
$intent->id = bin2hex(random_bytes(16));
$intent->user_id = $userId;
$intent->request_idempotency_key = $requestKey;
$intent->request_fingerprint = $fingerprint;
$intent->source_kind = 'upload';
$intent->name = (string) $canonical['name'];
$intent->os_family = (string) $canonical['os_family'];
$intent->os_version = (string) $canonical['os_version'];
$intent->source_filename = (string) $canonical['filename'];
$intent->source_size_bytes = (int) $canonical['size_bytes'];
$intent->source_last_modified =
(int) $canonical['last_modified'];
$intent->source_sha256 = '';
$intent->sealed_source = CloudSecrets::encrypt([
'kind' => 'upload',
'filename' => (string) $canonical['filename'],
'size_bytes' => (int) $canonical['size_bytes'],
'last_modified' => (int) $canonical['last_modified'],
], self::SOURCE_PURPOSE);
$intent->template_id = $templateId;
$intent->catalog_key = self::catalogKey(
(string) $canonical['os_family'],
(string) $canonical['os_version']
);
$intent->version_label = gmdate('Ymd-His', $now) . '-'
. substr($generation, 0, 8);
$intent->generation_token = $generation;
$intent->storage_revision = self::runtimeRevision($runtime);
$intent->sealed_storage_runtime = CloudSecrets::encrypt(
$runtime,
self::RUNTIME_PURPOSE
);
$intent->object_key =
CloudTemplateArtifactManager::plannedObjectKey(
$runtime,
$templateId,
$generation
);
$intent->multipart_upload_id = '';
$intent->multipart_part_size_bytes = 0;
$intent->multipart_part_count = 0;
$intent->object_version_id = '';
$intent->object_etag = '';
$intent->state = 'prepared';
$intent->active_job_id = null;
$intent->error_code = '';
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->completed_at = null;
$intent->created_at = $intent->updated_at = $now;
$intent->save();
return ['created' => true, 'intent' => self::dto($intent)];
}, 3);
}
private static function assertReplay(
CloudTemplateImportIntent $prior,
string $fingerprint
): void {
if (!hash_equals((string) $prior->request_fingerprint, $fingerprint)) {
throw new CloudError(
'同一请求标识不能用于不同的云镜像导入',
409
);
}
}
}

File diff suppressed because it is too large Load Diff

@ -0,0 +1,652 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
use App\Models\CloudTemplateImportPart;
/** Owns browser multipart upload planning, receipts and source verification. */
final class CloudTemplateMultipartAcquisition extends CloudTemplateImportModule
{
/** Reserve one resumable local-upload intent without crossing S3. */
public function beginUpload(array $input, array $actor): array
{
return (new CloudTemplateImportReservation(
$this->runtimeProvider,
$this->clock
))->beginUpload($input, $actor);
}
public function startUpload(
string $id,
array $actor,
?CloudObjectStorageS3Client $client = null
): array {
CloudAccess::manage($actor);
$id = self::intentId($id);
$client ??= new CloudObjectStorageS3Client();
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
$prepared = $connection->transaction(static function () use (
$id,
$now
): array {
$intent = self::lockIntent($id);
if ((string) $intent->source_kind !== 'upload') {
throw new CloudError('该导入记录不是本地上传', 409);
}
$state = (string) $intent->state;
if ($state === 'source_unknown') {
throw new CloudError(
'对象存储结果尚未确认,请先核对原上传结果',
409
);
}
if (!in_array($state,
['prepared', 'uploading', 'upload_failed'], true)) {
throw new CloudError('当前导入状态不能继续上传', 409);
}
if ((string) $intent->multipart_upload_id !== '') {
if ($state === 'upload_failed') {
CloudTemplateImportStateMachine::move(
$intent,
'uploading'
);
}
$intent->error_code = '';
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->updated_at = $now;
$intent->save();
return ['intent' => $intent, 'create' => false];
}
if ($state === 'uploading'
&& (int) $intent->updated_at > $now - 120) {
throw new CloudError('对象存储上传会话正在创建,请稍后刷新', 409);
}
if ($state === 'prepared' || $state === 'upload_failed') {
CloudTemplateImportStateMachine::move($intent, 'uploading');
}
$intent->error_code = 'multipart_starting';
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->updated_at = $now;
$intent->save();
return ['intent' => $intent, 'create' => true];
}, 3);
/** @var CloudTemplateImportIntent $intent */
$intent = $prepared['intent'];
$runtime = self::runtime($intent);
try {
$plan = $prepared['create']
? $client->prepareMultipartUpload(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(int) $intent->source_size_bytes,
$now,
self::INTENT_TTL_SECONDS
)
: $client->resumeMultipartUpload(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id,
(int) $intent->source_size_bytes,
$now,
self::INTENT_TTL_SECONDS
);
} catch (CloudObjectStorageTransferError $error) {
if ($prepared['create']) {
self::markUploadFailure(
$id,
$error->publicCode,
$error->effectMayHaveApplied,
$now
);
}
throw new CloudError($error->getMessage(), 502);
}
if ($prepared['create']) {
$intent = $connection->transaction(static function () use (
$id,
$plan,
$now
): CloudTemplateImportIntent {
$locked = self::lockIntent($id);
if ((string) $locked->state !== 'uploading'
|| (string) $locked->multipart_upload_id !== '') {
throw new CloudError('上传会话状态已变化,请刷新页面', 409);
}
$locked->multipart_upload_id = (string) $plan['upload_id'];
$locked->multipart_part_size_bytes =
(int) $plan['part_size_bytes'];
$locked->multipart_part_count = count($plan['part_urls']);
$locked->error_code = '';
$locked->expires_at = (int) $plan['expires_at'];
$locked->updated_at = $now;
$locked->save();
return $locked;
}, 3);
} else {
$intent->refresh();
}
return self::uploadPlanDto($intent, $plan);
}
public function recordPart(
string $id,
int $partNumber,
array $input,
array $actor
): array {
CloudAccess::manage($actor);
CloudInput::only($input, ['size_bytes', 'etag']);
$id = self::intentId($id);
$size = self::integer(
$input['size_bytes'] ?? null,
1,
self::MAX_UPLOAD_BYTES,
'上传分片大小无效'
);
$etag = self::etag($input['etag'] ?? null);
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
return $connection->transaction(static function () use (
$id,
$partNumber,
$size,
$etag,
$now
): array {
$intent = self::lockIntent($id);
if ((string) $intent->state !== 'uploading'
|| (string) $intent->multipart_upload_id === '') {
throw new CloudError('上传会话当前不能记录分片', 409);
}
self::assertPartGeometry($intent, $partNumber, $size);
$part = CloudTemplateImportPart::query()
->where('intent_id', $id)
->where('part_number', $partNumber)
->lockForUpdate()->first();
if ($part !== null) {
if ((int) $part->size_bytes !== $size
|| !hash_equals((string) $part->etag, $etag)) {
throw new CloudError(
'上传分片回执已变化,请刷新上传状态',
409
);
}
} else {
$part = new CloudTemplateImportPart();
$part->intent_id = $id;
$part->part_number = $partNumber;
$part->size_bytes = $size;
$part->etag = $etag;
$part->created_at = $part->updated_at = $now;
$part->save();
}
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->updated_at = $now;
$intent->save();
return [
'part_number' => $partNumber,
'intent' => self::dto($intent),
];
}, 3);
}
public function completeUpload(
string $id,
array $input,
array $actor,
?CloudObjectStorageS3Client $client = null
): array {
CloudAccess::manage($actor);
CloudInput::only($input, ['sha256']);
$id = self::intentId($id);
$sha256 = strtolower(trim((string) ($input['sha256'] ?? '')));
if (preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new CloudError('请提供完整的云镜像 SHA-256', 422);
}
$client ??= new CloudObjectStorageS3Client();
$snapshot = $this->completionSnapshot($id, $sha256);
if (isset($snapshot['ack'])) {
return $snapshot['ack'];
}
if (($snapshot['finalize'] ?? false) === true) {
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
/** @var CloudTemplateImportIntent $intent */
$intent = $snapshot['intent'];
$runtime = self::runtime($intent);
$providerParts = null;
if (($snapshot['reconcile'] ?? false) === true) {
try {
$identity = $client->inspectObject(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key
);
} catch (CloudObjectStorageTransferError $error) {
self::finishSourceFailure(
$id,
'source_unknown',
$error->publicCode,
(int) ($this->clock)()
);
throw new CloudError(
'无法确认云镜像是否已完成上传,请勿重新创建导入',
502
);
}
if ($identity !== null) {
$this->publication()->acceptCompletedIdentity($id, $identity);
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
// A successful ListParts on the same upload ID proves the
// multipart session still exists and the object was not committed.
// Only after that proof may a prior unknown/verifying state return
// to uploading and issue CompleteMultipartUpload once more.
try {
$providerParts = $client->listMultipartParts(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id
);
} catch (CloudObjectStorageTransferError $error) {
self::finishSourceFailure(
$id,
'source_unknown',
$error->publicCode,
(int) ($this->clock)()
);
throw new CloudError(
'无法确认原分片上传是否仍然存在,请勿重复完成上传',
502
);
}
self::assertProviderParts($snapshot['parts'], $providerParts);
$connection = $intent->getConnection();
$connection->transaction(static function () use ($id): void {
$locked = self::lockIntent($id);
if (!in_array((string) $locked->state,
['source_verifying', 'source_unknown'], true)) {
throw new CloudError('上传核对状态已变化,请刷新页面', 409);
}
if ((string) $locked->state === 'source_unknown') {
CloudTemplateImportStateMachine::move(
$locked,
'source_verifying'
);
}
CloudTemplateImportStateMachine::move(
$locked,
'upload_failed'
);
CloudTemplateImportStateMachine::move($locked, 'uploading');
$locked->error_code = '';
$locked->updated_at = time();
$locked->save();
}, 3);
$intent->state = 'uploading';
}
if ($providerParts === null) {
try {
$providerParts = $client->listMultipartParts(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id
);
} catch (CloudObjectStorageTransferError $error) {
throw new CloudError($error->getMessage(), 502);
}
}
self::assertProviderParts($snapshot['parts'], $providerParts);
$now = ($this->clock)();
$connection = $intent->getConnection();
$connection->transaction(static function () use (
$id,
$sha256,
$intent,
$now
): void {
$locked = self::lockIntent($id);
if ((string) $locked->state !== (string) $intent->state
|| (string) $locked->multipart_upload_id
!== (string) $intent->multipart_upload_id) {
throw new CloudError('上传状态已变化,请刷新页面', 409);
}
CloudTemplateImportStateMachine::move(
$locked,
'source_verifying'
);
$locked->source_sha256 = $sha256;
$locked->error_code = '';
$locked->updated_at = $now;
$locked->save();
}, 3);
try {
$identity = $client->completeMultipartUpload(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id,
array_map(static fn (array $part): array => [
'part_number' => (int) $part['part_number'],
'etag' => (string) $part['etag'],
], $providerParts)
);
} catch (CloudObjectStorageTransferError $error) {
if (!$error->effectMayHaveApplied) {
self::finishSourceFailure(
$id,
'upload_failed',
$error->publicCode,
$now
);
throw new CloudError($error->getMessage(), 502);
}
try {
$identity = $client->inspectObject(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key
);
} catch (\Throwable $inspectError) {
self::finishSourceFailure(
$id,
'source_unknown',
$error->publicCode,
$now
);
throw new CloudError(
'无法确认云镜像是否已完成上传,请勿重新创建导入',
502
);
}
if ($identity === null) {
try {
$remainingParts = $client->listMultipartParts(
$runtime['config'],
$runtime['credentials'],
(string) $intent->object_key,
(string) $intent->multipart_upload_id
);
self::assertProviderParts(
$snapshot['parts'],
$remainingParts
);
} catch (\Throwable $reconcileError) {
self::finishSourceFailure(
$id,
'source_unknown',
$error->publicCode,
$now
);
throw new CloudError(
'无法确认云镜像是否已完成上传,请勿重复完成上传',
502
);
}
self::finishSourceFailure(
$id,
'upload_failed',
'multipart_complete_not_applied',
$now
);
throw new CloudError(
'对象存储确认上传尚未完成,请重试完成步骤',
502
);
}
}
if ((int) ($identity['size_bytes'] ?? 0)
!== (int) $intent->source_size_bytes
|| !is_string($identity['etag'] ?? null)
|| trim((string) $identity['etag']) === '') {
self::finishSourceFailure(
$id,
'source_unknown',
'multipart_object_identity_mismatch',
$now
);
throw new CloudError('上传对象身份与导入意图不一致,记录已锁定', 409);
}
$this->publication()->acceptCompletedIdentity($id, $identity);
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
private function completionSnapshot(string $id, string $sha256): array
{
$connection = (new CloudTemplateImportIntent())->getConnection();
return $connection->transaction(static function () use (
$id,
$sha256
): array {
$intent = self::lockIntent($id);
if ((string) $intent->source_kind !== 'upload') {
throw new CloudError('该导入记录不是本地上传', 409);
}
$storedDigest = (string) $intent->source_sha256;
if ($storedDigest !== '' && !hash_equals($storedDigest, $sha256)) {
throw new CloudError('云镜像 SHA-256 与原完成请求不一致', 409);
}
$state = (string) $intent->state;
if (in_array($state,
['distributing', 'ready', 'distribution_failed'], true)) {
$jobId = (int) ($intent->active_job_id ?? 0);
$job = $jobId > 0 ? CloudJob::query()
->where('id', $jobId)->lockForUpdate()->first() : null;
$template = CloudTemplate::query()
->where('id', (string) $intent->template_id)
->lockForUpdate()->first();
if ($job === null || $template === null
|| (string) $job->kind !== 'template_import'
|| (int) $job->user_id !== (int) $intent->user_id
|| (int) ($template->active_job_id ?? 0) !== $jobId) {
throw new CloudError('云镜像导入任务账本不完整', 409);
}
return ['ack' => CloudJobService::acknowledgement($job)];
}
if ($state === 'source_ready') {
return ['finalize' => true, 'intent' => $intent];
}
if (!in_array($state, [
'uploading', 'upload_failed', 'source_verifying',
'source_unknown',
], true)) {
throw new CloudError('当前导入状态不能完成上传', 409);
}
if ((string) $intent->multipart_upload_id === ''
|| (int) $intent->multipart_part_size_bytes < 1
|| (int) $intent->multipart_part_count < 1) {
throw new CloudError('分片上传账本不完整', 409);
}
if ($state === 'upload_failed') {
CloudTemplateImportStateMachine::move($intent, 'uploading');
$intent->error_code = '';
$intent->updated_at = time();
$intent->save();
$state = 'uploading';
}
$parts = CloudTemplateImportPart::query()
->where('intent_id', $id)->orderBy('part_number')
->lockForUpdate()->get()->map(
static fn (CloudTemplateImportPart $part): array => [
'part_number' => (int) $part->part_number,
'size_bytes' => (int) $part->size_bytes,
'etag' => (string) $part->etag,
]
)->all();
if (count($parts) !== (int) $intent->multipart_part_count) {
throw new CloudError('云镜像分片尚未全部上传', 409);
}
foreach ($parts as $part) {
self::assertPartGeometry(
$intent,
(int) $part['part_number'],
(int) $part['size_bytes']
);
self::etag($part['etag']);
}
return [
'intent' => $intent,
'parts' => $parts,
'reconcile' => in_array($state,
['source_verifying', 'source_unknown'], true),
];
}, 3);
}
private static function markUploadFailure(
string $id,
string $code,
bool $unknown,
int $now
): void {
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use (
$id,
$code,
$unknown,
$now
): void {
$intent = self::lockIntent($id);
if ((string) $intent->state !== 'uploading'
|| (string) $intent->multipart_upload_id !== '') {
return;
}
CloudTemplateImportStateMachine::move(
$intent,
$unknown ? 'source_unknown' : 'upload_failed'
);
$intent->error_code = substr($code, 0, 128);
$intent->updated_at = $now;
$intent->save();
}, 3);
}
private static function finishSourceFailure(
string $id,
string $next,
string $code,
int $now
): void {
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use (
$id,
$next,
$code,
$now
): void {
$intent = self::lockIntent($id);
if (!in_array((string) $intent->state,
['source_verifying', 'source_unknown'], true)) {
return;
}
if ((string) $intent->state !== $next) {
CloudTemplateImportStateMachine::move($intent, $next);
}
$intent->error_code = substr($code, 0, 128);
$intent->updated_at = $now;
$intent->save();
}, 3);
}
private static function uploadPlanDto(
CloudTemplateImportIntent $intent,
array $plan
): array {
$urls = $plan['part_urls'] ?? null;
if (!is_array($urls) || count($urls) !== (int) $intent->multipart_part_count
|| (int) ($plan['part_size_bytes'] ?? 0)
!== (int) $intent->multipart_part_size_bytes
|| (string) ($plan['object_key'] ?? '')
!== (string) $intent->object_key
|| (string) ($plan['upload_id'] ?? '')
!== (string) $intent->multipart_upload_id
|| !array_is_list($urls)
|| array_filter($urls,
static fn ($url): bool => !is_string($url) || $url === '')
!== []) {
throw new CloudError('对象存储上传计划无效', 502);
}
return [
'intent' => self::dto($intent),
'part_size_bytes' => (int) $intent->multipart_part_size_bytes,
'part_count' => (int) $intent->multipart_part_count,
'part_urls' => array_values($urls),
'expires_at' => (int) ($plan['expires_at'] ?? $intent->expires_at),
];
}
private static function assertPartGeometry(
CloudTemplateImportIntent $intent,
int $partNumber,
int $size
): void {
$count = (int) $intent->multipart_part_count;
$partSize = (int) $intent->multipart_part_size_bytes;
$total = (int) $intent->source_size_bytes;
if ($partNumber < 1 || $partNumber > $count
|| $count < 1 || $partSize < 1 || $total < 1) {
throw new CloudError('上传分片编号无效', 422);
}
$expected = $partNumber === $count
? $total - ($count - 1) * $partSize : $partSize;
if ($expected < 1 || $size !== $expected) {
throw new CloudError('上传分片大小与预留计划不一致', 409);
}
}
private static function assertProviderParts(
array $recorded,
array $provider
): void {
if (count($recorded) !== count($provider)) {
throw new CloudError('对象存储分片账本与面板记录不一致', 409);
}
foreach ($recorded as $index => $part) {
$remote = $provider[$index] ?? null;
if (!is_array($remote)
|| (int) ($remote['part_number'] ?? 0)
!== (int) $part['part_number']
|| (int) ($remote['size_bytes'] ?? 0)
!== (int) $part['size_bytes']
|| !is_string($remote['etag'] ?? null)
|| !hash_equals(
(string) $part['etag'],
(string) $remote['etag']
)) {
throw new CloudError(
'对象存储分片账本与面板记录不一致',
409
);
}
}
}
private static function etag($value): string
{
if (!is_string($value)) {
throw new CloudError('上传分片 ETag 无效', 422);
}
$value = trim($value);
if ($value === '' || strlen($value) > 256
|| preg_match('/[\x00-\x1f\x7f]/D', $value) === 1) {
throw new CloudError('上传分片 ETag 无效', 422);
}
return $value;
}
private function publication(): CloudTemplateImportPublication
{
return new CloudTemplateImportPublication(
$this->runtimeProvider,
$this->clock
);
}
}

@ -0,0 +1,358 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudTemplateImportIntent;
/** Acquires and verifies one official HTTPS cloud image. */
final class CloudTemplateRemoteAcquisition extends CloudTemplateImportModule
{
public function importRemote(
array $input,
array $actor,
?CloudTemplateRemoteFetcher $fetcher = null,
?CloudObjectStorageS3Client $client = null
): array {
$reserved = $this->reservation()->beginRemote($input, $actor);
return $this->acquireRemote(
(string) $reserved['intent']['id'],
$actor,
$fetcher ?? new CloudTemplateRemoteFetcher(),
$client ?? new CloudObjectStorageS3Client()
);
}
public function resumeRemote(
string $id,
array $actor,
?CloudTemplateRemoteFetcher $fetcher = null,
?CloudObjectStorageS3Client $client = null
): array {
CloudAccess::manage($actor);
return $this->acquireRemote(
self::intentId($id),
$actor,
$fetcher ?? new CloudTemplateRemoteFetcher(),
$client ?? new CloudObjectStorageS3Client()
);
}
private function acquireRemote(
string $id,
array $actor,
CloudTemplateRemoteFetcher $fetcher,
CloudObjectStorageS3Client $client
): array {
$snapshot = $this->remoteSnapshot($id);
if (($snapshot['finalize'] ?? false) === true) {
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
/** @var CloudTemplateImportIntent $intent */
$intent = $snapshot['intent'];
try {
$runtime = self::runtime($intent);
} catch (CloudError $error) {
self::finishRemoteFailure(
$id,
'source_failed',
'remote_storage_runtime_invalid',
(int) ($this->clock)()
);
throw $error;
}
$transport = new CloudImmutableArtifactTransport($client);
if (($snapshot['reconcile'] ?? false) === true) {
try {
$identity = $transport->inspect(
$runtime,
(string) $intent->object_key
);
} catch (\Throwable $error) {
self::finishRemoteFailure(
$id,
'source_unknown',
'remote_source_reconcile_unavailable',
(int) ($this->clock)()
);
throw new CloudError(
'无法确认官方云镜像是否已保存,请勿创建新的导入',
502
);
}
if ($identity !== null) {
$this->publication()->acceptCompletedIdentity($id, $identity);
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
self::makeRemoteRetryable($id, (int) ($this->clock)());
return $this->acquireRemote(
$id,
$actor,
$fetcher,
$client
);
}
try {
$source = self::remoteSource($intent);
} catch (CloudError $error) {
self::finishRemoteFailure(
$id,
'source_failed',
'remote_source_ledger_invalid',
(int) ($this->clock)()
);
throw $error;
}
$file = null;
try {
$file = $fetcher->fetch(
$source['url'],
$source['expected_sha256']
);
$size = filter_var(
$file['size_bytes'] ?? null,
FILTER_VALIDATE_INT,
['options' => [
'min_range' => self::MIN_UPLOAD_BYTES,
'max_range' => self::MAX_UPLOAD_BYTES,
]]
);
$digest = strtolower((string) ($file['sha256'] ?? ''));
if ($size === false
|| preg_match('/^[a-f0-9]{64}$/D', $digest) !== 1
|| !is_string($file['path'] ?? null)
|| !is_file((string) $file['path'])) {
throw new CloudError('官方云镜像校验结果无效', 503);
}
$this->freezeRemoteFileIdentity($id, (int) $size, $digest);
$intent->refresh();
$publication = $transport->publish(
$runtime,
(string) $intent->object_key,
[
'path' => (string) $file['path'],
'size_bytes' => (int) $size,
'sha256' => $digest,
]
);
} catch (CloudError $error) {
self::finishRemoteFailure(
$id,
'source_failed',
'remote_fetch_failed',
(int) ($this->clock)()
);
throw $error;
} catch (\Throwable $error) {
self::finishRemoteFailure(
$id,
'source_failed',
'remote_acquire_failed',
(int) ($this->clock)()
);
throw new CloudError(
'处理官方云镜像时发生内部错误,可以从原导入记录重试',
503
);
} finally {
if (is_array($file) && is_string($file['path'] ?? null)
&& is_file((string) $file['path'])) {
@unlink((string) $file['path']);
}
}
$resolution = (string) ($publication['resolution'] ?? 'unknown');
$identity = $publication['identity'] ?? null;
if ($resolution !== 'applied' || !is_array($identity)) {
$code = (string) ($publication['error_code']
?? 'remote_source_publish_failed');
$next = $resolution === 'not_applied'
? 'source_failed' : 'source_unknown';
self::finishRemoteFailure(
$id,
$next,
$code,
(int) ($this->clock)()
);
throw new CloudError(
$resolution === 'conflict'
? '官方云镜像对象身份冲突,记录已锁定'
: ($resolution === 'not_applied'
? '对象存储已确认官方云镜像尚未保存,可以重试'
: '无法确认官方云镜像是否已保存,请勿创建新的导入'),
$resolution === 'conflict' ? 409 : 502
);
}
$this->publication()->acceptCompletedIdentity($id, $identity);
return $this->publication()->finalizeReadyIntent($id, $actor, $client);
}
private function remoteSnapshot(string $id): array
{
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
return $connection->transaction(static function () use (
$id,
$now
): array {
$intent = self::lockIntent($id);
if ((string) $intent->source_kind !== 'remote') {
throw new CloudError('该导入记录不是远程云镜像', 409);
}
$state = (string) $intent->state;
if (in_array($state, [
'source_ready', 'distributing', 'ready',
'distribution_failed',
], true)) {
return ['intent' => $intent, 'finalize' => true];
}
if (in_array($state,
['source_verifying', 'source_unknown'], true)) {
if ((int) $intent->source_size_bytes
< self::MIN_UPLOAD_BYTES
|| preg_match('/^[a-f0-9]{64}$/D',
(string) $intent->source_sha256) !== 1) {
throw new CloudError(
'远程云镜像核对账本不完整',
409
);
}
return ['intent' => $intent, 'reconcile' => true];
}
if (!in_array($state,
['prepared', 'fetching', 'source_failed'], true)) {
throw new CloudError('当前导入状态不能下载远程云镜像', 409);
}
if ($state === 'fetching'
&& (int) $intent->updated_at > $now - 3600) {
throw new CloudError(
'官方云镜像正在下载,请在当前导入记录中等待',
409
);
}
if ($state !== 'fetching') {
CloudTemplateImportStateMachine::move($intent, 'fetching');
}
$intent->error_code = '';
$intent->expires_at = $now + self::INTENT_TTL_SECONDS;
$intent->updated_at = $now;
$intent->save();
return ['intent' => $intent];
}, 3);
}
private function freezeRemoteFileIdentity(
string $id,
int $size,
string $sha256
): void {
$now = ($this->clock)();
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use (
$id,
$size,
$sha256,
$now
): void {
$intent = self::lockIntent($id);
if ((string) $intent->source_kind !== 'remote'
|| (string) $intent->state !== 'fetching') {
throw new CloudError('远程云镜像下载状态已变化', 409);
}
$expected = (string) $intent->source_sha256;
if ($expected !== '' && !hash_equals($expected, $sha256)) {
CloudTemplateImportStateMachine::move(
$intent,
'source_failed'
);
$intent->error_code = 'remote_sha256_mismatch';
$intent->updated_at = $now;
$intent->save();
throw new CloudError('云镜像 SHA-256 校验不一致', 409);
}
$intent->source_size_bytes = $size;
$intent->source_sha256 = $sha256;
CloudTemplateImportStateMachine::move(
$intent,
'source_verifying'
);
$intent->error_code = '';
$intent->updated_at = $now;
$intent->save();
}, 3);
}
private static function finishRemoteFailure(
string $id,
string $next,
string $code,
int $now
): void {
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use (
$id,
$next,
$code,
$now
): void {
$intent = self::lockIntent($id);
if ((string) $intent->source_kind !== 'remote'
|| !in_array((string) $intent->state, [
'fetching', 'source_verifying', 'source_unknown',
'source_failed',
], true)) {
return;
}
$preserveCode = (string) $intent->state === $next
&& trim((string) $intent->error_code) !== '';
if ((string) $intent->state !== $next) {
CloudTemplateImportStateMachine::move($intent, $next);
}
if (!$preserveCode) {
$intent->error_code = substr($code, 0, 128);
}
$intent->updated_at = $now;
$intent->save();
}, 3);
}
private static function makeRemoteRetryable(string $id, int $now): void
{
$connection = (new CloudTemplateImportIntent())->getConnection();
$connection->transaction(static function () use ($id, $now): void {
$intent = self::lockIntent($id);
if ((string) $intent->state === 'source_unknown') {
CloudTemplateImportStateMachine::move(
$intent,
'source_verifying'
);
}
if ((string) $intent->state !== 'source_verifying') {
throw new CloudError('远程云镜像核对状态已变化', 409);
}
CloudTemplateImportStateMachine::move(
$intent,
'source_failed'
);
$intent->error_code = 'remote_source_not_applied';
$intent->updated_at = $now;
$intent->save();
}, 3);
}
private function reservation(): CloudTemplateImportReservation
{
return new CloudTemplateImportReservation(
$this->runtimeProvider,
$this->clock
);
}
private function publication(): CloudTemplateImportPublication
{
return new CloudTemplateImportPublication(
$this->runtimeProvider,
$this->clock
);
}
}

@ -144,7 +144,7 @@ final class CloudWorkerService
$templateTemporaryCleanup = false;
if (!$this->policyOnly && !$this->vpcBatchOnly) {
try {
$templateCleanup = (new CloudTemplateImportWorkflow())
$templateCleanup = (new CloudTemplateImportCancellation())
->cleanupOneExpired();
} catch (\Throwable $error) {
// The intent has already moved to source_unknown when an S3

@ -13,8 +13,11 @@ $controller = file_get_contents(
$catalog = file_get_contents(
$root . '/app/Services/Cloud/CloudTemplateCatalogService.php'
);
$workflow = file_get_contents(
$root . '/app/Services/Cloud/CloudTemplateImportWorkflow.php'
$remoteAcquisition = file_get_contents(
$root . '/app/Services/Cloud/CloudTemplateRemoteAcquisition.php'
);
$publication = file_get_contents(
$root . '/app/Services/Cloud/CloudTemplateImportPublication.php'
);
$deletion = file_get_contents(
$root . '/app/Services/Cloud/CloudTemplateDeletionService.php'
@ -52,14 +55,16 @@ $assert(is_string($catalog)
'PHP-owned template catalog lost strict validation or stable errors.');
$assert(is_string($controller)
&& is_string($workflow)
&& is_string($remoteAcquisition)
&& is_string($publication)
&& str_contains($controller, 'CloudTemplateCatalogService::adminCatalog()')
&& str_contains($controller, 'CloudTemplateImportWorkflow())->importRemote(')
&& str_contains($controller, 'CloudTemplateRemoteAcquisition())->importRemote(')
&& str_contains($controller, 'CloudTemplateCatalogService::rename(')
&& str_contains($controller, 'CloudTemplateCatalogService::delete(')
&& str_contains($workflow, 'CloudTemplateRemoteFetcher')
&& str_contains($workflow, 'CloudImmutableArtifactTransport')
&& str_contains($workflow, 'finalizeReadyIntent(')
&& str_contains($remoteAcquisition, 'CloudTemplateRemoteFetcher')
&& str_contains($remoteAcquisition, 'CloudImmutableArtifactTransport')
&& str_contains($remoteAcquisition, 'publication()->finalizeReadyIntent(')
&& str_contains($publication, 'finalizeReadyIntent(')
&& !str_contains($controller, 'CloudLocalUploadService')
&& !str_contains($catalog, 'publishAndReserveImport('),
'Template sources must converge through the durable import workflow.');

@ -19,6 +19,15 @@ $workerService = file_get_contents(
$template = file_get_contents(
$root . '/resources/views/venix/admin/cloud/templates.tpl'
);
$importModules = [
'CloudTemplateImportModule',
'CloudTemplateImportReservation',
'CloudTemplateRemoteAcquisition',
'CloudTemplateMultipartAcquisition',
'CloudTemplateImportPublication',
'CloudTemplateImportCancellation',
'CloudTemplateImportReadModel',
];
if (!is_string($schema) || !is_string($setup) || !is_string($routes)
|| !is_string($controller) || !is_string($browser)
|| !is_string($worker) || !is_string($workerService)
@ -38,6 +47,13 @@ foreach (['cloud_template_import_intents',
$assert(str_contains($setup, "'" . $table . "'"),
'CloudSetup does not require template-import table: ' . $table);
}
foreach ($importModules as $module) {
$assert(is_file($root . '/app/Services/Cloud/' . $module . '.php'),
'Missing template-import module: ' . $module);
}
$assert(!is_file(
$root . '/app/Services/Cloud/CloudTemplateImportWorkflow.php'
), 'Retired template-import workflow facade still exists.');
$assert(str_contains($schema,
'UNIQUE KEY cloud_template_import_request (user_id, request_idempotency_key)')
&& str_contains($schema,
@ -63,7 +79,10 @@ $assert(str_contains($routes, "'/admin/cloud-template-imports'")
"'/admin/cloud-template-imports/remote'")
&& str_contains($routes,
"delete('/admin/cloud-template-imports/{id}'")
&& str_contains($controller, 'CloudTemplateImportWorkflow')
&& str_contains($controller, 'CloudTemplateImportReadModel')
&& str_contains($controller, 'CloudTemplateMultipartAcquisition')
&& str_contains($controller, 'CloudTemplateRemoteAcquisition')
&& str_contains($controller, 'CloudTemplateImportCancellation')
&& str_contains($controller, 'beginUpload(')
&& str_contains($controller, 'cloudTemplateImportRemote(')
&& str_contains($controller, 'importRemote(')

@ -18,7 +18,8 @@ namespace {
use App\Models\CloudTemplateImportIntent;
use App\Services\Cloud\CloudError;
use App\Services\Cloud\CloudTemplateImportStateMachine;
use App\Services\Cloud\CloudTemplateImportWorkflow;
use App\Services\Cloud\CloudTemplateImportReadModel;
use App\Services\Cloud\CloudTemplateMultipartAcquisition;
use App\Services\Config;
use Illuminate\Database\Capsule\Manager as Capsule;
use Illuminate\Database\Schema\Blueprint;
@ -98,7 +99,11 @@ namespace {
],
'revision' => 9,
];
$workflow = new CloudTemplateImportWorkflow(
$uploads = new CloudTemplateMultipartAcquisition(
static fn (): array => $runtime,
static fn (): int => 2000000000
);
$readModel = new CloudTemplateImportReadModel(
static fn (): array => $runtime,
static fn (): int => 2000000000
);
@ -118,8 +123,8 @@ namespace {
'last_modified' => 1999999000000,
];
$first = $workflow->beginUpload($input, $actor);
$second = $workflow->beginUpload($input, $actor);
$first = $uploads->beginUpload($input, $actor);
$second = $uploads->beginUpload($input, $actor);
$assert($first['created'] === true && $second['created'] === false
&& $first['intent']['id'] === $second['intent']['id']
&& $first['intent']['state'] === 'prepared'
@ -139,7 +144,7 @@ namespace {
'The intent did not freeze its object identity or leaked secrets.');
try {
$workflow->beginUpload(
$uploads->beginUpload(
array_replace($input, ['name' => 'Different']),
$actor
);
@ -149,8 +154,8 @@ namespace {
'A same-key fingerprint conflict returned the wrong status.');
}
$listed = $workflow->active($actor);
$one = $workflow->one((string) $stored->id, $actor);
$listed = $readModel->active($actor);
$one = $readModel->one((string) $stored->id, $actor);
$assert(count($listed['intents']) === 1
&& $one['intent']['id'] === (string) $stored->id,
'A refreshed administrator page cannot recover the active intent.');

@ -19,7 +19,10 @@ namespace {
use App\Services\Cloud\CloudError;
use App\Services\Cloud\CloudObjectStorageS3Client;
use App\Services\Cloud\CloudSecrets;
use App\Services\Cloud\CloudTemplateImportWorkflow;
use App\Services\Cloud\CloudTemplateImportCancellation;
use App\Services\Cloud\CloudTemplateImportReadModel;
use App\Services\Cloud\CloudTemplateMultipartAcquisition;
use App\Services\Cloud\CloudTemplateRemoteAcquisition;
use App\Services\Cloud\CloudTemplateRemoteFetcher;
use App\Services\Config;
use GuzzleHttp\Client;
@ -242,9 +245,19 @@ namespace {
'revision' => 11,
];
$clock = 2000001000;
$workflow = new CloudTemplateImportWorkflow(
static fn (): array => $runtime,
static fn (): int => $clock
$runtimeProvider = static fn (): array => $runtime;
$clockProvider = static fn (): int => $clock;
$uploads = new CloudTemplateMultipartAcquisition(
$runtimeProvider,
$clockProvider
);
$remote = new CloudTemplateRemoteAcquisition(
$runtimeProvider,
$clockProvider
);
$cancellation = new CloudTemplateImportCancellation(
$runtimeProvider,
$clockProvider
);
$actor = [
'user_id' => 9,
@ -288,18 +301,18 @@ namespace {
$stack->push(Middleware::history($history));
$client = new CloudObjectStorageS3Client(new Client(['handler' => $stack]));
$intent = $workflow->beginUpload($input, $actor)['intent'];
$plan = $workflow->startUpload((string) $intent['id'], $actor, $client);
$intent = $uploads->beginUpload($input, $actor)['intent'];
$plan = $uploads->startUpload((string) $intent['id'], $actor, $client);
$assert(count($plan['part_urls']) === 1
&& !array_key_exists('upload_id', $plan)
&& !str_contains(json_encode($plan, JSON_THROW_ON_ERROR),
'multipart-secret'),
'The browser upload plan leaked provider authority or credentials.');
$workflow->recordPart((string) $intent['id'], 1, [
$uploads->recordPart((string) $intent['id'], 1, [
'size_bytes' => 64 * 1024 * 1024,
'etag' => $partEtag,
], $actor);
$ack = $workflow->completeUpload(
$ack = $uploads->completeUpload(
(string) $intent['id'], ['sha256' => $digest], $actor, $client
);
$stored = CloudTemplateImportIntent::findOrFail((string) $intent['id']);
@ -335,7 +348,7 @@ namespace {
$emptyClient = new CloudObjectStorageS3Client(new Client([
'handler' => HandlerStack::create(new MockHandler([])),
]));
$replayAck = $workflow->completeUpload(
$replayAck = $uploads->completeUpload(
(string) $intent['id'], ['sha256' => $digest], $actor, $emptyClient
);
$assert(Capsule::table('cloud_templates')->count() === 1
@ -350,7 +363,7 @@ namespace {
// CompleteMultipartUpload may commit even when its response is lost. The
// workflow must reconcile HEAD and must never issue Complete a second time.
$actor['request_idempotency_key'] = 'multipart-template-intent-0002';
$lost = $workflow->beginUpload(array_replace($input, [
$lost = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 lost response',
'filename' => 'debian-13-lost.qcow2',
]), $actor)['intent'];
@ -377,12 +390,12 @@ namespace {
$lostClient = new CloudObjectStorageS3Client(new Client([
'handler' => $lostStack,
]));
$workflow->startUpload((string) $lost['id'], $actor, $lostClient);
$workflow->recordPart((string) $lost['id'], 1, [
$uploads->startUpload((string) $lost['id'], $actor, $lostClient);
$uploads->recordPart((string) $lost['id'], 1, [
'size_bytes' => 64 * 1024 * 1024,
'etag' => $partEtag,
], $actor);
$lostAck = $workflow->completeUpload(
$lostAck = $uploads->completeUpload(
(string) $lost['id'], ['sha256' => $digest], $actor, $lostClient
);
$lostStored = CloudTemplateImportIntent::findOrFail((string) $lost['id']);
@ -399,7 +412,7 @@ namespace {
// Refreshing the page must expose the exact server-confirmed part ledger;
// re-signing an existing upload must not allocate a second upload ID.
$actor['request_idempotency_key'] = 'multipart-template-intent-0003';
$resumable = $workflow->beginUpload(array_replace($input, [
$resumable = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 resumable',
'filename' => 'debian-13-resumable.qcow2',
]), $actor)['intent'];
@ -414,12 +427,12 @@ namespace {
$resumeClient = new CloudObjectStorageS3Client(new Client([
'handler' => $resumeStack,
]));
$workflow->startUpload((string) $resumable['id'], $actor, $resumeClient);
$workflow->recordPart((string) $resumable['id'], 1, [
$uploads->startUpload((string) $resumable['id'], $actor, $resumeClient);
$uploads->recordPart((string) $resumable['id'], 1, [
'size_bytes' => 64 * 1024 * 1024,
'etag' => $partEtag,
], $actor);
$resigned = $workflow->startUpload(
$resigned = $uploads->startUpload(
(string) $resumable['id'], $actor, $resumeClient
);
$assert(($resigned['intent']['parts'] ?? null) === [[
@ -429,7 +442,7 @@ namespace {
&& array_map(static fn (array $item): string =>
$item['request']->getMethod(), $resumeHistory) === ['POST'],
'Resume did not expose the exact part ledger or created a new upload.');
$cancelled = $workflow->cancel(
$cancelled = $cancellation->cancel(
(string) $resumable['id'], $actor, $resumeClient
);
$assert(($cancelled['state'] ?? null) === 'cancelled'
@ -442,7 +455,7 @@ namespace {
// A lost Abort response is reconciled with HEAD + ListParts. A 404 for
// the exact upload ID proves cancellation; DELETE must not be replayed.
$actor['request_idempotency_key'] = 'multipart-template-intent-0004';
$abortLost = $workflow->beginUpload(array_replace($input, [
$abortLost = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 abort lost',
'filename' => 'debian-13-abort-lost.qcow2',
]), $actor)['intent'];
@ -460,8 +473,8 @@ namespace {
$abortClient = new CloudObjectStorageS3Client(new Client([
'handler' => $abortStack,
]));
$workflow->startUpload((string) $abortLost['id'], $actor, $abortClient);
$abortResult = $workflow->cancel(
$uploads->startUpload((string) $abortLost['id'], $actor, $abortClient);
$abortResult = $cancellation->cancel(
(string) $abortLost['id'], $actor, $abortClient
);
$assert(($abortResult['state'] ?? null) === 'cancelled'
@ -474,7 +487,7 @@ namespace {
// If read-only evidence proves the upload still exists, cancellation is
// retryable with a new explicit action rather than reported as complete.
$actor['request_idempotency_key'] = 'multipart-template-intent-0005';
$abortActive = $workflow->beginUpload(array_replace($input, [
$abortActive = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 abort active',
'filename' => 'debian-13-abort-active.qcow2',
]), $actor)['intent'];
@ -491,9 +504,9 @@ namespace {
$activeClient = new CloudObjectStorageS3Client(new Client([
'handler' => $activeStack,
]));
$workflow->startUpload((string) $abortActive['id'], $actor, $activeClient);
$uploads->startUpload((string) $abortActive['id'], $actor, $activeClient);
try {
$workflow->cancel((string) $abortActive['id'], $actor, $activeClient);
$cancellation->cancel((string) $abortActive['id'], $actor, $activeClient);
throw new \RuntimeException('A still-active abort was reported complete.');
} catch (CloudError $error) {
$assert($error->httpStatus === 409,
@ -505,7 +518,7 @@ namespace {
$assert((string) $activeStored->state === 'source_unknown'
&& (string) $activeStored->error_code
=== 'multipart_abort_not_applied'
&& CloudTemplateImportWorkflow::dto($activeStored)['can_cancel']
&& CloudTemplateImportReadModel::project($activeStored)['can_cancel']
=== true,
'Provider proof that Abort did not apply was not made retryable.');
@ -513,7 +526,7 @@ namespace {
// proven no-effect failure. The panel can abandon the unique object key,
// while bucket lifecycle removes any provider-side orphan.
$actor['request_idempotency_key'] = 'multipart-template-intent-0006';
$createUnknown = $workflow->beginUpload(array_replace($input, [
$createUnknown = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 create unknown',
'filename' => 'debian-13-create-unknown.qcow2',
]), $actor)['intent'];
@ -524,7 +537,7 @@ namespace {
])),
]));
try {
$workflow->startUpload(
$uploads->startUpload(
(string) $createUnknown['id'], $actor, $createUnknownClient
);
throw new \RuntimeException('Unknown multipart create was retryable.');
@ -536,10 +549,10 @@ namespace {
(string) $createUnknown['id']
);
$assert((string) $unknownStored->state === 'source_unknown'
&& CloudTemplateImportWorkflow::dto($unknownStored)['can_cancel']
&& CloudTemplateImportReadModel::project($unknownStored)['can_cancel']
=== true,
'Unknown multipart create was not fenced for lifecycle abandonment.');
$abandoned = $workflow->cancel(
$abandoned = $cancellation->cancel(
(string) $createUnknown['id'], $actor, $createUnknownClient
);
$assert(($abandoned['state'] ?? null) === 'cancelled'
@ -550,14 +563,14 @@ namespace {
// An expired intent that never crossed multipart creation is cleaned
// locally without contacting object storage.
$actor['request_idempotency_key'] = 'multipart-template-intent-0007';
$expired = $workflow->beginUpload(array_replace($input, [
$expired = $uploads->beginUpload(array_replace($input, [
'name' => 'Debian 13 expired',
'filename' => 'debian-13-expired.qcow2',
]), $actor)['intent'];
Capsule::table('cloud_template_import_intents')
->where('id', (string) $expired['id'])
->update(['expires_at' => $clock - 1]);
$assert($workflow->cleanupOneExpired(new CloudObjectStorageS3Client(
$assert($cancellation->cleanupOneExpired(new CloudObjectStorageS3Client(
new Client(['handler' => HandlerStack::create(new MockHandler([]))])
))
&& (string) CloudTemplateImportIntent::findOrFail(
@ -604,7 +617,7 @@ namespace {
'url' => 'https://images.example.test/debian-13.qcow2',
'sha256' => $remoteDigest,
];
$remoteAck = $workflow->importRemote(
$remoteAck = $remote->importRemote(
$remoteInput,
$actor,
$remoteFetcher,
@ -636,7 +649,7 @@ namespace {
$emptyStorage = new CloudObjectStorageS3Client(new Client([
'handler' => HandlerStack::create(new MockHandler([])),
]));
$remoteReplay = $workflow->importRemote(
$remoteReplay = $remote->importRemote(
$remoteInput,
$actor,
$emptyFetcher,
@ -655,7 +668,7 @@ namespace {
static fn (string $host): array => ['93.184.216.34']
);
try {
$workflow->importRemote(
$remote->importRemote(
array_replace($remoteInput, ['name' => 'Debian 13 retry']),
$actor,
$failedFetcher,
@ -669,7 +682,7 @@ namespace {
$failedRemote = CloudTemplateImportIntent::query()
->where('request_idempotency_key',
'multipart-template-intent-0009')->firstOrFail();
$failedDto = CloudTemplateImportWorkflow::dto($failedRemote);
$failedDto = CloudTemplateImportReadModel::project($failedRemote);
$assert((string) $failedRemote->state === 'source_failed'
&& $failedDto['can_resume'] === true
&& $failedDto['can_cancel'] === true,
@ -696,7 +709,7 @@ namespace {
]),
]));
$retryStorageStack->push(Middleware::history($retryStorageHistory));
$retryAck = $workflow->resumeRemote(
$retryAck = $remote->resumeRemote(
(string) $failedRemote->id,
$actor,
new CloudTemplateRemoteFetcher(
@ -719,7 +732,7 @@ namespace {
// cancelled locally; no object-storage mutation is needed.
$actor['request_idempotency_key'] = 'multipart-template-intent-0010';
try {
$workflow->importRemote(
$remote->importRemote(
array_replace($remoteInput, ['name' => 'Debian 13 expired remote']),
$actor,
new CloudTemplateRemoteFetcher(
@ -739,7 +752,7 @@ namespace {
Capsule::table('cloud_template_import_intents')
->where('id', (string) $expiredRemote->id)
->update(['expires_at' => $clock - 1]);
$assert($workflow->cleanupOneExpired($emptyStorage)
$assert($cancellation->cleanupOneExpired($emptyStorage)
&& (string) CloudTemplateImportIntent::findOrFail(
(string) $expiredRemote->id
)->state === 'cancelled',
@ -766,7 +779,7 @@ namespace {
]));
$unknownStorageStack->push(Middleware::history($unknownStorageHistory));
try {
$workflow->importRemote(
$remote->importRemote(
array_replace($remoteInput, ['name' => 'Debian 13 unknown put']),
$actor,
new CloudTemplateRemoteFetcher(
@ -785,7 +798,7 @@ namespace {
$unknownRemote = CloudTemplateImportIntent::query()
->where('request_idempotency_key',
'multipart-template-intent-0011')->firstOrFail();
$unknownDto = CloudTemplateImportWorkflow::dto($unknownRemote);
$unknownDto = CloudTemplateImportReadModel::project($unknownRemote);
$assert((string) $unknownRemote->state === 'source_unknown'
&& $unknownDto['can_resume'] === true
&& $unknownDto['can_cancel'] === false
@ -810,7 +823,7 @@ namespace {
]),
]));
$reconcileStack->push(Middleware::history($reconcileHistory));
$unknownAck = $workflow->resumeRemote(
$unknownAck = $remote->resumeRemote(
(string) $unknownRemote->id,
$actor,
$emptyFetcher,
@ -843,7 +856,7 @@ namespace {
]));
$absentStorageStack->push(Middleware::history($absentStorageHistory));
try {
$workflow->importRemote(
$remote->importRemote(
array_replace($remoteInput, ['name' => 'Debian 13 absent put']),
$actor,
new CloudTemplateRemoteFetcher(
@ -882,7 +895,7 @@ namespace {
]),
])),
]));
$absentRetryAck = $workflow->resumeRemote(
$absentRetryAck = $remote->resumeRemote(
(string) $absentRemote->id,
$actor,
new CloudTemplateRemoteFetcher(

@ -757,7 +757,7 @@ $assert(str_contains($cloudRoutes,
&& str_contains($cloudAdminController,
'public function cloudTemplateImportRemote(')
&& str_contains($cloudAdminController,
'(new CloudTemplateImportWorkflow())->importRemote(')
'(new CloudTemplateRemoteAcquisition())->importRemote(')
&& !str_contains($cloudRoutes, '/admin/cloud-templates/upload')
&& !str_contains($cloudAdminController, 'CloudLocalUploadService')
&& !str_contains($cloudRoutes, '/admin/rescue-templates/upload')

Loading…
Cancel
Save