From cea6f27e3bc56992317e68582d5b2e753f236bfc Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 31 Oct 2026 01:59:29 +0800 Subject: [PATCH] feat(rescue): publish quarantined ISO artifacts --- .../Cloud/CloudRescueCatalogService.php | 157 +++++++++ .../CloudRescueTemplateArtifactManager.php | 316 ++++++++++++++++++ web/tests/CloudRescueCatalogImportTest.php | 213 ++++++++++++ 3 files changed, 686 insertions(+) create mode 100644 web/app/Services/Cloud/CloudRescueCatalogService.php create mode 100644 web/app/Services/Cloud/CloudRescueTemplateArtifactManager.php create mode 100644 web/tests/CloudRescueCatalogImportTest.php diff --git a/web/app/Services/Cloud/CloudRescueCatalogService.php b/web/app/Services/Cloud/CloudRescueCatalogService.php new file mode 100644 index 00000000..f73909a5 --- /dev/null +++ b/web/app/Services/Cloud/CloudRescueCatalogService.php @@ -0,0 +1,157 @@ + $id > 0))); + sort($eligibleHostIds, SORT_NUMERIC); + if ($eligibleHostIds === []) { + throw new CloudError('没有已启用且已配置 Agent 的宿主机', 409); + } + $runtime ??= CloudObjectStorageConfig::runtime(true); + $fetcher ??= new CloudRemoteArtifactFetcher( + '救援 ISO', + 1048576, + 8 * 1024 * 1024 * 1024, + 'virt-rescue-iso-' + ); + $file = $fetcher->fetch($url, $sha256); + try { + return self::publishQuarantine( + $name, + $file, + $runtime, + $client, + $eligibleHostIds[0] + ); + } finally { + $path = $file['path'] ?? null; + if (is_string($path) && is_file($path)) { + @unlink($path); + } + } + } + + /** @param array{path:string,size_bytes:int,sha256:string} $file */ + private static function publishQuarantine( + string $name, + array $file, + array $runtime, + ?CloudObjectStorageS3Client $client, + int $validationHostId + ): array { + $templateId = bin2hex(random_bytes(16)); + $generation = bin2hex(random_bytes(16)); + $connection = (new CloudRescueTemplate())->getConnection(); + $template = $connection->transaction(static function () use ( + $templateId, + $generation, + $name, + $file, + $runtime + ): CloudRescueTemplate { + $existing = CloudRescueTemplate::query() + ->where('name', $name) + ->where('state', '<>', 'retired') + ->lockForUpdate()->first(); + if ($existing !== null) { + throw new CloudError('已经存在同名救援 ISO', 409); + } + $now = time(); + $row = new CloudRescueTemplate(); + $row->id = $templateId; + $row->name = $name; + $row->size_bytes = (int) $file['size_bytes']; + $row->sha256 = (string) $file['sha256']; + $row->revision = 1; + $row->generation_token = $generation; + $row->state = 'preparing'; + $row->active_job_id = null; + $row->created_at = $row->updated_at = $now; + $row->save(); + CloudRescueTemplateArtifactManager::reserveLocked($row, $runtime); + return $row; + }, 3); + $artifact = CloudRescueTemplateArtifactManager::publishReserved( + $template, + $file, + $client + ); + $template->refresh(); + return [ + 'template_id' => (string) $template->id, + 'name' => (string) $template->name, + 'state' => (string) $template->state, + 'revision' => (int) $template->revision, + 'generation_token' => (string) $template->generation_token, + 'size_bytes' => (int) $template->size_bytes, + 'sha256' => (string) $template->sha256, + 'artifact_state' => (string) $artifact->state, + 'validation_host_id' => $validationHostId, + ]; + } + + private static function remoteUrl($value): string + { + if (!is_string($value) || strlen($value) > 2048 + || preg_match('//u', $value) !== 1) { + throw new CloudError('救援 ISO 地址无效'); + } + $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'] ?? '')), + '.iso' + )) { + throw new CloudError( + '请填写无需账号、使用 443 端口的 HTTPS ISO 直链' + ); + } + return $value; + } + + private static function name($value): string + { + if (!is_string($value) || preg_match('//u', $value) !== 1) { + throw new CloudError('救援 ISO 名称无效'); + } + $value = trim($value); + if ($value === '' || mb_strlen($value, 'UTF-8') > 64 + || preg_match('/[\x00-\x1f\x7f]/u', $value) === 1) { + throw new CloudError('救援 ISO 名称无效'); + } + return $value; + } +} diff --git a/web/app/Services/Cloud/CloudRescueTemplateArtifactManager.php b/web/app/Services/Cloud/CloudRescueTemplateArtifactManager.php new file mode 100644 index 00000000..da5ad8b6 --- /dev/null +++ b/web/app/Services/Cloud/CloudRescueTemplateArtifactManager.php @@ -0,0 +1,316 @@ +exists || (string) $template->state !== 'preparing' + || CloudRescueTemplateArtifact::find((string) $template->id) + !== null) { + throw new CloudError('救援 ISO 主文件预留状态无效', 409); + } + self::assertIdentity( + (string) $template->id, + (string) $template->generation_token + ); + $runtime ??= CloudObjectStorageConfig::runtime(true); + self::assertRuntime($runtime); + $now = time(); + $artifact = new CloudRescueTemplateArtifact(); + $artifact->template_id = (string) $template->id; + $artifact->storage_revision = (int) $runtime['revision']; + $artifact->sealed_storage_runtime = CloudSecrets::encrypt( + $runtime, + self::RUNTIME_PURPOSE + ); + $artifact->object_key = self::objectKey( + (string) $runtime['config']['prefix'], + (string) $template->id, + (string) $template->generation_token + ); + $artifact->object_version_id = ''; + $artifact->object_etag = ''; + $artifact->size_bytes = (int) $template->size_bytes; + $artifact->sha256 = (string) $template->sha256; + $artifact->state = 'reserved'; + $artifact->error_code = ''; + $artifact->delete_operation_id = ''; + $artifact->delete_generation = 0; + $artifact->delete_cycle_attempts = 0; + $artifact->delete_presence_confirmations = 0; + $artifact->delete_last_checked_at = 0; + $artifact->delete_next_check_at = 0; + $artifact->delete_attention_at = null; + $artifact->verified_at = 0; + $artifact->created_at = $artifact->updated_at = $now; + $artifact->save(); + return $artifact; + } + + /** Publish into quarantine; boot validation promotes it in a later stage. */ + public static function publishReserved( + CloudRescueTemplate $template, + array $file, + ?CloudObjectStorageS3Client $client = null + ): CloudRescueTemplateArtifact { + self::assertFile($file, $template); + $connection = $template->getConnection(); + $artifact = $connection->transaction(static function () use ( + $template + ): CloudRescueTemplateArtifact { + $lockedTemplate = CloudRescueTemplate::query() + ->where('id', (string) $template->id) + ->lockForUpdate()->first(); + $locked = CloudRescueTemplateArtifact::query() + ->where('template_id', (string) $template->id) + ->lockForUpdate()->first(); + if ($lockedTemplate === null || $locked === null + || (string) $lockedTemplate->state !== 'preparing' + || (string) $locked->state !== 'reserved') { + throw new CloudError('救援 ISO 主文件不在可发布状态', 409); + } + CloudRescueCatalogStateMachine::assertTransition( + 'artifact', 'reserved', 'publishing' + ); + $locked->state = 'publishing'; + $locked->updated_at = time(); + $locked->save(); + return $locked; + }, 3); + + $publication = (new CloudImmutableArtifactTransport($client))->publish( + self::runtime($artifact), + (string) $artifact->object_key, + [ + 'path' => (string) $file['path'], + 'size_bytes' => (int) $file['size_bytes'], + 'sha256' => (string) $file['sha256'], + ] + ); + $resolution = (string) ($publication['resolution'] ?? 'unknown'); + if ($resolution !== 'applied') { + self::recordPublishFailure( + (string) $template->id, + match ($resolution) { + 'unknown' => 'rescue_source_reconcile_unavailable', + 'conflict' => 'rescue_source_identity_mismatch', + default => self::errorCode( + (string) ($publication['error_code'] ?? ''), + 'rescue_source_publish_failed' + ), + }, + in_array($resolution, ['unknown', 'conflict'], true) + ); + throw new CloudError(match ($resolution) { + 'unknown' => '无法确认救援 ISO 主文件是否已经保存,记录已锁定', + 'conflict' => '救援 ISO 对象大小与导入文件不一致,记录已锁定', + default => (string) ($publication['message'] ?? + '对象存储已确认救援 ISO 主文件未保存'), + }, $resolution === 'conflict' ? 409 : 502); + } + $identity = $publication['identity'] ?? null; + if (!is_array($identity)) { + throw new CloudError('救援 ISO 主文件对象身份无效', 502); + } + + return $connection->transaction(static function () use ( + $template, + $identity + ): CloudRescueTemplateArtifact { + $lockedTemplate = CloudRescueTemplate::query() + ->where('id', (string) $template->id) + ->lockForUpdate()->first(); + $locked = CloudRescueTemplateArtifact::query() + ->where('template_id', (string) $template->id) + ->lockForUpdate()->first(); + if ($lockedTemplate === null || $locked === null + || (string) $lockedTemplate->state !== 'preparing' + || (string) $locked->state !== 'publishing') { + throw new CloudError('救援 ISO 发布状态已经变化', 409); + } + CloudRescueCatalogStateMachine::assertTransition( + 'artifact', 'publishing', 'validating' + ); + CloudRescueCatalogStateMachine::assertTransition( + 'catalog', 'preparing', 'validating' + ); + $now = time(); + $locked->object_version_id = (string) $identity['version_id']; + $locked->object_etag = (string) $identity['etag']; + $locked->state = 'validating'; + $locked->error_code = ''; + $locked->updated_at = $now; + $locked->save(); + $lockedTemplate->state = 'validating'; + $lockedTemplate->updated_at = $now; + $lockedTemplate->save(); + return $locked; + }, 3); + } + + /** Read the exact quarantine or ready object through a bounded URL. */ + public static function downloadSource( + CloudRescueTemplate $template, + ?CloudObjectStorageS3Client $client = null + ): array { + $artifact = CloudRescueTemplateArtifact::find((string) $template->id); + if ($artifact === null + || !in_array((string) $artifact->state, + ['validating', 'ready'], true) + || (int) $artifact->size_bytes !== (int) $template->size_bytes + || !hash_equals( + (string) $artifact->sha256, + (string) $template->sha256 + )) { + throw new CloudError('救援 ISO 主文件尚未就绪', 409); + } + $runtime = self::runtime($artifact); + $transport = new CloudImmutableArtifactTransport($client); + $identity = $transport->head( + $runtime, + (string) $artifact->object_key, + (string) $artifact->object_version_id + ); + if (!CloudImmutableArtifactTransport::identityMatches( + $identity, + (int) $artifact->size_bytes, + (string) $artifact->object_etag, + (string) $artifact->object_version_id + )) { + throw new CloudError('救援 ISO 主文件对象身份已经变化', 409); + } + return [ + 'source_url' => $transport->presignedDownload( + $runtime, + (string) $artifact->object_key, + (string) $artifact->object_version_id, + self::DOWNLOAD_SECONDS + ), + 'source_size_bytes' => (int) $artifact->size_bytes, + 'sha256' => (string) $artifact->sha256, + ]; + } + + private static function recordPublishFailure( + string $templateId, + string $code, + bool $unknown + ): void { + (new CloudRescueTemplateArtifact())->getConnection()->transaction( + static function () use ($templateId, $code, $unknown): void { + $template = CloudRescueTemplate::query() + ->where('id', $templateId)->lockForUpdate()->first(); + $artifact = CloudRescueTemplateArtifact::query() + ->where('template_id', $templateId) + ->lockForUpdate()->first(); + if ($template === null || $artifact === null + || (string) $artifact->state !== 'publishing') { + return; + } + $artifactNext = $unknown + ? 'publish_unknown' : 'publish_failed'; + $catalogNext = $unknown + ? 'source_unknown' : 'source_failed'; + CloudRescueCatalogStateMachine::assertTransition( + 'artifact', 'publishing', $artifactNext + ); + CloudRescueCatalogStateMachine::assertTransition( + 'catalog', (string) $template->state, $catalogNext + ); + $now = time(); + $artifact->state = $artifactNext; + $artifact->error_code = substr($code, 0, 64); + $artifact->updated_at = $now; + $artifact->save(); + $template->state = $catalogNext; + $template->updated_at = $now; + $template->save(); + }, + 3 + ); + } + + /** @param array $file */ + private static function assertFile( + array $file, + CloudRescueTemplate $template + ): void { + $path = $file['path'] ?? null; + $size = $file['size_bytes'] ?? null; + $sha256 = strtolower((string) ($file['sha256'] ?? '')); + $actual = is_string($path) && is_file($path) && is_readable($path) + ? @hash_file('sha256', $path) : false; + if (!is_string($path) || !is_int($size) || $size < 1048576 + || $size > 8 * 1024 * 1024 * 1024 + || preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1 + || @filesize($path) !== $size || !is_string($actual) + || !hash_equals($sha256, $actual) + || $size !== (int) $template->size_bytes + || !hash_equals($sha256, (string) $template->sha256)) { + throw new CloudError('救援 ISO 主文件校验失败', 422); + } + } + + /** @return array */ + private static function runtime( + CloudRescueTemplateArtifact $artifact + ): array { + $runtime = CloudSecrets::decrypt( + (string) $artifact->sealed_storage_runtime, + self::RUNTIME_PURPOSE + ); + self::assertRuntime($runtime); + return $runtime; + } + + private static function objectKey( + string $prefix, + string $templateId, + string $generationToken + ): string { + $prefix = trim($prefix, '/'); + return ($prefix === '' ? '' : $prefix . '/') + . 'rescue-isos/' . $templateId . '/' + . $generationToken . '/rescue.iso'; + } + + private static function assertIdentity( + string $templateId, + string $generationToken + ): void { + if (preg_match('/^[a-f0-9]{32}$/D', $templateId) !== 1 + || preg_match('/^[a-f0-9]{32}$/D', $generationToken) !== 1) { + throw new CloudError('救援 ISO 主文件身份无效', 422); + } + } + + /** @param array $runtime */ + private static function assertRuntime(array $runtime): void + { + if (!is_array($runtime['config'] ?? null) + || !is_array($runtime['credentials'] ?? null) + || !is_int($runtime['revision'] ?? null) + || (int) $runtime['revision'] < 1 + || !is_string($runtime['config']['prefix'] ?? null)) { + throw new CloudError('救援 ISO 对象存储运行时无效', 503); + } + } + + private static function errorCode(string $code, string $fallback): string + { + return preg_match('/^[a-z][a-z0-9_]{0,63}$/D', $code) === 1 + ? $code : $fallback; + } +} diff --git a/web/tests/CloudRescueCatalogImportTest.php b/web/tests/CloudRescueCatalogImportTest.php new file mode 100644 index 00000000..5f555c84 --- /dev/null +++ b/web/tests/CloudRescueCatalogImportTest.php @@ -0,0 +1,213 @@ +addConnection([ + 'driver' => 'sqlite', 'database' => ':memory:', + ], 'default'); + $capsule->setAsGlobal(); + $capsule->bootEloquent(); + $capsule->schema('default')->create('cloud_rescue_templates', + static function (Blueprint $table): void { + $table->string('id')->primary(); + $table->string('name'); + $table->integer('size_bytes'); + $table->string('sha256'); + $table->integer('revision'); + $table->string('generation_token')->unique(); + $table->string('state'); + $table->integer('active_job_id')->nullable(); + $table->integer('created_at'); + $table->integer('updated_at'); + }); + $capsule->schema('default')->create( + 'cloud_rescue_template_artifacts', + static function (Blueprint $table): void { + $table->string('template_id')->primary(); + $table->integer('storage_revision'); + $table->text('sealed_storage_runtime'); + $table->string('object_key')->unique(); + $table->string('object_version_id')->default(''); + $table->string('object_etag')->default(''); + $table->integer('size_bytes'); + $table->string('sha256'); + $table->string('state'); + $table->string('error_code')->default(''); + $table->string('delete_operation_id')->default(''); + $table->integer('delete_generation')->default(0); + $table->integer('delete_cycle_attempts')->default(0); + $table->integer('delete_presence_confirmations')->default(0); + $table->integer('delete_last_checked_at')->default(0); + $table->integer('delete_next_check_at')->default(0); + $table->integer('delete_attention_at')->nullable(); + $table->integer('verified_at')->default(0); + $table->integer('created_at'); + $table->integer('updated_at'); + }); + + $body = str_repeat('bootable-rescue-iso-', 65536); + $digest = hash('sha256', $body); + $fetchHistory = []; + $fetchStack = HandlerStack::create(new MockHandler([ + new Response(200, [ + 'Content-Length' => (string) strlen($body), + 'Content-Encoding' => 'identity', + ], $body), + ])); + $fetchStack->push(Middleware::history($fetchHistory)); + $fetcher = new CloudRemoteArtifactFetcher( + '救援 ISO', + 1, + 8 * 1024 * 1024 * 1024, + 'virt-rescue-test-', + new Client(['handler' => $fetchStack]), + static fn (string $host): array => ['93.184.216.34'] + ); + + $storageHistory = []; + $storageStack = HandlerStack::create(new MockHandler([ + new Response(200, [ + 'ETag' => '"rescue-etag"', + 'x-amz-version-id' => 'rescue-version-1', + ]), + ])); + $storageStack->push(Middleware::history($storageHistory)); + $client = new CloudObjectStorageS3Client(new Client([ + 'handler' => $storageStack, + ])); + $runtime = [ + 'config' => [ + 'endpoint' => 'https://objects.example.com', + 'region' => 'ewr', + 'bucket' => 'rescue-bucket', + 'prefix' => 'virt-cloud', + 'path_style' => true, + ], + 'credentials' => [ + 'access_key_id' => 'RESCUEACCESSKEY', + 'secret_access_key' => 'rescue-secret', + ], + 'revision' => 9, + ]; + $result = CloudRescueCatalogService::importRemote([ + 'name' => 'SystemRescue', + 'url' => 'https://images.example.com/systemrescue.iso', + 'sha256' => $digest, + ], [ + 'is_super_admin' => true, + 'can_manage' => true, + 'user_id' => 1, + ], $fetcher, $runtime, $client, [32, 31]); + + $template = CloudRescueTemplate::find($result['template_id']); + $artifact = CloudRescueTemplateArtifact::find($result['template_id']); + $request = $storageHistory[0]['request']; + $assert($template !== null && $artifact !== null + && (string) $template->state === 'validating' + && (string) $artifact->state === 'validating' + && (int) $artifact->storage_revision === 9 + && (string) $artifact->object_version_id === 'rescue-version-1' + && (string) $template->sha256 === $digest + && (int) $template->size_bytes === strlen($body) + && $result['validation_host_id'] === 31, + 'Rescue import did not freeze the quarantine identity and host order.'); + $assert($request->getMethod() === 'PUT' + && str_contains( + (string) $request->getUri(), + '/rescue-bucket/virt-cloud/rescue-isos/' + . (string) $template->id . '/' + . (string) $template->generation_token . '/rescue.iso' + ) + && $request->getHeaderLine('If-None-Match') === '*' + && $request->getHeaderLine('X-Amz-Content-Sha256') === $digest, + 'Rescue master was not published to an immutable exact object key.'); + $assert(count($fetchHistory) === 1 && count($storageHistory) === 1, + 'Rescue import unexpectedly replayed a remote side effect.'); + + $unknownFetcher = new CloudRemoteArtifactFetcher( + '救援 ISO', + 1, + 8 * 1024 * 1024 * 1024, + 'virt-rescue-test-', + new Client(['handler' => HandlerStack::create(new MockHandler([ + new Response(200, [ + 'Content-Length' => (string) strlen($body), + ], $body), + ]))]), + static fn (string $host): array => ['93.184.216.34'] + ); + $unknownClient = new CloudObjectStorageS3Client(new Client([ + 'handler' => HandlerStack::create(new MockHandler([ + new ConnectException( + 'simulated lost rescue PUT response', + new Request('PUT', 'https://objects.example.com') + ), + new ConnectException( + 'simulated unavailable rescue HEAD', + new Request('HEAD', 'https://objects.example.com') + ), + ])), + ])); + try { + CloudRescueCatalogService::importRemote([ + 'name' => 'Unknown Rescue', + 'url' => 'https://images.example.com/unknown.iso', + 'sha256' => $digest, + ], [ + 'is_super_admin' => true, + 'can_manage' => true, + 'user_id' => 1, + ], $unknownFetcher, $runtime, $unknownClient, [31]); + throw new RuntimeException('Unknown rescue publication succeeded.'); + } catch (CloudError $error) { + $assert($error->httpStatus === 502, + 'Unknown rescue publication returned an unsafe status.'); + } + $unknownTemplate = CloudRescueTemplate::query() + ->where('name', 'Unknown Rescue')->first(); + $unknownArtifact = $unknownTemplate === null ? null + : CloudRescueTemplateArtifact::find((string) $unknownTemplate->id); + $assert($unknownTemplate !== null && $unknownArtifact !== null + && (string) $unknownTemplate->state === 'source_unknown' + && (string) $unknownArtifact->state === 'publish_unknown', + 'Unknown rescue PUT effect was not durably fenced for reconciliation.'); + + echo "Global rescue ISO quarantine import passed.\n"; +}