feat(traffic): model aggregate network policy

go
codex 3 weeks ago
parent e35e93c8a6
commit 5495137946

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

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

@ -0,0 +1,21 @@
<?php
namespace App\Models;
final class CloudInstanceNetworkPolicyState extends Model
{
protected $connection = 'default';
protected $table = 'cloud_instance_network_policy_states';
protected $primaryKey = 'instance_id';
public $incrementing = false;
protected $casts = [
'instance_id' => 'int',
'user_id' => 'int',
'desired_suspended' => 'boolean',
'applied_suspended' => 'boolean',
'revision' => 'int',
'created_at' => 'int',
'updated_at' => 'int',
];
}

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

@ -0,0 +1,604 @@
<?php
namespace App\Services\Cloud;
use App\Models\CloudInstance;
use App\Models\CloudInstanceNetworkPolicyState;
use App\Models\CloudInstanceNetworkRestriction;
use App\Models\CloudServicePeriod;
use App\Models\CloudTrafficPool;
use App\Models\CloudTrafficPoolGroup;
/**
* Aggregate public-network policy for one already-locked instance.
*
* Restriction rows are independent facts. The policy-state row is the only
* owner of the one remote NIC mutation needed to apply their union. Callers
* must lock the instance first; this module then locks the policy state and
* restriction rows in reason-code order. It never locks a traffic pool or
* calls an Agent.
*/
final class CloudInstanceNetworkPolicy
{
public const REASON_TRAFFIC = 'traffic_pool_exhausted';
public const REASON_SERVICE = 'service_expired';
public const REASON_ADMIN = 'admin_hold';
private const REASONS = [
self::REASON_ADMIN,
self::REASON_SERVICE,
self::REASON_TRAFFIC,
];
public static function isEnforcedPeriod(?CloudServicePeriod $period): bool
{
if ($period === null || $period->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<string,mixed>
*/
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<string,mixed> */
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<string,mixed> 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<string,mixed>
*/
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<string,mixed> */
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<string,mixed> */
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<string,mixed> */
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.');
}
}
}

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

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

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

@ -0,0 +1,418 @@
<?php
require dirname(__DIR__) . '/vendor/autoload.php';
use App\Models\CloudInstance;
use App\Models\CloudInstanceNetworkPolicyState;
use App\Models\CloudInstanceNetworkRestriction;
use App\Models\CloudServicePeriod;
use App\Services\Cloud\CloudInstanceNetworkPolicy;
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('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";

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

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

@ -0,0 +1,44 @@
<?php
$root = dirname(__DIR__);
$policy = file_get_contents(
$root . '/app/Services/Cloud/CloudInstanceNetworkPolicy.php'
);
$accounting = file_get_contents(
$root . '/app/Services/Cloud/CloudTrafficPoolAccounting.php'
);
if (!is_string($policy) || !is_string($accounting)) {
throw new RuntimeException('Unable to read traffic policy sources.');
}
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$assert(!str_contains($accounting, 'CloudInstanceNetworkPolicy')
&& !str_contains($accounting, 'CloudInstanceNetworkRestriction')
&& !str_contains($accounting, 'CloudInstanceNetworkPolicyState')
&& !str_contains($accounting, 'CloudAgentClient'),
'Pool accounting crossed into the instance policy/Agent lock domain.');
$assert(str_contains($policy, 'lockState($instance, $now)')
&& str_contains($policy, 'lockRestrictions((int) $instance->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";
Loading…
Cancel
Save