From 25b386f02b422b4e05b4e549fc8defcf513c2e71 Mon Sep 17 00:00:00 2001 From: codex Date: Tue, 3 Nov 2026 21:04:42 +0800 Subject: [PATCH] feat: add restore and migration network ledgers --- web/app/Command/CloudSetup.php | 105 ++++++- web/app/Models/CloudBackupRestore.php | 8 + web/app/Models/CloudBackupRestoreAttempt.php | 63 ++++ web/app/Models/CloudInstanceMigration.php | 8 + .../CloudInstanceMigrationSourceDebt.php | 58 ++++ web/app/Models/CloudResourceReservation.php | 45 ++- .../CloudActivePublicNetworkClaimSet.php | 4 + .../CloudFrozenPublicNetworkIdentity.php | 250 ++++++++++++++++ .../CloudPublicNetworkAllocationService.php | 33 +++ web/sql/cloud.sql | 171 ++++++++++- web/tests/CloudFreshSchemaContractTest.php | 13 +- ...licIpPoolReplacementSchemaContractTest.php | 2 +- ...loudPublicNetworkAllocationServiceTest.php | 131 ++++++++- ...licNetworkTransitionSchemaContractTest.php | 2 +- .../CloudRescueCatalogSchemaContractTest.php | 2 +- ...loudRestoreMigrationLedgerContractTest.php | 278 ++++++++++++++++++ .../CloudTemplateImportIntentContractTest.php | 2 +- .../CloudTrafficPoolSchemaContractTest.php | 2 +- web/tests/CloudVpcSchemaContractTest.php | 2 +- 19 files changed, 1157 insertions(+), 22 deletions(-) create mode 100644 web/app/Models/CloudBackupRestoreAttempt.php create mode 100644 web/app/Models/CloudInstanceMigrationSourceDebt.php create mode 100644 web/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php create mode 100644 web/tests/CloudRestoreMigrationLedgerContractTest.php diff --git a/web/app/Command/CloudSetup.php b/web/app/Command/CloudSetup.php index 7187a072..06947f27 100644 --- a/web/app/Command/CloudSetup.php +++ b/web/app/Command/CloudSetup.php @@ -8,7 +8,7 @@ use App\Services\Config; /** Initializes only the clean-break PHP business and Agent log schemas. */ final class CloudSetup { - private const SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'; + private const SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'; private const MAIN_TABLES = [ 'cloud_regions', 'cloud_traffic_pool_groups', 'cloud_network_lines', 'cloud_resource_pools', @@ -34,8 +34,10 @@ final class CloudSetup 'cloud_platform_test_policy_rules', 'cloud_instance_snapshots', 'cloud_backup_subscriptions', 'cloud_backup_period_entitlements', 'cloud_instance_backups', 'cloud_deployment_snapshots', - 'cloud_backup_restores', 'cloud_backup_recoveries', - 'cloud_instance_migrations', 'cloud_peer_migration_artifacts', + 'cloud_backup_restores', 'cloud_backup_restore_attempts', + 'cloud_backup_recoveries', 'cloud_instance_migrations', + 'cloud_instance_migration_source_debts', + 'cloud_peer_migration_artifacts', 'cloud_instance_runtime', 'cloud_orders', 'cloud_order_items', 'cloud_resource_reservations', 'cloud_resource_reservation_ips', 'cloud_public_network_transitions', @@ -286,6 +288,16 @@ final class CloudSetup 'new_uuid', 'new_name', 'state', 'error_code', 'ready_at', 'created_at', 'updated_at', ], + 'cloud_backup_restore_attempts' => [ + 'id', 'attempt_key', 'backup_restore_id', 'generation', + 'operation_id', 'job_id', 'reservation_id', 'target_host_id', + 'target_uuid', 'target_name', 'target_network_attachment_id', + 'target_identity_json', 'target_identity_sha256', + 'target_claim_set_sha256', 'target_public_network_json', + 'target_public_network_sha256', 'state', 'effect_resolution', + 'active_attempt', 'last_error_code', 'effect_resolved_at', + 'terminal_at', 'created_at', 'updated_at', + ], 'cloud_backup_recoveries' => [ 'id', 'recovery_key', 'backup_id', 'instance_id', 'job_id', 'operation_id', 'state', 'error_code', 'completed_at', @@ -312,6 +324,16 @@ final class CloudSetup 'source_service_status', 'source_network_status', 'error_code', 'cutover_at', 'completed_at', 'created_at', 'updated_at', ], + 'cloud_instance_migration_source_debts' => [ + 'id', 'debt_key', 'migration_id', 'source_reservation_id', + 'source_host_id', 'source_uuid', + 'source_network_attachment_id', 'source_identity_json', + 'source_identity_sha256', 'source_claim_set_sha256', + 'source_public_network_json', 'source_public_network_sha256', + 'cleanup_operation_id', 'cleanup_job_id', 'state', + 'active_debt', 'last_error_code', 'resolved_at', + 'created_at', 'updated_at', + ], 'cloud_peer_migration_artifacts' => [ 'id', 'migration_id', 'artifact_id', 'role', 'source_snapshot_id', 'snapshot_key', 'name', 'consistency', @@ -321,7 +343,9 @@ final class CloudSetup ], 'cloud_resource_reservations' => [ 'id', 'reservation_key', 'operation_id', 'order_id', - 'backup_restore_id', 'offer_id', 'resource_pool_id', 'host_id', + 'backup_restore_id', 'backup_restore_attempt_key', + 'migration_source_debt_id', 'offer_id', 'resource_pool_id', + 'host_id', 'user_id', 'instance_id', 'network_attachment_id', 'public_ip_pool_id', 'public_ip_id', 'cpu_cores', 'memory_mib', 'disk_gib', 'state', 'expires_at', 'released_at', @@ -536,6 +560,18 @@ final class CloudSetup 'cloud_deployment_snapshots' => [ 'chk_cloud_deployment_snapshot_state', ], + 'cloud_backup_restore_attempts' => [ + 'chk_cloud_backup_restore_attempt_generation', + 'chk_cloud_backup_restore_attempt_active', + 'chk_cloud_backup_restore_attempt_state', + 'chk_cloud_backup_restore_attempt_shape', + ], + 'cloud_instance_migration_source_debts' => [ + 'chk_cloud_migration_source_debt_active', + 'chk_cloud_migration_source_debt_state', + 'chk_cloud_migration_source_debt_cleanup_pair', + 'chk_cloud_migration_source_debt_shape', + ], 'cloud_invoice_payments' => [ 'chk_cloud_invoice_payment_status', ], @@ -792,6 +828,15 @@ final class CloudSetup 'cloud_backup_restore_instance', 'cloud_backup_restore_backup', 'cloud_backup_restore_host', ], + 'cloud_backup_restore_attempts' => [ + 'PRIMARY', 'cloud_backup_restore_attempt_key', + 'cloud_backup_restore_attempt_operation', + 'cloud_backup_restore_attempt_generation', + 'cloud_backup_restore_attempt_active', + 'cloud_backup_restore_attempt_job', + 'cloud_backup_restore_attempt_reservation', + 'cloud_backup_restore_attempt_host', + ], 'cloud_backup_recoveries' => [ 'PRIMARY', 'cloud_backup_recovery_key', 'cloud_backup_recovery_operation', 'cloud_backup_recovery_job', @@ -818,6 +863,14 @@ final class CloudSetup 'cloud_instance_migration_source', 'cloud_instance_migration_target', ], + 'cloud_instance_migration_source_debts' => [ + 'PRIMARY', 'cloud_migration_source_debt_key', + 'cloud_migration_source_debt_migration', + 'cloud_migration_source_debt_active_reservation', + 'cloud_migration_source_debt_cleanup_operation', + 'cloud_migration_source_debt_cleanup_job', + 'cloud_migration_source_debt_host', + ], 'cloud_peer_migration_artifacts' => [ 'PRIMARY', 'cloud_peer_migration_artifact', 'cloud_peer_migration_snapshot', @@ -829,6 +882,8 @@ final class CloudSetup 'cloud_resource_reservation_operation', 'cloud_resource_reservation_order', 'cloud_resource_reservation_backup_restore', + 'cloud_resource_reservation_backup_attempt', + 'cloud_resource_reservation_migration_debt', 'cloud_resource_reservation_host', 'cloud_resource_reservation_pool', 'cloud_resource_reservation_instance', @@ -842,6 +897,48 @@ final class CloudSetup * non-unique. Column order is part of the ownership/fencing semantics. */ private const REQUIRED_INDEX_SHAPES = [ + 'cloud_backup_restore_attempts' => [ + 'cloud_backup_restore_attempt_generation' => [ + 'non_unique' => 0, + 'columns' => ['backup_restore_id', 'generation'], + ], + 'cloud_backup_restore_attempt_active' => [ + 'non_unique' => 0, + 'columns' => ['backup_restore_id', 'active_attempt'], + ], + 'cloud_backup_restore_attempt_operation' => [ + 'non_unique' => 0, + 'columns' => ['operation_id'], + ], + 'cloud_backup_restore_attempt_reservation' => [ + 'non_unique' => 0, + 'columns' => ['reservation_id'], + ], + ], + 'cloud_instance_migration_source_debts' => [ + 'cloud_migration_source_debt_migration' => [ + 'non_unique' => 0, + 'columns' => ['migration_id'], + ], + 'cloud_migration_source_debt_active_reservation' => [ + 'non_unique' => 0, + 'columns' => ['source_reservation_id', 'active_debt'], + ], + 'cloud_migration_source_debt_cleanup_operation' => [ + 'non_unique' => 0, + 'columns' => ['cleanup_operation_id'], + ], + ], + 'cloud_resource_reservations' => [ + 'cloud_resource_reservation_backup_attempt' => [ + 'non_unique' => 0, + 'columns' => ['backup_restore_attempt_key'], + ], + 'cloud_resource_reservation_migration_debt' => [ + 'non_unique' => 0, + 'columns' => ['migration_source_debt_id'], + ], + ], 'cloud_public_ips' => [ 'cloud_public_ip_reservation' => [ 'non_unique' => 1, diff --git a/web/app/Models/CloudBackupRestore.php b/web/app/Models/CloudBackupRestore.php index 19576acf..37e0fca4 100644 --- a/web/app/Models/CloudBackupRestore.php +++ b/web/app/Models/CloudBackupRestore.php @@ -18,4 +18,12 @@ final class CloudBackupRestore extends Model 'created_at' => 'int', 'updated_at' => 'int', ]; + + public function attempts() + { + return $this->hasMany( + CloudBackupRestoreAttempt::class, + 'backup_restore_id' + ); + } } diff --git a/web/app/Models/CloudBackupRestoreAttempt.php b/web/app/Models/CloudBackupRestoreAttempt.php new file mode 100644 index 00000000..249b652e --- /dev/null +++ b/web/app/Models/CloudBackupRestoreAttempt.php @@ -0,0 +1,63 @@ + 'int', + 'backup_restore_id' => 'int', + 'generation' => 'int', + 'job_id' => 'int', + 'reservation_id' => 'int', + 'target_host_id' => 'int', + 'target_network_attachment_id' => 'int', + 'active_attempt' => 'int', + 'effect_resolved_at' => 'int', + 'terminal_at' => 'int', + 'created_at' => 'int', + 'updated_at' => 'int', + ]; + + public function restore() + { + return $this->belongsTo(CloudBackupRestore::class, 'backup_restore_id'); + } + + public function boundReservationQuery() + { + $reservationId = (int) ($this->reservation_id ?? 0); + $attemptKey = (string) ($this->attempt_key ?? ''); + if ($reservationId < 1 + || preg_match('/^[a-f0-9]{32}$/D', $attemptKey) !== 1) { + throw new \LogicException( + 'Restore attempt reservation identity is incomplete.' + ); + } + return CloudResourceReservation::query() + ->where('id', $reservationId) + ->where('backup_restore_attempt_key', $attemptKey); + } + + public function job() + { + return $this->belongsTo(CloudJob::class, 'job_id'); + } + + public function matchesReservation( + CloudResourceReservation $reservation + ): bool { + $attemptKey = (string) ($this->attempt_key ?? ''); + return (int) ($this->reservation_id ?? 0) > 0 + && (int) $this->reservation_id === (int) ($reservation->id ?? 0) + && preg_match('/^[a-f0-9]{32}$/D', $attemptKey) === 1 + && hash_equals( + $attemptKey, + (string) ($reservation->backup_restore_attempt_key ?? '') + ); + } +} diff --git a/web/app/Models/CloudInstanceMigration.php b/web/app/Models/CloudInstanceMigration.php index f09849dd..c13c44a7 100644 --- a/web/app/Models/CloudInstanceMigration.php +++ b/web/app/Models/CloudInstanceMigration.php @@ -30,4 +30,12 @@ final class CloudInstanceMigration extends Model 'created_at' => 'int', 'updated_at' => 'int', ]; + + public function sourceDebt() + { + return $this->hasOne( + CloudInstanceMigrationSourceDebt::class, + 'migration_id' + ); + } } diff --git a/web/app/Models/CloudInstanceMigrationSourceDebt.php b/web/app/Models/CloudInstanceMigrationSourceDebt.php new file mode 100644 index 00000000..282c6d84 --- /dev/null +++ b/web/app/Models/CloudInstanceMigrationSourceDebt.php @@ -0,0 +1,58 @@ + 'int', + 'migration_id' => 'int', + 'source_reservation_id' => 'int', + 'source_host_id' => 'int', + 'source_network_attachment_id' => 'int', + 'cleanup_job_id' => 'int', + 'active_debt' => 'int', + 'resolved_at' => 'int', + 'created_at' => 'int', + 'updated_at' => 'int', + ]; + + public function migration() + { + return $this->belongsTo(CloudInstanceMigration::class, 'migration_id'); + } + + public function boundReservationQuery() + { + $debtId = (int) ($this->id ?? 0); + $reservationId = (int) ($this->source_reservation_id ?? 0); + if ($debtId < 1 || $reservationId < 1) { + throw new \LogicException( + 'Migration source-debt reservation identity is incomplete.' + ); + } + return CloudResourceReservation::query() + ->where('id', $reservationId) + ->where('migration_source_debt_id', $debtId); + } + + public function cleanupJob() + { + return $this->belongsTo(CloudJob::class, 'cleanup_job_id'); + } + + public function matchesReservation( + CloudResourceReservation $reservation + ): bool { + return (int) ($this->id ?? 0) > 0 + && (int) ($this->source_reservation_id ?? 0) > 0 + && (int) $this->source_reservation_id + === (int) ($reservation->id ?? 0) + && (int) ($reservation->migration_source_debt_id ?? 0) + === (int) $this->id; + } +} diff --git a/web/app/Models/CloudResourceReservation.php b/web/app/Models/CloudResourceReservation.php index e425b423..d8ecc38e 100644 --- a/web/app/Models/CloudResourceReservation.php +++ b/web/app/Models/CloudResourceReservation.php @@ -11,6 +11,7 @@ final class CloudResourceReservation extends Model 'id' => 'int', 'order_id' => 'int', 'backup_restore_id' => 'int', + 'migration_source_debt_id' => 'int', 'offer_id' => 'int', 'resource_pool_id' => 'int', 'host_id' => 'int', @@ -37,11 +38,20 @@ final class CloudResourceReservation extends Model if (!$this->exists) { $order = (int) ($this->order_id ?? 0); $restore = (int) ($this->backup_restore_id ?? 0); + $attemptKey = (string) ($this->backup_restore_attempt_key ?? ''); + $debt = (int) ($this->migration_source_debt_id ?? 0); $offer = (int) ($this->offer_id ?? 0); - if (!(($order > 0 && $restore === 0 && $offer > 0) - || ($order === 0 && $restore > 0 && $offer === 0))) { + if (!(($order > 0 && $offer > 0 && $restore === 0 + && $attemptKey === '' && $debt === 0) + || ($order === 0 && $offer === 0 && $restore > 0 + && $attemptKey === '' && $debt === 0) + || ($order === 0 && $offer === 0 && $restore === 0 + && preg_match('/^[a-f0-9]{32}$/D', $attemptKey) === 1 + && $debt === 0) + || ($order === 0 && $offer === 0 && $restore === 0 + && $attemptKey === '' && $debt > 0))) { throw new \LogicException( - 'New reservations require exactly one order or backup restore source.' + 'New reservations require exactly one immutable source.' ); } } @@ -63,4 +73,33 @@ final class CloudResourceReservation extends Model 'reservation_id' )->where('active_claim', 1); } + + public function backupRestoreAttemptQuery() + { + $reservationId = (int) ($this->id ?? 0); + $attemptKey = (string) ($this->backup_restore_attempt_key ?? ''); + if ($reservationId < 1 + || preg_match('/^[a-f0-9]{32}$/D', $attemptKey) !== 1) { + throw new \LogicException( + 'Restore attempt reservation identity is incomplete.' + ); + } + return CloudBackupRestoreAttempt::query() + ->where('reservation_id', $reservationId) + ->where('attempt_key', $attemptKey); + } + + public function migrationSourceDebtQuery() + { + $reservationId = (int) ($this->id ?? 0); + $debtId = (int) ($this->migration_source_debt_id ?? 0); + if ($reservationId < 1 || $debtId < 1) { + throw new \LogicException( + 'Migration source-debt reservation identity is incomplete.' + ); + } + return CloudInstanceMigrationSourceDebt::query() + ->where('id', $debtId) + ->where('source_reservation_id', $reservationId); + } } diff --git a/web/app/Services/Cloud/CloudActivePublicNetworkClaimSet.php b/web/app/Services/Cloud/CloudActivePublicNetworkClaimSet.php index 2f890130..33d47863 100644 --- a/web/app/Services/Cloud/CloudActivePublicNetworkClaimSet.php +++ b/web/app/Services/Cloud/CloudActivePublicNetworkClaimSet.php @@ -20,6 +20,10 @@ final class CloudActivePublicNetworkClaimSet } /** + * @internal Topology constructors only. Application business paths must + * obtain this value through + * CloudPublicNetworkAllocationService::currentClaimSet(). + * * @param array $claims * @param array $addresses keyed by public IP id */ diff --git a/web/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php b/web/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php new file mode 100644 index 00000000..ed203989 --- /dev/null +++ b/web/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php @@ -0,0 +1,250 @@ +reservationId(); + $networkAttachmentId = $claimSet->networkAttachmentId(); + self::assertResourceIdentity( + $reservationId, + $hostId, + $uuid, + $networkAttachmentId + ); + $network = $claimSet->publicNetwork(); + $claimSetSha256 = $claimSet->digest(); + if (preg_match('/^[a-f0-9]{64}$/D', $claimSetSha256) !== 1) { + throw new \InvalidArgumentException( + 'Frozen public network claim-set digest is invalid.' + ); + } + return new self(self::identity( + $reservationId, + $hostId, + $uuid, + $networkAttachmentId, + $claimSetSha256, + $network->fingerprint() + ), $network, $claimSetSha256); + } + + /** + * Rebuild a frozen identity from its row and the current authoritative + * claim-set projection. The host id must come from the same locked + * reservation used to obtain the claim set. Top-level row columns remain + * separate so a self-consistent cross-target JSON replacement is rejected. + */ + public static function fromStored(int $reservationId, int $hostId, + string $uuid, int $networkAttachmentId, string $identityJson, + string $identitySha256, string $publicNetworkJson, + string $publicNetworkSha256, string $claimSetSha256, + CloudActivePublicNetworkClaimSet $claimSet): self + { + self::assertResourceIdentity( + $reservationId, + $hostId, + $uuid, + $networkAttachmentId + ); + if (preg_match('/^[a-f0-9]{64}$/D', $identitySha256) !== 1 + || preg_match('/^[a-f0-9]{64}$/D', $publicNetworkSha256) !== 1 + || preg_match('/^[a-f0-9]{64}$/D', $claimSetSha256) !== 1) { + throw new \InvalidArgumentException( + 'Frozen public network digest is invalid.' + ); + } + try { + $identity = json_decode( + $identityJson, + true, + 16, + JSON_THROW_ON_ERROR + ); + $decoded = json_decode( + $publicNetworkJson, + true, + 64, + JSON_THROW_ON_ERROR + ); + } catch (\JsonException $exception) { + throw new \InvalidArgumentException( + 'Frozen public network JSON is invalid.', + 0, + $exception + ); + } + if (!is_array($identity) || array_is_list($identity)) { + throw new \InvalidArgumentException( + 'Frozen public network identity is invalid.' + ); + } + self::exactKeys($identity, [ + 'claim_set_sha256', 'contract', 'host_id', + 'network_attachment_id', 'public_network_sha256', + 'reservation_id', 'uuid', + ]); + if (($identity['contract'] ?? null) !== 1 + || !is_int($identity['reservation_id'] ?? null) + || !is_int($identity['host_id'] ?? null) + || !is_int($identity['network_attachment_id'] ?? null) + || !is_string($identity['uuid'] ?? null) + || !is_string($identity['claim_set_sha256'] ?? null) + || !is_string($identity['public_network_sha256'] ?? null)) { + throw new \InvalidArgumentException( + 'Frozen public network identity is invalid.' + ); + } + $network = CloudPublicNetworkSnapshot::fromArray($decoded); + if (!hash_equals($network->fingerprint(), $publicNetworkSha256)) { + throw new \InvalidArgumentException( + 'Frozen public network digest does not match its payload.' + ); + } + $canonical = self::identity( + $reservationId, + $hostId, + $uuid, + $networkAttachmentId, + $claimSetSha256, + $publicNetworkSha256 + ); + if ($identity !== $canonical + || !hash_equals($identity['claim_set_sha256'], $claimSetSha256) + || !hash_equals( + $identity['public_network_sha256'], + $publicNetworkSha256 + ) + || !hash_equals(self::digest($canonical), $identitySha256)) { + throw new \InvalidArgumentException( + 'Frozen public network identity digest does not match.' + ); + } + $authoritative = self::fromClaimSet($hostId, $uuid, $claimSet); + if ($claimSet->reservationId() !== $reservationId + || $claimSet->networkAttachmentId() !== $networkAttachmentId + || !hash_equals( + $authoritative->claimSetSha256(), + $claimSetSha256 + ) + || !hash_equals( + $authoritative->publicNetworkSha256(), + $publicNetworkSha256 + ) + || !hash_equals( + $authoritative->publicNetwork()->fingerprint(), + $network->fingerprint() + )) { + throw new \InvalidArgumentException( + 'Frozen public network identity does not match its claim set.' + ); + } + return new self($canonical, $network, $claimSetSha256); + } + + public function identityJson(): string + { + return self::encode($this->identity); + } + + public function identitySha256(): string + { + return self::digest($this->identity); + } + + public function publicNetwork(): CloudPublicNetworkSnapshot + { + return $this->network; + } + + public function publicNetworkJson(): string + { + return json_encode( + $this->network->toArray(), + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + ); + } + + public function publicNetworkSha256(): string + { + return $this->network->fingerprint(); + } + + public function claimSetSha256(): string + { + return $this->claimSetSha256; + } + + private static function identity(int $reservationId, int $hostId, + string $uuid, int $networkAttachmentId, string $claimSetSha256, + string $publicNetworkSha256): array + { + return [ + 'contract' => 1, + 'reservation_id' => $reservationId, + 'host_id' => $hostId, + 'uuid' => strtolower($uuid), + 'network_attachment_id' => $networkAttachmentId, + 'claim_set_sha256' => $claimSetSha256, + 'public_network_sha256' => $publicNetworkSha256, + ]; + } + + private static function assertResourceIdentity(int $reservationId, + int $hostId, string $uuid, int $networkAttachmentId): void + { + if ($reservationId < 1 || $hostId < 1 || $networkAttachmentId < 1 + || preg_match( + '/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/D', + strtolower($uuid) + ) !== 1) { + throw new \InvalidArgumentException( + 'Frozen public network resource identity is invalid.' + ); + } + } + + private static function exactKeys(array $value, array $expected): void + { + $actual = array_keys($value); + sort($actual, SORT_STRING); + sort($expected, SORT_STRING); + if ($actual !== $expected) { + throw new \InvalidArgumentException( + 'Frozen public network identity fields are invalid.' + ); + } + } + + private static function encode(array $value): string + { + return json_encode( + $value, + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + ); + } + + private static function digest(array $value): string + { + return hash('sha256', self::encode($value)); + } +} diff --git a/web/app/Services/Cloud/CloudPublicNetworkAllocationService.php b/web/app/Services/Cloud/CloudPublicNetworkAllocationService.php index 4f68cf80..23c21b60 100644 --- a/web/app/Services/Cloud/CloudPublicNetworkAllocationService.php +++ b/web/app/Services/Cloud/CloudPublicNetworkAllocationService.php @@ -90,10 +90,43 @@ final class CloudPublicNetworkAllocationService if ($set->reservationId() !== $reservationId) { throw new CloudError('公网网络活动声明归属不一致', 409); } + if ($expectedState === 'committed') { + self::assertInstancePublicNetworkSnapshot($instance, $set); + } return $set; }); } + private static function assertInstancePublicNetworkSnapshot( + ?object $instance, + CloudActivePublicNetworkClaimSet $claimSet + ): void { + try { + $spec = json_decode( + (string) ($instance->spec_json ?? ''), + true, + 64, + JSON_THROW_ON_ERROR + ); + if (!is_array($spec) || array_is_list($spec)) { + throw new \InvalidArgumentException( + 'Instance specification is invalid.' + ); + } + $frozen = CloudPublicNetworkSnapshot::fromArray( + $spec['public_network'] ?? null + ); + } catch (\Throwable) { + throw new CloudError('实例缺少有效的冻结公网网络快照', 409); + } + if (!hash_equals( + $frozen->fingerprint(), + $claimSet->publicNetwork()->fingerprint() + )) { + throw new CloudError('实例冻结公网网络快照与活动声明不一致', 409); + } + } + public static function reserveBundle(int $hostId, int $lineId, int $reservationId, string $operationId): CloudPublicNetworkSnapshot { diff --git a/web/sql/cloud.sql b/web/sql/cloud.sql index ca7dfd4f..dbe82a97 100644 --- a/web/sql/cloud.sql +++ b/web/sql/cloud.sql @@ -1267,6 +1267,86 @@ CREATE TABLE cloud_backup_restores ( KEY cloud_backup_restore_backup (backup_id, state, id), KEY cloud_backup_restore_host (target_host_id, state, id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; +-- Every independent restore dispatch owns one immutable attempt. A confirmed +-- not-applied retry creates a new generation and operation instead of +-- rewriting the historical reservation or claim identity. Unknown effects +-- remain active and therefore keep the complete dual-stack bundle fenced. +CREATE TABLE cloud_backup_restore_attempts ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + backup_restore_id BIGINT UNSIGNED NOT NULL, + generation INT UNSIGNED NOT NULL, + operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + job_id BIGINT UNSIGNED DEFAULT NULL, + reservation_id BIGINT UNSIGNED NOT NULL, + target_host_id BIGINT UNSIGNED NOT NULL, + target_uuid CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + target_name VARCHAR(63) NOT NULL, + target_network_attachment_id BIGINT UNSIGNED NOT NULL, + target_identity_json LONGTEXT NOT NULL, + target_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + target_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + target_public_network_json LONGTEXT NOT NULL, + target_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + state VARCHAR(24) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'reserved', + effect_resolution VARCHAR(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'not_applicable', + active_attempt TINYINT UNSIGNED DEFAULT 1, + last_error_code VARCHAR(128) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '', + effect_resolved_at BIGINT UNSIGNED DEFAULT NULL, + terminal_at BIGINT UNSIGNED DEFAULT NULL, + created_at BIGINT UNSIGNED NOT NULL, + updated_at BIGINT UNSIGNED NOT NULL, + UNIQUE KEY cloud_backup_restore_attempt_key (attempt_key), + UNIQUE KEY cloud_backup_restore_attempt_operation (operation_id), + UNIQUE KEY cloud_backup_restore_attempt_generation ( + backup_restore_id, generation + ), + UNIQUE KEY cloud_backup_restore_attempt_active ( + backup_restore_id, active_attempt + ), + UNIQUE KEY cloud_backup_restore_attempt_job (job_id), + UNIQUE KEY cloud_backup_restore_attempt_reservation (reservation_id), + KEY cloud_backup_restore_attempt_host (target_host_id, state, id), + CONSTRAINT chk_cloud_backup_restore_attempt_generation CHECK ( + generation >= 1 + ), + CONSTRAINT chk_cloud_backup_restore_attempt_active CHECK ( + active_attempt IS NULL OR active_attempt = 1 + ), + CONSTRAINT chk_cloud_backup_restore_attempt_state CHECK ( + state IN ('reserved','queued','awaiting_receipt','effect_unknown', + 'finalization_pending','succeeded','failed') + ), + CONSTRAINT chk_cloud_backup_restore_attempt_shape CHECK ( + (state = 'reserved' + AND job_id IS NULL + AND effect_resolution = 'not_applicable' + AND active_attempt IS NOT NULL AND active_attempt = 1 + AND effect_resolved_at IS NULL AND terminal_at IS NULL) + OR (state IN ('queued','awaiting_receipt') + AND job_id IS NOT NULL + AND effect_resolution = 'not_applicable' + AND active_attempt IS NOT NULL AND active_attempt = 1 + AND effect_resolved_at IS NULL AND terminal_at IS NULL) + OR (state = 'effect_unknown' AND effect_resolution = 'unknown' + AND job_id IS NOT NULL + AND active_attempt IS NOT NULL AND active_attempt = 1 + AND effect_resolved_at IS NULL AND terminal_at IS NULL) + OR (state = 'finalization_pending' + AND job_id IS NOT NULL + AND effect_resolution IN ('applied','not_applied') + AND active_attempt IS NOT NULL AND active_attempt = 1 + AND effect_resolved_at IS NOT NULL AND terminal_at IS NULL) + OR (state = 'succeeded' AND effect_resolution = 'applied' + AND job_id IS NOT NULL + AND active_attempt IS NULL + AND effect_resolved_at IS NOT NULL AND terminal_at IS NOT NULL) + OR (state = 'failed' AND effect_resolution = 'not_applied' + AND job_id IS NOT NULL + AND active_attempt IS NULL + AND effect_resolved_at IS NOT NULL AND terminal_at IS NOT NULL) + ) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; -- Restoring a backup onto its source instance is a destructive disk switch, -- distinct from creating an independent restored VM. This ledger fences the -- original operation until its exact Agent receipt is reconciled. @@ -1339,6 +1419,71 @@ CREATE TABLE cloud_instance_migrations ( KEY cloud_instance_migration_source (source_host_id, source_uuid), KEY cloud_instance_migration_target (target_host_id, target_uuid) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; +-- After cutover the stopped source duplicate is not an ordinary restore. Its +-- exact reservation and dual-stack identity remain a durable cleanup debt +-- until source deletion is confirmed or rollback restores source authority. +CREATE TABLE cloud_instance_migration_source_debts ( + id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, + debt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + migration_id BIGINT UNSIGNED NOT NULL, + source_reservation_id BIGINT UNSIGNED NOT NULL, + source_host_id BIGINT UNSIGNED NOT NULL, + source_uuid CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + source_network_attachment_id BIGINT UNSIGNED NOT NULL, + source_identity_json LONGTEXT NOT NULL, + source_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + source_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + source_public_network_json LONGTEXT NOT NULL, + source_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + cleanup_operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, + cleanup_job_id BIGINT UNSIGNED DEFAULT NULL, + state VARCHAR(24) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'prepared', + active_debt TINYINT UNSIGNED DEFAULT 1, + last_error_code VARCHAR(128) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '', + resolved_at BIGINT UNSIGNED DEFAULT NULL, + created_at BIGINT UNSIGNED NOT NULL, + updated_at BIGINT UNSIGNED NOT NULL, + UNIQUE KEY cloud_migration_source_debt_key (debt_key), + UNIQUE KEY cloud_migration_source_debt_migration (migration_id), + UNIQUE KEY cloud_migration_source_debt_active_reservation ( + source_reservation_id, active_debt + ), + UNIQUE KEY cloud_migration_source_debt_cleanup_operation ( + cleanup_operation_id + ), + UNIQUE KEY cloud_migration_source_debt_cleanup_job (cleanup_job_id), + KEY cloud_migration_source_debt_host (source_host_id, state, id), + CONSTRAINT chk_cloud_migration_source_debt_active CHECK ( + active_debt IS NULL OR active_debt = 1 + ), + CONSTRAINT chk_cloud_migration_source_debt_state CHECK ( + state IN ('prepared','retained','cleanup_running','released', + 'rollback_restored','attention') + ), + CONSTRAINT chk_cloud_migration_source_debt_cleanup_pair CHECK ( + (cleanup_operation_id IS NULL AND cleanup_job_id IS NULL) + OR (cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL) + ), + CONSTRAINT chk_cloud_migration_source_debt_shape CHECK ( + (state IN ('prepared','retained') + AND active_debt IS NOT NULL AND active_debt = 1 + AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL + AND resolved_at IS NULL) + OR (state = 'cleanup_running' + AND active_debt IS NOT NULL AND active_debt = 1 + AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL + AND resolved_at IS NULL) + OR (state = 'attention' + AND active_debt IS NOT NULL AND active_debt = 1 + AND resolved_at IS NULL) + OR (state = 'released' AND active_debt IS NULL + AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL + AND resolved_at IS NOT NULL) + OR (state = 'rollback_restored' AND active_debt IS NULL + AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL + AND resolved_at IS NOT NULL) + ) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; -- Immutable direct-transfer artifacts that exist only for one PeerMigration V3 -- session. Host paths and tickets are never stored in this catalog. CREATE TABLE cloud_peer_migration_artifacts ( @@ -1439,6 +1584,8 @@ CREATE TABLE cloud_resource_reservations ( operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, order_id BIGINT UNSIGNED DEFAULT NULL, backup_restore_id BIGINT UNSIGNED DEFAULT NULL, + backup_restore_attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, + migration_source_debt_id BIGINT UNSIGNED DEFAULT NULL, offer_id BIGINT UNSIGNED DEFAULT NULL, resource_pool_id BIGINT UNSIGNED NOT NULL, host_id BIGINT UNSIGNED NOT NULL, @@ -1460,14 +1607,34 @@ CREATE TABLE cloud_resource_reservations ( UNIQUE KEY cloud_resource_reservation_operation (operation_id), UNIQUE KEY cloud_resource_reservation_order (order_id), UNIQUE KEY cloud_resource_reservation_backup_restore (backup_restore_id), + UNIQUE KEY cloud_resource_reservation_backup_attempt ( + backup_restore_attempt_key + ), + UNIQUE KEY cloud_resource_reservation_migration_debt ( + migration_source_debt_id + ), KEY cloud_resource_reservation_host (host_id, state, expires_at, id), KEY cloud_resource_reservation_pool (resource_pool_id, state, id), KEY cloud_resource_reservation_instance (instance_id), KEY cloud_resource_reservation_network (network_attachment_id, public_ip_pool_id), KEY cloud_resource_reservation_ip (public_ip_id), CONSTRAINT chk_cloud_resource_reservation_source CHECK ( - (order_id IS NOT NULL AND backup_restore_id IS NULL AND offer_id IS NOT NULL) - OR (order_id IS NULL AND backup_restore_id IS NOT NULL AND offer_id IS NULL) + (order_id IS NOT NULL AND offer_id IS NOT NULL + AND backup_restore_id IS NULL + AND backup_restore_attempt_key IS NULL + AND migration_source_debt_id IS NULL) + OR (order_id IS NULL AND offer_id IS NULL + AND backup_restore_id IS NOT NULL + AND backup_restore_attempt_key IS NULL + AND migration_source_debt_id IS NULL) + OR (order_id IS NULL AND offer_id IS NULL + AND backup_restore_id IS NULL + AND backup_restore_attempt_key IS NOT NULL + AND migration_source_debt_id IS NULL) + OR (order_id IS NULL AND offer_id IS NULL + AND backup_restore_id IS NULL + AND backup_restore_attempt_key IS NULL + AND migration_source_debt_id IS NOT NULL) ) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; diff --git a/web/tests/CloudFreshSchemaContractTest.php b/web/tests/CloudFreshSchemaContractTest.php index 5ad777c2..0e1ef24a 100644 --- a/web/tests/CloudFreshSchemaContractTest.php +++ b/web/tests/CloudFreshSchemaContractTest.php @@ -22,7 +22,7 @@ $assert(stripos($schema, 'compatibility import') === false $assert(!preg_match('/\bengine_[A-Za-z0-9_]*\b/', $schema), 'cloud.sql retained an engine-prefixed identifier.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && !str_contains($setup, "SCHEMA_VERSION = 'go-v1'"), 'Outbound Agent schema must reject the incompatible earlier Go database.'); $assert(str_contains($schema, @@ -44,9 +44,11 @@ foreach (['cloud_host_agents', 'cloud_templates', 'cloud_instance_backups', 'cloud_deployment_snapshots', 'cloud_backup_subscriptions', 'cloud_backup_period_entitlements', - 'cloud_backup_restores', + 'cloud_backup_restores', 'cloud_backup_restore_attempts', 'cloud_backup_recoveries', 'cloud_order_items', 'cloud_invoice_items', - 'cloud_instance_migrations', 'cloud_peer_migration_artifacts', + 'cloud_instance_migrations', + 'cloud_instance_migration_source_debts', + 'cloud_peer_migration_artifacts', 'cloud_resource_reservation_ips', 'cloud_public_network_transitions', 'cloud_public_network_transition_ips', @@ -122,8 +124,9 @@ $assert(str_contains($schema, 'KEY cloud_job_backup_recovery (backup_recovery_id, id)') && str_contains($setup, "'cloud_backup_subscriptions', 'cloud_backup_period_entitlements'") - && str_contains($setup, - "'cloud_backup_restores', 'cloud_backup_recoveries'") + && str_contains($setup, "'cloud_backup_restores'") + && str_contains($setup, "'cloud_backup_restore_attempts'") + && str_contains($setup, "'cloud_backup_recoveries'") && str_contains($setup, "'cloud_job_backup', 'cloud_job_backup_restore'") && str_contains($setup, diff --git a/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php b/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php index eb2c047d..49ccd36b 100644 --- a/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php +++ b/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php @@ -65,7 +65,7 @@ $assert(is_string($schema) 'Public-pool replacement lacks durable batch, child, or active-claim schema.'); $assert(is_string($setup) && str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && str_contains($setup, "'cloud_public_ip_pool_replacement_batches'") && str_contains($setup, diff --git a/web/tests/CloudPublicNetworkAllocationServiceTest.php b/web/tests/CloudPublicNetworkAllocationServiceTest.php index 25879d72..5330fa9e 100644 --- a/web/tests/CloudPublicNetworkAllocationServiceTest.php +++ b/web/tests/CloudPublicNetworkAllocationServiceTest.php @@ -5,6 +5,7 @@ require dirname(__DIR__) . '/vendor/autoload.php'; use App\Services\Cloud\CloudPublicNetworkAllocationService; use App\Services\Cloud\CloudPublicNetworkCapacityUnavailable; use App\Services\Cloud\CloudActivePublicNetworkClaimSet; +use App\Services\Cloud\CloudFrozenPublicNetworkIdentity; use App\Services\Cloud\CloudPublicNetworkSnapshot; use App\Services\Cloud\CloudError; use Illuminate\Database\Capsule\Manager as Capsule; @@ -127,6 +128,7 @@ $schema->create('cloud_instances', static function (Blueprint $table): void { $table->integer('host_id'); $table->integer('resource_pool_id'); $table->integer('user_id'); + $table->text('spec_json'); }); $schema->create('cloud_instance_migrations', static function ( Blueprint $table @@ -285,11 +287,11 @@ foreach ($operations as $id => $operationId) { Capsule::table('cloud_instances')->insert([ [ 'id' => 900, 'reservation_id' => 500, 'host_id' => 1, - 'resource_pool_id' => 30, 'user_id' => 42, + 'resource_pool_id' => 30, 'user_id' => 42, 'spec_json' => '{}', ], [ 'id' => 901, 'reservation_id' => 504, 'host_id' => 1, - 'resource_pool_id' => 30, 'user_id' => 42, + 'resource_pool_id' => 30, 'user_id' => 42, 'spec_json' => '{}', ], ]); @@ -332,6 +334,12 @@ Capsule::table('cloud_resource_reservations')->where('id', 500)->update([ 'state' => 'committed', 'instance_id' => 900, ]); +Capsule::table('cloud_instances')->where('id', 900)->update([ + 'spec_json' => json_encode( + ['public_network' => $committed->toArray()], + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + ), +]); $replacementAttempt = CloudPublicNetworkAllocationService::reserveBundle( 1, 7, @@ -426,6 +434,12 @@ Capsule::table('cloud_resource_reservations')->where('id', 504)->update([ 'state' => 'committed', 'instance_id' => 901, ]); +Capsule::table('cloud_instances')->where('id', 901)->update([ + 'spec_json' => json_encode( + ['public_network' => $recoveredSuccess->toArray()], + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + ), +]); $rejects(static fn () => CloudPublicNetworkAllocationService::commitBundle( 504, 902, @@ -470,6 +484,103 @@ $assert($mixedGeneration->generation(4) === 1 && $mixedGeneration->generation(6) === 2 && strlen($mixedGeneration->digest()) === 64, 'A legal active pair required both families to share generation or operation.'); +$frozenUuid = '123e4567-e89b-42d3-a456-426614174000'; +$frozen = CloudFrozenPublicNetworkIdentity::fromClaimSet( + 1, + $frozenUuid, + $mixedGeneration +); +$restoredFrozen = CloudFrozenPublicNetworkIdentity::fromStored( + 500, + 1, + $frozenUuid, + 10, + $frozen->identityJson(), + $frozen->identitySha256(), + $frozen->publicNetworkJson(), + $frozen->publicNetworkSha256(), + $frozen->claimSetSha256(), + $mixedGeneration +); +$assert(hash_equals( + $restoredFrozen->identitySha256(), + $frozen->identitySha256() + ) && hash_equals( + $restoredFrozen->claimSetSha256(), + $mixedGeneration->digest() + ), + 'A frozen identity did not round-trip its authoritative claim set.'); +$tamperedTopLevel = json_decode( + $frozen->identityJson(), + true, + 16, + JSON_THROW_ON_ERROR +); +$tamperedTopLevel['network_attachment_id'] = 11; +$tamperedTopLevelJson = json_encode( + $tamperedTopLevel, + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES +); +$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored( + 500, + 1, + $frozenUuid, + 11, + $tamperedTopLevelJson, + hash('sha256', $tamperedTopLevelJson), + $frozen->publicNetworkJson(), + $frozen->publicNetworkSha256(), + $frozen->claimSetSha256(), + $mixedGeneration +), 'A self-consistent attachment rewrite bypassed the current claim set.'); +$tamperedNetwork = $mixedGeneration->publicNetwork()->toArray(); +$tamperedNetwork['network_selector'] = 'bridge:br1'; +$tamperedNetwork = CloudPublicNetworkSnapshot::fromArray($tamperedNetwork); +$tamperedNetworkJson = json_encode( + $tamperedNetwork->toArray(), + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES +); +$tamperedNetworkIdentity = json_decode( + $frozen->identityJson(), + true, + 16, + JSON_THROW_ON_ERROR +); +$tamperedNetworkIdentity['public_network_sha256'] = + $tamperedNetwork->fingerprint(); +$tamperedNetworkIdentityJson = json_encode( + $tamperedNetworkIdentity, + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES +); +$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored( + 500, + 1, + $frozenUuid, + 10, + $tamperedNetworkIdentityJson, + hash('sha256', $tamperedNetworkIdentityJson), + $tamperedNetworkJson, + $tamperedNetwork->fingerprint(), + $frozen->claimSetSha256(), + $mixedGeneration +), 'A self-consistent network rewrite bypassed the current claim set.'); +$otherGeneration = CloudPublicNetworkAllocationService::currentClaimSet( + 504, + 'committed', + 901 +); +$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored( + 500, + 1, + $frozenUuid, + 10, + $frozen->identityJson(), + $frozen->identitySha256(), + $frozen->publicNetworkJson(), + $frozen->publicNetworkSha256(), + $frozen->claimSetSha256(), + $otherGeneration +), 'A frozen identity accepted another reservation claim set.'); $activeRows = Capsule::table('cloud_resource_reservation_ips') ->where('reservation_id', 500)->where('active_claim', 1) ->orderBy('address_family')->get()->all(); @@ -562,6 +673,8 @@ $instance900 = [ 'host_id' => 1, 'resource_pool_id' => 30, 'user_id' => 42, + 'spec_json' => (string) Capsule::table('cloud_instances') + ->where('id', 900)->value('spec_json'), ]; $assertCurrentAuthorityRejects( static fn () => Capsule::table('cloud_instances') @@ -665,6 +778,13 @@ $assertCurrentAuthorityRejects( ->where('id', 10)->update(['line_id' => 7]), 'A claim set accepted an attachment outside the reservation line.' ); +$assertCurrentAuthorityRejects( + static fn () => Capsule::table('cloud_host_network_attachments') + ->where('id', 10)->update(['network_selector' => 'bridge:br1']), + static fn () => Capsule::table('cloud_host_network_attachments') + ->where('id', 10)->update(['network_selector' => 'bridge:br0']), + 'A claim set accepted selector drift from the frozen instance snapshot.' +); $assertCurrentAuthorityRejects( static fn () => Capsule::table('cloud_resource_reservations') ->where('id', 500)->update(['resource_pool_id' => 31]), @@ -679,6 +799,13 @@ $assertCurrentAuthorityRejects( ->where('id', 100)->update(['host_id' => 1]), 'A claim set accepted a pool outside the reservation host.' ); +$assertCurrentAuthorityRejects( + static fn () => Capsule::table('cloud_public_ip_pools') + ->where('id', 100)->update(['network_attachment_id' => 11]), + static fn () => Capsule::table('cloud_public_ip_pools') + ->where('id', 100)->update(['network_attachment_id' => 10]), + 'A claim set accepted a pool outside the active attachment.' +); $assertCurrentAuthorityRejects( static fn () => Capsule::table('cloud_public_ips') ->where('id', (int) $ipv4Claim->public_ip_id) diff --git a/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php b/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php index 8babe648..f54f5674 100644 --- a/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php +++ b/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php @@ -170,7 +170,7 @@ $assert(str_contains($setup, 'CloudSetup does not verify index uniqueness and ordered columns.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && str_contains($setup, "'cloud_public_network_transitions'") && str_contains($setup, "'cloud_public_network_transition_ips'") && str_contains($setup, "'reservation_ip_claim_id'") diff --git a/web/tests/CloudRescueCatalogSchemaContractTest.php b/web/tests/CloudRescueCatalogSchemaContractTest.php index 5fb12860..799732c3 100644 --- a/web/tests/CloudRescueCatalogSchemaContractTest.php +++ b/web/tests/CloudRescueCatalogSchemaContractTest.php @@ -56,7 +56,7 @@ $assert($replica !== '' && str_contains($replica, 'cleanup_resolved_at BIGINT UNSIGNED'), 'Rescue replica cannot prove exact identity or retain cleanup debt.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && str_contains($setup, "'cloud_rescue_artifact_delete_due'") && str_contains($setup, "'cloud_rescue_replica_cleanup'"), 'CloudSetup version or rescue catalog indexes are incomplete.'); diff --git a/web/tests/CloudRestoreMigrationLedgerContractTest.php b/web/tests/CloudRestoreMigrationLedgerContractTest.php new file mode 100644 index 00000000..f69d2496 --- /dev/null +++ b/web/tests/CloudRestoreMigrationLedgerContractTest.php @@ -0,0 +1,278 @@ +addConnection([ + 'driver' => 'sqlite', + 'database' => ':memory:', +], 'default'); +$capsule->setAsGlobal(); +$capsule->bootEloquent(); +$schemaBuilder = $capsule->schema('default'); +$schemaBuilder->create('cloud_backup_restore_attempts', static function ( + $table +): void { + $table->integer('id')->primary(); + $table->string('attempt_key'); + $table->integer('reservation_id'); +}); +$schemaBuilder->create('cloud_instance_migration_source_debts', static function ( + $table +): void { + $table->integer('id')->primary(); + $table->integer('source_reservation_id'); +}); +$schemaBuilder->create('cloud_resource_reservations', static function ( + $table +): void { + $table->integer('id')->primary(); + $table->string('backup_restore_attempt_key')->nullable(); + $table->integer('migration_source_debt_id')->nullable(); +}); + +$attempts = $table('cloud_backup_restore_attempts'); +$debts = $table('cloud_instance_migration_source_debts'); +$reservations = $table('cloud_resource_reservations'); +$assert($attempts !== '' + && str_contains($attempts, + 'reservation_id BIGINT UNSIGNED NOT NULL') + && str_contains($attempts, + 'UNIQUE KEY cloud_backup_restore_attempt_generation') + && str_contains($attempts, + 'UNIQUE KEY cloud_backup_restore_attempt_active') + && str_contains($attempts, + 'UNIQUE KEY cloud_backup_restore_attempt_operation (operation_id)') + && str_contains($attempts, + 'target_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($attempts, + 'target_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($attempts, + 'target_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($attempts, + 'CONSTRAINT chk_cloud_backup_restore_attempt_shape CHECK'), + 'Backup restore attempts do not fence immutable generations and network identity.'); +$attemptShape = $normalized($attempts); +$assert(str_contains($attemptShape, + "state = 'reserved' AND job_id IS NULL AND effect_resolution = 'not_applicable' AND active_attempt IS NOT NULL AND active_attempt = 1") + && str_contains($attemptShape, + "state IN ('queued','awaiting_receipt') AND job_id IS NOT NULL AND effect_resolution = 'not_applicable' AND active_attempt IS NOT NULL AND active_attempt = 1") + && str_contains($attemptShape, + "state = 'effect_unknown' AND effect_resolution = 'unknown' AND job_id IS NOT NULL AND active_attempt IS NOT NULL AND active_attempt = 1") + && str_contains($attemptShape, + "state = 'finalization_pending' AND job_id IS NOT NULL AND effect_resolution IN ('applied','not_applied') AND active_attempt IS NOT NULL AND active_attempt = 1") + && str_contains($attemptShape, + "state = 'succeeded' AND effect_resolution = 'applied' AND job_id IS NOT NULL AND active_attempt IS NULL") + && str_contains($attemptShape, + "state = 'failed' AND effect_resolution = 'not_applied' AND job_id IS NOT NULL AND active_attempt IS NULL"), + 'Restore-attempt terminal and unknown-effect fencing can diverge.'); + +$assert($debts !== '' + && str_contains($debts, + 'UNIQUE KEY cloud_migration_source_debt_migration (migration_id)') + && str_contains($debts, + 'UNIQUE KEY cloud_migration_source_debt_active_reservation') + && str_contains($debts, + 'source_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($debts, + 'source_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($debts, + 'source_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL') + && str_contains($debts, + "state IN ('prepared','retained','cleanup_running','released',") + && str_contains($debts, + 'CONSTRAINT chk_cloud_migration_source_debt_shape CHECK'), + 'Maintenance migration source cleanup debt is not durable and exclusive.'); +$debtShape = $normalized($debts); +$assert(str_contains($debtShape, + "(cleanup_operation_id IS NULL AND cleanup_job_id IS NULL) OR (cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL)") + && str_contains($debtShape, + "state IN ('prepared','retained') AND active_debt IS NOT NULL AND active_debt = 1 AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL AND resolved_at IS NULL") + && str_contains($debtShape, + "state = 'cleanup_running' AND active_debt IS NOT NULL AND active_debt = 1 AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL AND resolved_at IS NULL") + && str_contains($debtShape, + "state = 'attention' AND active_debt IS NOT NULL AND active_debt = 1 AND resolved_at IS NULL") + && str_contains($debtShape, + "state = 'released' AND active_debt IS NULL AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL AND resolved_at IS NOT NULL") + && str_contains($debtShape, + "state = 'rollback_restored' AND active_debt IS NULL AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL AND resolved_at IS NOT NULL"), + 'Source debt can become terminal without confirmed resolution.'); +// MySQL accepts CHECK expressions that evaluate to UNKNOWN. Every live-state +// branch must therefore reject NULL explicitly before comparing the nullable +// unique-index fence with 1. +$assert(!str_contains($attemptShape, + "effect_resolution = 'unknown' AND active_attempt = 1") + && !str_contains($debtShape, + "state = 'attention' AND active_debt = 1"), + 'A nullable active fence can satisfy MySQL CHECK through UNKNOWN.'); + +$assert($reservations !== '' + && str_contains($reservations, + 'backup_restore_attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL') + && str_contains($reservations, + 'migration_source_debt_id BIGINT UNSIGNED DEFAULT NULL') + && str_contains($reservations, + 'UNIQUE KEY cloud_resource_reservation_backup_attempt') + && str_contains($reservations, + 'UNIQUE KEY cloud_resource_reservation_migration_debt') + && !str_contains($reservations, 'backup_restore_attempt_id') + && substr_count($reservations, + 'backup_restore_attempt_key IS NOT NULL') === 1 + && substr_count($reservations, 'migration_source_debt_id IS NOT NULL') === 1, + 'Reservation ownership does not enforce one source ledger.'); + +foreach ([ + "'cloud_backup_restore_attempts'", + "'cloud_instance_migration_source_debts'", + "'backup_restore_attempt_key'", + "'migration_source_debt_id'", + "'chk_cloud_backup_restore_attempt_shape'", + "'chk_cloud_migration_source_debt_shape'", + "'chk_cloud_migration_source_debt_cleanup_pair'", + "'cloud_backup_restore_attempt_active'", + "'cloud_migration_source_debt_active_reservation'", + "'columns' => ['backup_restore_attempt_key']", + "'columns' => ['migration_source_debt_id']", +] as $required) { + $assert(str_contains($setup, $required), + 'CloudSetup omits restore/migration ledger contract: ' . $required); +} +$assert(str_contains($setup, + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") + && str_contains($attemptModel, + "protected \$table = 'cloud_backup_restore_attempts';") + && str_contains($attemptModel, "'active_attempt' => 'int'") + && str_contains($debtModel, + "protected \$table = 'cloud_instance_migration_source_debts';") + && str_contains($debtModel, "'active_debt' => 'int'") + && str_contains($reservationModel, + "function backupRestoreAttemptQuery()") + && str_contains($attemptModel, + "function boundReservationQuery()") + && str_contains($debtModel, + "function boundReservationQuery()") + && str_contains($reservationModel, + "'migration_source_debt_id' => 'int'"), + 'Models or setup version do not expose the new ownership boundary.'); + +$frozenIdentity = file_get_contents( + $root . '/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php' +); +$assert(is_string($frozenIdentity) + && str_contains($frozenIdentity, + 'public static function fromClaimSet(int $hostId, string $uuid,') + && str_contains($frozenIdentity, + 'CloudActivePublicNetworkClaimSet $claimSet') + && str_contains($frozenIdentity, + 'CloudPublicNetworkAllocationService::currentClaimSet()') + && !str_contains($frozenIdentity, + 'public static function fromLedger(') + && !str_contains($frozenIdentity, 'array $claims') + && !str_contains($frozenIdentity, 'array $addresses'), + 'Frozen identity can bypass the authoritative claim-set module.'); + +$attemptRecord = new CloudBackupRestoreAttempt(); +$attemptRecord->id = 91; +$attemptRecord->attempt_key = str_repeat('e', 32); +$attemptRecord->reservation_id = 92; +$reservationRecord = new CloudResourceReservation(); +$reservationRecord->id = 92; +$reservationRecord->backup_restore_attempt_key = str_repeat('e', 32); +Capsule::table('cloud_backup_restore_attempts')->insert([ + 'id' => 91, + 'attempt_key' => str_repeat('e', 32), + 'reservation_id' => 92, +]); +Capsule::table('cloud_resource_reservations')->insert([ + 'id' => 92, + 'backup_restore_attempt_key' => str_repeat('e', 32), + 'migration_source_debt_id' => null, +]); +$assert($attemptRecord->matchesReservation($reservationRecord) + && (int) $attemptRecord->boundReservationQuery()->first()?->id === 92 + && (int) $reservationRecord->backupRestoreAttemptQuery()->first()?->id + === 91, + 'Restore attempt and reservation are not joined by id and stable key.'); +$reservationRecord->backup_restore_attempt_key = str_repeat('f', 32); +Capsule::table('cloud_resource_reservations')->where('id', 92)->update([ + 'backup_restore_attempt_key' => str_repeat('f', 32), +]); +$assert(!$attemptRecord->matchesReservation($reservationRecord) + && $attemptRecord->boundReservationQuery()->first() === null + && $reservationRecord->backupRestoreAttemptQuery()->first() === null, + 'Restore attempt accepted a cross-bound reservation identity.'); + +$debtRecord = new CloudInstanceMigrationSourceDebt(); +$debtRecord->id = 101; +$debtRecord->source_reservation_id = 102; +$debtReservation = new CloudResourceReservation(); +$debtReservation->id = 102; +$debtReservation->migration_source_debt_id = 101; +Capsule::table('cloud_instance_migration_source_debts')->insert([ + 'id' => 101, + 'source_reservation_id' => 102, +]); +Capsule::table('cloud_resource_reservations')->insert([ + 'id' => 102, + 'backup_restore_attempt_key' => null, + 'migration_source_debt_id' => 101, +]); +$assert($debtRecord->matchesReservation($debtReservation) + && (int) $debtRecord->boundReservationQuery()->first()?->id === 102 + && (int) $debtReservation->migrationSourceDebtQuery()->first()?->id + === 101, + 'Migration source debt does not bind the exact source reservation both ways.'); +$debtReservation->migration_source_debt_id = 103; +Capsule::table('cloud_resource_reservations')->where('id', 102)->update([ + 'migration_source_debt_id' => 103, +]); +$assert(!$debtRecord->matchesReservation($debtReservation) + && $debtRecord->boundReservationQuery()->first() === null + && $debtReservation->migrationSourceDebtQuery()->first() === null, + 'Migration source debt accepted a cross-bound reservation identity.'); + +echo "Restore/migration durable-ledger contract tests passed.\n"; diff --git a/web/tests/CloudTemplateImportIntentContractTest.php b/web/tests/CloudTemplateImportIntentContractTest.php index 41173adc..a76a6d06 100644 --- a/web/tests/CloudTemplateImportIntentContractTest.php +++ b/web/tests/CloudTemplateImportIntentContractTest.php @@ -63,7 +63,7 @@ $assert(str_contains($schema, && str_contains($schema, 'CONSTRAINT chk_cloud_template_import_completion CHECK (') && str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'"), + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'"), 'Template imports are missing durable identity or terminal-state constraints.'); $assert(str_contains($routes, "'/admin/cloud-template-imports'") && str_contains($routes, "'/admin/cloud-template-imports/{id}'") diff --git a/web/tests/CloudTrafficPoolSchemaContractTest.php b/web/tests/CloudTrafficPoolSchemaContractTest.php index 79a6302d..56c45743 100644 --- a/web/tests/CloudTrafficPoolSchemaContractTest.php +++ b/web/tests/CloudTrafficPoolSchemaContractTest.php @@ -71,7 +71,7 @@ $assert(str_contains($schema, 'Service-period traffic-pool identity is not frozen or indexed.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && str_contains($setup, "'chk_cloud_traffic_entitlement_balance'") && str_contains($setup, "'cloud_traffic_ledger_sequence'"), 'CloudSetup schema version or named-object validation is incomplete.'); diff --git a/web/tests/CloudVpcSchemaContractTest.php b/web/tests/CloudVpcSchemaContractTest.php index 5e5eda66..bc2a632b 100644 --- a/web/tests/CloudVpcSchemaContractTest.php +++ b/web/tests/CloudVpcSchemaContractTest.php @@ -101,7 +101,7 @@ $assert(str_contains($jobs, 'vpc_id BIGINT UNSIGNED DEFAULT NULL') 'Cloud jobs cannot be correlated to VPC or VPC-port work.'); $assert(str_contains($setup, - "private const SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'") + "private const SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'") && str_contains($setup, "'name' => 'cloud_vpc_enabled'") && str_contains($setup, "'value' => 'false'") && str_contains($setup,