From 54951379467b5b8561a489bf17bb85f447fdce8e Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 31 Oct 2026 23:56:27 +0800 Subject: [PATCH] feat(traffic): model aggregate network policy --- docs/TRAFFIC_POOL.md | 17 +- web/app/Command/CloudSetup.php | 22 +- .../CloudInstanceNetworkPolicyState.php | 21 + .../CloudInstanceNetworkRestriction.php | 1 - .../Cloud/CloudInstanceNetworkPolicy.php | 604 ++++++++++++++++++ .../Cloud/CloudTrafficPoolPeriodBinding.php | 12 +- web/app/Services/UserDataDeletionService.php | 1 + web/sql/cloud.sql | 28 +- web/tests/CloudInstanceNetworkPolicyTest.php | 418 ++++++++++++ .../CloudTrafficPoolPeriodBindingTest.php | 10 + .../CloudTrafficPoolSchemaContractTest.php | 5 +- ...rafficRestrictionLockOrderContractTest.php | 44 ++ 12 files changed, 1163 insertions(+), 20 deletions(-) create mode 100644 web/app/Models/CloudInstanceNetworkPolicyState.php create mode 100644 web/app/Services/Cloud/CloudInstanceNetworkPolicy.php create mode 100644 web/tests/CloudInstanceNetworkPolicyTest.php create mode 100644 web/tests/CloudTrafficRestrictionLockOrderContractTest.php diff --git a/docs/TRAFFIC_POOL.md b/docs/TRAFFIC_POOL.md index f03aa69e..61f90dc9 100644 --- a/docs/TRAFFIC_POOL.md +++ b/docs/TRAFFIC_POOL.md @@ -53,13 +53,22 @@ All mutations for one pool serialize under a single pool row lock. The lock order is always: ```text -pool -> instance cursor -> entitlements -> network restrictions +pool -> instance cursor -> entitlements ``` The accounting transaction advances the instance cursor, appends immutable -ledger events, updates entitlement and pool projections, and updates desired -network restrictions atomically. It never calls an Agent while holding a -database transaction. +ledger events, and updates entitlement and pool projections atomically. It +never locks instances, writes network restrictions, or calls an Agent. A +later per-instance policy transaction reads the pool projection and owns the +separate lock order: + +```text +instance -> network policy state -> network restrictions (reason_code ASC) +``` + +The policy state is one aggregate execution projection per instance; reason +rows contain facts only. This avoids assigning one NIC mutation to an +arbitrary restriction when several reasons are active at the same time. Repeated observations and repeated lifecycle finalization must have no new effect. A counter regression is an attention condition; it must not refund diff --git a/web/app/Command/CloudSetup.php b/web/app/Command/CloudSetup.php index 3ecb985a..7548bc9e 100644 --- a/web/app/Command/CloudSetup.php +++ b/web/app/Command/CloudSetup.php @@ -8,7 +8,7 @@ use App\Services\Config; /** Initializes only the clean-break PHP business and Agent log schemas. */ final class CloudSetup { - private const SCHEMA_VERSION = 'go-agent-wss-v21-traffic-scan-backoff'; + private const SCHEMA_VERSION = 'go-agent-wss-v22-network-policy'; private const MAIN_TABLES = [ 'cloud_regions', 'cloud_traffic_pool_groups', 'cloud_network_lines', 'cloud_resource_pools', @@ -39,6 +39,7 @@ final class CloudSetup 'cloud_traffic_ledger_events', 'cloud_traffic_instance_cursors', 'cloud_traffic_scan_failures', 'cloud_instance_network_restrictions', + 'cloud_instance_network_policy_states', 'cloud_renewals', 'cloud_invoices', 'cloud_invoice_items', 'cloud_invoice_payments', 'cloud_mail_outbox', 'cloud_jobs', 'cloud_agent_completion_events', @@ -305,8 +306,12 @@ final class CloudSetup ], 'cloud_instance_network_restrictions' => [ 'instance_id', 'user_id', 'reason_code', 'desired_active', - 'applied_active', 'revision', 'state', 'source_type', - 'source_id', 'operation_id', 'created_at', 'updated_at', + 'revision', 'source_type', 'source_id', 'created_at', 'updated_at', + ], + 'cloud_instance_network_policy_states' => [ + 'instance_id', 'user_id', 'desired_suspended', + 'applied_suspended', 'revision', 'state', 'operation_id', + 'created_at', 'updated_at', ], ]; private const REQUIRED_LOG_COLUMNS = [ @@ -352,7 +357,9 @@ final class CloudSetup ], 'cloud_instance_network_restrictions' => [ 'chk_cloud_network_restriction_reason', - 'chk_cloud_network_restriction_state', + ], + 'cloud_instance_network_policy_states' => [ + 'chk_cloud_network_policy_state', ], 'cloud_template_import_intents' => [ 'chk_cloud_template_import_source', @@ -462,10 +469,13 @@ final class CloudSetup 'cloud_traffic_scan_failure_retry', ], 'cloud_instance_network_restrictions' => [ - 'PRIMARY', 'cloud_network_restriction_operation', - 'cloud_network_restriction_state', + 'PRIMARY', 'cloud_network_restriction_desired', 'cloud_network_restriction_owner', ], + 'cloud_instance_network_policy_states' => [ + 'PRIMARY', 'cloud_network_policy_operation', + 'cloud_network_policy_state', 'cloud_network_policy_owner', + ], 'cloud_template_import_intents' => [ 'PRIMARY', 'cloud_template_import_request', 'cloud_template_import_template', diff --git a/web/app/Models/CloudInstanceNetworkPolicyState.php b/web/app/Models/CloudInstanceNetworkPolicyState.php new file mode 100644 index 00000000..727c592c --- /dev/null +++ b/web/app/Models/CloudInstanceNetworkPolicyState.php @@ -0,0 +1,21 @@ + 'int', + 'user_id' => 'int', + 'desired_suspended' => 'boolean', + 'applied_suspended' => 'boolean', + 'revision' => 'int', + 'created_at' => 'int', + 'updated_at' => 'int', + ]; +} diff --git a/web/app/Models/CloudInstanceNetworkRestriction.php b/web/app/Models/CloudInstanceNetworkRestriction.php index 22308a6d..9e122774 100644 --- a/web/app/Models/CloudInstanceNetworkRestriction.php +++ b/web/app/Models/CloudInstanceNetworkRestriction.php @@ -12,7 +12,6 @@ final class CloudInstanceNetworkRestriction extends Model 'instance_id' => 'int', 'user_id' => 'int', 'desired_active' => 'boolean', - 'applied_active' => 'boolean', 'revision' => 'int', 'created_at' => 'int', 'updated_at' => 'int', diff --git a/web/app/Services/Cloud/CloudInstanceNetworkPolicy.php b/web/app/Services/Cloud/CloudInstanceNetworkPolicy.php new file mode 100644 index 00000000..bbe93e4f --- /dev/null +++ b/web/app/Services/Cloud/CloudInstanceNetworkPolicy.php @@ -0,0 +1,604 @@ +traffic_pool_group_id === null) { + return false; + } + $group = CloudTrafficPoolGroup::find( + (int) $period->traffic_pool_group_id + ); + return $group !== null && (string) $group->mode === 'enforced'; + } + + public static function hasState(int $instanceId): bool + { + return CloudInstanceNetworkPolicyState::where( + 'instance_id', $instanceId + )->exists(); + } + + /** + * Refresh the two system-owned reasons and return the aggregate decision. + * A missing/attention pool is not evidence for either a new block or a + * restore: the previous traffic reason is retained until accounting is + * trustworthy again. + * + * @return array + */ + public static function synchronizeLocked( + CloudInstance $instance, + ?CloudServicePeriod $period, + ?int $now = null + ): array { + $now ??= time(); + $enforced = self::isEnforcedPeriod($period); + if (!$enforced && !self::hasState((int) $instance->id)) { + return ['managed' => false, 'action' => 'none']; + } + if (!self::hasState((int) $instance->id) + && !self::stableInitialProjection($instance)) { + // The pre-policy state machine still owns this in-flight/failed + // generation. It must reconcile the original operation before the + // aggregate policy may take ownership. + return [ + 'managed' => true, + 'deferred' => true, + 'action' => 'none', + ]; + } + + $state = self::lockState($instance, $now); + $rows = self::lockRestrictions((int) $instance->id); + self::setReasonFact( + $instance, + $rows, + self::REASON_SERVICE, + (string) $instance->service_status === 'expired_grace' + && $instance->expires_at !== null + && (int) $instance->expires_at <= $now, + 'instance_expiry', + (string) max(0, (int) ($instance->expires_at ?? 0)), + $now + ); + + $trafficDecision = 'preserved'; + if ($enforced && $period !== null) { + $finiteActive = (string) $period->traffic_quota_mode === 'finite' + && in_array((string) $period->status, + ['active', 'exhausted'], true) + && (int) $period->starts_at <= $now + && (int) $period->ends_at > $now + && (string) $instance->service_status === 'active'; + if (!$finiteActive) { + self::setReasonFact( + $instance, + $rows, + self::REASON_TRAFFIC, + false, + 'traffic_pool', + 'period:' . (int) $period->id, + $now + ); + $trafficDecision = 'cleared'; + } else { + $pool = CloudTrafficPool::where( + 'user_id', (int) $instance->user_id + )->where( + 'traffic_pool_group_id', + (int) $period->traffic_pool_group_id + )->first(); + if ($pool !== null && (string) $pool->state !== 'attention') { + $blocked = (string) $pool->state === 'exhausted' + || (int) $pool->overage_bytes > 0; + self::setReasonFact( + $instance, + $rows, + self::REASON_TRAFFIC, + $blocked, + 'traffic_pool', + 'pool:' . (int) $pool->id + . ':v' . (int) $pool->version, + $now + ); + $trafficDecision = $blocked ? 'asserted' : 'cleared'; + } elseif ($rows->firstWhere( + 'reason_code', self::REASON_TRAFFIC + ) === null && in_array((string) $instance->network_status, [ + 'blocking', 'blocked_traffic', 'block_failed', + ], true)) { + // A rollout can meet an already suspended instance while + // the shared projection is unavailable. Preserve that + // known-safe physical state instead of guessing a restore. + self::setReasonFact( + $instance, + $rows, + self::REASON_TRAFFIC, + true, + 'traffic_pool', + 'group:' . (int) $period->traffic_pool_group_id + . ':untrusted', + $now + ); + } + } + } + + $rows = self::lockRestrictions((int) $instance->id); + self::refreshAggregate($state, $rows, $now); + $snapshot = self::projectInstance($instance, $state, $rows, $now); + $snapshot['managed'] = true; + $snapshot['traffic_decision'] = $trafficDecision; + return $snapshot; + } + + /** @return array */ + public static function setReasonLocked( + CloudInstance $instance, + string $reason, + bool $desired, + string $sourceType, + string $sourceId, + ?int $now = null + ): array { + self::assertReason($reason); + self::assertSource($sourceType, $sourceId); + $now ??= time(); + $state = self::lockState($instance, $now); + $rows = self::lockRestrictions((int) $instance->id); + self::setReasonFact( + $instance, + $rows, + $reason, + $desired, + $sourceType, + $sourceId, + $now + ); + $rows = self::lockRestrictions((int) $instance->id); + self::refreshAggregate($state, $rows, $now); + return self::projectInstance($instance, $state, $rows, $now); + } + + /** + * Bind a fresh queued Agent operation to the aggregate projection. + * + * @return array immutable payload marker + */ + public static function prepareJobLocked( + CloudInstance $instance, + string $kind, + string $operationId, + ?int $now = null + ): array { + self::assertKind($kind); + if (preg_match('/^[a-f0-9]{32}$/D', $operationId) !== 1) { + throw new CloudError('网络策略操作标识无效', 409); + } + $now ??= time(); + $state = self::lockState($instance, $now); + $rows = self::lockRestrictions((int) $instance->id); + self::refreshAggregate($state, $rows, $now); + $action = self::action($state); + $expected = $kind === 'network_suspend' ? 'suspend' : 'resume'; + if ($action !== $expected || in_array((string) $state->state, + ['applying', 'unknown'], true)) { + throw new CloudError('网络策略当前不需要该操作', 409); + } + $state->state = 'applying'; + $state->operation_id = $operationId; + $state->updated_at = $now; + $state->save(); + + return [ + 'version' => 1, + 'instance_id' => (int) $instance->id, + 'operation_id' => $operationId, + 'policy_revision' => (int) $state->revision, + 'desired_suspended' => (bool) $state->desired_suspended, + 'applied_suspended' => (bool) $state->applied_suspended, + 'suspend_reason' => self::suspendReason($rows), + ]; + } + + public static function jobStillDesired( + int $instanceId, + string $kind, + string $operationId + ): ?bool { + self::assertKind($kind); + $state = CloudInstanceNetworkPolicyState::where( + 'instance_id', $instanceId + )->first(); + if ($state === null) { + return null; + } + if (!is_string($state->operation_id) + || !hash_equals((string) $state->operation_id, $operationId)) { + throw new CloudRecoveryInstanceStateConflict( + '网络策略任务与当前执行代次不一致', + 409 + ); + } + return $kind === 'network_suspend' + ? (bool) $state->desired_suspended + : !(bool) $state->desired_suspended; + } + + /** + * Settle one policy operation after the Worker has validated its receipt. + * The caller still owns the locked job and instance in the same transaction. + * + * @return array + */ + public static function finishJobLocked( + CloudInstance $instance, + string $kind, + string $operationId, + string $status, + bool $skipped, + bool $effectMayHaveApplied, + ?int $now = null + ): array { + self::assertKind($kind); + if (!in_array($status, ['succeeded', 'failed'], true)) { + throw new CloudError('网络策略任务尚未终结', 409); + } + $now ??= time(); + $state = self::lockState($instance, $now); + $rows = self::lockRestrictions((int) $instance->id); + if (!in_array((string) $state->state, ['applying', 'unknown'], true) + || !is_string($state->operation_id) + || !hash_equals((string) $state->operation_id, $operationId)) { + throw new CloudRecoveryInstanceStateConflict( + '网络策略任务与当前执行代次不一致', + 409 + ); + } + + if ($status === 'succeeded') { + if (!$skipped) { + $state->applied_suspended = $kind === 'network_suspend'; + } + $state->state = (bool) $state->desired_suspended + === (bool) $state->applied_suspended ? 'applied' : 'pending'; + $state->operation_id = null; + } elseif ($effectMayHaveApplied) { + $state->state = 'unknown'; + } elseif ((bool) $state->desired_suspended + === (bool) $state->applied_suspended) { + $state->state = 'applied'; + $state->operation_id = null; + } else { + $state->state = 'failed'; + } + $state->updated_at = $now; + $state->save(); + return self::projectInstance($instance, $state, $rows, $now, $kind); + } + + /** Move a proven-not-applied failure into a fresh, separately audited job. */ + public static function allowRetryLocked( + CloudInstance $instance, + string $kind, + ?int $now = null + ): bool { + self::assertKind($kind); + $now ??= time(); + $state = self::lockState($instance, $now); + if ((string) $state->state !== 'failed') { + return false; + } + $expected = $kind === 'network_suspend' ? 'suspend' : 'resume'; + if (self::actionFromValues( + (bool) $state->desired_suspended, + (bool) $state->applied_suspended + ) !== $expected) { + return false; + } + $state->state = 'pending'; + $state->operation_id = null; + $state->updated_at = $now; + $state->save(); + $rows = self::lockRestrictions((int) $instance->id); + self::projectInstance($instance, $state, $rows, $now); + return true; + } + + /** @return array */ + public static function snapshotLocked( + CloudInstance $instance, + ?int $now = null + ): array { + $now ??= time(); + $state = self::lockState($instance, $now); + $rows = self::lockRestrictions((int) $instance->id); + self::refreshAggregate($state, $rows, $now); + return self::snapshot($state, $rows); + } + + private static function lockState( + CloudInstance $instance, + int $now + ): CloudInstanceNetworkPolicyState { + $state = CloudInstanceNetworkPolicyState::where( + 'instance_id', (int) $instance->id + )->lockForUpdate()->first(); + if ($state !== null) { + if ((int) $state->user_id !== (int) $instance->user_id) { + throw new CloudRecoveryInstanceStateConflict( + '网络策略所有者与实例不一致', + 409 + ); + } + return $state; + } + + if (!self::stableInitialProjection($instance)) { + throw new CloudError('实例仍有未决网络策略,暂不能接管', 409); + } + + $applied = self::instanceAppearsSuspended($instance); + $state = new CloudInstanceNetworkPolicyState(); + $state->instance_id = (int) $instance->id; + $state->user_id = (int) $instance->user_id; + $state->desired_suspended = $applied ? 1 : 0; + $state->applied_suspended = $applied ? 1 : 0; + $state->revision = 1; + $state->state = 'applied'; + $state->operation_id = null; + $state->created_at = $state->updated_at = $now; + $state->save(); + return CloudInstanceNetworkPolicyState::where( + 'instance_id', (int) $instance->id + )->lockForUpdate()->firstOrFail(); + } + + private static function instanceAppearsSuspended( + CloudInstance $instance + ): bool { + return $instance->network_suspended_at !== null + || in_array((string) $instance->network_status, [ + 'blocked_traffic', 'blocked_expired', 'restore_pending', + 'restoring', 'restore_failed', + ], true); + } + + private static function stableInitialProjection( + CloudInstance $instance + ): bool { + return in_array((string) $instance->network_status, [ + 'active', 'blocked_traffic', 'blocked_expired', + ], true); + } + + private static function lockRestrictions(int $instanceId) + { + return CloudInstanceNetworkRestriction::where( + 'instance_id', $instanceId + )->orderBy('reason_code')->lockForUpdate()->get(); + } + + private static function setReasonFact( + CloudInstance $instance, + $rows, + string $reason, + bool $desired, + string $sourceType, + string $sourceId, + int $now + ): void { + self::assertReason($reason); + self::assertSource($sourceType, $sourceId); + $row = $rows->firstWhere('reason_code', $reason); + if ($row === null) { + $row = new CloudInstanceNetworkRestriction(); + $row->instance_id = (int) $instance->id; + $row->user_id = (int) $instance->user_id; + $row->reason_code = $reason; + $row->desired_active = $desired ? 1 : 0; + $row->revision = 1; + $row->source_type = $sourceType; + $row->source_id = $sourceId; + $row->created_at = $row->updated_at = $now; + $row->save(); + return; + } + if ((int) $row->user_id !== (int) $instance->user_id) { + throw new CloudRecoveryInstanceStateConflict( + '网络限制所有者与实例不一致', + 409 + ); + } + $changed = (bool) $row->desired_active !== $desired; + CloudInstanceNetworkRestriction::where( + 'instance_id', (int) $instance->id + )->where('reason_code', $reason)->update([ + 'desired_active' => $desired ? 1 : 0, + 'revision' => (int) $row->revision + ($changed ? 1 : 0), + 'source_type' => $sourceType, + 'source_id' => $sourceId, + 'updated_at' => $now, + ]); + } + + private static function refreshAggregate( + CloudInstanceNetworkPolicyState $state, + $rows, + int $now + ): void { + $desired = $rows->contains( + static fn ($row): bool => (bool) $row->desired_active + ); + if ((bool) $state->desired_suspended !== $desired) { + $state->desired_suspended = $desired ? 1 : 0; + $state->revision = (int) $state->revision + 1; + } + if (!in_array((string) $state->state, ['applying', 'unknown'], true)) { + if ($desired === (bool) $state->applied_suspended) { + $state->state = 'applied'; + $state->operation_id = null; + } elseif ((string) $state->state !== 'failed') { + $state->state = 'pending'; + $state->operation_id = null; + } + } + $state->updated_at = $now; + $state->save(); + } + + /** @return array */ + private static function projectInstance( + CloudInstance $instance, + CloudInstanceNetworkPolicyState $state, + $rows, + int $now, + ?string $failedKind = null + ): array { + $policyState = (string) $state->state; + if ($policyState === 'pending') { + $instance->network_status = (bool) $state->desired_suspended + ? (self::hasDesired($rows, self::REASON_SERVICE) + ? 'blocking_expired' : 'blocking') + : 'restore_pending'; + if (!(bool) $state->desired_suspended) { + $instance->network_suspended_at = $instance->network_suspended_at + ?? $now; + } + } elseif ($policyState === 'applied') { + if ((bool) $state->applied_suspended) { + $instance->network_status = self::hasDesired( + $rows, + self::REASON_SERVICE + ) ? 'blocked_expired' : 'blocked_traffic'; + $instance->network_suspended_at = + $instance->network_suspended_at ?? $now; + } else { + $instance->network_status = 'active'; + $instance->network_suspended_at = null; + } + } elseif (in_array($policyState, ['failed', 'unknown'], true)) { + $instance->network_status = $failedKind === 'network_resume' + || (!(bool) $state->desired_suspended + && (bool) $state->applied_suspended) + ? 'restore_failed' : 'block_failed'; + } + $instance->updated_at = $now; + return self::snapshot($state, $rows); + } + + /** @return array */ + private static function snapshot( + CloudInstanceNetworkPolicyState $state, + $rows + ): array { + $desiredReasons = []; + foreach ($rows as $row) { + if ((bool) $row->desired_active) { + $desiredReasons[] = (string) $row->reason_code; + } + } + sort($desiredReasons, SORT_STRING); + return [ + 'managed' => true, + 'state' => (string) $state->state, + 'revision' => (int) $state->revision, + 'desired_suspended' => (bool) $state->desired_suspended, + 'applied_suspended' => (bool) $state->applied_suspended, + 'operation_id' => $state->operation_id === null + ? null : (string) $state->operation_id, + 'desired_reasons' => $desiredReasons, + 'action' => self::action($state), + 'suspend_reason' => self::suspendReason($rows), + ]; + } + + private static function action( + CloudInstanceNetworkPolicyState $state + ): string { + if ((string) $state->state !== 'pending') { + return 'none'; + } + return self::actionFromValues( + (bool) $state->desired_suspended, + (bool) $state->applied_suspended + ); + } + + private static function actionFromValues( + bool $desired, + bool $applied + ): string { + if ($desired === $applied) { + return 'none'; + } + return $desired ? 'suspend' : 'resume'; + } + + private static function suspendReason($rows): string + { + return self::hasDesired($rows, self::REASON_SERVICE) + ? 'expired' : 'traffic'; + } + + private static function hasDesired($rows, string $reason): bool + { + $row = $rows->firstWhere('reason_code', $reason); + return $row !== null && (bool) $row->desired_active; + } + + private static function assertKind(string $kind): void + { + if (!in_array($kind, ['network_suspend', 'network_resume'], true)) { + throw new \InvalidArgumentException('Unsupported network policy kind.'); + } + } + + private static function assertReason(string $reason): void + { + if (!in_array($reason, self::REASONS, true)) { + throw new \InvalidArgumentException('Unsupported network restriction.'); + } + } + + private static function assertSource( + string $sourceType, + string $sourceId + ): void { + if (preg_match('/^[a-z][a-z0-9_]{1,31}$/D', $sourceType) !== 1 + || $sourceId === '' || strlen($sourceId) > 191 + || preg_match('/^[\x20-\x7e]+$/D', $sourceId) !== 1) { + throw new \InvalidArgumentException('Invalid network restriction source.'); + } + } +} diff --git a/web/app/Services/Cloud/CloudTrafficPoolPeriodBinding.php b/web/app/Services/Cloud/CloudTrafficPoolPeriodBinding.php index e5e7fb7c..397a5c09 100644 --- a/web/app/Services/Cloud/CloudTrafficPoolPeriodBinding.php +++ b/web/app/Services/Cloud/CloudTrafficPoolPeriodBinding.php @@ -73,8 +73,18 @@ final class CloudTrafficPoolPeriodBinding $groupId = self::nullableGroupId( $trafficPoolGroupId ); + $quotaMode = self::quotaMode($quotaBytes); + if ($period->exists && $groupId !== null + && in_array((string) $period->traffic_quota_mode, + ['finite', 'unlimited'], true) + && (string) $period->traffic_quota_mode !== $quotaMode) { + throw new CloudError( + '活动服务周期不支持在有限与无限流量之间切换', + 409 + ); + } $period->traffic_pool_group_id = $groupId; - $period->traffic_quota_mode = self::quotaMode($quotaBytes); + $period->traffic_quota_mode = $quotaMode; } public static function quotaMode(int $quotaBytes): string diff --git a/web/app/Services/UserDataDeletionService.php b/web/app/Services/UserDataDeletionService.php index 547e1818..0372a9bd 100644 --- a/web/app/Services/UserDataDeletionService.php +++ b/web/app/Services/UserDataDeletionService.php @@ -24,6 +24,7 @@ class UserDataDeletionService ['cloud_instance_snapshots', 'user_id'], ['cloud_instance_firewalls', 'user_id'], ['cloud_backup_period_entitlements', 'user_id'], + ['cloud_instance_network_policy_states', 'user_id'], ['cloud_instance_network_restrictions', 'user_id'], ['cloud_traffic_instance_cursors', 'user_id'], ['cloud_traffic_ledger_events', 'user_id'], diff --git a/web/sql/cloud.sql b/web/sql/cloud.sql index 263a605b..29a73180 100644 --- a/web/sql/cloud.sql +++ b/web/sql/cloud.sql @@ -1450,22 +1450,36 @@ CREATE TABLE cloud_instance_network_restrictions ( user_id BIGINT UNSIGNED NOT NULL, reason_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, desired_active TINYINT(1) NOT NULL DEFAULT 1, - applied_active TINYINT(1) NOT NULL DEFAULT 0, revision BIGINT UNSIGNED NOT NULL DEFAULT 1, - state VARCHAR(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'pending', source_type VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, source_id VARCHAR(191) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, - operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, created_at BIGINT UNSIGNED NOT NULL, updated_at BIGINT UNSIGNED NOT NULL, PRIMARY KEY (instance_id, reason_code), - UNIQUE KEY cloud_network_restriction_operation (operation_id), - KEY cloud_network_restriction_state (state, updated_at, instance_id), + KEY cloud_network_restriction_desired (desired_active, updated_at, instance_id), KEY cloud_network_restriction_owner (user_id, instance_id), CONSTRAINT chk_cloud_network_restriction_reason CHECK ( reason_code IN ('traffic_pool_exhausted','service_expired','admin_hold') - ), - CONSTRAINT chk_cloud_network_restriction_state CHECK ( + ) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; + +-- Restriction rows are independent policy facts. The remote NIC mutation is +-- one aggregate operation per instance, so its execution state must not be +-- duplicated onto whichever reason happened to trigger the transition. +CREATE TABLE cloud_instance_network_policy_states ( + instance_id BIGINT UNSIGNED NOT NULL PRIMARY KEY, + user_id BIGINT UNSIGNED NOT NULL, + desired_suspended TINYINT(1) NOT NULL DEFAULT 0, + applied_suspended TINYINT(1) NOT NULL DEFAULT 0, + revision BIGINT UNSIGNED NOT NULL DEFAULT 1, + state VARCHAR(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'applied', + operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL, + created_at BIGINT UNSIGNED NOT NULL, + updated_at BIGINT UNSIGNED NOT NULL, + UNIQUE KEY cloud_network_policy_operation (operation_id), + KEY cloud_network_policy_state (state, updated_at, instance_id), + KEY cloud_network_policy_owner (user_id, instance_id), + CONSTRAINT chk_cloud_network_policy_state CHECK ( state IN ('pending','applying','applied','failed','unknown') ) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; diff --git a/web/tests/CloudInstanceNetworkPolicyTest.php b/web/tests/CloudInstanceNetworkPolicyTest.php new file mode 100644 index 00000000..792fa21c --- /dev/null +++ b/web/tests/CloudInstanceNetworkPolicyTest.php @@ -0,0 +1,418 @@ +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('code'); + $t->string('name'); + $t->string('mode'); + $t->integer('created_at'); + $t->integer('updated_at'); +}); +$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'); + $t->integer('overage_bytes'); + $t->integer('version'); + $t->integer('last_sequence')->default(0); + $t->integer('last_event_id')->nullable(); + $t->integer('created_at'); + $t->integer('updated_at'); +}); +$schema->create('cloud_instances', static function (Blueprint $t): void { + $t->increments('id'); + $t->integer('user_id'); + $t->string('service_status'); + $t->string('network_status'); + $t->integer('network_suspended_at')->nullable(); + $t->integer('expires_at')->nullable(); + $t->integer('updated_at'); +}); +$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'); + $t->string('status'); + $t->integer('starts_at'); + $t->integer('ends_at'); +}); +$schema->create('cloud_instance_network_restrictions', + static function (Blueprint $t): void { + $t->integer('instance_id'); + $t->integer('user_id'); + $t->string('reason_code'); + $t->boolean('desired_active'); + $t->integer('revision'); + $t->string('source_type'); + $t->string('source_id'); + $t->integer('created_at'); + $t->integer('updated_at'); + $t->primary(['instance_id', 'reason_code']); + }); +$schema->create('cloud_instance_network_policy_states', + static function (Blueprint $t): void { + $t->integer('instance_id')->primary(); + $t->integer('user_id'); + $t->boolean('desired_suspended'); + $t->boolean('applied_suspended'); + $t->integer('revision'); + $t->string('state'); + $t->string('operation_id')->nullable()->unique(); + $t->integer('created_at'); + $t->integer('updated_at'); + }); + +Capsule::table('cloud_traffic_pool_groups')->insert([ + ['id' => 1, 'code' => 'shadow', 'name' => 'Shadow', 'mode' => 'shadow', + 'created_at' => 1, 'updated_at' => 1], + ['id' => 2, 'code' => 'shared', 'name' => 'Shared', 'mode' => 'enforced', + 'created_at' => 1, 'updated_at' => 1], +]); +$instance = new CloudInstance(); +$instance->id = 10; +$instance->user_id = 20; +$instance->service_status = 'active'; +$instance->network_status = 'active'; +$instance->network_suspended_at = null; +$instance->expires_at = 2000; +$instance->updated_at = 1000; +$instance->save(); + +$period = new CloudServicePeriod(); +$period->id = 30; +$period->instance_id = 10; +$period->user_id = 20; +$period->traffic_pool_group_id = 1; +$period->traffic_quota_mode = 'finite'; +$period->status = 'active'; +$period->starts_at = 900; +$period->ends_at = 2000; +$period->save(); + +$shadow = $instance->getConnection()->transaction( + static function () use ($instance, $period): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + return CloudInstanceNetworkPolicy::synchronizeLocked( + $locked, + $period, + 1000 + ); + } +); +$assert($shadow['managed'] === false + && CloudInstanceNetworkPolicyState::count() === 0, + 'Shadow mode created an enforced network-policy projection.'); + +$instance->network_status = 'block_failed'; +$instance->save(); +$period->traffic_pool_group_id = 2; +$period->save(); +$deferred = $instance->getConnection()->transaction( + static function () use ($instance, $period): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + return CloudInstanceNetworkPolicy::synchronizeLocked( + $locked, + CloudServicePeriod::findOrFail($period->id), + 1000 + ); + } +); +$assert(($deferred['deferred'] ?? false) === true + && CloudInstanceNetworkPolicyState::count() === 0, + 'An unresolved legacy network generation bypassed its recovery fence.'); +$instance->network_status = 'active'; +$instance->save(); + +Capsule::table('cloud_traffic_pools')->insert([ + 'id' => 40, + 'user_id' => 20, + 'traffic_pool_group_id' => 2, + 'state' => 'available', + 'available_bytes' => 100, + 'overage_bytes' => 0, + 'version' => 1, + 'last_sequence' => 0, + 'last_event_id' => null, + 'created_at' => 1000, + 'updated_at' => 1000, +]); +$available = $instance->getConnection()->transaction( + static function () use ($instance, $period): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + $freshPeriod = CloudServicePeriod::findOrFail($period->id); + $result = CloudInstanceNetworkPolicy::synchronizeLocked( + $locked, + $freshPeriod, + 1001 + ); + $locked->save(); + return $result; + } +); +$assert($available['managed'] === true + && $available['desired_suspended'] === false + && $available['action'] === 'none', + 'An available enforced pool requested a network suspension.'); + +Capsule::table('cloud_traffic_pools')->where('id', 40)->update([ + 'state' => 'exhausted', + 'available_bytes' => 0, + 'overage_bytes' => 5, + 'version' => 2, +]); +$exhausted = $instance->getConnection()->transaction( + static function () use ($instance, $period): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + $result = CloudInstanceNetworkPolicy::synchronizeLocked( + $locked, + CloudServicePeriod::findOrFail($period->id), + 1002 + ); + $locked->save(); + return $result; + } +); +$traffic = CloudInstanceNetworkRestriction::where( + 'instance_id', 10 +)->where('reason_code', 'traffic_pool_exhausted')->firstOrFail(); +$trafficRevision = (int) $traffic->revision; +$assert($exhausted['desired_suspended'] === true + && $exhausted['action'] === 'suspend' + && (string) CloudInstance::find(10)->network_status === 'blocking' + && (bool) $traffic->desired_active, + 'Pool exhaustion did not create one pending aggregate suspension.'); + +$instance->getConnection()->transaction(static function () use ($instance): void { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + CloudInstanceNetworkPolicy::setReasonLocked( + $locked, + CloudInstanceNetworkPolicy::REASON_TRAFFIC, + true, + 'traffic_pool', + 'pool:40:v2', + 1003 + ); + $locked->save(); +}); +$assert((int) CloudInstanceNetworkRestriction::where('instance_id', 10) + ->where('reason_code', 'traffic_pool_exhausted')->firstOrFail()->revision + === $trafficRevision, + 'Idempotent reason synchronization changed its revision.'); + +$firstOperation = str_repeat('a', 32); +$marker = $instance->getConnection()->transaction( + static function () use ($instance, $firstOperation): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + CloudInstanceNetworkPolicy::setReasonLocked( + $locked, + CloudInstanceNetworkPolicy::REASON_SERVICE, + true, + 'instance_expiry', + '2000', + 1004 + ); + $marker = CloudInstanceNetworkPolicy::prepareJobLocked( + $locked, + 'network_suspend', + $firstOperation, + 1004 + ); + $locked->save(); + return $marker; + } +); +$assert($marker['suspend_reason'] === 'expired' + && CloudInstanceNetworkPolicy::jobStillDesired( + 10, + 'network_suspend', + $firstOperation + ) === true, + 'Multiple reasons did not collapse into one expiry-priority operation.'); + +// Both reasons disappear while the suspend is in flight. The successful +// suspend must be compensated by a later resume, never projected as active. +$instance->getConnection()->transaction(static function () use ($instance): void { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + foreach ([ + CloudInstanceNetworkPolicy::REASON_SERVICE, + CloudInstanceNetworkPolicy::REASON_TRAFFIC, + ] as $reason) { + CloudInstanceNetworkPolicy::setReasonLocked( + $locked, + $reason, + false, + $reason === CloudInstanceNetworkPolicy::REASON_SERVICE + ? 'instance_expiry' : 'traffic_pool', + $reason === CloudInstanceNetworkPolicy::REASON_SERVICE + ? '2000' : 'pool:40:v3', + 1005 + ); + } + $locked->save(); +}); +$compensation = $instance->getConnection()->transaction( + static function () use ($instance, $firstOperation): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + $result = CloudInstanceNetworkPolicy::finishJobLocked( + $locked, + 'network_suspend', + $firstOperation, + 'succeeded', + false, + false, + 1006 + ); + $locked->save(); + return $result; + } +); +$assert($compensation['action'] === 'resume' + && $compensation['applied_suspended'] === true + && (string) CloudInstance::find(10)->network_status === 'restore_pending', + 'A cleared in-flight suspend did not request compensating restoration.'); + +$resumeOperation = str_repeat('b', 32); +$instance->getConnection()->transaction( + static function () use ($instance, $resumeOperation): void { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + CloudInstanceNetworkPolicy::prepareJobLocked( + $locked, + 'network_resume', + $resumeOperation, + 1007 + ); + CloudInstanceNetworkPolicy::setReasonLocked( + $locked, + CloudInstanceNetworkPolicy::REASON_ADMIN, + true, + 'administrator', + 'user:1', + 1008 + ); + $locked->save(); + } +); +$reblock = $instance->getConnection()->transaction( + static function () use ($instance, $resumeOperation): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + $result = CloudInstanceNetworkPolicy::finishJobLocked( + $locked, + 'network_resume', + $resumeOperation, + 'succeeded', + false, + false, + 1009 + ); + $locked->save(); + return $result; + } +); +$assert($reblock['action'] === 'suspend' + && $reblock['applied_suspended'] === false + && (string) CloudInstance::find(10)->network_status === 'blocking', + 'A reason added during resume left the instance connected.'); + +$secondSuspend = str_repeat('c', 32); +$instance->getConnection()->transaction( + static function () use ($instance, $secondSuspend): void { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + CloudInstanceNetworkPolicy::prepareJobLocked( + $locked, + 'network_suspend', + $secondSuspend, + 1010 + ); + CloudInstanceNetworkPolicy::finishJobLocked( + $locked, + 'network_suspend', + $secondSuspend, + 'succeeded', + false, + false, + 1011 + ); + $locked->save(); + } +); +$assert((string) CloudInstance::find(10)->network_status === 'blocked_traffic', + 'An applied administrator restriction was not projected as blocked.'); + +// An attention pool cannot clear an already asserted traffic reason. +$instance->getConnection()->transaction(static function () use ($instance): void { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + CloudInstanceNetworkPolicy::setReasonLocked( + $locked, + CloudInstanceNetworkPolicy::REASON_TRAFFIC, + true, + 'traffic_pool', + 'pool:40:v3', + 1012 + ); + $locked->save(); +}); +Capsule::table('cloud_traffic_pools')->where('id', 40)->update([ + 'state' => 'attention', + 'available_bytes' => 100, + 'overage_bytes' => 0, + 'version' => 4, +]); +$attention = $instance->getConnection()->transaction( + static function () use ($instance, $period): array { + $locked = CloudInstance::where('id', $instance->id) + ->lockForUpdate()->firstOrFail(); + $result = CloudInstanceNetworkPolicy::synchronizeLocked( + $locked, + CloudServicePeriod::findOrFail($period->id), + 1013 + ); + $locked->save(); + return $result; + } +); +$assert($attention['traffic_decision'] === 'preserved' + && in_array('traffic_pool_exhausted', + $attention['desired_reasons'], true), + 'An attention projection guessed that traffic access could be restored.'); + +echo "Cloud instance network policy checks passed.\n"; diff --git a/web/tests/CloudTrafficPoolPeriodBindingTest.php b/web/tests/CloudTrafficPoolPeriodBindingTest.php index 8c7784db..b4530504 100644 --- a/web/tests/CloudTrafficPoolPeriodBindingTest.php +++ b/web/tests/CloudTrafficPoolPeriodBindingTest.php @@ -133,5 +133,15 @@ CloudTrafficPoolPeriodBinding::bindPeriod($period, 7, 2048); $assert((int) $period->traffic_pool_group_id === 7 && (string) $period->traffic_quota_mode === 'finite', 'A finite upgrade changed the frozen group or quota mode.'); +$persisted = new CloudServicePeriod(); +$persisted->exists = true; +$persisted->traffic_pool_group_id = 7; +$persisted->traffic_quota_mode = 'finite'; +$expectConflict( + static function () use ($persisted): void { + CloudTrafficPoolPeriodBinding::bindPeriod($persisted, 7, 0); + }, + 'An active pooled period switched from finite to unlimited without a ledger event.' +); echo "Cloud traffic pool period binding checks passed.\n"; diff --git a/web/tests/CloudTrafficPoolSchemaContractTest.php b/web/tests/CloudTrafficPoolSchemaContractTest.php index f1402c72..4d0d1881 100644 --- a/web/tests/CloudTrafficPoolSchemaContractTest.php +++ b/web/tests/CloudTrafficPoolSchemaContractTest.php @@ -26,6 +26,7 @@ foreach ([ 'cloud_traffic_instance_cursors', 'cloud_traffic_scan_failures', 'cloud_instance_network_restrictions', + 'cloud_instance_network_policy_states', ] as $table) { $assert(str_contains($schema, 'CREATE TABLE ' . $table . ' ('), 'Missing traffic-pool table: ' . $table); @@ -68,12 +69,13 @@ $assert(str_contains($schema, 'Service-period traffic-pool identity is not frozen or indexed.'); $assert(str_contains($setup, - "SCHEMA_VERSION = 'go-agent-wss-v21-traffic-scan-backoff'") + "SCHEMA_VERSION = 'go-agent-wss-v22-network-policy'") && str_contains($setup, "'chk_cloud_traffic_entitlement_balance'") && str_contains($setup, "'cloud_traffic_ledger_sequence'"), 'CloudSetup schema version or named-object validation is incomplete.'); $expectedDeletionOrder = [ + "['cloud_instance_network_policy_states', 'user_id']", "['cloud_instance_network_restrictions', 'user_id']", "['cloud_traffic_instance_cursors', 'user_id']", "['cloud_traffic_ledger_events', 'user_id']", @@ -102,6 +104,7 @@ foreach ([ 'CloudTrafficLedgerEvent', 'CloudTrafficInstanceCursor', 'CloudTrafficScanFailure', 'CloudInstanceNetworkRestriction', + 'CloudInstanceNetworkPolicyState', ] as $model) { $assert(is_file($root . '/app/Models/' . $model . '.php'), 'Missing traffic-pool model: ' . $model); diff --git a/web/tests/CloudTrafficRestrictionLockOrderContractTest.php b/web/tests/CloudTrafficRestrictionLockOrderContractTest.php new file mode 100644 index 00000000..044b73d1 --- /dev/null +++ b/web/tests/CloudTrafficRestrictionLockOrderContractTest.php @@ -0,0 +1,44 @@ +id)') + && strpos($policy, 'lockState($instance, $now)') + < strpos($policy, 'lockRestrictions((int) $instance->id)'), + 'Network policy no longer locks state before ordered reasons.'); +$assert(str_contains($policy, "orderBy('reason_code')->lockForUpdate()"), + 'Network restriction rows are not locked in reason-code order.'); +$poolRead = strpos($policy, '$pool = CloudTrafficPool::where('); +$poolReadEnd = $poolRead === false ? false + : strpos($policy, ')->first();', $poolRead); +$assert($poolRead !== false && $poolReadEnd !== false + && !str_contains( + substr($policy, $poolRead, $poolReadEnd - $poolRead), + 'lockForUpdate' + ), + 'Network policy acquired a traffic-pool write lock.'); +$assert(!str_contains($policy, 'CloudAgentClient') + && !str_contains($policy, 'CloudJobService'), + 'Network policy gained a remote side effect or queue dependency.'); + +echo "Cloud traffic restriction lock-order contract passed.\n";