feat(traffic): add verified settlement reconciliation

go
codex 47 minutes ago
parent 9a70559732
commit 69e4f0fca8

@ -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=<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 |
| --- | --- |

@ -0,0 +1,65 @@
<?php
namespace App\Command;
use App\Services\Cloud\CloudTrafficSettlementRecovery;
/** CLI-only plan/apply entry for delayed traffic settlement. */
final class CloudTrafficSettlementRecoveryCommand
{
public static function run(array $argv): int
{
$command = self::parse($argv);
$result = $command['action'] === 'inspect'
? CloudTrafficSettlementRecovery::inspect()
: CloudTrafficSettlementRecovery::apply($command['plan_hash']);
fwrite(STDOUT, json_encode(
$result,
JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT
| JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
) . PHP_EOL);
return 0;
}
/** @return array{action:string,plan_hash?:string} */
private static function parse(array $argv): array
{
$action = (string) ($argv[2] ?? '');
if ($action === 'inspect' && count($argv) === 3) {
return ['action' => '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'],
];
}
}

@ -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"

@ -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');
}
}

@ -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);

@ -0,0 +1,404 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudInstance;
use App\Models\CloudServicePeriod;
use App\Models\CloudTrafficEntitlement;
use App\Models\CloudTrafficInstanceCursor;
use App\Models\CloudTrafficLedgerEvent;
use App\Models\CloudTrafficUsageSettlementBucket;
/** Local plan/apply recovery for delayed traffic settlement only. */
final class CloudTrafficSettlementRecovery
{
private const MAX_PLAN_ITEMS = 2000;
/** @return array<string,mixed> */
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<string,mixed> */
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<array<string,int|string>> */
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<array<string,int|string>> */
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<CloudTrafficUsageSettlementBucket> $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;
}
}

@ -0,0 +1,276 @@
<?php
require dirname(__DIR__) . '/vendor/autoload.php';
use App\Command\CloudTrafficSettlementRecoveryCommand;
use App\Services\Cloud\CloudTrafficSettlementRecovery;
use Illuminate\Database\Capsule\Manager as Capsule;
use Illuminate\Database\Schema\Blueprint;
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$capsule = new Capsule();
$capsule->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";
Loading…
Cancel
Save