feat(cloud): freeze service compensation batches

go
codex 2 weeks ago
parent 4786c0c5f6
commit eff7605c0f

@ -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',

@ -0,0 +1,560 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudServiceCompensation;
use App\Models\CloudServiceCompensationItem;
use App\Models\CloudServiceCompensationRecipient;
use Illuminate\Database\Capsule\Manager as DB;
use Illuminate\Database\QueryException;
/** Owns reviewed compensation batches and their durable item projections. */
final class CloudServiceCompensationService
{
private const STATES = [
'pending', 'applying', 'completed', 'partial', 'attention',
];
private readonly \Closure $clock;
public function __construct(
private readonly CloudServiceCompensationPlanner $planner =
new CloudServiceCompensationPlanner(),
?callable $clock = null
) {
$this->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 : [];
}
}

@ -0,0 +1,108 @@
<?php
declare(strict_types=1);
$root = dirname(__DIR__);
$service = file_get_contents(
$root . '/app/Services/Cloud/CloudServiceCompensationService.php'
);
$catalog = file_get_contents(
$root . '/app/Services/Cloud/CloudOperationCatalog.php'
);
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$assert($service !== false && $catalog !== false,
'Service-compensation sources could not be read.');
foreach ([
"'scope_type', 'scope_id', 'incident_key', 'reason_text'",
"'incident_starts_at', 'incident_ends_at'",
"'compensation_seconds', 'notify_users', 'audience_digest'",
"'max_range' => 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";
Loading…
Cancel
Save