From 77d16f080d96e5d318ad61adfa207a37ec0cac4a Mon Sep 17 00:00:00 2001 From: codex Date: Fri, 6 Nov 2026 18:43:12 +0800 Subject: [PATCH] feat(storage): persist backup preparation identity --- web/app/Command/CloudSetup.php | 19 +++++- web/app/Models/CloudInstanceBackup.php | 4 ++ web/sql/cloud.sql | 13 ++++ ...blicationPreparationSchemaContractTest.php | 66 +++++++++++++++++++ web/tests/CloudFreshSchemaContractTest.php | 2 +- ...oudMaintenanceNoticeSchemaContractTest.php | 2 +- ...licIpPoolReplacementSchemaContractTest.php | 2 +- ...licNetworkTransitionSchemaContractTest.php | 2 +- .../CloudRescueCatalogSchemaContractTest.php | 2 +- ...loudRestoreMigrationLedgerContractTest.php | 2 +- ...dServiceCompensationSchemaContractTest.php | 2 +- ...udStoragePublicationSchemaContractTest.php | 2 +- .../CloudTemplateImportIntentContractTest.php | 2 +- .../CloudTrafficPoolSchemaContractTest.php | 2 +- web/tests/CloudVpcSchemaContractTest.php | 2 +- 15 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 web/tests/CloudBackupPublicationPreparationSchemaContractTest.php diff --git a/web/app/Command/CloudSetup.php b/web/app/Command/CloudSetup.php index fde6631e..5192bf0e 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-v37-storage-publications'; + private const SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'; private const MAIN_TABLES = [ 'cloud_regions', 'cloud_traffic_pool_groups', 'cloud_network_lines', 'cloud_resource_pools', @@ -312,7 +312,9 @@ final class CloudSetup 'source', 'paid_at', 'created_at', 'updated_at', ], 'cloud_instance_backups' => [ - 'id', 'backup_key', 'storage_artifact_id', + 'id', 'backup_key', 'create_request_actor_id', + 'create_request_idempotency_key', + 'create_request_fingerprint', 'storage_artifact_id', 'source_instance_id', 'source_host_id', 'user_id', 'source_uuid', 'name', 'purpose', 'source', 'subscription_id', 'scheduled_for', 'state', 'consistency', @@ -605,6 +607,9 @@ final class CloudSetup 'chk_cloud_storage_operation_effect', 'chk_cloud_storage_operation_terminal', ], + 'cloud_instance_backups' => [ + 'chk_cloud_instance_backup_create_request', + ], 'cloud_public_ip_pool_catalog_mutex' => [ 'chk_cloud_public_ip_pool_catalog_mutex', ], @@ -1067,6 +1072,7 @@ final class CloudSetup ], 'cloud_instance_backups' => [ 'PRIMARY', 'cloud_instance_backup_key', + 'cloud_instance_backup_create_request', 'cloud_instance_backup_storage', 'cloud_instance_backup_object', 'cloud_instance_backup_schedule', 'cloud_instance_backup_source', @@ -1169,6 +1175,15 @@ final class CloudSetup * non-unique. Column order is part of the ownership/fencing semantics. */ private const REQUIRED_INDEX_SHAPES = [ + 'cloud_instance_backups' => [ + 'cloud_instance_backup_create_request' => [ + 'non_unique' => 0, + 'columns' => [ + 'create_request_actor_id', + 'create_request_idempotency_key', + ], + ], + ], 'cloud_maintenance_notices' => [ 'cloud_maintenance_notice_key' => [ 'non_unique' => 0, diff --git a/web/app/Models/CloudInstanceBackup.php b/web/app/Models/CloudInstanceBackup.php index 63bf4b29..d6579f5a 100644 --- a/web/app/Models/CloudInstanceBackup.php +++ b/web/app/Models/CloudInstanceBackup.php @@ -12,9 +12,13 @@ final class CloudInstanceBackup extends Model protected $hidden = [ 'sealed_storage_runtime', 'sealed_credential', 'object_etag', 'object_version_id', 'delete_operation_id', + 'create_request_actor_id', 'create_request_idempotency_key', + 'create_request_fingerprint', ]; protected $casts = [ 'id' => 'int', + 'create_request_actor_id' => 'int', + 'storage_artifact_id' => 'int', 'source_instance_id' => 'int', 'source_host_id' => 'int', 'user_id' => 'int', diff --git a/web/sql/cloud.sql b/web/sql/cloud.sql index 072f9993..8b453503 100644 --- a/web/sql/cloud.sql +++ b/web/sql/cloud.sql @@ -1398,6 +1398,9 @@ CREATE TABLE cloud_backup_period_entitlements ( CREATE TABLE cloud_instance_backups ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, backup_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + create_request_actor_id BIGINT UNSIGNED DEFAULT NULL, + create_request_idempotency_key VARCHAR(128) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, + create_request_fingerprint CHAR(64) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, storage_artifact_id BIGINT UNSIGNED DEFAULT NULL, source_instance_id BIGINT UNSIGNED NOT NULL, source_host_id BIGINT UNSIGNED NOT NULL, @@ -1437,6 +1440,7 @@ CREATE TABLE cloud_instance_backups ( created_at BIGINT UNSIGNED NOT NULL, updated_at BIGINT UNSIGNED NOT NULL, UNIQUE KEY cloud_instance_backup_key (backup_key), + UNIQUE KEY cloud_instance_backup_create_request (create_request_actor_id, create_request_idempotency_key), UNIQUE KEY cloud_instance_backup_storage (storage_artifact_id), UNIQUE KEY cloud_instance_backup_object (object_key), UNIQUE KEY cloud_instance_backup_schedule (subscription_id, scheduled_for), @@ -1444,6 +1448,15 @@ CREATE TABLE cloud_instance_backups ( KEY cloud_instance_backup_owner (user_id, id), KEY cloud_instance_backup_operation (last_operation_id), KEY cloud_instance_backup_delete_due (state, delete_next_check_at, id), + CONSTRAINT chk_cloud_instance_backup_create_request CHECK ( + (create_request_actor_id IS NULL + AND create_request_idempotency_key IS NULL + AND create_request_fingerprint IS NULL) + OR (create_request_actor_id IS NOT NULL + AND create_request_idempotency_key IS NOT NULL + AND CHAR_LENGTH(create_request_idempotency_key) BETWEEN 16 AND 128 + AND create_request_fingerprint REGEXP '^[a-f0-9]{64}$') + ), CONSTRAINT fk_cloud_instance_backup_storage FOREIGN KEY (storage_artifact_id) REFERENCES cloud_storage_artifacts (id) ON DELETE RESTRICT ON UPDATE RESTRICT diff --git a/web/tests/CloudBackupPublicationPreparationSchemaContractTest.php b/web/tests/CloudBackupPublicationPreparationSchemaContractTest.php new file mode 100644 index 00000000..7200132a --- /dev/null +++ b/web/tests/CloudBackupPublicationPreparationSchemaContractTest.php @@ -0,0 +1,66 @@ + [\n 'create_request_actor_id',\n 'create_request_idempotency_key',") + && str_contains($setup, "'non_unique' => 0"), + 'CloudSetup does not verify the exact unique request fence.'); +$assert(str_contains($model, "'create_request_actor_id' => 'int'") + && str_contains($model, "'storage_artifact_id' => 'int'") + && str_contains($model, "'create_request_idempotency_key'") + && str_contains($model, "'create_request_fingerprint'"), + 'Backup model exposes or miscasts durable preparation identity.'); + +echo "Backup publication preparation schema contracts passed.\n"; diff --git a/web/tests/CloudFreshSchemaContractTest.php b/web/tests/CloudFreshSchemaContractTest.php index 025cfdbb..ee56691b 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-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && !str_contains($setup, "SCHEMA_VERSION = 'go-v1'"), 'Outbound Agent schema must reject the incompatible earlier Go database.'); $assert(str_contains($schema, diff --git a/web/tests/CloudMaintenanceNoticeSchemaContractTest.php b/web/tests/CloudMaintenanceNoticeSchemaContractTest.php index fc73c36e..8d29554d 100644 --- a/web/tests/CloudMaintenanceNoticeSchemaContractTest.php +++ b/web/tests/CloudMaintenanceNoticeSchemaContractTest.php @@ -56,7 +56,7 @@ foreach ([ } $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v37-storage-publications'"), + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'"), 'CloudSetup schema version was not advanced for maintenance notices.'); echo "Maintenance notice schema contracts passed.\n"; diff --git a/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php b/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php index 76ecfeaf..b74692f2 100644 --- a/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php +++ b/web/tests/CloudPublicIpPoolReplacementSchemaContractTest.php @@ -53,7 +53,7 @@ $assert(is_string($schema) 'Public-pool replacement lacks durable batch, child, or claim schema.'); $assert(is_string($setup) && str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && str_contains($setup, "'cloud_public_ip_pool_replacement_batches'") && str_contains($setup, diff --git a/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php b/web/tests/CloudPublicNetworkTransitionSchemaContractTest.php index e874029e..cfc4eae7 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-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && 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 ad13595e..0cb84020 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-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && 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 index 956d209d..ba29d5bc 100644 --- a/web/tests/CloudRestoreMigrationLedgerContractTest.php +++ b/web/tests/CloudRestoreMigrationLedgerContractTest.php @@ -218,7 +218,7 @@ foreach ([ 'CloudSetup omits restore/migration ledger contract: ' . $required); } $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && str_contains($attemptModel, "protected \$table = 'cloud_backup_restore_attempts';") && str_contains($attemptModel, "'active_attempt' => 'int'") diff --git a/web/tests/CloudServiceCompensationSchemaContractTest.php b/web/tests/CloudServiceCompensationSchemaContractTest.php index eb8f2986..52ec80ec 100644 --- a/web/tests/CloudServiceCompensationSchemaContractTest.php +++ b/web/tests/CloudServiceCompensationSchemaContractTest.php @@ -105,7 +105,7 @@ $assert(str_contains($setup, 'CloudSetup lost the open-compensation fence index contract.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v37-storage-publications'"), + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'"), 'CloudSetup schema version was not advanced for service compensation.'); $appliedShape = preg_match( diff --git a/web/tests/CloudStoragePublicationSchemaContractTest.php b/web/tests/CloudStoragePublicationSchemaContractTest.php index 4837e394..d7b7c186 100644 --- a/web/tests/CloudStoragePublicationSchemaContractTest.php +++ b/web/tests/CloudStoragePublicationSchemaContractTest.php @@ -137,7 +137,7 @@ $assert(is_string($publicationModel) && str_contains($artifactModel, "'maximum_size_bytes' => 'int'"), 'Storage publication/artifact model contracts are incomplete.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v37-storage-publications'"), + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'"), 'CloudSetup schema version was not advanced for durable publications.'); echo "Storage publication schema contracts passed.\n"; diff --git a/web/tests/CloudTemplateImportIntentContractTest.php b/web/tests/CloudTemplateImportIntentContractTest.php index 22344697..84ddb230 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-v37-storage-publications'"), + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'"), '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 ac212d5a..a19cd55d 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-v37-storage-publications'") + "SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && 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 85f69110..735321af 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-v37-storage-publications'") + "private const SCHEMA_VERSION = 'go-agent-wss-v38-backup-publication-preparation'") && str_contains($setup, "'name' => 'cloud_vpc_enabled'") && str_contains($setup, "'value' => 'false'") && str_contains($setup,