From eff7605c0fb7749ac3c2906363ef9ba2b259cc1b Mon Sep 17 00:00:00 2001 From: codex Date: Fri, 6 Nov 2026 03:14:28 +0800 Subject: [PATCH] feat(cloud): freeze service compensation batches --- .../Services/Cloud/CloudOperationCatalog.php | 2 + .../Cloud/CloudServiceCompensationService.php | 560 ++++++++++++++++++ ...ServiceCompensationServiceContractTest.php | 108 ++++ 3 files changed, 670 insertions(+) create mode 100644 web/app/Services/Cloud/CloudServiceCompensationService.php create mode 100644 web/tests/CloudServiceCompensationServiceContractTest.php diff --git a/web/app/Services/Cloud/CloudOperationCatalog.php b/web/app/Services/Cloud/CloudOperationCatalog.php index 76ac948a..3771b312 100644 --- a/web/app/Services/Cloud/CloudOperationCatalog.php +++ b/web/app/Services/Cloud/CloudOperationCatalog.php @@ -22,6 +22,7 @@ final class CloudOperationCatalog 'public_ip_pool_replacement_batch' => '批量迁移公网地址池', 'instance_upgrade' => '升级实例', 'instance_settings' => '实例设置', + 'service_compensation' => '实例可用时间补偿', 'snapshot_create' => '创建快照', 'snapshot_restore' => '恢复快照', 'snapshot_delete' => '删除快照', @@ -75,6 +76,7 @@ final class CloudOperationCatalog 'action', 'reinstall', 'instance_settings', + 'service_compensation', 'network_change', 'instance_upgrade', 'firewall_apply', diff --git a/web/app/Services/Cloud/CloudServiceCompensationService.php b/web/app/Services/Cloud/CloudServiceCompensationService.php new file mode 100644 index 00000000..b77bc852 --- /dev/null +++ b/web/app/Services/Cloud/CloudServiceCompensationService.php @@ -0,0 +1,560 @@ +clock = $clock === null + ? static fn (): int => time() + : \Closure::fromCallable($clock); + } + + public function preview(string $scopeType, int $scopeId): array + { + return $this->planner->preview($scopeType, $scopeId); + } + + public function create( + int $actorId, + string $idempotencyKey, + array $input + ): array { + if ($actorId < 1) { + throw new CloudError('管理员身份无效', 403); + } + $idempotencyKey = trim($idempotencyKey); + if (preg_match('/^[A-Za-z0-9._:-]{16,128}$/D', $idempotencyKey) + !== 1) { + throw new CloudError('幂等键无效', 422); + } + $request = $this->validateRequest($input); + $fingerprint = hash('sha256', self::json($request)); + $existing = $this->requestBatch($actorId, $idempotencyKey); + if ($existing !== null) { + return $this->idempotentResult($existing, $fingerprint); + } + + try { + return DB::connection('default')->transaction(function () use ( + $actorId, + $idempotencyKey, + $request, + $fingerprint + ): array { + $existing = $this->requestBatch( + $actorId, + $idempotencyKey, + true + ); + if ($existing !== null) { + return $this->idempotentResult($existing, $fingerprint); + } + + $plan = $this->planner->preview( + $request['scope_type'], + $request['scope_id'] + ); + if (!hash_equals( + $request['audience_digest'], + (string) $plan['audience_digest'] + )) { + throw new CloudError( + '受影响实例或服务周期已变化,请重新预览后再补偿', + 409 + ); + } + if ((int) $plan['eligible_count'] < 1) { + throw new CloudError('当前范围没有可补偿实例', 409); + } + + $now = $this->now(); + $batch = new CloudServiceCompensation(); + $batch->compensation_key = bin2hex(random_bytes(16)); + $batch->incident_key = $request['incident_key']; + $batch->requested_by_user_id = $actorId; + $batch->request_idempotency_key = $idempotencyKey; + $batch->request_fingerprint = $fingerprint; + $batch->scope_type = $request['scope_type']; + $batch->scope_id = $request['scope_id']; + $batch->scope_snapshot_json = self::json($plan['scope']); + $batch->reason_text = $request['reason_text']; + $batch->incident_starts_at = $request['incident_starts_at']; + $batch->incident_ends_at = $request['incident_ends_at']; + $batch->compensation_seconds = + $request['compensation_seconds']; + $batch->notify_users = $request['notify_users']; + $batch->audience_digest = $plan['audience_digest']; + $batch->instance_count = count($plan['instances']); + $batch->recipient_count = 0; + $batch->applied_count = 0; + $batch->deferred_count = 0; + $batch->rejected_count = (int) $plan['rejected_count']; + $batch->attention_count = (int) $plan['attention_count']; + $batch->state = 'pending'; + $batch->last_error_code = ''; + $batch->terminal_at = null; + $batch->created_at = $batch->updated_at = $now; + $batch->save(); + + foreach ($plan['instances'] as $instance) { + $eligibility = (array) ($instance['eligibility'] ?? []); + $eligibilityState = (string) ( + $eligibility['state'] ?? 'attention' + ); + $state = match ($eligibilityState) { + 'eligible' => 'pending', + 'rejected' => 'rejected', + default => 'attention', + }; + $terminal = $state !== 'pending'; + $errorCode = $terminal + ? (string) ($eligibility['code'] + ?? 'eligibility_unknown') + : ''; + + $item = new CloudServiceCompensationItem(); + $item->item_key = bin2hex(random_bytes(16)); + $item->batch_id = (int) $batch->id; + $item->incident_key = $request['incident_key']; + $item->instance_id = (int) $instance['id']; + $item->user_id = (int) $instance['user_id']; + $item->host_id = (int) $instance['host_id']; + $item->instance_name = (string) $instance['name']; + $item->requested_seconds = + $request['compensation_seconds']; + $item->service_period_id = null; + $item->traffic_entitlement_id = null; + $item->backup_entitlement_id = null; + $item->source_invoice_id = null; + $item->replacement_invoice_id = null; + $item->audit_job_id = null; + $item->before_expires_at = null; + $item->after_expires_at = null; + $item->before_period_ends_at = null; + $item->after_period_ends_at = null; + $item->before_traffic_ends_at = null; + $item->after_traffic_ends_at = null; + $item->before_backup_ends_at = null; + $item->after_backup_ends_at = null; + $item->before_snapshot_json = self::json($instance); + $item->after_snapshot_json = null; + $item->state = $state; + $item->attempts = 0; + $item->available_at = $now; + $item->lease_token = null; + $item->lease_until = 0; + $item->applied_at = null; + $item->terminal_at = $terminal ? $now : null; + $item->last_error_code = $errorCode; + $item->last_error = ''; + $item->created_at = $item->updated_at = $now; + $item->save(); + } + if (CloudServiceCompensationItem::where( + 'batch_id', (int) $batch->id + )->count() !== (int) $batch->instance_count) { + throw new CloudError('实例补偿明细冻结不完整', 500); + } + + return $this->detailModel($batch); + }, 3); + } catch (QueryException $error) { + $existing = $this->requestBatch($actorId, $idempotencyKey); + if ($existing !== null) { + return $this->idempotentResult($existing, $fingerprint); + } + if ((string) $error->getCode() === '23000') { + $latest = $this->planner->preview( + $request['scope_type'], + $request['scope_id'] + ); + $instanceIds = array_values(array_filter(array_map( + static fn (array $instance): int => + (int) ($instance['id'] ?? 0), + (array) ($latest['instances'] ?? []) + ), static fn (int $id): bool => $id > 0)); + if ($instanceIds !== [] + && CloudServiceCompensationItem::where( + 'incident_key', $request['incident_key'] + )->whereIn('instance_id', $instanceIds)->exists()) { + throw new CloudError( + '同一事故已经包含这些实例,不能重复补偿', + 409 + ); + } + } + throw $error; + } + } + + public function detail(string $compensationKey): array + { + $batch = CloudServiceCompensation::where( + 'compensation_key', + $this->compensationKey($compensationKey) + )->first(); + if ($batch === null) { + throw new CloudError('实例补偿批次不存在', 404); + } + return $this->detailModel($batch); + } + + public function page(array $query = []): array + { + $page = filter_var($query['page'] ?? 1, FILTER_VALIDATE_INT, + ['options' => ['min_range' => 1]]) ?: 1; + $perPage = filter_var($query['per_page'] ?? 20, FILTER_VALIDATE_INT, + ['options' => ['min_range' => 1, 'max_range' => 100]]) ?: 20; + $builder = CloudServiceCompensation::query(); + $state = trim((string) ($query['state'] ?? '')); + if ($state !== '') { + if (!in_array($state, self::STATES, true)) { + throw new CloudError('补偿状态筛选无效', 422); + } + $builder->where('state', $state); + } + $scopeType = trim((string) ($query['scope_type'] ?? '')); + if ($scopeType !== '') { + if (!in_array($scopeType, [ + 'instance', 'host', 'public_ip_pool', + ], true)) { + throw new CloudError('补偿范围筛选无效', 422); + } + $builder->where('scope_type', $scopeType); + } + $total = (clone $builder)->count(); + $rows = $builder->orderByDesc('id') + ->forPage((int) $page, (int) $perPage)->get(); + return [ + 'page' => (int) $page, + 'per_page' => (int) $perPage, + 'total' => (int) $total, + 'items' => $rows->map(static fn ($batch): array => [ + 'compensation_key' => (string) $batch->compensation_key, + 'incident_key' => (string) $batch->incident_key, + 'scope' => self::decode( + (string) $batch->scope_snapshot_json + ), + 'reason_text' => (string) $batch->reason_text, + 'compensation_seconds' => + (int) $batch->compensation_seconds, + 'notify_users' => (bool) $batch->notify_users, + 'instance_count' => (int) $batch->instance_count, + 'recipient_count' => (int) $batch->recipient_count, + 'applied_count' => (int) $batch->applied_count, + 'deferred_count' => (int) $batch->deferred_count, + 'rejected_count' => (int) $batch->rejected_count, + 'attention_count' => (int) $batch->attention_count, + 'state' => (string) $batch->state, + 'last_error_code' => (string) $batch->last_error_code, + 'terminal_at' => $batch->terminal_at === null + ? null : (int) $batch->terminal_at, + 'created_at' => (int) $batch->created_at, + ])->all(), + ]; + } + + public function recalculate(int $batchId): void + { + if ($batchId < 1) { + throw new \InvalidArgumentException('Compensation batch is invalid.'); + } + DB::connection('default')->transaction(function () use ($batchId): void { + $batch = CloudServiceCompensation::where('id', $batchId) + ->lockForUpdate()->first(); + if ($batch !== null) { + $this->recalculateLocked($batch, $this->now()); + } + }, 3); + } + + public function recalculateLocked( + CloudServiceCompensation $batch, + int $now + ): void { + if (!$batch->exists || (int) $batch->id < 1) { + throw new \InvalidArgumentException('Compensation batch is invalid.'); + } + $items = CloudServiceCompensationItem::where( + 'batch_id', (int) $batch->id + )->orderBy('id')->lockForUpdate()->get(); + $counts = []; + $attempted = false; + foreach ($items as $item) { + $state = (string) $item->state; + $counts[$state] = ($counts[$state] ?? 0) + 1; + $attempted = $attempted || (int) $item->attempts > 0; + } + $count = static fn (string $state): int => + (int) ($counts[$state] ?? 0); + $open = $count('pending') + $count('applying') + $count('deferred'); + $applied = $count('applied'); + $deferred = $count('deferred'); + $rejected = $count('rejected') + $count('cancelled'); + $attention = $count('attention'); + + $batch->applied_count = $applied; + $batch->deferred_count = $deferred; + $batch->rejected_count = $rejected; + $batch->attention_count = $attention; + if ($items->count() !== (int) $batch->instance_count) { + $batch->state = 'attention'; + $batch->last_error_code = 'item_catalog_incomplete'; + if ($batch->terminal_at === null) { + $batch->terminal_at = $now; + } + $batch->updated_at = $now; + $batch->save(); + return; + } + if ($open > 0) { + $batch->state = $count('applying') > 0 || $deferred > 0 + || $applied > 0 || $attempted ? 'applying' : 'pending'; + $batch->last_error_code = ''; + if ($batch->terminal_at !== null) { + throw new CloudError('终态补偿批次不能重新进入执行状态', 409); + } + } else { + if ($attention > 0) { + $batch->state = 'attention'; + $batch->last_error_code = 'item_attention'; + } elseif ($items->count() > 0 + && $applied === $items->count()) { + $batch->state = 'completed'; + $batch->last_error_code = ''; + } else { + $batch->state = 'partial'; + $batch->last_error_code = 'partial_result'; + } + if ($batch->terminal_at === null) { + $batch->terminal_at = $now; + } + } + $batch->updated_at = $now; + $batch->save(); + } + + private function validateRequest(array $input): array + { + CloudInput::only($input, [ + 'scope_type', 'scope_id', 'incident_key', 'reason_text', + 'incident_starts_at', 'incident_ends_at', + 'compensation_seconds', 'notify_users', 'audience_digest', + ]); + $scopeType = trim((string) ($input['scope_type'] ?? '')); + $scopeId = filter_var($input['scope_id'] ?? null, + FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]); + $incidentKey = strtolower(trim((string) ( + $input['incident_key'] ?? '' + ))); + $reason = trim((string) ($input['reason_text'] ?? '')); + $seconds = filter_var($input['compensation_seconds'] ?? null, + FILTER_VALIDATE_INT, + ['options' => ['min_range' => 1, 'max_range' => 31622400]]); + $notify = $input['notify_users'] ?? null; + $digest = strtolower(trim((string) ( + $input['audience_digest'] ?? '' + ))); + if (!in_array($scopeType, [ + 'instance', 'host', 'public_ip_pool', + ], true) + || $scopeId === false + || preg_match('/^[a-z0-9][a-z0-9._:-]{0,127}$/D', + $incidentKey) !== 1 + || $reason === '' || mb_strlen($reason) > 500 + || preg_match('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', + $reason) === 1 + || $seconds === false || !is_bool($notify) + || preg_match('/^[a-f0-9]{64}$/D', $digest) !== 1) { + throw new CloudError('实例补偿请求无效', 422); + } + + $startsAt = $this->optionalPositiveInt( + $input, 'incident_starts_at' + ); + $endsAt = $this->optionalPositiveInt($input, 'incident_ends_at'); + if (($startsAt === null) !== ($endsAt === null) + || ($startsAt !== null && $endsAt <= $startsAt)) { + throw new CloudError('事故时间范围无效', 422); + } + return [ + 'scope_type' => $scopeType, + 'scope_id' => (int) $scopeId, + 'incident_key' => $incidentKey, + 'reason_text' => $reason, + 'incident_starts_at' => $startsAt, + 'incident_ends_at' => $endsAt, + 'compensation_seconds' => (int) $seconds, + 'notify_users' => $notify, + 'audience_digest' => $digest, + ]; + } + + private function optionalPositiveInt(array $input, string $key): ?int + { + if (!array_key_exists($key, $input) || $input[$key] === null + || $input[$key] === '') { + return null; + } + $value = filter_var($input[$key], FILTER_VALIDATE_INT, + ['options' => ['min_range' => 1]]); + if ($value === false) { + throw new CloudError('事故时间范围无效', 422); + } + return (int) $value; + } + + private function requestBatch( + int $actorId, + string $idempotencyKey, + bool $lock = false + ): ?CloudServiceCompensation { + $query = CloudServiceCompensation::where( + 'requested_by_user_id', $actorId + )->where('request_idempotency_key', $idempotencyKey); + return ($lock ? $query->lockForUpdate() : $query)->first(); + } + + private function idempotentResult( + CloudServiceCompensation $batch, + string $fingerprint + ): array { + if (!hash_equals((string) $batch->request_fingerprint, $fingerprint)) { + throw new CloudError('幂等键已用于其他实例补偿请求', 409); + } + return $this->detailModel($batch); + } + + private function detailModel(CloudServiceCompensation $batch): array + { + $items = CloudServiceCompensationItem::where( + 'batch_id', (int) $batch->id + )->orderBy('id')->get()->map(static fn ($item): array => [ + 'item_key' => (string) $item->item_key, + 'instance_id' => (int) $item->instance_id, + 'user_id' => (int) $item->user_id, + 'host_id' => (int) $item->host_id, + 'instance_name' => (string) $item->instance_name, + 'requested_seconds' => (int) $item->requested_seconds, + 'service_period_id' => $item->service_period_id === null + ? null : (int) $item->service_period_id, + 'traffic_entitlement_id' => + $item->traffic_entitlement_id === null + ? null : (int) $item->traffic_entitlement_id, + 'backup_entitlement_id' => + $item->backup_entitlement_id === null + ? null : (int) $item->backup_entitlement_id, + 'source_invoice_id' => $item->source_invoice_id === null + ? null : (int) $item->source_invoice_id, + 'replacement_invoice_id' => + $item->replacement_invoice_id === null + ? null : (int) $item->replacement_invoice_id, + 'audit_job_id' => $item->audit_job_id === null + ? null : (int) $item->audit_job_id, + 'before_expires_at' => $item->before_expires_at === null + ? null : (int) $item->before_expires_at, + 'after_expires_at' => $item->after_expires_at === null + ? null : (int) $item->after_expires_at, + 'before_snapshot' => self::decode( + (string) $item->before_snapshot_json + ), + 'after_snapshot' => $item->after_snapshot_json === null + ? null : self::decode((string) $item->after_snapshot_json), + 'state' => (string) $item->state, + 'attempts' => (int) $item->attempts, + 'available_at' => (int) $item->available_at, + 'applied_at' => $item->applied_at === null + ? null : (int) $item->applied_at, + 'terminal_at' => $item->terminal_at === null + ? null : (int) $item->terminal_at, + 'last_error_code' => (string) $item->last_error_code, + 'last_error' => (string) $item->last_error, + ])->all(); + $recipients = CloudServiceCompensationRecipient::where( + 'batch_id', (int) $batch->id + )->orderBy('id')->get()->map(static fn ($recipient): array => [ + 'user_id' => (int) $recipient->user_id, + 'email' => (string) $recipient->email_snapshot, + 'instance_count' => (int) $recipient->instance_count, + 'status' => (string) $recipient->status, + 'attempts' => (int) $recipient->attempts, + 'sent_at' => $recipient->sent_at === null + ? null : (int) $recipient->sent_at, + 'last_error_code' => (string) $recipient->last_error_code, + ])->all(); + return [ + 'compensation_key' => (string) $batch->compensation_key, + 'incident_key' => (string) $batch->incident_key, + 'requested_by_user_id' => (int) $batch->requested_by_user_id, + 'scope_type' => (string) $batch->scope_type, + 'scope_id' => (int) $batch->scope_id, + 'scope' => self::decode((string) $batch->scope_snapshot_json), + 'reason_text' => (string) $batch->reason_text, + 'incident_starts_at' => $batch->incident_starts_at === null + ? null : (int) $batch->incident_starts_at, + 'incident_ends_at' => $batch->incident_ends_at === null + ? null : (int) $batch->incident_ends_at, + 'compensation_seconds' => (int) $batch->compensation_seconds, + 'notify_users' => (bool) $batch->notify_users, + 'audience_digest' => (string) $batch->audience_digest, + 'instance_count' => (int) $batch->instance_count, + 'recipient_count' => (int) $batch->recipient_count, + 'applied_count' => (int) $batch->applied_count, + 'deferred_count' => (int) $batch->deferred_count, + 'rejected_count' => (int) $batch->rejected_count, + 'attention_count' => (int) $batch->attention_count, + 'state' => (string) $batch->state, + 'last_error_code' => (string) $batch->last_error_code, + 'terminal_at' => $batch->terminal_at === null + ? null : (int) $batch->terminal_at, + 'created_at' => (int) $batch->created_at, + 'updated_at' => (int) $batch->updated_at, + 'items' => $items, + 'recipients' => $recipients, + ]; + } + + private function compensationKey(string $value): string + { + $value = strtolower(trim($value)); + if (preg_match('/^[a-f0-9]{32}$/D', $value) !== 1) { + throw new CloudError('实例补偿编号无效', 422); + } + return $value; + } + + private function now(): int + { + return max(1, (int) ($this->clock)()); + } + + private static function json(array $value): string + { + return json_encode($value, JSON_THROW_ON_ERROR + | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + } + + private static function decode(string $value): array + { + $decoded = json_decode($value, true, 64, JSON_THROW_ON_ERROR); + return is_array($decoded) ? $decoded : []; + } +} diff --git a/web/tests/CloudServiceCompensationServiceContractTest.php b/web/tests/CloudServiceCompensationServiceContractTest.php new file mode 100644 index 00000000..82d56161 --- /dev/null +++ b/web/tests/CloudServiceCompensationServiceContractTest.php @@ -0,0 +1,108 @@ + 31622400", + "!is_bool(\$notify)", + "'/^[a-f0-9]{64}\$/D'", + "'/^[a-z0-9][a-z0-9._:-]{0,127}\$/D'", + 'mb_strlen($reason) > 500', + "(\$startsAt === null) !== (\$endsAt === null)", + "\$endsAt <= \$startsAt", +] as $validationContract) { + $assert(str_contains($service, $validationContract), + 'Request validation lost contract: ' . $validationContract); +} + +foreach ([ + "hash('sha256', self::json(\$request))", + "'requested_by_user_id', \$actorId", + "'request_idempotency_key', \$idempotencyKey", + "hash_equals((string) \$batch->request_fingerprint, \$fingerprint)", + "'幂等键已用于其他实例补偿请求'", +] as $idempotencyContract) { + $assert(str_contains($service, $idempotencyContract), + 'Idempotency contract is missing: ' . $idempotencyContract); +} + +$previewPosition = strpos($service, '$plan = $this->planner->preview('); +$digestPosition = strpos($service, "!hash_equals(\n \$request['audience_digest']"); +$batchSavePosition = strpos($service, '$batch->save();'); +$assert($previewPosition !== false && $digestPosition !== false + && $batchSavePosition !== false + && $previewPosition < $digestPosition + && $digestPosition < $batchSavePosition, + 'Audience digest must be recalculated and checked before freezing a batch.'); +$assert(str_contains($service, + "'受影响实例或服务周期已变化,请重新预览后再补偿'"), + 'Audience drift no longer has a stable conflict response.'); + +foreach ([ + "CloudServiceCompensationItem::where(\n 'incident_key', \$request['incident_key']", + "->whereIn('instance_id', \$instanceIds)->exists()", + "'同一事故已经包含这些实例,不能重复补偿'", +] as $incidentContract) { + $assert(str_contains($service, $incidentContract), + 'Incident overlap contract is missing: ' . $incidentContract); +} +$incidentWhere = strpos($service, + "'incident_key', \$request['incident_key']"); +$incidentOverlap = strpos($service, "->whereIn('instance_id', \$instanceIds)"); +$incidentConflict = strpos($service, "'同一事故已经包含这些实例,不能重复补偿'"); +$assert($incidentWhere !== false && $incidentOverlap !== false + && $incidentConflict !== false + && $incidentWhere < $incidentOverlap + && $incidentOverlap < $incidentConflict, + 'Incident-key conflicts must be narrowed to overlapping instances.'); + +foreach ([ + "->count() !== (int) \$batch->instance_count", + "'实例补偿明细冻结不完整'", + "\$items->count() !== (int) \$batch->instance_count", + "\$batch->state = 'attention'", + "\$batch->last_error_code = 'item_catalog_incomplete'", +] as $catalogContract) { + $assert(str_contains($service, $catalogContract), + 'Frozen-item catalog contract is missing: ' . $catalogContract); +} + +foreach ([ + "\$open = \$count('pending') + \$count('applying') + \$count('deferred')", + "\$applied = \$count('applied')", + "\$rejected = \$count('rejected') + \$count('cancelled')", + "\$attention = \$count('attention')", + "\$batch->state = 'completed'", + "\$batch->state = 'partial'", + "\$batch->last_error_code = 'item_attention'", + "'终态补偿批次不能重新进入执行状态'", +] as $projectionContract) { + $assert(str_contains($service, $projectionContract), + 'Batch-state projection lost contract: ' . $projectionContract); +} + +$assert(substr_count($catalog, "'service_compensation'") >= 2, + 'Service compensation must be registered in labels and instance logs.'); +$assert(str_contains($catalog, + "'service_compensation' => '实例可用时间补偿'"), + 'Service-compensation task label is missing.'); + +echo "Service compensation service contracts passed.\n";