From 69e4f0fca8aa07ea9aa58a67b8b4e337affa8ff0 Mon Sep 17 00:00:00 2001 From: codex Date: Tue, 17 Nov 2026 20:10:42 +0800 Subject: [PATCH] feat(traffic): add verified settlement reconciliation --- docs/TRAFFIC_POOL_ROLLOUT.md | 28 +- .../CloudTrafficSettlementRecoveryCommand.php | 65 +++ web/app/Command/XCat.php | 6 + .../CloudTrafficUsageSettlementBucket.php | 5 + .../Cloud/CloudTrafficPoolAccounting.php | 21 + .../Cloud/CloudTrafficSettlementRecovery.php | 404 ++++++++++++++++++ .../CloudTrafficSettlementRecoveryTest.php | 276 ++++++++++++ 7 files changed, 804 insertions(+), 1 deletion(-) create mode 100644 web/app/Command/CloudTrafficSettlementRecoveryCommand.php create mode 100644 web/app/Services/Cloud/CloudTrafficSettlementRecovery.php create mode 100644 web/tests/CloudTrafficSettlementRecoveryTest.php diff --git a/docs/TRAFFIC_POOL_ROLLOUT.md b/docs/TRAFFIC_POOL_ROLLOUT.md index bc42a145..434edfbf 100644 --- a/docs/TRAFFIC_POOL_ROLLOUT.md +++ b/docs/TRAFFIC_POOL_ROLLOUT.md @@ -331,7 +331,33 @@ ordinary and policy workers paused as described in section 5.2 until the resolved projection, active restrictions and queued target state have been reviewed; then restore the workers and observe the original task flow. -### 5.4 Rollback matrix +### 5.4 Delayed settlement recovery + +When storage health reports overdue open settlement buckets or persisted +instance counters that have not crossed the accounting seam, first generate a +local read-only plan: + +```bash +php xcat cloudTrafficSettlementRecovery inspect +``` + +The output binds the exact bucket identities, period states, instance counters +and cursor positions into `plan_hash`. Review every blocker and action. The +command refuses to apply while an event-identity conflict or attention cursor +exists. If the plan is clean, execute that exact generation once: + +```bash +php xcat cloudTrafficSettlementRecovery apply --plan-hash= --apply +``` + +Any intervening state change invalidates the hash and requires a new inspect. +Apply uses only the ordinary bucket sealing, period reconciliation and usage +settlement interfaces. It cannot delete or rewrite an immutable ledger event, +change an entitlement balance manually, clear attention, or dispatch an Agent +operation. A process interruption may leave a safe partial application; run a +new inspect and continue only from its new plan. + +### 5.5 Rollback matrix | State | Operational action | | --- | --- | diff --git a/web/app/Command/CloudTrafficSettlementRecoveryCommand.php b/web/app/Command/CloudTrafficSettlementRecoveryCommand.php new file mode 100644 index 00000000..2d450682 --- /dev/null +++ b/web/app/Command/CloudTrafficSettlementRecoveryCommand.php @@ -0,0 +1,65 @@ + 'inspect']; + } + if ($action !== 'apply') { + throw new \InvalidArgumentException( + '用法:php xcat cloudTrafficSettlementRecovery inspect;' + . '或 apply --plan-hash=<64位哈希> --apply' + ); + } + $options = []; + foreach (array_slice($argv, 3) as $argument) { + if ($argument === '--apply') { + if (isset($options['apply'])) { + throw new \InvalidArgumentException('参数重复:apply'); + } + $options['apply'] = true; + continue; + } + if (preg_match('/^--([a-z-]+)=(.*)$/D', $argument, $match) + !== 1 || isset($options[$match[1]])) { + throw new \InvalidArgumentException('恢复参数无效或重复'); + } + $options[$match[1]] = $match[2]; + } + if (array_diff(array_keys($options), ['plan-hash', 'apply']) !== [] + || ($options['apply'] ?? false) !== true + || preg_match('/^[a-f0-9]{64}$/D', + (string) ($options['plan-hash'] ?? '')) !== 1) { + throw new \InvalidArgumentException( + '执行恢复必须绑定 inspect 返回的 plan-hash 并显式提供 --apply' + ); + } + return [ + 'action' => 'apply', + 'plan_hash' => (string) $options['plan-hash'], + ]; + } +} diff --git a/web/app/Command/XCat.php b/web/app/Command/XCat.php index 0cefd65b..5c651100 100644 --- a/web/app/Command/XCat.php +++ b/web/app/Command/XCat.php @@ -33,6 +33,10 @@ class XCat 'cloudLifecycle' => CloudLifecycle::run($this->argv) === 0, 'cloudTrafficPoolAttention' => CloudTrafficPoolAttention::run($this->argv) === 0, + 'cloudTrafficSettlementRecovery' => + CloudTrafficSettlementRecoveryCommand::run( + $this->argv + ) === 0, 'cloudRepairInstanceMetadata' => CloudRepairInstanceMetadata::run($this->argv) === 0, 'setTelegram' => $this->setTelegram(), @@ -117,6 +121,8 @@ class XCat . " php xcat cloudTrafficPoolAttention inspect --pool-id=N\n" . " php xcat cloudTrafficPoolAttention inspect-resolution --resolution-key=UUID\n" . " php xcat cloudTrafficPoolAttention resolve --pool-id=N --expected-version=V --resolution-key=UUID --apply --confirm=RESOLVE_TRAFFIC_POOL:N:V:UUID\n" + . " php xcat cloudTrafficSettlementRecovery inspect\n" + . " php xcat cloudTrafficSettlementRecovery apply --plan-hash=HASH --apply\n" . " php xcat cloudRepairInstanceMetadata [--apply] [--limit=N] [--after-id=N]\n" . " php xcat setTelegram\n" . " php xcat backup\n" diff --git a/web/app/Models/CloudTrafficUsageSettlementBucket.php b/web/app/Models/CloudTrafficUsageSettlementBucket.php index 08ac3ba5..888c98eb 100644 --- a/web/app/Models/CloudTrafficUsageSettlementBucket.php +++ b/web/app/Models/CloudTrafficUsageSettlementBucket.php @@ -29,4 +29,9 @@ final class CloudTrafficUsageSettlementBucket extends Model 'created_at' => 'int', 'updated_at' => 'int', ]; + + public function pool() + { + return $this->belongsTo(CloudTrafficPool::class, 'pool_id'); + } } diff --git a/web/app/Services/Cloud/CloudTrafficPoolAccounting.php b/web/app/Services/Cloud/CloudTrafficPoolAccounting.php index 34f380bb..e114f9d2 100644 --- a/web/app/Services/Cloud/CloudTrafficPoolAccounting.php +++ b/web/app/Services/Cloud/CloudTrafficPoolAccounting.php @@ -1398,6 +1398,27 @@ final class CloudTrafficPoolAccounting ->orderBy('seal_at')->orderBy('id') ->limit($limit)->pluck('id') ->map(static fn ($id): int => (int) $id)->all(); + return self::sealPlannedUsageBuckets($ids, $now); + } + + /** Seal only the exact due bucket identities approved by a local plan. */ + public static function sealPlannedUsageBuckets( + array $bucketIds, + ?int $now = null + ): int { + $now ??= time(); + $ids = array_values(array_unique(array_map( + static fn ($id): int => (int) $id, + $bucketIds + ))); + if (count($ids) > 2000 + || array_filter($ids, static fn (int $id): bool => $id < 1) + !== []) { + throw new \InvalidArgumentException( + 'traffic_settlement_planned_bucket_ids_invalid' + ); + } + sort($ids, SORT_NUMERIC); $sealed = 0; foreach ($ids as $id) { $hint = CloudTrafficUsageSettlementBucket::find($id); diff --git a/web/app/Services/Cloud/CloudTrafficSettlementRecovery.php b/web/app/Services/Cloud/CloudTrafficSettlementRecovery.php new file mode 100644 index 00000000..e735f8c1 --- /dev/null +++ b/web/app/Services/Cloud/CloudTrafficSettlementRecovery.php @@ -0,0 +1,404 @@ + */ + public static function inspect(): array + { + $now = time(); + $blockers = []; + $missingIdentityCount = 0; + $missingIdentityIds = []; + CloudTrafficUsageSettlementBucket::query() + ->select(['id', 'event_identity']) + ->chunkById(500, static function ($rows) use ( + &$missingIdentityCount, + &$missingIdentityIds + ): void { + foreach ($rows as $row) { + if (strlen((string) $row->event_identity) + === CloudTrafficSettlementEnvelope::IDENTITY_BYTES) { + continue; + } + $missingIdentityCount++; + if (count($missingIdentityIds) + < self::MAX_PLAN_ITEMS) { + $missingIdentityIds[] = (int) $row->id; + } + } + }); + $buckets = CloudTrafficUsageSettlementBucket::with('pool') + ->where('state', 'open')->where('seal_at', '<=', $now) + ->orderBy('seal_at')->orderBy('id') + ->limit(self::MAX_PLAN_ITEMS + 1)->get(); + if ($buckets->count() > self::MAX_PLAN_ITEMS) { + $blockers[] = [ + 'code' => 'due_settlement_bucket_scan_truncated', + 'count' => $buckets->count(), + ]; + $buckets = $buckets->take(self::MAX_PLAN_ITEMS); + } + $dueBuckets = []; + $validBuckets = []; + foreach ($buckets as $bucket) { + if (strlen((string) $bucket->event_identity) + !== CloudTrafficSettlementEnvelope::IDENTITY_BYTES) { + continue; + } + $validBuckets[] = $bucket; + $dueBuckets[] = self::bucketPlanItem($bucket); + } + if ($missingIdentityCount > 0) { + $blockers[] = [ + 'code' => 'settlement_event_identity_missing', + 'count' => $missingIdentityCount, + 'subject_ids' => $missingIdentityIds, + ]; + } + $eventConflicts = self::eventConflicts($validBuckets); + if ($eventConflicts !== []) { + $blockers[] = [ + 'code' => 'settlement_v2_event_conflict', + 'count' => count($eventConflicts), + 'subject_ids' => $eventConflicts, + ]; + } + + $attentionCursorIds = CloudTrafficInstanceCursor::where( + 'state', 'attention' + )->orderBy('instance_id')->limit(self::MAX_PLAN_ITEMS + 1) + ->pluck('instance_id')->map( + static fn ($id): int => (int) $id + )->all(); + if (count($attentionCursorIds) > self::MAX_PLAN_ITEMS) { + $blockers[] = [ + 'code' => 'attention_cursor_scan_truncated', + 'count' => count($attentionCursorIds), + ]; + $attentionCursorIds = array_slice( + $attentionCursorIds, + 0, + self::MAX_PLAN_ITEMS + ); + } + if ($attentionCursorIds !== []) { + $blockers[] = [ + 'code' => 'attention_cursor_requires_operator', + 'count' => count($attentionCursorIds), + 'subject_ids' => $attentionCursorIds, + ]; + } + + $periods = self::unsettledPeriods($now); + $instances = self::unsettledInstances(); + $actions = [ + 'due_buckets' => $dueBuckets, + 'unsettled_periods' => $periods, + 'unsettled_instances' => $instances, + ]; + $plan = [ + 'plan_version' => 1, + 'actions' => $actions, + 'blockers' => $blockers, + ]; + return [ + 'generated_at' => $now, + 'plan_hash' => self::planHash($plan), + 'actionable' => $blockers === [], + 'counts' => [ + 'due_buckets' => count($dueBuckets), + 'unsettled_periods' => count($periods), + 'unsettled_instances' => count($instances), + 'blockers' => count($blockers), + ], + 'actions' => $actions, + 'blockers' => $blockers, + ]; + } + + /** @return array */ + public static function apply(string $planHash): array + { + if (preg_match('/^[a-f0-9]{64}$/D', $planHash) !== 1) { + throw new \InvalidArgumentException( + 'traffic_settlement_recovery_plan_hash_invalid' + ); + } + $inspection = self::inspect(); + if (!hash_equals((string) $inspection['plan_hash'], $planHash)) { + throw new \RuntimeException( + 'traffic_settlement_recovery_plan_changed' + ); + } + if (($inspection['actionable'] ?? false) !== true) { + throw new \RuntimeException( + 'traffic_settlement_recovery_blocked' + ); + } + $bucketIds = array_map( + static fn (array $item): int => (int) $item['id'], + $inspection['actions']['due_buckets'] + ); + $sealed = CloudTrafficPoolAccounting::sealPlannedUsageBuckets( + $bucketIds, + (int) $inspection['generated_at'] + ); + $periods = 0; + foreach ($inspection['actions']['unsettled_periods'] as $item) { + $periodId = (int) $item['id']; + CloudTrafficPoolAccounting::reconcileServicePeriod( + $periodId, + 'settlement-recovery:' . $planHash . ':period:' . $periodId, + (int) $inspection['generated_at'] + ); + $periods++; + } + $instances = 0; + foreach ($inspection['actions']['unsettled_instances'] as $item) { + CloudTrafficPoolAccounting::settleInstanceUsage( + (int) $item['id'], + (int) $item['traffic_synced_at'] + ); + $instances++; + } + return [ + 'applied_plan_hash' => $planHash, + 'sealed_buckets' => $sealed, + 'reconciled_periods' => $periods, + 'settled_instances' => $instances, + 'after' => self::inspect(), + ]; + } + + /** @return list> */ + private static function unsettledPeriods(int $now): array + { + $ids = []; + $missing = CloudServicePeriod::query() + ->leftJoin('cloud_traffic_entitlements as recovery_entitlement', + 'recovery_entitlement.service_period_id', '=', + 'cloud_service_periods.id') + ->join('cloud_traffic_pool_groups as recovery_group', + 'recovery_group.id', '=', + 'cloud_service_periods.traffic_pool_group_id') + ->whereIn('recovery_group.mode', ['shadow', 'enforced']) + ->whereIn('cloud_service_periods.status', + ['scheduled', 'active', 'exhausted', 'finished']) + ->whereNull('recovery_entitlement.id') + ->orderBy('cloud_service_periods.id') + ->limit(self::MAX_PLAN_ITEMS + 1) + ->pluck('cloud_service_periods.id')->all(); + $due = CloudTrafficEntitlement::query() + ->join('cloud_traffic_pools as recovery_pool', + 'recovery_pool.id', '=', + 'cloud_traffic_entitlements.pool_id') + ->join('cloud_traffic_pool_groups as recovery_group', + 'recovery_group.id', '=', + 'recovery_pool.traffic_pool_group_id') + ->whereIn('recovery_group.mode', ['shadow', 'enforced']) + ->where(function ($query) use ($now): void { + $query->where(function ($scheduled) use ($now): void { + $scheduled->where( + 'cloud_traffic_entitlements.state', 'scheduled' + )->where('cloud_traffic_entitlements.starts_at', + '<=', $now); + })->orWhere(function ($ending) use ($now): void { + $ending->whereIn('cloud_traffic_entitlements.state', + ['active', 'exhausted']) + ->where('cloud_traffic_entitlements.ends_at', + '<=', $now); + })->orWhere(function ($closing) use ($now): void { + $closing->where( + 'cloud_traffic_entitlements.state', 'closing' + )->where('cloud_traffic_entitlements.closed_at', + '<=', $now); + }); + })->orderBy('cloud_traffic_entitlements.service_period_id') + ->limit(self::MAX_PLAN_ITEMS + 1) + ->pluck('cloud_traffic_entitlements.service_period_id')->all(); + $changed = CloudTrafficEntitlement::query() + ->join('cloud_service_periods as recovery_period', + 'recovery_period.id', '=', + 'cloud_traffic_entitlements.service_period_id') + ->join('cloud_traffic_pools as recovery_pool', + 'recovery_pool.id', '=', + 'cloud_traffic_entitlements.pool_id') + ->join('cloud_traffic_pool_groups as recovery_group', + 'recovery_group.id', '=', + 'recovery_pool.traffic_pool_group_id') + ->whereIn('recovery_group.mode', ['shadow', 'enforced']) + ->whereColumn('recovery_period.traffic_quota_bytes', '>', + 'cloud_traffic_entitlements.granted_bytes') + ->orderBy('cloud_traffic_entitlements.service_period_id') + ->limit(self::MAX_PLAN_ITEMS + 1) + ->pluck('cloud_traffic_entitlements.service_period_id')->all(); + foreach (array_merge($missing, $due, $changed) as $id) { + $ids[(int) $id] = true; + } + ksort($ids, SORT_NUMERIC); + if (count($ids) > self::MAX_PLAN_ITEMS) { + throw new \RuntimeException( + 'traffic_settlement_recovery_period_scan_truncated' + ); + } + if ($ids === []) { + return []; + } + $rows = CloudServicePeriod::whereIn('id', array_keys($ids)) + ->orderBy('id')->get(); + return $rows->map(static fn (CloudServicePeriod $period): array => [ + 'id' => (int) $period->id, + 'status' => (string) $period->status, + 'traffic_quota_bytes' => (int) $period->traffic_quota_bytes, + 'starts_at' => (int) $period->starts_at, + 'ends_at' => (int) $period->ends_at, + 'updated_at' => (int) ($period->updated_at ?? 0), + ])->all(); + } + + /** @return list> */ + private static function unsettledInstances(): array + { + $rows = CloudInstance::query() + ->leftJoin('cloud_traffic_instance_cursors as recovery_cursor', + 'recovery_cursor.instance_id', '=', 'cloud_instances.id') + ->whereExists(function ($eligible): void { + $eligible->selectRaw('1') + ->from('cloud_service_periods as recovery_period') + ->join('cloud_traffic_pool_groups as recovery_group', + 'recovery_group.id', '=', + 'recovery_period.traffic_pool_group_id') + ->whereColumn('recovery_period.instance_id', + 'cloud_instances.id') + ->whereIn('recovery_group.mode', ['shadow', 'enforced']); + })->where(function ($query): void { + $query->where(function ($missing): void { + $missing->whereNull('recovery_cursor.instance_id') + ->where('cloud_instances.traffic_synced_at', '>', 0); + })->orWhere('recovery_cursor.state', 'ready'); + })->where(function ($query): void { + $query->whereNull('recovery_cursor.instance_id') + ->orWhereColumn('cloud_instances.lifetime_download_bytes', + '!=', 'recovery_cursor.accounted_download_bytes') + ->orWhereColumn('cloud_instances.lifetime_upload_bytes', + '!=', 'recovery_cursor.accounted_upload_bytes') + ->orWhereColumn('cloud_instances.traffic_synced_at', '>', + 'recovery_cursor.last_observed_at'); + })->orderBy('cloud_instances.id') + ->limit(self::MAX_PLAN_ITEMS + 1)->distinct()->get([ + 'cloud_instances.id', + 'cloud_instances.traffic_synced_at', + 'cloud_instances.lifetime_download_bytes', + 'cloud_instances.lifetime_upload_bytes', + 'recovery_cursor.accounted_download_bytes', + 'recovery_cursor.accounted_upload_bytes', + 'recovery_cursor.last_observed_at', + 'recovery_cursor.state as cursor_state', + ]); + if ($rows->count() > self::MAX_PLAN_ITEMS) { + throw new \RuntimeException( + 'traffic_settlement_recovery_instance_scan_truncated' + ); + } + return $rows->map(static fn ($row): array => [ + 'id' => (int) $row->id, + 'traffic_synced_at' => (int) $row->traffic_synced_at, + 'lifetime_download_bytes' => + (int) $row->lifetime_download_bytes, + 'lifetime_upload_bytes' => (int) $row->lifetime_upload_bytes, + 'accounted_download_bytes' => + (int) ($row->accounted_download_bytes ?? 0), + 'accounted_upload_bytes' => + (int) ($row->accounted_upload_bytes ?? 0), + 'last_observed_at' => (int) ($row->last_observed_at ?? 0), + 'cursor_state' => (string) ($row->cursor_state ?? 'missing'), + ])->all(); + } + + /** @param iterable $buckets */ + private static function eventConflicts(iterable $buckets): array + { + $byKey = []; + foreach ($buckets as $bucket) { + $key = 'traffic-settlement:v2:' + . bin2hex((string) $bucket->event_identity); + $byKey[$key] = $bucket; + } + if ($byKey === []) { + return []; + } + $events = CloudTrafficLedgerEvent::whereIn( + 'event_key', array_keys($byKey) + )->get()->keyBy('event_key'); + $conflicts = []; + foreach ($byKey as $key => $bucket) { + $event = $events->get($key); + if ($event === null) { + continue; + } + $pool = $bucket->pool; + if ($pool === null) { + $conflicts[] = (int) $bucket->id; + continue; + } + try { + CloudTrafficSettlementEnvelope::assertMatches( + $pool, + $bucket, + $event + ); + } catch (\Throwable) { + $conflicts[] = (int) $bucket->id; + } + } + sort($conflicts, SORT_NUMERIC); + return $conflicts; + } + + private static function bucketPlanItem( + CloudTrafficUsageSettlementBucket $bucket + ): array { + return [ + 'id' => (int) $bucket->id, + 'event_identity' => bin2hex((string) $bucket->event_identity), + 'amount_bytes' => (int) $bucket->amount_bytes, + 'seal_at' => (int) $bucket->seal_at, + 'updated_at' => (int) $bucket->updated_at, + ]; + } + + private static function planHash(array $plan): string + { + return hash('sha256', json_encode( + self::canonicalize($plan), + JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES + | JSON_UNESCAPED_UNICODE + )); + } + + private static function canonicalize(mixed $value): mixed + { + if (!is_array($value)) { + return $value; + } + if (!array_is_list($value)) { + ksort($value, SORT_STRING); + } + foreach ($value as $key => $item) { + $value[$key] = self::canonicalize($item); + } + return $value; + } +} diff --git a/web/tests/CloudTrafficSettlementRecoveryTest.php b/web/tests/CloudTrafficSettlementRecoveryTest.php new file mode 100644 index 00000000..f8df4001 --- /dev/null +++ b/web/tests/CloudTrafficSettlementRecoveryTest.php @@ -0,0 +1,276 @@ +addConnection([ + 'driver' => 'sqlite', 'database' => ':memory:', +], 'default'); +$capsule->setAsGlobal(); +$capsule->bootEloquent(); +$schema = $capsule->schema('default'); + +$schema->create('cloud_traffic_pool_groups', static function (Blueprint $t): void { + $t->increments('id'); + $t->string('mode'); +}); +$schema->create('cloud_traffic_pools', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('user_id'); + $t->integer('traffic_pool_group_id'); + $t->string('state'); + $t->integer('available_bytes')->default(0); + $t->integer('overage_bytes')->default(0); + $t->integer('version')->default(1); + $t->integer('last_sequence')->default(0); + $t->integer('last_event_id')->nullable(); + $t->integer('created_at'); + $t->integer('updated_at'); +}); +$schema->create('cloud_traffic_ledger_events', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('pool_id'); + $t->integer('user_id'); + $t->integer('pool_sequence'); + $t->string('event_key')->unique(); + $t->string('event_type'); + $t->string('source_type'); + $t->string('source_id'); + $t->integer('source_revision'); + $t->string('payload_hash'); + $t->integer('instance_id')->nullable(); + $t->integer('service_period_id')->nullable(); + $t->integer('entitlement_id')->nullable(); + $t->integer('amount_bytes'); + $t->integer('effective_at'); + $t->integer('observed_at')->nullable(); + $t->text('payload_json'); + $t->integer('created_at'); + $t->unique(['pool_id', 'pool_sequence']); +}); +$schema->create('cloud_traffic_usage_settlement_buckets', + static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('pool_id'); + $t->integer('user_id'); + $t->integer('instance_id'); + $t->integer('service_period_id'); + $t->integer('entitlement_id')->nullable(); + $t->string('allocation_kind'); + $t->integer('allocation_target_id'); + $t->integer('bucket_start'); + $t->integer('seal_at'); + $t->integer('bucket_revision'); + $t->binary('event_identity')->unique(); + $t->integer('amount_bytes'); + $t->integer('download_bytes'); + $t->integer('upload_bytes'); + $t->integer('sample_count'); + $t->integer('first_observed_at'); + $t->integer('last_observed_at'); + $t->string('state'); + $t->integer('sealed_event_id')->nullable(); + $t->integer('created_at'); + $t->integer('updated_at'); + }); +$schema->create('cloud_traffic_instance_cursors', + static function (Blueprint $t): void { + $t->integer('instance_id')->primary(); + $t->integer('user_id'); + $t->integer('pool_id'); + $t->integer('accounted_download_bytes'); + $t->integer('accounted_upload_bytes'); + $t->integer('last_observed_at'); + $t->integer('last_event_id')->nullable(); + $t->string('state'); + $t->string('attention_code'); + $t->integer('version'); + $t->integer('updated_at'); + }); +$schema->create('cloud_instances', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('user_id'); + $t->integer('current_period_id')->nullable(); + $t->integer('lifetime_download_bytes')->default(0); + $t->integer('lifetime_upload_bytes')->default(0); + $t->integer('traffic_synced_at')->default(0); + $t->string('status')->default('active'); + $t->integer('created_at')->default(0); + $t->integer('updated_at')->default(0); +}); +$schema->create('cloud_service_periods', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('instance_id'); + $t->integer('user_id'); + $t->integer('traffic_pool_group_id')->nullable(); + $t->string('traffic_quota_mode')->default('finite'); + $t->integer('traffic_quota_bytes')->default(0); + $t->integer('starts_at'); + $t->integer('ends_at'); + $t->string('status'); + $t->integer('updated_at')->default(0); +}); +$schema->create('cloud_traffic_entitlements', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('pool_id'); + $t->integer('user_id'); + $t->integer('instance_id'); + $t->integer('service_period_id'); + $t->integer('starts_at'); + $t->integer('ends_at'); + $t->string('quota_mode'); + $t->integer('granted_bytes'); + $t->integer('consumed_bytes')->default(0); + $t->integer('forfeited_bytes')->default(0); + $t->string('state'); + $t->integer('activated_at')->nullable(); + $t->integer('closed_at')->nullable(); + $t->integer('version')->default(1); + $t->integer('created_at')->default(0); + $t->integer('updated_at')->default(0); +}); + +$now = time(); +Capsule::table('cloud_traffic_pool_groups')->insert([ + 'id' => 1, 'mode' => 'enforced', +]); +Capsule::table('cloud_traffic_pools')->insert([ + 'id' => 1, 'user_id' => 7, 'traffic_pool_group_id' => 1, + 'state' => 'available', 'available_bytes' => 0, 'overage_bytes' => 10, + 'version' => 1, 'last_sequence' => 0, 'last_event_id' => null, + 'created_at' => $now - 100, 'updated_at' => $now - 100, +]); +$identity = random_bytes(16); +$bucket = [ + 'id' => 1, 'pool_id' => 1, 'user_id' => 7, 'instance_id' => 11, + 'service_period_id' => 101, 'entitlement_id' => null, + 'allocation_kind' => 'overage', 'allocation_target_id' => 0, + 'bucket_start' => $now - 86_500, 'seal_at' => $now - 100, + 'bucket_revision' => 1, 'event_identity' => $identity, + 'amount_bytes' => 10, 'download_bytes' => 7, 'upload_bytes' => 3, + 'sample_count' => 1, 'first_observed_at' => $now - 86_490, + 'last_observed_at' => $now - 86_490, 'state' => 'open', + 'sealed_event_id' => null, 'created_at' => $now - 100, + 'updated_at' => $now - 100, +]; +Capsule::table('cloud_traffic_usage_settlement_buckets')->insert($bucket); + +$plan = CloudTrafficSettlementRecovery::inspect(); +$assert($plan['actionable'] === true + && $plan['counts']['due_buckets'] === 1 + && preg_match('/^[a-f0-9]{64}$/D', $plan['plan_hash']) === 1, + 'Inspect did not produce a bounded actionable settlement plan: ' + . json_encode($plan, JSON_THROW_ON_ERROR)); +Capsule::table('cloud_traffic_usage_settlement_buckets')->where('id', 1) + ->update(['amount_bytes' => 11, 'download_bytes' => 8]); +try { + CloudTrafficSettlementRecovery::apply($plan['plan_hash']); + throw new RuntimeException('A changed recovery plan was applied.'); +} catch (RuntimeException $error) { + $assert($error->getMessage() + === 'traffic_settlement_recovery_plan_changed', + 'Changed plan failed with the wrong safety code.'); +} +Capsule::table('cloud_traffic_usage_settlement_buckets')->where('id', 1) + ->update(['amount_bytes' => 10, 'download_bytes' => 7]); +$fresh = CloudTrafficSettlementRecovery::inspect(); +$applied = CloudTrafficSettlementRecovery::apply($fresh['plan_hash']); +$assert($applied['sealed_buckets'] === 1 + && Capsule::table('cloud_traffic_usage_settlement_buckets') + ->where('id', 1)->value('state') === 'sealed' + && Capsule::table('cloud_traffic_ledger_events') + ->where('event_key', 'traffic-settlement:v2:' . bin2hex($identity)) + ->count() === 1, + 'The exact approved plan did not use the normal immutable seal path.'); +$empty = CloudTrafficSettlementRecovery::inspect(); +$repeat = CloudTrafficSettlementRecovery::apply($empty['plan_hash']); +$assert($repeat['sealed_buckets'] === 0 + && $repeat['reconciled_periods'] === 0 + && $repeat['settled_instances'] === 0, + 'A repeated empty recovery plan was not idempotent.'); + +Capsule::table('cloud_traffic_usage_settlement_buckets')->insert(array_merge( + $bucket, + [ + 'id' => 2, + 'event_identity' => '', + 'state' => 'open', + 'sealed_event_id' => null, + ] +)); +$blocked = CloudTrafficSettlementRecovery::inspect(); +$assert($blocked['actionable'] === false + && $blocked['blockers'][0]['code'] + === 'settlement_event_identity_missing', + 'A malformed persistent event identity did not block recovery.'); +try { + CloudTrafficSettlementRecovery::apply($blocked['plan_hash']); + throw new RuntimeException('A blocked recovery plan was applied.'); +} catch (RuntimeException $error) { + $assert($error->getMessage() === 'traffic_settlement_recovery_blocked', + 'Blocked plan failed with the wrong safety code.'); +} + +$parse = new ReflectionMethod( + CloudTrafficSettlementRecoveryCommand::class, + 'parse' +); +$assert($parse->invoke(null, [ + 'xcat', 'cloudTrafficSettlementRecovery', 'inspect', +]) === ['action' => 'inspect'], 'CLI inspect arguments drifted.'); +$hash = str_repeat('a', 64); +$assert($parse->invoke(null, [ + 'xcat', 'cloudTrafficSettlementRecovery', 'apply', + '--plan-hash=' . $hash, '--apply', +]) === ['action' => 'apply', 'plan_hash' => $hash], + 'CLI apply did not bind the exact reviewed plan hash.'); +foreach ([ + ['apply', '--plan-hash=' . $hash], + ['apply', '--plan-hash=bad', '--apply'], + ['apply', '--plan-hash=' . $hash, '--apply', '--force'], + ['inspect', '--apply'], +] as $arguments) { + try { + $parse->invoke(null, array_merge([ + 'xcat', 'cloudTrafficSettlementRecovery', + ], $arguments)); + throw new RuntimeException('Unsafe CLI arguments were accepted.'); + } catch (ReflectionException $error) { + throw $error; + } catch (Throwable $error) { + $actual = $error->getPrevious() ?? $error; + $assert($actual instanceof InvalidArgumentException, + 'Unsafe CLI arguments failed with the wrong exception.'); + } +} + +$service = file_get_contents(dirname(__DIR__) + . '/app/Services/Cloud/CloudTrafficSettlementRecovery.php'); +$xcat = file_get_contents(dirname(__DIR__) . '/app/Command/XCat.php'); +$assert(is_string($service) + && is_string($xcat) + && !str_contains($service, '->delete(') + && !str_contains($service, 'CloudAgentClient') + && !str_contains($service, 'CloudJob') + && str_contains($service, + 'CloudTrafficPoolAccounting::sealPlannedUsageBuckets(') + && str_contains($service, + 'CloudTrafficPoolAccounting::reconcileServicePeriod(') + && str_contains($service, + 'CloudTrafficPoolAccounting::settleInstanceUsage(') + && str_contains($xcat, "'cloudTrafficSettlementRecovery'") + && str_contains($xcat, + 'cloudTrafficSettlementRecovery apply --plan-hash=HASH --apply'), + 'Recovery acquired a destructive or remote bypass path.'); + +echo "Traffic settlement recovery plan/apply checks passed.\n";