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 ((bool) $state->applied_suspended || in_array((string) $instance->network_status, [ 'blocking', 'blocked_traffic', 'blocked_expired', 'block_failed', 'restore_pending', 'restoring', 'restore_failed', ], true)) { // Missing/attention accounting is never authority to // restore a known-blocked instance. Reassert the traffic // fence even when a prior available projection had already // cleared this row; a queued resume will then be skipped, // while an already-dispatched resume is compensated. self::setReasonFact( $instance, $rows, self::REASON_TRAFFIC, true, 'traffic_pool', 'group:' . (int) $period->traffic_pool_group_id . ':untrusted', $now ); $trafficDecision = 'fenced'; } } } $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 ); } if ($kind === 'network_suspend') { return (bool) $state->desired_suspended; } if ((bool) $state->desired_suspended) { return false; } // Accounting and instance convergence run in separate transactions. // Revalidate the current enforced pool at the last pre-dispatch // boundary so an old queued resume cannot cross a newly persisted // exhausted/attention/missing projection before Lifecycle has copied // that fact into the instance policy state. These are plain reads: // the policy lock domain never takes a traffic-pool row lock. return !self::currentResumeFence($instanceId); } private static function currentResumeFence(int $instanceId): bool { $instance = CloudInstance::find($instanceId); if ($instance === null) { return true; } if ((string) $instance->service_status !== 'exempt' && !$instance->serviceAvailable()) { return true; } if ($instance->current_period_id === null) { return false; } $period = CloudServicePeriod::where( 'id', (int) $instance->current_period_id )->where('instance_id', $instanceId)->where( 'user_id', (int) $instance->user_id )->first(); if ($period === null || !self::isEnforcedPeriod($period)) { return false; } if ((string) $period->traffic_quota_mode !== 'finite') { return false; } $now = time(); if (!in_array((string) $period->status, ['active', 'exhausted'], true) || (int) $period->starts_at > $now || (int) $period->ends_at <= $now) { return true; } $pool = CloudTrafficPool::where( 'user_id', (int) $instance->user_id )->where( 'traffic_pool_group_id', (int) $period->traffic_pool_group_id )->first(); return $pool === null || (string) $pool->state !== 'available' || (int) $pool->overage_bytes > 0; } /** @return array|null */ public static function payloadMarker( array $payload, int $instanceId, string $operationId ): ?array { if (!array_key_exists('_network_policy', $payload)) { return null; } $marker = $payload['_network_policy']; if (!is_array($marker) || array_is_list($marker) || ($marker['version'] ?? null) !== 1 || ($marker['instance_id'] ?? null) !== $instanceId || !is_string($marker['operation_id'] ?? null) || !hash_equals($operationId, $marker['operation_id']) || !is_int($marker['policy_revision'] ?? null) || $marker['policy_revision'] < 1 || !is_bool($marker['desired_suspended'] ?? null) || !is_bool($marker['applied_suspended'] ?? null) || !is_string($marker['suspend_reason'] ?? null) || !in_array($marker['suspend_reason'], ['traffic', 'expired'], true)) { throw new CloudRecoveryPayloadUnavailable( '网络策略任务缺少不可变执行快照', 409 ); } return $marker; } /** * 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); } public static function releaseAfterInstanceDeletedLocked( CloudInstance $instance ): void { CloudInstanceNetworkPolicyState::where( 'instance_id', (int) $instance->id )->delete(); CloudInstanceNetworkRestriction::where( 'instance_id', (int) $instance->id )->delete(); } 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'; $instance->network_suspended_at = (bool) $state->applied_suspended ? ($instance->network_suspended_at ?? $now) : null; } 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.'); } } }