You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/app/Services/Cloud/CloudVpcService.php

6086 lines
304 KiB
PHP

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?php
namespace App\Services\Cloud;
use App\Models\CloudHost;
use App\Models\CloudHostResourcePoolMembership;
use App\Models\CloudInstance;
use App\Models\CloudPrivateNetwork;
use App\Models\CloudRegion;
use App\Models\CloudRegionFabric;
use App\Models\CloudVpc;
use App\Models\CloudVpcAclRule;
use App\Models\CloudVpcHostDeployment;
use App\Models\CloudVpcMember;
use App\Models\CloudVpcOperation;
use App\Models\CloudVpcPrivateIp;
use App\Models\CloudVpcRoute;
use App\Models\CloudVpcSubnet;
use App\Models\User;
use App\Services\Config;
/**
* PHP-owned VPC control plane.
*
* This service is intentionally independent from the general VM job queue and
* the public network mutation lane. It stores only typed tenant intent,
* serialises each VPC with its own row lock, and advances observed state only after the engine
* reports an exact desired revision/digest for every participating host.
* Tenant NICs, routes and nftables are applied by the engine's independent
* VPC dataplane lane; a VPC remains unusable until typed host readback proves
* the requested revision on every participating host.
*/
final class CloudVpcService
{
/** Protocol/readback ceiling retained for existing large VPCs. */
public const MAX_MEMBERS = 4096;
/** Tenant creation policy for newly allocated /24 VPCs. */
public const DEFAULT_MAX_MEMBERS = 200;
public const DEFAULT_MAX_VPCS_PER_ACCOUNT = 5;
public const MAX_VPCS_PER_ACCOUNT = 100;
public const MAX_ROUTES = 256;
public const MAX_ACL_RULES = 256;
private const DEFAULT_PREFIX_LENGTH = 24;
/**
* Version of the engine observation contract that proves guest-visible
* private addressing and routes, rather than only host/libvirt state.
*/
public const OBSERVATION_EVIDENCE_VERSION = 2;
/** PHP transport budget must exceed the engine-wide VPC probe budget. */
public const ENGINE_TIMEOUT_SECONDS = 60.0;
public const OPERATION_LEASE_SECONDS = 120;
/** Engine reason codes that may cross the host/operation/root boundary. */
private const DEFERRED_EVIDENCE_ERRORS = [
'vpc_private_guest_restart_required',
'vpc_private_guest_agent_unavailable',
'vpc_private_guest_probe_unsupported',
'vpc_private_guest_probe_uncertain',
'vpc_private_guest_probe_deadline_exceeded',
'vpc_private_guest_probe_reap_required',
'vpc_private_guest_address_mismatch',
'vpc_private_guest_route_mismatch',
'vpc_private_guest_link_mismatch',
// Compatibility with the short-lived pre-contract preview.
'vpc_private_guest_readback_unavailable',
'vpc_private_guest_network_mismatch',
'vpc_observation_contract_outdated',
// Intentional lifecycle state, safe for host/root diagnostics but not
// treated as a guest-probe success.
'vpc_private_network_suspended',
'vpc_private_guest_stopped',
'vpc_private_guest_shutdown_pending',
];
/** Maximum exact /32 destinations present in one host readback. */
private const MAX_OBSERVED_DESTINATIONS = self::MAX_MEMBERS + self::MAX_ROUTES;
private const KEY_PATTERN = '/^[0-9a-f]{32}$/D';
private const REQUEST_KEY_PATTERN = '/^[A-Za-z0-9_.:-]{8,128}$/D';
private const FABRIC_KEY_PATTERN = '/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/D';
private const LIVE_STATES = ['applying', 'active', 'degraded', 'uncertain'];
private const PUBLIC_STATES = ['applying', 'active', 'degraded', 'uncertain', 'deleting'];
private const DIRECTIONS = ['ingress', 'egress'];
private const ACTIONS = ['allow', 'deny'];
private const PROTOCOLS = ['all', 'tcp', 'udp', 'icmp'];
/** Stable private NIC/dataplane contract shared with the engine. */
private const PRIVATE_INTERFACE = 'private0';
private const FABRIC_INTERFACE = 'wg-fabric0';
private const PRIVATE_DATAPLANE_OWNER = 'virt-cloud-vpc-dataplane-v1';
/** Return VPCs visible to an actor without contacting a host. */
public static function listing(array $actor): array
{
$query = CloudVpc::query()->whereIn('state', self::PUBLIC_STATES);
if (!self::isGlobal($actor)) {
$query->where('user_id', (int) ($actor['user_id'] ?? 0));
}
$includeInfrastructure = self::canViewInfrastructure($actor);
return $query->orderByDesc('id')->limit(200)->get()
->map(static fn (CloudVpc $vpc): array => self::publicRoot($vpc, $includeInfrastructure))
->all();
}
/** Return a complete typed control-plane projection for one VPC. */
public static function show(string $vpcKey, array $actor): array
{
$vpc = self::findOwned($vpcKey, $actor, false);
return self::documentView($vpc, $actor);
}
/**
* Create a VPC reservation and its first subnet. The CIDR allocator row
* is only an address reservation; the VPC root deliberately starts in
* applying/pending until Fabric and the future data plane are observed.
*/
public static function create(array $actor, array $input): array
{
// Tenant intent is deliberately small. CIDR, subnet shape, member
// capacity and Fabric identity are platform policy and must never be
// accepted merely because a caller guessed the current values.
CloudInput::only($input, ['name', 'region_id', 'request_key']);
$name = CloudInput::name($input['name'] ?? null);
$regionId = self::positiveInt($input['region_id'] ?? null, 1, 1000000000,
'地区无效');
$requestKey = self::requestKey($input['request_key'] ?? null);
$userId = (int) ($actor['user_id'] ?? 0);
if ($userId < 1) {
throw new CloudError('账户无效', 401);
}
$allocationKey = substr(hash('sha256', 'vpc-allocation:' . $userId . ':' . $requestKey), 0, 32);
$vpcKey = substr(hash('sha256', 'vpc:' . $userId . ':' . $requestKey), 0, 32);
// Only immutable tenant intent belongs in the idempotency hash. A
// lost response must remain replayable after Fabric or policy changes.
$requestHash = self::requestHash('vpc_create', [
'name' => $name,
'region_id' => $regionId,
]);
$maxMembers = self::DEFAULT_MAX_MEMBERS;
$prefix = self::DEFAULT_PREFIX_LENGTH;
$connection = (new CloudVpc())->getConnection();
try {
return $connection->transaction(function () use (
$actor, $name, $requestKey, $requestHash, $maxMembers,
$vpcKey, $allocationKey, $userId, $regionId, $prefix,
$connection
): array {
// Account deletion locks the owner row before checking VPCs.
// The same row also serializes quota checks for this account.
if (!$connection->getSchemaBuilder()->hasTable('user')) {
throw new CloudError('账户表尚未安装', 503);
}
$owner = User::where('id', $userId)->lockForUpdate()->first();
if ($owner === null) {
throw new CloudError('账户不存在', 401);
}
// Replay committed intent before consulting mutable platform
// state, quota or the allocator. This also prevents a deleted
// tombstone from being resurrected under its old request key.
$existing = CloudVpc::where('vpc_key', $vpcKey)
->lockForUpdate()->first();
if ($existing !== null) {
return self::replayCreateLocked(
$existing, $actor, $userId, $regionId, $name,
$requestKey, $allocationKey
);
}
$accountLimit = self::accountVpcLimit();
$accountVpcCount = CloudVpc::where('user_id', $userId)
->where('state', '<>', 'deleted')->count();
if ($accountVpcCount >= $accountLimit) {
throw new CloudError(
'账户 VPC 数量已达到上限(' . $accountLimit . ' 个)', 409
);
}
// Only a genuinely new intent consults the current region and
// Fabric mapping. Lock both rows so an administrator cannot
// change the mapping while this root is being committed.
if (!$connection->getSchemaBuilder()->hasTable('cloud_region_fabrics')) {
throw new CloudError('VPC Fabric 映射表尚未安装', 503);
}
$region = CloudRegion::where('id', $regionId)
->where('status', 'active')->lockForUpdate()->first();
$fabric = CloudRegionFabric::where('region_id', $regionId)
->where('state', 'active')->lockForUpdate()->first();
if ($region === null) {
throw new CloudError('地区不存在或暂不可用', 409);
}
if ($fabric === null) {
throw new CloudError('该地区尚未配置可用的 WireGuard Fabric', 409);
}
$fabricId = self::fabricId((string) $fabric->fabric_id);
$fabricRegion = self::fabricId((string) $fabric->fabric_region);
$fabricRevision = self::positiveInt($fabric->fabric_revision, 1,
9000000000000000, 'Fabric 版本无效');
$network = CloudPrivateCidrAllocator::allocate(
$allocationKey, $userId, $regionId, null, $prefix, $vpcKey
);
$now = time();
$vpc = new CloudVpc();
$vpc->vpc_key = $vpcKey;
$vpc->user_id = (int) $actor['user_id'];
$vpc->region_id = (int) $region->id;
$vpc->private_network_id = (int) $network->id;
$vpc->name = $name;
$vpc->cidr = (string) $network->cidr;
$vpc->fabric_id = $fabricId;
$vpc->fabric_region = $fabricRegion;
$vpc->fabric_revision = $fabricRevision;
$vpc->max_members = $maxMembers;
$vpc->state = 'applying';
$vpc->desired_revision = 0;
$vpc->observed_revision = 0;
$vpc->desired_digest = str_repeat('0', 64);
$vpc->observed_digest = null;
$vpc->sync_state = 'pending';
$vpc->last_operation_id = null;
$vpc->last_error_code = null;
$vpc->last_success_at = 0;
$vpc->last_failure_at = 0;
$vpc->created_at = $now;
$vpc->updated_at = $now;
$vpc->save();
$subnetValue = self::cidr((string) $network->cidr, 24, 24, '子网 CIDR');
if ($subnetValue['network'] < (int) $network->network_address
|| $subnetValue['broadcast'] > (int) $network->broadcast_address) {
throw new CloudError('子网必须完全位于 VPC CIDR 内');
}
// No gateway is installed in the control-plane-only phase.
$row = new CloudVpcSubnet();
$row->subnet_key = self::randomKey();
$row->vpc_id = $vpc->id;
$row->cidr = $subnetValue['cidr'];
$row->network_address = $subnetValue['network'];
$row->broadcast_address = $subnetValue['broadcast'];
$row->prefix_length = $subnetValue['prefix'];
$row->gateway_ip = null;
$row->state = 'applying';
$row->desired_revision = 0;
$row->observed_revision = 0;
$row->desired_digest = null;
$row->observed_digest = null;
$row->last_error_code = null;
$row->created_at = $now;
$row->updated_at = $now;
$row->save();
$result = self::touchDesiredLocked($vpc, 'vpc_create', $requestKey, $requestHash);
return self::documentView($result['vpc'], $actor);
}, 3);
} catch (\Throwable $error) {
// CIDR allocation and root creation use the same default
// connection and outer transaction, so failure rolls both back.
// A post-rollback release would race a same-key retry and could
// release the retry's newly committed allocation.
if ($error instanceof CloudError) {
throw $error;
}
throw new CloudError('VPC 创建未完成,请稍后重试', 503);
}
}
/**
* Queue destruction of the complete VPC root and every private child.
*
* The CIDR remains reserved until the dedicated engine delete endpoint
* returns an exact, durable deletion receipt. A retry with the same
* request key is read-only; a second delete identity cannot supersede an
* in-flight teardown.
*/
public static function delete(string $vpcKey, array $actor, array $input): array
{
CloudInput::only($input, ['confirmation_name', 'request_key']);
$confirmationName = $input['confirmation_name'] ?? null;
if (!is_string($confirmationName)) {
throw new CloudError('请输入 VPC 名称确认删除');
}
$key = self::requestKey($input['request_key'] ?? null);
$requestHash = self::requestHash('vpc_delete', [
'confirmation_name' => $confirmationName,
]);
$vpc = self::findOwned($vpcKey, $actor, true);
return $vpc->getConnection()->transaction(function () use (
$vpc, $actor, $confirmationName, $key, $requestHash
): array {
$locked = self::lockOwnedForDelete((string) $vpc->vpc_key, $actor);
if (!hash_equals((string) $locked->name, $confirmationName)) {
throw new CloudError('确认名称与 VPC 名称不一致');
}
if (self::hasOperation($locked, $key, 'vpc_delete', $requestHash)) {
return self::documentView($locked, $actor);
}
if ((string) $locked->state === 'deleted') {
// DELETE remains idempotent after the original operation has
// completed, even when the caller generated a fresh request
// key after losing the prior HTTP response.
return self::documentView($locked, $actor);
}
if ((string) $locked->state === 'deleting') {
throw new CloudError('VPC 删除正在核对,请勿重复提交', 409);
}
$now = time();
foreach ([
CloudVpcRoute::class,
CloudVpcAclRule::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcSubnet::class,
] as $childModel) {
$rows = $childModel::where('vpc_id', $locked->id)
->where('state', '<>', 'deleted')->lockForUpdate()->get();
foreach ($rows as $row) {
$row->state = 'deleting';
$row->updated_at = $now;
$row->save();
}
}
$locked->state = 'deleting';
$locked->sync_state = 'pending';
$locked->last_error_code = null;
$locked->updated_at = $now;
$locked->save();
$result = self::touchDesiredLocked(
$locked, 'vpc_delete', $key, $requestHash
);
return self::documentView($result['vpc'], $actor);
}, 3);
}
public static function attachMember(string $vpcKey, array $actor, array $input): array
{
// Legacy subnet/IP fields are admitted only far enough to replay an
// already committed operation during a rolling UI/API deployment.
// They can never create a new member under the automatic policy.
CloudInput::only($input, [
'instance_id', 'request_key', 'subnet_key', 'private_ip',
]);
$key = self::requestKey($input['request_key'] ?? null);
$instanceId = self::positiveInt($input['instance_id'] ?? null, 1, 1000000000,
'虚拟机无效');
$hasLegacySubnet = array_key_exists('subnet_key', $input);
$hasLegacyIp = array_key_exists('private_ip', $input);
if ($hasLegacyIp && !$hasLegacySubnet) {
throw new CloudError('私网 IP 只能由平台自动分配,请刷新页面后重试', 422);
}
$legacyRequestHash = null;
if ($hasLegacySubnet) {
self::assertKey($input['subnet_key'] ?? null, '子网');
$legacyIpForHash = null;
if ($hasLegacyIp && $input['private_ip'] !== null) {
self::ipv4($input['private_ip'], '私网 IP');
// The former implementation hashed the validated raw string
// before storing its canonical address in the lease row.
$legacyIpForHash = (string) $input['private_ip'];
}
$legacyRequestHash = self::requestHash('member_attach', [
'subnet_key' => (string) $input['subnet_key'],
'instance_id' => $instanceId,
'private_ip' => $legacyIpForHash,
]);
}
// Older workers could persist a locally proven `deleted` pair after
// the VPC root and every historical host had already reached the same
// exact revision. Such rows still own the database uniqueness keys.
// Reap only those fully proven pairs before taking the target VPC lock;
// cross-VPC cleanup otherwise creates a target -> source lock inversion.
$vpc = self::findOwned($vpcKey, $actor, true);
if (!in_array((string) $vpc->state, self::LIVE_STATES, true)) {
throw new CloudError(
(string) $vpc->state === 'deleted'
? 'VPC 已删除' : 'VPC 正在删除,不能再修改',
409
);
}
// Preserve attach idempotency before instance/Fabric preconditions or
// legacy garbage collection. A client retry after the first response
// was lost must still resolve the original operation even if the VM's
// runtime state or host-region mapping has changed in the meantime.
$prepared = $vpc->getConnection()->transaction(function () use (
$vpc, $actor, $key, $instanceId, $legacyRequestHash
): array {
$locked = self::lockOwned($vpc->vpc_key, $actor);
if (self::hasMemberAttachOperation(
$locked, $key, $instanceId, $legacyRequestHash
)) {
return [
'request_hash' => null,
'subnet_key' => null,
'replay' => self::documentView($locked, $actor),
];
}
if ($legacyRequestHash !== null) {
throw new CloudError(
'子网和私网 IP 由平台自动分配,请刷新页面后重试',
422
);
}
$subnet = self::lockedAutomaticSubnet($locked);
// Preserve the historical automatic-attach hash shape so a lost
// response from the former subnet selector remains replayable.
$requestHash = self::requestHash('member_attach', [
'subnet_key' => (string) $subnet->subnet_key,
'instance_id' => $instanceId,
'private_ip' => null,
]);
return [
'request_hash' => $requestHash,
'subnet_key' => (string) $subnet->subnet_key,
'replay' => null,
];
}, 3);
if ($prepared['replay'] !== null) {
return $prepared['replay'];
}
$requestHash = (string) $prepared['request_hash'];
$automaticSubnetKey = (string) $prepared['subnet_key'];
$instance = CloudInstance::where('id', $instanceId)
->where('status', '<>', 'deleted')->first();
if ($instance !== null
&& ((int) $instance->user_id === (int) $vpc->user_id || self::isGlobal($actor))
&& (string) $instance->status === 'active'
&& $instance->serviceAvailable()) {
self::assertInstanceRegion($instance, (int) $vpc->region_id);
self::releasePersistedDeletedMembershipsBeforeAttach(
$vpc, $instance, $actor
);
}
return $vpc->getConnection()->transaction(function () use (
$vpc, $actor, $key, $requestHash, $instanceId, $automaticSubnetKey,
$legacyRequestHash
): array {
$vpc = self::lockOwned($vpc->vpc_key, $actor);
if (self::hasMemberAttachOperation(
$vpc, $key, $instanceId, $legacyRequestHash
)) {
return self::documentView($vpc, $actor);
}
$subnet = self::lockedAutomaticSubnet($vpc);
if (!hash_equals($automaticSubnetKey, (string) $subnet->subnet_key)) {
throw new CloudError('VPC 自动子网状态已变化,请重新读取', 409);
}
$existing = CloudVpcMember::where('vpc_id', $vpc->id)
->where('instance_id', $instanceId)->lockForUpdate()->first();
if ($existing !== null) {
if (in_array((string) $existing->state, ['deleted', 'deleting'], true)) {
throw new CloudError('该虚拟机的旧 VPC 成员仍在清理,暂不能重新加入', 409);
}
$existingInstance = CloudInstance::where('id', $instanceId)
->where('status', '<>', 'deleted')->lockForUpdate()->first();
if ($existingInstance === null) {
throw new CloudError('虚拟机不存在', 404);
}
if ((int) $existingInstance->user_id !== (int) $vpc->user_id
&& !self::isGlobal($actor)) {
throw new CloudError('无权使用该 VPC 成员', 403);
}
if ((string) $existingInstance->status !== 'active') {
throw new CloudError('虚拟机正在删除,不能继续使用私网成员', 409);
}
if (!$existingInstance->serviceAvailable()) {
throw new CloudError('虚拟机当前服务周期不可用,不能继续使用私网成员', 409);
}
self::assertInstanceRegion($existingInstance, (int) $vpc->region_id);
if ((int) $existing->host_id !== (int) $existingInstance->host_id) {
throw new CloudError('虚拟机宿主机已变化,请先移除旧私网成员', 409);
}
if ((int) $existing->subnet_id !== (int) $subnet->id) {
throw new CloudError('该虚拟机已加入 VPC 的其他子网,请先移除现有成员', 409);
}
$privateIp = self::lockedPrivateIpForMember($existing);
if ((int) $privateIp->subnet_id !== (int) $subnet->id
|| (string) $privateIp->private_ip !== (string) $existing->private_ip
|| (int) $privateIp->instance_id !== $instanceId
|| in_array((string) $privateIp->state, ['deleted', 'deleting'], true)) {
throw new CloudError('VPC 私网地址账本与成员不一致,请联系管理员', 503);
}
return self::documentView($vpc, $actor);
}
$instance = CloudInstance::where('id', $instanceId)
->where('status', '<>', 'deleted')->lockForUpdate()->first();
if ($instance === null) {
throw new CloudError('虚拟机不存在', 404);
}
if ((int) $instance->user_id !== (int) $vpc->user_id && !self::isGlobal($actor)) {
throw new CloudError('无权添加该虚拟机', 403);
}
$otherMembership = CloudVpcMember::where('instance_id', $instanceId)
->where('vpc_id', '<>', $vpc->id)->lockForUpdate()->first();
if ($otherMembership !== null) {
$message = in_array((string) $otherMembership->state,
['deleted', 'deleting'], true)
? '该虚拟机的旧 VPC 成员仍在清理,暂不能迁移'
: '首版每台虚拟机只能加入一个 VPC';
throw new CloudError($message, 409);
}
// A lease without its member is not reusable capacity. It can
// represent a partially migrated/corrupt ledger or an unproven
// host-side address, so do not let the global member unique key be
// recreated while that independent identity still exists.
if (CloudVpcPrivateIp::where('instance_id', $instanceId)
->lockForUpdate()->exists()) {
throw new CloudError(
'VPC 私网地址账本与成员不一致,请联系管理员',
503
);
}
if ((string) $instance->status !== 'active' || !$instance->serviceAvailable()) {
throw new CloudError('虚拟机当前不可加入私网', 409);
}
self::assertInstanceRegion($instance, (int) $vpc->region_id);
$members = CloudVpcMember::where('vpc_id', $vpc->id)->lockForUpdate()->get();
// A deleting member still owns its address and host-side state
// until exact tombstone convergence. Only deleted frees capacity.
$liveCount = $members->filter(static fn ($row): bool =>
(string) $row->state !== 'deleted')->count();
if ($liveCount >= (int) $vpc->max_members) {
throw new CloudError('VPC 成员数量已达到上限', 409);
}
// Address leases are a separate child aggregate. Lock the full
// VPC lease set before choosing an automatic address; the unique
// address key remains the final database guard for another
// process that bypasses this service.
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->lockForUpdate()->get();
$reservedRouteIps = [];
$liveRoutes = CloudVpcRoute::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted'])->lockForUpdate()
->get(['destination_cidr', 'next_hop_ip']);
foreach ($liveRoutes as $route) {
$destination = explode('/', (string) $route->destination_cidr, 2)[0];
if (filter_var($destination,
FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) !== false) {
$reservedRouteIps[$destination] = true;
}
if (filter_var((string) $route->next_hop_ip,
FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) !== false) {
$reservedRouteIps[(string) $route->next_hop_ip] = true;
}
}
$ip = self::firstFreeIp($subnet, $privateIps, $reservedRouteIps);
$ipInt = self::ipToInt($ip);
if ($ipInt <= (int) $subnet->network_address
|| $ipInt >= (int) $subnet->broadcast_address) {
throw new CloudError('私网 IP 必须位于子网可用地址范围内');
}
if (isset($reservedRouteIps[$ip])) {
throw new CloudError('私网 IP 仍被 VPC 路由占用', 409);
}
foreach ($privateIps as $row) {
if ((string) $row->private_ip === $ip) {
throw new CloudError('私网 IP 已被占用', 409);
}
}
// Keep the legacy member mirror as a second fail-closed guard
// while older rows are being migrated into the lease table.
foreach ($members as $row) {
if ((string) $row->private_ip === $ip) {
throw new CloudError('私网 IP 已被占用', 409);
}
}
$now = time();
$member = new CloudVpcMember();
$member->member_key = self::randomKey();
$member->vpc_id = $vpc->id;
$member->subnet_id = $subnet->id;
$member->private_ip_id = null;
$member->instance_id = $instance->id;
$member->host_id = $instance->host_id;
$member->private_ip = $ip;
$member->private_ip_int = $ipInt;
$member->state = 'applying';
$member->created_at = $member->updated_at = $now;
$member->save();
$privateIp = new CloudVpcPrivateIp();
$privateIp->ip_key = self::randomKey();
$privateIp->vpc_id = $vpc->id;
$privateIp->subnet_id = $subnet->id;
$privateIp->member_id = $member->id;
$privateIp->instance_id = $instance->id;
$privateIp->private_ip = $ip;
$privateIp->private_ip_int = $ipInt;
$privateIp->state = 'applying';
$privateIp->created_at = $privateIp->updated_at = $now;
$privateIp->save();
$member->private_ip_id = $privateIp->id;
$member->save();
$result = self::touchDesiredLocked($vpc, 'member_attach', $key, $requestHash);
return self::documentView($result['vpc'], $actor);
}, 3);
}
public static function detachMember(string $vpcKey, string $memberKey,
array $actor, array $input): array
{
CloudInput::only($input, ['request_key']);
$key = self::requestKey($input['request_key'] ?? null);
self::assertKey($memberKey, '成员');
$requestHash = self::requestHash('member_detach', ['member_key' => $memberKey]);
$vpc = self::lockOwned($vpcKey, $actor);
return $vpc->getConnection()->transaction(function () use (
$vpc, $memberKey, $actor, $key, $requestHash
): array {
$vpc = self::lockOwned($vpc->vpc_key, $actor);
if (self::hasOperation($vpc, $key, 'member_detach', $requestHash)) {
return self::documentView($vpc, $actor);
}
$member = CloudVpcMember::where('vpc_id', $vpc->id)
->where('member_key', $memberKey)->lockForUpdate()->first();
if ($member === null || in_array((string) $member->state, ['deleted', 'deleting'], true)) {
throw new CloudError('VPC 成员不存在', 404);
}
if (CloudVpcRoute::where('vpc_id', $vpc->id)
->where('member_id', $member->id)
->whereNotIn('state', ['deleted', 'deleting'])
->exists()) {
throw new CloudError('该成员仍被路由引用,请先替换或删除路由', 409);
}
// Lifecycle commits lock VPC -> instance before validating the
// captured private target. Take the same order here so a detach
// cannot flip the member to deleting while a VM job is committing.
$instance = CloudInstance::where('id', (int) $member->instance_id)
->lockForUpdate()->first();
if ($instance === null || (string) $instance->status === 'deleted') {
throw new CloudError('虚拟机不存在', 404);
}
$privateIp = self::lockedPrivateIpForMember($member);
$member->state = 'deleting';
$member->updated_at = time();
$member->save();
$privateIp->state = 'deleting';
$privateIp->updated_at = time();
$privateIp->save();
$result = self::touchDesiredLocked($vpc, 'member_detach', $key, $requestHash);
return self::documentView($result['vpc'], $actor);
}, 3);
}
/** Replace the complete typed route set; raw route commands never cross the API. */
public static function replaceRoutes(string $vpcKey, array $actor, array $input): array
{
CloudInput::only($input, ['routes', 'request_key']);
$key = self::requestKey($input['request_key'] ?? null);
$routes = self::routeInput($input['routes'] ?? null);
$requestHash = self::requestHash('routes_replace', ['routes' => $routes]);
$vpc = self::lockOwned($vpcKey, $actor);
return $vpc->getConnection()->transaction(function () use (
$vpc, $actor, $routes, $key, $requestHash
): array {
$vpc = self::lockOwned($vpc->vpc_key, $actor);
if (self::hasOperation($vpc, $key, 'routes_replace', $requestHash)) {
return self::documentView($vpc, $actor);
}
$members = CloudVpcMember::where('vpc_id', $vpc->id)->lockForUpdate()->get();
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->lockForUpdate()->get()->keyBy('member_id');
$byIp = [];
foreach ($members as $member) {
if (!in_array((string) $member->state, ['deleted', 'deleting'], true)) {
$privateIp = $privateIps[(int) $member->id] ?? null;
if ($privateIp === null
|| (int) $member->private_ip_id !== (int) $privateIp->id
|| (string) $privateIp->private_ip !== (string) $member->private_ip
|| in_array((string) $privateIp->state, ['deleted', 'deleting'], true)) {
throw new CloudError('VPC 私网地址账本与成员不一致,请联系管理员', 503);
}
$byIp[(string) $privateIp->private_ip] = $member;
}
}
$rows = CloudVpcRoute::where('vpc_id', $vpc->id)->lockForUpdate()->get();
$existingByDestination = [];
$deletedByDestination = [];
$existingByKey = [];
foreach ($rows as $row) {
$existingByKey[(string) $row->route_key] = $row;
if ((string) $row->state === 'deleted') {
// A proven tombstone still owns the destination/key
// unique indexes. It may be revived by a later complete
// replacement, but must never be reopened merely because
// another save includes unrelated routes.
$deletedByDestination[(string) $row->destination_cidr] = $row;
} else {
$existingByDestination[(string) $row->destination_cidr] = $row;
}
}
if ($rows->contains(static fn ($row): bool =>
(string) $row->state === 'deleting')) {
throw new CloudError('路由仍在清理,请等待宿主机回读后再保存', 409);
}
$seenDestinations = [];
foreach ($routes as $route) {
$destination = (string) $route['destination']['cidr'];
if (isset($seenDestinations[$destination])) {
throw new CloudError('路由目标不能重复', 409);
}
$destinationIp = explode('/', $destination, 2)[0];
if (isset($byIp[$destinationIp])) {
throw new CloudError('路由目标不能与 VPC 成员私网 IP 重复', 409);
}
$seenDestinations[$destination] = true;
$existing = $existingByDestination[$destination]
?? $deletedByDestination[$destination] ?? null;
if ($existing !== null
&& (string) $existing->state !== 'deleted'
&& (string) $existing->route_key !== $route['route_key']) {
throw new CloudError('路由目标已存在,请沿用原 route_key 修改', 409);
}
$sameKey = $existingByKey[$route['route_key']] ?? null;
if ($sameKey !== null && $existing !== null
&& (int) $sameKey->id !== (int) $existing->id) {
throw new CloudError('route_key 已被其他路由使用', 409);
}
}
foreach ($rows as $row) {
if ((string) $row->state === 'deleted') {
continue;
}
$row->state = 'deleting';
$row->updated_at = time();
$row->save();
}
$now = time();
foreach ($routes as $route) {
$destination = (string) $route['destination']['cidr'];
$next = $byIp[$route['next_hop_ip']] ?? null;
if ($next === null) {
throw new CloudError('路由下一跳必须是本 VPC 的成员私网 IP');
}
$root = self::cidr((string) $vpc->cidr, 16, 24, 'VPC CIDR');
if (!self::contains($root['network'], $root['broadcast'],
$route['destination']['network'], $route['destination']['broadcast'])) {
throw new CloudError('路由目标必须位于 VPC CIDR 内');
}
$row = CloudVpcRoute::where('vpc_id', $vpc->id)
->where('route_key', $route['route_key'])->lockForUpdate()->first();
if ($row === null) {
// Reuse a proven tombstone when the user recreates the
// same destination with a fresh browser-generated key.
// This satisfies both unique indexes without exposing
// historical keys in the tenant editor.
$row = $deletedByDestination[$destination] ?? null;
}
if ($row === null) {
$row = new CloudVpcRoute();
$row->route_key = $route['route_key'];
$row->vpc_id = $vpc->id;
$row->created_at = $now;
}
$row->route_key = $route['route_key'];
$row->member_id = $next->id;
$row->destination_cidr = $route['destination']['cidr'];
$row->destination_int = $route['destination']['network'];
$row->broadcast_int = $route['destination']['broadcast'];
$row->prefix_length = $route['destination']['prefix'];
$row->next_hop_ip = $route['next_hop_ip'];
$row->metric = $route['metric'];
$row->state = 'applying';
$row->updated_at = $now;
$row->save();
}
$result = self::touchDesiredLocked($vpc, 'routes_replace', $key, $requestHash);
return self::documentView($result['vpc'], $actor);
}, 3);
}
/** Replace typed private ACL rules. Default engine policy remains deny. */
public static function replaceAcl(string $vpcKey, array $actor, array $input): array
{
CloudInput::only($input, ['rules', 'request_key']);
$key = self::requestKey($input['request_key'] ?? null);
$rules = self::aclInput($input['rules'] ?? null);
$requestHash = self::requestHash('acl_replace', ['rules' => $rules]);
$vpc = self::lockOwned($vpcKey, $actor);
return $vpc->getConnection()->transaction(function () use (
$vpc, $actor, $rules, $key, $requestHash
): array {
$vpc = self::lockOwned($vpc->vpc_key, $actor);
if (self::hasOperation($vpc, $key, 'acl_replace', $requestHash)) {
return self::documentView($vpc, $actor);
}
$root = self::cidr((string) $vpc->cidr, 16, 24, 'VPC CIDR');
$rows = CloudVpcAclRule::where('vpc_id', $vpc->id)->lockForUpdate()->get();
$existingByPriority = [];
$deletedByPriority = [];
$existingByKey = [];
foreach ($rows as $row) {
$priorityKey = (string) $row->direction . ':' . (int) $row->priority;
$existingByKey[(string) $row->rule_key] = $row;
if ((string) $row->state === 'deleted') {
$deletedByPriority[$priorityKey] = $row;
} else {
$existingByPriority[$priorityKey] = $row;
}
}
if ($rows->contains(static fn ($row): bool =>
(string) $row->state === 'deleting')) {
throw new CloudError('ACL 仍在清理,请等待宿主机回读后再保存', 409);
}
$seenPriorities = [];
foreach ($rules as $rule) {
$priorityKey = (string) $rule['direction'] . ':' . (int) $rule['priority'];
if (isset($seenPriorities[$priorityKey])) {
throw new CloudError('同一方向的 ACL 优先级不能重复', 409);
}
$seenPriorities[$priorityKey] = true;
$existing = $existingByPriority[$priorityKey]
?? $deletedByPriority[$priorityKey] ?? null;
if ($existing !== null
&& (string) $existing->state !== 'deleted'
&& (string) $existing->rule_key !== $rule['rule_key']) {
throw new CloudError('ACL 优先级已存在,请沿用原 rule_key 修改', 409);
}
$sameKey = $existingByKey[$rule['rule_key']] ?? null;
if ($sameKey !== null && $existing !== null
&& (int) $sameKey->id !== (int) $existing->id) {
throw new CloudError('rule_key 已被其他 ACL 使用', 409);
}
}
foreach ($rows as $row) {
if ((string) $row->state === 'deleted') {
continue;
}
$row->state = 'deleting';
$row->updated_at = time();
$row->save();
}
$now = time();
foreach ($rules as $rule) {
$priorityKey = (string) $rule['direction'] . ':' . (int) $rule['priority'];
foreach (['source', 'destination'] as $side) {
if (!self::contains($root['network'], $root['broadcast'],
$rule[$side]['network'], $rule[$side]['broadcast'])) {
throw new CloudError('ACL 地址范围必须位于 VPC CIDR 内');
}
}
$row = CloudVpcAclRule::where('vpc_id', $vpc->id)
->where('rule_key', $rule['rule_key'])->lockForUpdate()->first();
if ($row === null) {
// As with routes, a terminal tombstone can be reused for
// the same direction/priority without exposing its key.
$row = $deletedByPriority[$priorityKey] ?? null;
}
if ($row === null) {
$row = new CloudVpcAclRule();
$row->rule_key = $rule['rule_key'];
$row->vpc_id = $vpc->id;
$row->created_at = $now;
}
$row->rule_key = $rule['rule_key'];
$row->priority = $rule['priority'];
$row->direction = $rule['direction'];
$row->action = $rule['action'];
$row->protocol = $rule['protocol'];
$row->source_cidr = $rule['source']['cidr'];
$row->source_int = $rule['source']['network'];
$row->source_broadcast_int = $rule['source']['broadcast'];
$row->source_prefix_length = $rule['source']['prefix'];
$row->destination_cidr = $rule['destination']['cidr'];
$row->destination_int = $rule['destination']['network'];
$row->destination_broadcast_int = $rule['destination']['broadcast'];
$row->destination_prefix_length = $rule['destination']['prefix'];
$row->port_from = $rule['port_from'];
$row->port_to = $rule['port_to'];
$row->state = 'applying';
$row->updated_at = $now;
$row->save();
}
$result = self::touchDesiredLocked($vpc, 'acl_replace', $key, $requestHash);
return self::documentView($result['vpc'], $actor);
}, 3);
}
/**
* Send the latest desired document to the private engine VPC lane. The
* engine rejects it unless the referenced Fabric is active on every host,
* then applies/readbacks the private dataplane. No general VM-job or
* public-network mutation row is created here.
*/
public static function reconcile(string $vpcKey, array $actor, bool $allowDeferredRetry = false): array
{
$vpc = self::findOwned($vpcKey, $actor, true);
$claim = $vpc->getConnection()->transaction(function () use ($vpc, $allowDeferredRetry): ?array {
$locked = CloudVpc::where('id', $vpc->id)->lockForUpdate()->first();
if ($locked === null) {
throw new CloudError('VPC 不存在', 404);
}
$runtimeRetryableSync = in_array(
(string) $locked->sync_state, ['waiting', 'uncertain'], true
) || ((string) $locked->sync_state === 'applied'
&& in_array((string) ($locked->last_error_code ?? ''), [
'vpc_private_guest_shutdown_pending',
'vpc_private_guest_stopped',
], true));
$runtimeObservationPending = $allowDeferredRetry
&& (string) $locked->state === 'degraded'
&& $runtimeRetryableSync
&& (int) $locked->desired_revision === (int) $locked->observed_revision
&& self::digestMatches(
(string) $locked->desired_digest,
(string) $locked->observed_digest
);
$operation = CloudVpcOperation::where('vpc_id', $locked->id)
->where(function ($query) use (
$allowDeferredRetry, $runtimeObservationPending, $locked
): void {
$query->whereIn('status', $allowDeferredRetry
? ['queued', 'running', 'uncertain', 'waiting_observed']
: ['queued', 'running', 'uncertain']);
if ($allowDeferredRetry) {
// A definitive delete rejection stays fail-closed,
// but an explicit reconcile may retry the exact same
// operation after an operator repairs engine state.
$query->orWhere(function ($failed): void {
$failed->where('status', 'failed')
->where('kind', 'vpc_delete');
});
$query->orWhere(function ($legacy) use ($locked): void {
$legacy->where('status', 'succeeded')
->where('kind', '!=', 'vpc_delete')
->where('evidence_version', '<',
self::OBSERVATION_EVIDENCE_VERSION)
->where('operation_id',
(string) $locked->last_operation_id)
->where('desired_revision',
(int) $locked->desired_revision);
});
if ($runtimeObservationPending) {
// Member removal may already be durably committed
// while a surviving VM still lacks exact guest
// evidence. Re-run only this root's current,
// idempotent target until runtime proof catches up.
$query->orWhere(function ($runtime) use ($locked): void {
$runtime->where('status', 'succeeded')
->where('kind', '!=', 'vpc_delete')
->where('evidence_version', '>=',
self::OBSERVATION_EVIDENCE_VERSION)
->where('operation_id',
(string) $locked->last_operation_id)
->where('desired_revision',
(int) $locked->desired_revision);
});
}
}
})
->orderByDesc('desired_revision')->lockForUpdate()->first();
if ($operation === null) {
throw new CloudError('VPC 没有待核对的目标版本', 409);
}
// A newer mutation owns the VPC's desired state. A worker can
// still have selected an older row before that mutation committed;
// retire it here before it can replay stale routes or ACLs against
// the engine. touchDesiredLocked performs the same transition
// eagerly, while this guard also repairs rows created before the
// supersede rule was introduced.
if ((int) $operation->desired_revision !== (int) $locked->desired_revision
|| (string) $operation->operation_id !== (string) ($locked->last_operation_id ?? '')) {
$operation->status = 'superseded';
$operation->error_code = 'vpc_revision_superseded';
$operation->finished_at = $now = time();
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->updated_at = $now;
$operation->save();
return null;
}
$now = time();
// Runtime-only refreshes intentionally keep a completed operation
// terminal while borrowing its lease. The lease, rather than the
// status string, is therefore the concurrency boundary for both
// ordinary applies and background observation refreshes.
if ((int) $operation->lease_until > $now) {
return null;
}
$payload = json_decode((string) $operation->payload_json, true);
if (!is_array($payload)
|| ($payload['operation_id'] ?? null) !== (string) $operation->operation_id) {
$corruptAt = time();
$operation->status = 'failed';
$operation->error_code = 'vpc_operation_corrupt';
$operation->finished_at = $corruptAt;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->updated_at = $corruptAt;
$operation->save();
$locked->state = (string) $operation->kind === 'vpc_delete'
? 'deleting' : 'degraded';
$locked->sync_state = 'failed';
$locked->last_error_code = 'vpc_operation_corrupt';
$locked->last_failure_at = $corruptAt;
$locked->updated_at = $corruptAt;
$locked->save();
return null;
}
$runtimeProofRefresh = (string) $operation->status === 'succeeded'
&& (int) ($operation->evidence_version ?? 0)
>= self::OBSERVATION_EVIDENCE_VERSION;
if (!$runtimeProofRefresh) {
$operation->status = 'running';
$operation->finished_at = null;
}
$operation->lease_token = self::randomKey();
$operation->lease_until = $now + self::OPERATION_LEASE_SECONDS;
$operation->attempts = (int) $operation->attempts + 1;
$operation->updated_at = $now;
$operation->save();
return [$operation, $payload, $runtimeProofRefresh];
}, 3);
if ($claim === null) {
return self::show($vpcKey, $actor);
}
[$operation, $payload, $runtimeProofRefresh] = $claim;
$leaseToken = (string) $operation->lease_token;
try {
if ((string) $operation->kind === 'vpc_delete') {
$result = (new CloudEngineClient(
null, self::ENGINE_TIMEOUT_SECONDS
))->vpc(
'POST', '/internal/v1/vpcs/' . $vpcKey . '/delete',
$actor, $payload, (string) $operation->operation_id
);
$expectedRevision = (int) ($payload['desired_revision'] ?? 0);
$expectedDigest = (string) ($payload['desired_digest'] ?? '');
if (!is_array($result)
|| (string) ($result['vpc_id'] ?? '') !== $vpcKey
|| (string) ($result['operation_id'] ?? '')
!== (string) $operation->operation_id
|| (int) ($result['desired_revision'] ?? 0) !== $expectedRevision
|| !hash_equals($expectedDigest,
(string) ($result['desired_digest'] ?? ''))
|| ($result['deleted'] ?? false) !== true
|| (string) ($result['state'] ?? '') !== 'deleted'
|| (string) ($result['readback'] ?? '') !== 'confirmed'
|| !is_array($result['removed_host_ids'] ?? null)
|| !is_int($result['completed_at'] ?? null)
|| (int) $result['completed_at'] < 1) {
throw new CloudError('引擎 VPC 删除回执不完整,正在核对', 502);
}
self::recordDeleted(
$vpcKey, $expectedRevision, $expectedDigest, $result,
(string) $operation->operation_id, $leaseToken
);
return self::show($vpcKey, $actor);
}
$result = (new CloudEngineClient(
null, self::ENGINE_TIMEOUT_SECONDS
))->vpc('POST', '/internal/v1/vpcs/apply',
$actor, $payload, (string) $operation->operation_id);
$expectedRevision = (int) ($payload['desired_revision'] ?? 0);
$expectedDigest = (string) ($payload['desired_digest'] ?? '');
if (!is_array($result)
|| (string) ($result['operation_id'] ?? '')
!== (string) $operation->operation_id
|| (string) ($result['vpc_id'] ?? '')
!== (string) ($payload['vpc_id'] ?? '')
|| (int) ($result['desired_revision'] ?? 0) !== $expectedRevision
|| !hash_equals($expectedDigest, (string) ($result['desired_digest'] ?? ''))) {
throw new CloudError('引擎 VPC 结果与操作编号不一致,正在核对', 502);
}
$observed = is_array($result['observed'] ?? null) ? $result['observed'] : $result;
// Some engine versions expose a compact `observed` projection and
// the full typed host readback beside it. Merge the latter into
// the bounded projection before validating; never discard
// member_nics/routes/WireGuard evidence merely because the
// transport envelope used a compact view.
if (is_array($result['hosts'] ?? null)) {
if (!is_array($observed['hosts'] ?? null)) {
$observed['hosts'] = [];
}
foreach ($result['hosts'] as $hostKey => $hostItem) {
if (!is_array($hostItem)) {
continue;
}
$hostKey = (string) ($hostItem['host_id'] ?? $hostKey);
$compact = is_array($observed['hosts'][$hostKey] ?? null)
? $observed['hosts'][$hostKey] : [];
$observed['hosts'][$hostKey] = array_replace($compact, $hostItem);
}
}
if (isset($observed['operation_id'])
&& (string) $observed['operation_id'] !== (string) $operation->operation_id) {
throw new CloudError('引擎 VPC 观测与操作编号不一致,正在核对', 502);
}
if (isset($observed['vpc_id'])
&& (string) $observed['vpc_id'] !== (string) ($payload['vpc_id'] ?? '') ) {
throw new CloudError('引擎 VPC 观测目标不一致,正在核对', 502);
}
if (isset($observed['desired_revision'])
&& (int) $observed['desired_revision'] !== $expectedRevision) {
throw new CloudError('引擎 VPC 观测版本不一致,正在核对', 502);
}
if (isset($observed['desired_digest'])
&& !hash_equals($expectedDigest, (string) $observed['desired_digest'])) {
throw new CloudError('引擎 VPC 观测摘要不一致,正在核对', 502);
}
self::recordObserved($vpcKey, (int) ($payload['desired_revision'] ?? 0),
(string) ($payload['desired_digest'] ?? ''), $observed,
(string) $operation->operation_id, $leaseToken);
return self::show($vpcKey, $actor);
} catch (CloudError $error) {
$status = $error->httpStatus >= 500 ? 'uncertain' : 'failed';
$now = time();
$connection = (new CloudVpc())->getConnection();
$connection->transaction(function () use (
$operation, $leaseToken, $vpc, $status, $error, $now,
$runtimeProofRefresh
): void {
// Keep the lock order identical to every mutator: VPC root
// first, then its operation row. This also prevents an old
// lease from overwriting a newer desired revision.
$root = CloudVpc::where('id', $vpc->id)->lockForUpdate()->first();
if ($root === null) {
return;
}
$row = CloudVpcOperation::where('operation_id', (string) $operation->operation_id)
->where('status', $runtimeProofRefresh ? 'succeeded' : 'running')
->where('lease_token', $leaseToken)->lockForUpdate()->first();
if ($row === null) {
return;
}
if ($runtimeProofRefresh) {
// A runtime-only poll must not erase the last successful
// configuration proof when transport is temporarily
// unavailable. Release the lease and retry later.
$row->lease_token = null;
$row->lease_until = 0;
$row->updated_at = $now;
$row->save();
return;
}
$row->status = $status;
$row->error_code = self::safeErrorCode((string) ($error->errorCode ?? ''))
?? self::safeErrorCode($error->getMessage())
?? ($status === 'uncertain' ? 'vpc_result_uncertain' : 'vpc_apply_failed');
$row->updated_at = $now;
$row->finished_at = $status === 'failed' ? $now : null;
$row->lease_until = 0;
$row->save();
if ((string) $root->last_operation_id === (string) $row->operation_id
&& (int) $root->desired_revision === (int) $row->desired_revision) {
$root->state = (string) $row->kind === 'vpc_delete'
? 'deleting'
: ($status === 'uncertain' ? 'uncertain' : 'degraded');
$root->sync_state = $status === 'uncertain' ? 'uncertain' : 'failed';
$root->last_error_code = $row->error_code;
$root->last_failure_at = $now;
$root->updated_at = $now;
$root->save();
}
}, 3);
throw $error;
}
}
/** Finalize a root deletion only from an exact durable engine receipt. */
public static function recordDeleted(string $vpcKey, int $revision, string $digest,
array $receipt, string $operationId, ?string $leaseToken = null): void
{
self::assertKey($vpcKey, 'VPC');
if ($revision < 1 || preg_match('/^[a-f0-9]{64}$/D', $digest) !== 1
|| preg_match(self::KEY_PATTERN, $operationId) !== 1) {
throw new CloudError('VPC 删除回执版本无效', 502);
}
$connection = (new CloudVpc())->getConnection();
$connection->transaction(function () use (
$vpcKey, $revision, $digest, $receipt, $operationId, $leaseToken
): void {
$vpc = CloudVpc::where('vpc_key', $vpcKey)->lockForUpdate()->first();
if ($vpc === null) {
throw new CloudError('VPC 不存在', 404);
}
if ((string) $vpc->state !== 'deleting'
|| (int) $vpc->desired_revision !== $revision
|| !hash_equals((string) $vpc->desired_digest, $digest)
|| (string) $vpc->last_operation_id !== $operationId) {
throw new CloudError('VPC 删除回执不是当前目标版本', 409);
}
$operationQuery = CloudVpcOperation::where('operation_id', $operationId)
->where('vpc_id', $vpc->id)->where('kind', 'vpc_delete');
if ($leaseToken !== null) {
$operationQuery->where('lease_token', $leaseToken)
->where('status', 'running');
}
$operation = $operationQuery->lockForUpdate()->first();
if ($operation === null
|| (int) $operation->desired_revision !== $revision) {
throw new CloudError('VPC 删除操作记录不存在', 502);
}
$payload = json_decode((string) $operation->payload_json, true);
$currentDeleteDocument = self::deletionDocument($vpc);
$payloadDocument = is_array($payload) ? $payload : [];
unset($payloadDocument['operation_id'], $payloadDocument['desired_digest']);
if (!is_array($payload)
|| (string) ($payload['operation_id'] ?? '') !== $operationId
|| !hash_equals($digest,
(string) ($payload['desired_digest'] ?? ''))
|| !is_array($payload['hosts'] ?? null)
|| !is_array($payload['retiring_members'] ?? null)
|| self::canonicalJson($payloadDocument)
!== self::canonicalJson($currentDeleteDocument)
|| self::canonicalJson([
'retiring_members' => $payload['retiring_members'],
]) !== self::canonicalJson([
'retiring_members' => self::retiringMembersForDeletion($vpc),
])
|| !hash_equals($digest,
hash('sha256', self::canonicalJson($currentDeleteDocument)))) {
throw new CloudError('VPC 删除成员闭集与操作记录不一致', 409);
}
if ((string) ($receipt['vpc_id'] ?? '') !== $vpcKey
|| (string) ($receipt['operation_id'] ?? '') !== $operationId
|| (int) ($receipt['desired_revision'] ?? 0) !== $revision
|| !hash_equals($digest, (string) ($receipt['desired_digest'] ?? ''))
|| ($receipt['deleted'] ?? false) !== true
|| (string) ($receipt['state'] ?? '') !== 'deleted'
|| (string) ($receipt['readback'] ?? '') !== 'confirmed'
|| !is_int($receipt['completed_at'] ?? null)
|| (int) $receipt['completed_at'] < 1) {
throw new CloudError('VPC 删除回执身份不一致', 502);
}
$deployments = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->orderBy('host_id')->lockForUpdate()->get();
$historicalHostIds = $deployments->map(
static fn ($row): string => (string) $row->host_id
)->unique()->values()->all();
sort($historicalHostIds, SORT_STRING);
$pendingHostIds = $deployments->filter(
static fn ($row): bool => (string) $row->state !== 'deleted'
)->map(static fn ($row): string => (string) $row->host_id)
->unique()->values()->all();
sort($pendingHostIds, SORT_STRING);
$payloadHostIds = array_map(
static fn (array $host): string => (string) $host['host_id'],
$payload['hosts']
);
sort($payloadHostIds, SORT_STRING);
if ($payloadHostIds !== $pendingHostIds) {
throw new CloudError('VPC 删除待清宿主机闭集已变化', 409);
}
$removedHostIds = $receipt['removed_host_ids'] ?? null;
if (!is_array($removedHostIds) || !array_is_list($removedHostIds)) {
throw new CloudError('VPC 删除回执宿主机集合无效', 502);
}
foreach ($removedHostIds as $hostId) {
if (!is_string($hostId)
|| preg_match('/^[1-9][0-9]*$/D', $hostId) !== 1) {
throw new CloudError('VPC 删除回执宿主机集合无效', 502);
}
}
if (count($removedHostIds) !== count(array_unique($removedHostIds))) {
throw new CloudError('VPC 删除回执宿主机集合重复', 502);
}
$canonicalRemovedHostIds = $removedHostIds;
sort($canonicalRemovedHostIds, SORT_STRING);
if ($removedHostIds !== $canonicalRemovedHostIds
|| array_diff($payloadHostIds, $canonicalRemovedHostIds) !== []
|| array_diff($canonicalRemovedHostIds, $historicalHostIds) !== []) {
throw new CloudError('VPC 删除回执缺少待清宿主机证明或包含未知宿主机', 502);
}
$now = time();
foreach ([
CloudVpcSubnet::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcRoute::class,
CloudVpcAclRule::class,
] as $childModel) {
$rows = $childModel::where('vpc_id', $vpc->id)
->lockForUpdate()->get();
foreach ($rows as $row) {
if ((string) $row->state === 'deleted') {
continue;
}
if ((string) $row->state !== 'deleting') {
throw new CloudError('VPC 删除账本仍包含活动资源', 409);
}
}
}
foreach ($deployments as $deployment) {
if ((string) $deployment->state === 'deleted') {
// Preserve the revision/digest of the earlier exact
// absence proof when this engine receipt legitimately
// omits an already-retired historical host.
continue;
}
if ((string) $deployment->state !== 'deleting') {
throw new CloudError('VPC 删除账本仍包含活动宿主机', 409);
}
$deployment->observed_revision = $revision;
$deployment->observed_digest = $digest;
$deployment->state = 'deleted';
$deployment->last_error_code = null;
$deployment->last_success_at = $now;
$deployment->updated_at = $now;
$deployment->save();
}
$network = CloudPrivateNetwork::where(
'id', (int) $vpc->private_network_id
)->lockForUpdate()->first();
if ($network === null
|| !hash_equals((string) $network->vpc_key, $vpcKey)
|| (int) $network->user_id !== (int) $vpc->user_id
|| (int) $network->region_id !== (int) $vpc->region_id
|| (string) $network->cidr !== (string) $vpc->cidr
|| (string) ($network->active_cidr ?? '') !== (string) $vpc->cidr
|| !in_array((string) $network->state,
['active', 'applying', 'degraded', 'uncertain'], true)
|| (int) $network->revision < 1
|| preg_match(self::KEY_PATTERN,
(string) $network->allocation_key) !== 1) {
throw new CloudError('VPC 私网 CIDR 删除账本不一致', 409);
}
$released = CloudPrivateCidrAllocator::release(
(string) $network->allocation_key, (int) $network->revision
);
if ((int) $released->id !== (int) $network->id
|| (string) $released->state !== 'released'
|| $released->active_cidr !== null
|| (int) $released->revision !== (int) $network->revision + 1) {
throw new CloudError('VPC 私网 CIDR 未确认释放', 409);
}
// The signed operation payload is the durable deletion manifest
// and the engine receipt is the absence proof. Once both and the
// CIDR CAS are exact, remove child ledgers so their global unique
// keys (notably member.instance_id) cannot block a VM from
// joining a new VPC. Root, host deployments and operations remain
// as the idempotent audit tombstone.
foreach ([
CloudVpcRoute::class,
CloudVpcAclRule::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcSubnet::class,
] as $childModel) {
$childModel::where('vpc_id', $vpc->id)->delete();
}
$safeReceipt = [
'vpc_id' => $vpcKey,
'operation_id' => $operationId,
'desired_revision' => $revision,
'desired_digest' => $digest,
'state' => 'deleted',
'deleted' => true,
'readback' => 'confirmed',
'removed_host_ids' => $canonicalRemovedHostIds,
'completed_at' => (int) $receipt['completed_at'],
];
$operation->observed_json = json_encode($safeReceipt,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
$operation->evidence_version = self::OBSERVATION_EVIDENCE_VERSION;
$operation->status = 'succeeded';
$operation->error_code = null;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->finished_at = $now;
$operation->updated_at = $now;
$operation->save();
$vpc->observed_revision = $revision;
$vpc->observed_digest = $digest;
$vpc->state = 'deleted';
$vpc->sync_state = 'applied';
$vpc->last_error_code = null;
$vpc->last_success_at = $now;
$vpc->updated_at = $now;
$vpc->save();
}, 3);
}
/** Apply an exact engine observation and enforce the all-host gate. */
public static function recordObserved(string $vpcKey, int $revision, string $digest,
array $observed, string $operationId, ?string $leaseToken = null): void
{
self::assertKey($vpcKey, 'VPC');
if ($revision < 1 || preg_match('/^[a-f0-9]{64}$/D', $digest) !== 1
|| preg_match(self::KEY_PATTERN, $operationId) !== 1) {
throw new CloudError('VPC 观测版本无效', 502);
}
$connection = (new CloudVpc())->getConnection();
$connection->transaction(function () use (
$vpcKey, $revision, $digest, $observed, $operationId, $leaseToken
): void {
$vpc = CloudVpc::where('vpc_key', $vpcKey)->lockForUpdate()->first();
if ($vpc === null) {
throw new CloudError('VPC 不存在', 404);
}
if ((int) $vpc->desired_revision !== $revision
|| !hash_equals((string) $vpc->desired_digest, $digest)
|| (string) $vpc->last_operation_id !== $operationId) {
throw new CloudError('VPC 观测版本不是当前目标版本', 409);
}
// Validate the operation lease before touching any host or child
// evidence. A superseded worker must not be able to write a
// stale observation into the current revision.
$operationQuery = CloudVpcOperation::where('operation_id', $operationId)
->where('vpc_id', $vpc->id);
if ($leaseToken !== null) {
$operationQuery->where('lease_token', $leaseToken)
->where(function ($status): void {
$status->where('status', 'running')
->orWhere(function ($runtime): void {
$runtime->where('status', 'succeeded')
->where('evidence_version', '>=',
self::OBSERVATION_EVIDENCE_VERSION);
});
});
}
$operation = $operationQuery->lockForUpdate()->first();
if ($operation === null) {
throw new CloudError('VPC 操作记录不存在', 502);
}
$hosts = [];
foreach (is_array($observed['hosts'] ?? null) ? $observed['hosts'] : [] as $key => $item) {
if (!is_array($item)) {
continue;
}
$hostKey = (string) ($item['host_id'] ?? $key);
$hosts[$hostKey] = $item;
}
$evidenceVersion = max(0, (int) ($observed['evidence_version']
?? $observed['observation_version'] ?? 0));
$evidenceContractCurrent =
$evidenceVersion === self::OBSERVATION_EVIDENCE_VERSION;
// An older engine can report an otherwise exact host/libvirt
// observation without proving that the running guest consumed its
// address and routes. Preserve the receipt for audit, but close
// every activation gate and keep the same operation retryable.
if (!$evidenceContractCurrent) {
$observed['evidence_version'] = $evidenceVersion;
$observed['next_stage_allowed'] = false;
$observed['private_dataplane_verified'] = false;
foreach ($hosts as $hostKey => $item) {
$item['private_dataplane_verified'] = false;
$item['last_error_code'] = 'vpc_observation_contract_outdated';
$hosts[$hostKey] = $item;
}
$observed['hosts'] = $hosts;
}
// Validate typed tenant dataplane evidence before evaluating the
// all-host gate. Fabric transport alone can only leave this
// independent VPC lane waiting/uncertain.
$expectedMembersByHost = [];
$allExpectedMembers = [];
$expectedDestinations = [];
$expectedVpcCidr = null;
$desiredRoutes = [];
$desiredContractValid = true;
try {
$desired = self::desiredDocument($vpc);
$expectedVpcCidr = self::cidr(
$desired['cidr'] ?? null, 16, 24, 'VPC CIDR'
)['cidr'];
// The host adapter installs only member /32 routes and the
// explicitly configured VPC routes. The VPC/subnet CIDRs
// themselves are control-plane address ranges, not an
// allowance for a broad host route in the data plane.
foreach (is_array($desired['routes'] ?? null) ? $desired['routes'] : [] as $route) {
if (is_array($route) && isset($route['destination_cidr'])) {
$desiredRoutes[] = $route;
$expectedDestinations[] = (string) $route['destination_cidr'];
}
}
foreach (is_array($desired['members'] ?? null) ? $desired['members'] : [] as $member) {
if (!is_array($member) || !isset($member['member_id'])) {
continue;
}
$memberId = (string) $member['member_id'];
$memberHost = (string) ($member['host_id'] ?? '');
$member['private_mac'] = strtolower((string) ($member['private_mac'] ?? ''));
$expectedMembersByHost[$memberHost][$memberId] = $member;
$allExpectedMembers[$memberId] = $member;
if (isset($member['private_ip_cidr'])) {
$expectedDestinations[] = (string) $member['private_ip_cidr'];
}
}
} catch (\Throwable) {
// A malformed desired ledger is itself a closed gate.
$desiredContractValid = false;
$expectedMembersByHost = [];
$allExpectedMembers = [];
$expectedDestinations = [];
$expectedVpcCidr = null;
$desiredRoutes = [];
}
$expectedDestinations = array_values(array_unique(array_filter(
$expectedDestinations,
static fn ($value): bool => is_string($value) && $value !== ''
)));
$shutdownPendingMembers = [];
if ($allExpectedMembers !== []) {
$shutdownPendingMembers = array_fill_keys(
CloudVpcMember::where('vpc_id', $vpc->id)
->where('state', 'stopping')
->whereIn('member_key', array_keys($allExpectedMembers))
->pluck('member_key')->map(
static fn ($value): string => (string) $value
)->all(),
true
);
}
$memberGuestEvidence = [];
foreach ($hosts as $hostKey => $item) {
$localExpectedMembers =
$expectedMembersByHost[(string) $hostKey] ?? [];
$configError = $evidenceContractCurrent && $desiredContractValid
? self::validateHostDataplaneEvidence(
$item,
(string) $hostKey,
$localExpectedMembers,
array_values($allExpectedMembers),
$expectedDestinations,
(string) $expectedVpcCidr,
$desiredRoutes,
$vpcKey,
$revision,
$digest,
false
)
: ($evidenceContractCurrent
? 'vpc_private_readback_mismatch'
: 'vpc_observation_contract_outdated');
$item['config_evidence_verified'] = $configError === null;
if ($configError !== null) {
$item['last_error_code'] = $configError;
}
if (($item['private_dataplane_verified'] ?? false) === true) {
$errorCode = $evidenceContractCurrent && $desiredContractValid
? self::validateHostDataplaneEvidence(
$item,
(string) $hostKey,
$localExpectedMembers,
array_values($allExpectedMembers),
$expectedDestinations,
(string) $expectedVpcCidr,
$desiredRoutes,
$vpcKey,
$revision,
$digest
)
: ($evidenceContractCurrent
? 'vpc_private_readback_mismatch'
: 'vpc_observation_contract_outdated');
if ($errorCode !== null) {
$item['private_dataplane_verified'] = false;
$item['last_error_code'] = $errorCode;
$observed['private_dataplane_verified'] = false;
} elseif (($item['removed'] ?? false) === true) {
$item['removal_verified'] = true;
}
} elseif ($configError === null
&& !is_string($item['last_error_code'] ?? null)) {
$item['last_error_code'] = 'vpc_private_guest_probe_uncertain';
}
if (($item['removed'] ?? false) === true && $configError === null) {
$item['removal_verified'] = true;
}
// Host configuration can be exact while only a subset of its
// running guests has consumed that configuration. Preserve
// one proof result per member; aggregate host/root readiness
// is evaluated separately below.
if ($configError === null
&& ($item['transport_verified'] ?? false) === true
&& ($item['removed'] ?? false) !== true
&& is_array($item['member_nics'] ?? null)) {
foreach ($item['member_nics'] as $nic) {
if (!is_array($nic)) {
continue;
}
$memberId = (string) ($nic['member_id'] ?? '');
$expectedMember = $localExpectedMembers[$memberId] ?? null;
if (!is_array($expectedMember)) {
continue;
}
$memberError = self::validateMemberNicEvidence(
$nic,
$expectedMember,
(string) $expectedVpcCidr,
true
);
$intentionalSuspended = ($nic['xml_verified'] ?? false) === true
&& ($nic['config_verified'] ?? false) === true
&& ($nic['seed_verified'] ?? false) === true
&& ($nic['domain_running'] ?? false) === true
&& ($nic['restart_required'] ?? null) === false
&& ($nic['link_state'] ?? null) === 'down';
$intentionalStopped = ($nic['xml_verified'] ?? false) === true
&& ($nic['config_verified'] ?? false) === true
&& ($nic['seed_verified'] ?? false) === true
&& ($nic['domain_running'] ?? null) === false
&& ($nic['restart_required'] ?? null) === false
&& in_array(($nic['link_state'] ?? null),
['up', 'down'], true);
$intentionalStopping = isset(
$shutdownPendingMembers[$memberId]
) && !$intentionalStopped
&& ($nic['xml_verified'] ?? false) === true
&& ($nic['config_verified'] ?? false) === true
&& ($nic['seed_verified'] ?? false) === true
&& ($nic['restart_required'] ?? null) === false
&& in_array(($nic['link_state'] ?? null),
['up', 'down'], true);
// Retain the exact shape used to classify this member.
// In particular, a generic probe/link failure must not
// be able to masquerade as an intentional suspension.
$memberGuestEvidence[$memberId] = [
'state' => $intentionalStopped ? 'stopped'
: ($intentionalStopping ? 'stopping'
: ($intentionalSuspended ? 'suspended'
: ($memberError === null ? 'active' : 'degraded'))),
'error_code' => $intentionalStopped
? 'vpc_private_guest_stopped'
: ($intentionalStopping
? 'vpc_private_guest_shutdown_pending'
: ($intentionalSuspended
? 'vpc_private_network_suspended'
: ($memberError === null ? null
: (self::deferredEvidenceError($memberError)
?? 'vpc_private_observation_mismatch')))),
'xml_verified' => ($nic['xml_verified'] ?? false) === true,
'config_verified' =>
($nic['config_verified'] ?? false) === true,
'seed_verified' =>
($nic['seed_verified'] ?? false) === true,
'domain_running' =>
($nic['domain_running'] ?? false) === true,
'restart_required' => $nic['restart_required'] ?? null,
'link_state' => is_string($nic['link_state'] ?? null)
? (string) $nic['link_state'] : null,
'guest_network_verified' =>
($nic['guest_network_verified'] ?? false) === true,
'guest_network_readback' => is_string(
$nic['guest_network_readback'] ?? null
) ? (string) $nic['guest_network_readback'] : null,
'guest_link_state' => is_string(
$nic['guest_link_state'] ?? null
) ? (string) $nic['guest_link_state'] : null,
'guest_exact' => $memberError === null,
];
}
$localSuspended = false;
$localStopping = false;
$localStopped = false;
$localUnresolved = false;
foreach ($localExpectedMembers as $localMemberId => $_localMember) {
$localRuntime = $memberGuestEvidence[
(string) $localMemberId
] ?? null;
$localState = is_array($localRuntime)
? (string) ($localRuntime['state'] ?? '') : '';
if ($localState === 'suspended') {
$localSuspended = true;
} elseif ($localState === 'stopping') {
$localStopping = true;
} elseif ($localState === 'stopped') {
$localStopped = true;
} elseif ($localState !== 'active') {
$localUnresolved = true;
}
}
if (!$localUnresolved) {
if ($localStopped) {
$item['last_error_code'] =
'vpc_private_guest_stopped';
} elseif ($localStopping) {
$item['last_error_code'] =
'vpc_private_guest_shutdown_pending';
} elseif ($localSuspended) {
$item['last_error_code'] =
'vpc_private_network_suspended';
}
}
}
$hosts[$hostKey] = $item;
$observedHosts = is_array($observed['hosts'] ?? null)
? $observed['hosts'] : [];
$observedHosts[$hostKey] = $item;
$observed['hosts'] = $observedHosts;
}
$deployments = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->lockForUpdate()->get()->keyBy(static fn ($row): int => (int) $row->host_id);
$required = $deployments->filter(static fn ($row): bool =>
(string) $row->state !== 'deleted');
// A per-host removal proof is monotonic. Keep terminal deployment
// rows available while validating a retry or the next revision so
// an engine may either omit the already-removed host or echo its
// exact typed absence proof. A host absent from both collections
// remains an unknown-host failure.
$knownDeletedDeployments = $deployments->filter(static fn ($row): bool =>
(string) $row->state === 'deleted');
$observedRevision = (int) ($observed['revision']
?? $observed['observed_revision'] ?? 0);
$observedDigest = (string) ($observed['digest']
?? $observed['observed_digest'] ?? '');
$privateDataplaneVerified = ($observed['private_dataplane_verified']
?? false) === true;
$globalActive = $evidenceContractCurrent
&& ($observed['state'] ?? null) === 'active'
&& ($observed['next_stage_allowed'] ?? false) === true
&& $privateDataplaneVerified
&& $observedRevision === $revision
&& hash_equals($digest, $observedDigest);
$pendingHostTombstone = $required->contains(static fn ($row): bool =>
(string) $row->state === 'deleting');
$fabricGate = is_array($observed['fabric_gate'] ?? null)
? $observed['fabric_gate'] : [];
// An empty VPC is a valid tenant reservation, but there is no
// host operation to retry until a member is attached. Treat
// these two gate results as terminal for this revision; a later
// member mutation creates a new desired revision and operation.
$gateError = (string) ($fabricGate['error_code'] ?? '');
$terminalGate = in_array($gateError, [
'vpc_no_members', 'vpc_no_participating_hosts',
], true)
&& ($fabricGate['active'] ?? null) === false
&& ($observed['next_stage_allowed'] ?? null) === false
&& ($observed['private_dataplane_verified'] ?? null) === false;
$dataPlaneDeferred = !$terminalGate
&& ($fabricGate['active'] ?? false) === true
&& ($observed['next_stage_allowed'] ?? true) === false
&& $required->count() > 0
&& $hosts !== []
&& count($hosts) === $required->count();
if ($dataPlaneDeferred) {
foreach ($hosts as $hostKey => $_item) {
if (!$required->has((int) $hostKey)) {
$dataPlaneDeferred = false;
break;
}
}
}
if ($dataPlaneDeferred) {
foreach ($required as $hostId => $_deployment) {
$item = $hosts[(string) $hostId] ?? null;
if (!is_array($item)
|| !in_array((string) ($item['state'] ?? ''), ['applying', 'active'], true)
|| ($item['transport_verified'] ?? false) !== true) {
$dataPlaneDeferred = false;
break;
}
}
}
$liveRequired = $required->filter(static fn ($row): bool =>
(string) $row->state !== 'deleting');
// A Fabric or host control-plane digest cannot prove that a
// deleting private interface/address is gone. The engine reaches
// an exact host observation only after consuming every durable
// retiring-member row and reading back the current libvirt/XML,
// route, WireGuard and nft state. Subnets have no independent
// host object, but still wait for this same revision boundary (or
// the explicit no-host terminal proof below).
$pendingChildTombstone = false;
foreach ([
CloudVpcSubnet::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcRoute::class,
CloudVpcAclRule::class,
] as $childModel) {
if ($childModel::where('vpc_id', $vpc->id)
->where('state', 'deleting')->exists()) {
$pendingChildTombstone = true;
break;
}
}
$allActive = false;
// Evaluate one closed host set for this revision. A required host
// is exact when it either reports the current active data plane or,
// for a deleting deployment, the typed positive removal proof.
// In particular, a retiring host must not make a still-live sibling
// inexact merely because both appear in the same operation.
$allRequiredHostsExact = $required->count() > 0;
$allRequiredHostsConfigExact = $required->count() > 0;
$allRemovalProof = true;
$hasRemovalTarget = false;
$currentConfigExactHostIds = [];
$onlyKnownDeletedHostEvidence = true;
$exactRemovalEvidence = static function ($item) use ($revision, $digest): bool {
return is_array($item)
&& ($item['removed'] ?? false) === true
&& ($item['removal_verified'] ?? false) === true
&& ($item['state'] ?? null) === 'active'
&& ($item['transport_verified'] ?? false) === true
&& ($item['private_dataplane_verified'] ?? false) === true
&& (int) ($item['observed_revision'] ?? $item['revision'] ?? 0) === $revision
&& hash_equals($digest, (string) (
$item['observed_digest'] ?? $item['digest'] ?? ''
));
};
foreach ($hosts as $hostKey => $item) {
if ($required->has((int) $hostKey)) {
$onlyKnownDeletedHostEvidence = false;
continue;
}
$knownDeleted = $knownDeletedDeployments->get((int) $hostKey);
if ($knownDeleted === null || !$exactRemovalEvidence($item)) {
$allRequiredHostsExact = false;
$allRequiredHostsConfigExact = false;
$onlyKnownDeletedHostEvidence = false;
continue;
}
// Refresh an optional historical proof when the engine echoes
// a current-revision typed absence record. Missing echoes are
// also valid; contradictory/inexact echoes close the gate but
// never erase the last monotonic proof.
$knownDeleted->desired_revision = $revision;
$knownDeleted->observed_revision = $revision;
$knownDeleted->desired_digest = $digest;
$knownDeleted->observed_digest = $digest;
$knownDeleted->last_error_code = null;
$knownDeleted->last_success_at = time();
$knownDeleted->updated_at = time();
$knownDeleted->save();
}
$hostEvidence = [];
foreach ($required as $hostId => $deployment) {
$item = $hosts[(string) $hostId] ?? null;
$deleting = (string) $deployment->state === 'deleting';
if ($deleting) {
$hasRemovalTarget = true;
}
if (!is_array($item)) {
$allRequiredHostsExact = false;
$allRequiredHostsConfigExact = false;
if ($deleting) {
// A missing deleting host is failed removal proof,
// not an absent target. Without this assignment a
// second host's valid receipt could incorrectly make
// a partial multi-host teardown look complete.
$allRemovalProof = false;
}
// A deleting host remains a tombstone until an exact
// desired revision proves that the empty-host target was
// accepted. Converting it to uncertain would make a
// later retry lose the removal intent.
if ((string) $deployment->state !== 'deleting') {
$deployment->state = 'uncertain';
}
$deployment->last_error_code = 'vpc_host_observation_missing';
$deployment->last_failure_at = time();
$deployment->updated_at = time();
$deployment->save();
continue;
}
$itemRevision = (int) ($item['observed_revision'] ?? $item['revision'] ?? 0);
$itemDigest = (string) ($item['observed_digest'] ?? $item['digest'] ?? '');
$itemError = self::deferredEvidenceError(
$item['last_error_code'] ?? null
);
$active = ($item['state'] ?? null) === 'active'
&& ($item['transport_verified'] ?? false) === true
&& ($item['private_dataplane_verified'] ?? false) === true
&& ($item['removed'] ?? false) !== true
&& $itemRevision <= $revision
&& $itemRevision === $revision && hash_equals($digest, $itemDigest);
$configActive = !$deleting
&& ($item['config_evidence_verified'] ?? false) === true
&& ($item['transport_verified'] ?? false) === true
&& ($item['removed'] ?? false) !== true
&& (int) ($item['config_observed_revision'] ?? 0) === $revision
&& hash_equals($digest,
(string) ($item['config_observed_digest'] ?? ''));
$removalActive = $deleting
&& ($item['removed'] ?? false) === true
&& ($item['removal_verified'] ?? false) === true
&& ($item['state'] ?? null) === 'active'
&& ($item['transport_verified'] ?? false) === true
&& ($item['private_dataplane_verified'] ?? false) === true
&& $itemRevision === $revision
&& hash_equals($digest, $itemDigest);
if ($deleting) {
if (!$removalActive) {
$allRemovalProof = false;
}
}
if (($deleting && !$removalActive) || (!$deleting && !$active)) {
$allRequiredHostsExact = false;
}
if (($deleting && !$removalActive)
|| (!$deleting && !$configActive)) {
$allRequiredHostsConfigExact = false;
}
if (!$deleting && $configActive) {
$currentConfigExactHostIds[(int) $hostId] = true;
}
$hostEvidence[(int) $hostId] = [
'active' => $active,
'config_active' => $configActive,
'removal_active' => $removalActive,
'revision' => $itemRevision,
'digest' => $itemDigest,
'last_error_code' => $itemError,
];
}
// Persist each exact removal proof monotonically even when another
// host is still missing. Child identity rows remain gated by the
// complete host closure below, while a later retry can reuse this
// host's stored proof without requiring the removed host online.
foreach ($required as $hostId => $deployment) {
$evidence = $hostEvidence[(int) $hostId] ?? null;
if (!is_array($evidence)) {
continue;
}
$active = ($evidence['active'] ?? false) === true;
$removalActive = ($evidence['removal_active'] ?? false) === true;
$deleting = (string) $deployment->state === 'deleting';
$itemRevision = (int) ($evidence['revision'] ?? 0);
$itemDigest = (string) ($evidence['digest'] ?? '');
$configActive = ($evidence['config_active'] ?? false) === true;
$deployment->observed_revision = $configActive
? $revision : $itemRevision;
$deployment->observed_digest = $configActive
? $digest : ($itemDigest !== '' ? $itemDigest : null);
// An empty-host target is only a desired control-plane
// document. Without a data-plane removal readback, preserve
// the deleting state even when the Fabric digest is exact.
if ($deleting && $removalActive) {
$deployment->state = 'deleted';
$deployment->last_error_code = null;
} elseif (!$deleting) {
$hostError = is_string($evidence['last_error_code'] ?? null)
? (string) $evidence['last_error_code'] : null;
$deployment->state = $active ? 'active' : 'degraded';
$deployment->last_error_code = $active ? null
: ($hostError ?? 'vpc_host_observation_mismatch');
} else {
$deployment->last_error_code = $removalActive
? 'vpc_observation_incomplete'
: 'vpc_host_removal_unverified';
}
$deployment->updated_at = time();
if ($active || $removalActive) {
$deployment->last_success_at = time();
} else {
$deployment->last_failure_at = time();
}
$deployment->save();
}
// A deleted row is useful only while it retains a complete exact
// absence proof. Validate the whole historical host ledger, not
// only the owner of the member being released: any stale host may
// still carry route/proxy/WireGuard state for the old address.
$allKnownDeletedProofValid = $knownDeletedDeployments->every(
static fn ($deployment): bool =>
self::hostDeploymentRemovalProven($deployment)
);
if (!$allKnownDeletedProofValid) {
$allRequiredHostsExact = false;
$allRequiredHostsConfigExact = false;
}
// A terminal no-members/no-participating-hosts response is a
// positive control-plane proof only when this revision has no
// host deployment left to remove. In that case no host-side
// route or nft object can still be owned by this VPC, so route,
// ACL and an unreferenced subnet tombstone may converge without
// pretending that a private NIC, address or member was removed.
// Keep the proof in the operation audit.
$noDataPlaneTerminalProof = $evidenceContractCurrent && $terminalGate
&& $required->count() === 0
&& $liveRequired->count() === 0
&& ($hosts === [] || $onlyKnownDeletedHostEvidence)
&& $allKnownDeletedProofValid
&& !$pendingHostTombstone;
// A newly reserved VPC deliberately has no participating host until
// its first member is attached. The current engine evidence can
// therefore complete only the control-plane reservation, never the
// private data plane. Capture the original child-tombstone gate
// before the generic terminal-proof cleanup below; a malformed
// create ledger must not become successful merely because a route
// or ACL tombstone was closed while processing the observation.
$emptyAutomaticSubnetValid = false;
if ($noDataPlaneTerminalProof
&& (string) $operation->kind === 'vpc_create'
&& $desiredContractValid) {
try {
$emptyAutomaticSubnet = self::lockedAutomaticSubnet($vpc);
$emptyAutomaticSubnetValid =
(int) $emptyAutomaticSubnet->desired_revision === $revision
&& self::digestMatches(
(string) $emptyAutomaticSubnet->desired_digest,
$digest
);
} catch (\Throwable) {
$emptyAutomaticSubnetValid = false;
}
}
$emptyCreateLedgerValid = $desiredContractValid
&& is_array($desired ?? null)
&& (int) ($desired['desired_revision'] ?? 0) === $revision
&& ($desired['hosts'] ?? null) === []
&& ($desired['members'] ?? null) === []
&& ($desired['routes'] ?? null) === []
&& ($desired['acls'] ?? null) === []
&& is_array($desired['subnets'] ?? null)
&& count($desired['subnets']) === 1
&& $emptyAutomaticSubnetValid
&& self::digestMatches(
$digest,
hash('sha256', self::canonicalJson($desired))
)
&& !CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists()
&& !CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists()
&& !CloudVpcRoute::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists()
&& !CloudVpcAclRule::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists();
$emptyControlPlaneComplete = $noDataPlaneTerminalProof
&& (string) $operation->kind === 'vpc_create'
&& $emptyCreateLedgerValid
&& !$pendingChildTombstone;
$terminalSubnetReleased = 0;
$storedMemberRemovalReleased = 0;
$configMemberRemovalReleased = 0;
if ($noDataPlaneTerminalProof) {
$observed['no_data_plane_terminal_proof'] = [
'revision' => $revision,
'digest' => $digest,
'gate' => $gateError,
];
$observedAt = time();
foreach ([CloudVpcRoute::class, CloudVpcAclRule::class] as $childModel) {
$childModel::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)
->where('state', 'deleting')
->update([
'observed_revision' => $revision,
'observed_digest' => $digest,
'state' => 'deleted',
'last_error_code' => null,
'updated_at' => $observedAt,
]);
}
// A subnet is only a control-plane address range. Historical
// subnet-removal operations were admitted only after proving
// no live member or lease, so an empty-VPC terminal gate is
// sufficient absence proof. Never
// extend this branch to member/private-IP tombstones: those
// still require libvirt removal readback from a host.
if ((string) $operation->kind === 'member_detach') {
// A previous partial response may already have persisted
// every owner host's exact absence proof while the global
// child gate stayed incomplete. The terminal response is
// not NIC proof; it merely confirms there is no live host
// left. Release deleting pairs only from those stored,
// individually validated owner proofs.
$storedMemberRemovalReleased = self::releaseMemberTombstones(
$vpc, $revision, $digest, true, []
);
} elseif ((string) $operation->kind === 'subnet_remove') {
// A previously proven terminal member/lease pair may have
// survived an older worker version and still occupy the
// subnet's unique keys. Garbage-collect only `deleted`
// pairs whose owner deployment retains an exact removal
// proof; never release a merely `deleting` pair here.
self::releaseMemberTombstones(
$vpc, $revision, $digest, false, []
);
$terminalSubnetReleased = self::releaseSubnetTombstones(
$vpc, $revision, $digest
);
}
}
// Routes and ACLs are part of the exact host dataplane digest.
// Close their tombstones only after every required live host was
// individually matched above; a top-level active envelope with a
// missing or mismatched host must remain fail-closed.
if ($allRequiredHostsConfigExact && $allRemovalProof) {
$observedAt = time();
foreach ([CloudVpcRoute::class, CloudVpcAclRule::class] as $childModel) {
$childModel::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)
->where('state', 'deleting')
->update([
'observed_revision' => $revision,
'observed_digest' => $digest,
'state' => 'deleted',
'last_error_code' => null,
'updated_at' => $observedAt,
]);
}
// Host exactness is the commit boundary for libvirt NIC
// teardown. Physically release member/address identity rows
// so their global unique keys can be reused; the operation's
// bounded observed_json remains the durable audit record.
$configMemberRemovalReleased = self::releaseMemberTombstones(
$vpc, $revision, $digest, true, $currentConfigExactHostIds
);
self::releaseSubnetTombstones($vpc, $revision, $digest);
}
// Re-read after route/ACL closure so their former tombstones do
// not keep an otherwise exact VPC in degraded state.
$pendingChildTombstone = false;
foreach ([
CloudVpcSubnet::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcRoute::class,
CloudVpcAclRule::class,
] as $childModel) {
if ($childModel::where('vpc_id', $vpc->id)
->where('state', 'deleting')->exists()) {
$pendingChildTombstone = true;
break;
}
}
$allMemberRuntimeActive = $allExpectedMembers !== [];
foreach ($allExpectedMembers as $memberId => $_expectedMember) {
if ((string) ($memberGuestEvidence[(string) $memberId]['state'] ?? '')
!== 'active') {
$allMemberRuntimeActive = false;
break;
}
}
$allActive = $globalActive && $allRequiredHostsExact && $allRemovalProof
&& $liveRequired->count() > 0
&& $allMemberRuntimeActive
&& !$pendingChildTombstone;
$configurationComplete = $allRequiredHostsConfigExact
&& $allRemovalProof && $liveRequired->count() > 0
&& !$pendingChildTombstone;
$removalOnlyComplete = $hasRemovalTarget && $allRemovalProof
&& $allRequiredHostsExact && $liveRequired->count() === 0
&& !$pendingChildTombstone;
$terminalSubnetComplete = $noDataPlaneTerminalProof
&& (string) $operation->kind === 'subnet_remove'
&& $terminalSubnetReleased > 0 && !$pendingChildTombstone;
$storedMemberRemovalComplete = $noDataPlaneTerminalProof
&& (string) $operation->kind === 'member_detach'
&& $storedMemberRemovalReleased > 0 && !$pendingChildTombstone;
$configMemberRemovalComplete =
(string) $operation->kind === 'member_detach'
&& $configMemberRemovalReleased > 0
&& $allRequiredHostsConfigExact && $allRemovalProof
&& !$pendingChildTombstone;
// Once the detach mutation has advanced the root to this exact
// revision, later runtime-only retries must not reopen or repeat
// the already released member/IP tombstone. They keep the same
// operation terminal while retrying guest evidence for siblings.
$memberDetachPreviouslyCommitted =
(string) $operation->kind === 'member_detach'
&& (int) $vpc->observed_revision === $revision
&& self::digestMatches($digest, (string) $vpc->observed_digest)
&& !$pendingChildTombstone;
$operationPreviouslySucceeded =
(string) $operation->status === 'succeeded'
&& (int) ($operation->evidence_version ?? 0)
>= self::OBSERVATION_EVIDENCE_VERSION
&& (int) $vpc->observed_revision === $revision
&& self::digestMatches($digest, (string) $vpc->observed_digest);
$operationSucceeded = $configurationComplete || $allActive
|| $removalOnlyComplete
|| $emptyControlPlaneComplete
|| $terminalSubnetComplete || $storedMemberRemovalComplete
|| $configMemberRemovalComplete || $memberDetachPreviouslyCommitted
|| $operationPreviouslySucceeded;
// A reviewed guest reason is diagnostic evidence even when the
// outer engine envelope chose `degraded` instead of `applying`.
// Derive it solely from the per-host closed set; mixed reasons
// intentionally collapse to the generic control-plane code.
$deferredError = self::singleDeferredEvidenceError($hostEvidence);
$hasUnresolvedMemberEvidence = false;
$hasSuspendedMemberEvidence = false;
$hasStoppingMemberEvidence = false;
$hasStoppedMemberEvidence = false;
foreach ($allExpectedMembers as $memberId => $_expectedMember) {
$runtimeEvidence = $memberGuestEvidence[(string) $memberId] ?? null;
$runtimeState = is_array($runtimeEvidence)
? (string) ($runtimeEvidence['state'] ?? '') : '';
if (!in_array(
$runtimeState, ['active', 'suspended', 'stopping', 'stopped'], true
)) {
$hasUnresolvedMemberEvidence = true;
} elseif ($runtimeState === 'suspended') {
$hasSuspendedMemberEvidence = true;
} elseif ($runtimeState === 'stopping') {
$hasStoppingMemberEvidence = true;
} elseif ($runtimeState === 'stopped') {
$hasStoppedMemberEvidence = true;
}
}
$runtimeObservationPending = $operationSucceeded
&& $configurationComplete
&& $liveRequired->count() > 0 && !$allActive
&& ($hasUnresolvedMemberEvidence || $hasStoppingMemberEvidence
|| $hasStoppedMemberEvidence);
$intentionalRuntimeSuspended = $operationSucceeded
&& $configurationComplete && !$allActive
&& !$hasUnresolvedMemberEvidence && !$hasStoppingMemberEvidence
&& !$hasStoppedMemberEvidence
&& $hasSuspendedMemberEvidence;
$configurationObservationUncertain = $operationPreviouslySucceeded
&& !$configurationComplete && $liveRequired->count() > 0;
// A no-members Fabric gate is terminal only after the database has
// no unresolved host deployment. While a deleting host still
// needs its SSH/libvirt proof, keep the operation retryable instead
// of freezing the tombstone in a finished `failed` row.
$terminalFailure = $terminalGate && $noDataPlaneTerminalProof
&& !$emptyControlPlaneComplete;
// The engine's current observed contract is host-scoped: an
// active exact digest means the complete typed document for this
// revision was accepted by every participating host. Mirror that
// gate onto live child rows. Deletion tombstones intentionally
// remain untouched until a typed removal readback proves absence.
if ($configurationComplete || $allActive) {
$observedAt = time();
// Subnets, routes and ACLs are host configuration. Members
// and leases are advanced separately from their own exact
// guest proof below; one stopped VM cannot revoke a ready
// sibling's runtime evidence.
foreach ([
CloudVpcSubnet::class,
CloudVpcRoute::class,
CloudVpcAclRule::class,
] as $childModel) {
$childModel::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)
->whereNotIn('state', ['deleting', 'deleted'])
->update([
'observed_revision' => $revision,
'observed_digest' => $digest,
'state' => 'active',
'last_error_code' => null,
'updated_at' => $observedAt,
]);
}
self::persistMemberGuestEvidence(
$vpc,
$revision,
$digest,
$operationId,
$allExpectedMembers,
$memberGuestEvidence,
$observedAt
);
} elseif ($emptyControlPlaneComplete) {
// This exact revision proves only the PHP-owned address-range
// reservation. Route and ACL rows are host configuration and
// must never become active without an exact host readback.
CloudVpcSubnet::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)
->whereNotIn('state', ['deleting', 'deleted'])
->update([
'observed_revision' => $revision,
'observed_digest' => $digest,
'state' => 'active',
'last_error_code' => null,
'updated_at' => time(),
]);
} elseif ($terminalSubnetComplete) {
// No host exists to observe an unchanged address range. The
// terminal no-data-plane proof is nevertheless exact for the
// subnet-only mutation and may advance the remaining subnet
// rows with the root operation.
CloudVpcSubnet::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)
->whereNotIn('state', ['deleting', 'deleted'])
->update([
'observed_revision' => $revision,
'observed_digest' => $digest,
'state' => 'active',
'last_error_code' => null,
'updated_at' => time(),
]);
}
$operation->observed_json = json_encode(self::boundedObserved($observed),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
$operation->evidence_version = $evidenceContractCurrent
? self::OBSERVATION_EVIDENCE_VERSION : 0;
$operation->status = $operationSucceeded ? 'succeeded'
: ($dataPlaneDeferred ? 'waiting_observed'
: ($terminalFailure ? 'failed' : 'uncertain'));
$operation->error_code = $operationSucceeded ? null
: ($dataPlaneDeferred ? ($deferredError ?? 'vpc_data_plane_deferred')
: ($terminalFailure ? $gateError : 'vpc_observation_incomplete'));
$operation->updated_at = time();
$operation->finished_at = ($operationSucceeded || $dataPlaneDeferred || $terminalFailure)
? time() : null;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->save();
$vpc->observed_revision = $operationSucceeded ? $revision : (int) $vpc->observed_revision;
$vpc->observed_digest = $operationSucceeded ? $digest : $vpc->observed_digest;
// Completing a control-plane-only empty-VPC mutation does not make
// a tenant data plane active. It may advance the exact desired
// revision and finish the operation, but stays degraded/unusable
// until a live member host passes the Fabric gate.
$vpc->state = $operationSucceeded && $allActive ? 'active' : 'degraded';
$vpc->sync_state = $operationSucceeded
? ($configurationObservationUncertain ? 'uncertain'
: ($runtimeObservationPending ? 'waiting' : 'applied'))
: ($dataPlaneDeferred ? 'waiting' : ($terminalFailure ? 'failed' : 'uncertain'));
$vpc->last_error_code = $operationSucceeded
? (($runtimeObservationPending || $configurationObservationUncertain)
? ($deferredError ?? 'vpc_data_plane_deferred')
: ($intentionalRuntimeSuspended
? 'vpc_private_network_suspended' : null))
: ($dataPlaneDeferred ? ($deferredError ?? 'vpc_data_plane_deferred')
: ($terminalFailure ? $gateError : 'vpc_observation_incomplete'));
$vpc->last_success_at = $operationSucceeded ? time() : (int) $vpc->last_success_at;
$vpc->last_failure_at = $operationSucceeded ? (int) $vpc->last_failure_at : time();
$vpc->updated_at = time();
$vpc->save();
}, 3);
}
/** Build the exact typed document signed into a VPC operation. */
public static function desiredDocument(CloudVpc $vpc): array
{
$subnets = CloudVpcSubnet::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted', 'deleting'])->orderBy('subnet_key')->get();
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted', 'deleting'])->orderBy('member_key')->get();
$routes = CloudVpcRoute::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted', 'deleting'])->orderBy('route_key')->get();
$acl = CloudVpcAclRule::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted', 'deleting'])->orderBy('priority')->orderBy('rule_key')->get();
$region = CloudRegion::where('id', (int) $vpc->region_id)->first();
$fabricRegion = (string) ($vpc->fabric_region ?? '');
if ($region === null || $fabricRegion === ''
|| preg_match('/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/D', $fabricRegion) !== 1) {
throw new CloudError('VPC 地区记录缺失,无法生成引擎目标', 503);
}
$subnetKeys = [];
foreach ($subnets as $row) {
$subnetKeys[(int) $row->id] = (string) $row->subnet_key;
}
$instanceIds = $members->pluck('instance_id')->map(static fn ($id): int => (int) $id)
->unique()->values()->all();
$instances = $instanceIds === [] ? [] : CloudInstance::whereIn('id', $instanceIds)
->get()->keyBy('id');
$privateIpRows = $members->isEmpty() ? [] : CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('member_id', $members->pluck('id')->map(static fn ($id): int => (int) $id)->all())
->get()->keyBy('member_id');
$memberKeys = [];
$privateMacs = [];
$memberRows = [];
foreach ($members as $row) {
$instance = $instances[(int) $row->instance_id] ?? null;
$subnetKey = $subnetKeys[(int) $row->subnet_id] ?? null;
$privateIp = $privateIpRows[(int) $row->id] ?? null;
if ($instance === null || $subnetKey === null || $privateIp === null
|| (int) $row->private_ip_id !== (int) $privateIp->id
|| (int) $privateIp->subnet_id !== (int) $row->subnet_id
|| (int) $privateIp->instance_id !== (int) $row->instance_id
|| (string) $privateIp->private_ip !== (string) $row->private_ip
|| in_array((string) $privateIp->state, ['deleted', 'deleting'], true)) {
throw new CloudError('VPC 成员引用记录缺失,无法生成引擎目标', 409);
}
if ((string) $instance->status !== 'active') {
throw new CloudError('VPC 成员引用的虚拟机当前不可用,请先完成实例清理', 409);
}
$memberKey = (string) $row->member_key;
$memberKeys[(int) $row->id] = $memberKey;
// The MAC is derived from the immutable VPC/member identities so
// retries, host migration and engine restarts keep the same NIC
// identity. It is locally administered and unicast; no schema
// column is needed and the value remains part of the signed DTO.
$privateMac = self::privateMacForMember((string) $vpc->vpc_key, $memberKey);
if ($privateMac === null || isset($privateMacs[$privateMac])) {
throw new CloudError('VPC 成员私网 MAC 无效,无法生成引擎目标', 409);
}
$privateMacs[$privateMac] = $memberKey;
$memberRows[] = [
'member_id' => $memberKey,
'instance_uuid' => strtolower((string) $instance->uuid),
'host_id' => (string) $row->host_id,
'private_ip_cidr' => (string) $privateIp->private_ip . '/32',
'subnet_id' => $subnetKey,
'private_mac' => $privateMac,
];
}
$hostMembers = [];
foreach ($memberRows as $row) {
$hostMembers[$row['host_id']][] = $row['member_id'];
}
// Keep a host with an empty member list in the desired DTO while its
// deployment row is deleting. This gives the engine an explicit,
// typed removal target. The host row remains a tombstone until a
// later data-plane readback explicitly proves removal.
$deployments = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted'])->get();
foreach ($deployments as $deployment) {
$hostMembers[(string) $deployment->host_id] ??= [];
}
$hostRows = [];
foreach ($hostMembers as $hostId => $ids) {
sort($ids, SORT_STRING);
$hostRows[] = ['host_id' => (string) $hostId, 'members' => $ids];
}
usort($hostRows, static fn (array $a, array $b): int => strcmp($a['host_id'], $b['host_id']));
$routeRows = [];
foreach ($routes as $row) {
$nextMember = $memberKeys[(int) $row->member_id] ?? null;
if ($nextMember === null) {
throw new CloudError('VPC 路由引用了不存在或正在删除的成员', 409);
}
$routeRows[] = [
'route_id' => (string) $row->route_key,
'destination_cidr' => (string) $row->destination_cidr,
'next_hop_member_id' => $nextMember,
'metric' => (int) $row->metric,
];
}
$aclRows = [];
foreach ($acl as $row) {
$aclValue = [
'acl_id' => (string) $row->rule_key,
'priority' => (int) $row->priority,
'direction' => (string) $row->direction,
'action' => (string) $row->action,
// The engine's typed vocabulary calls the unrestricted
// protocol "any"; the DB/API may retain the friendlier
// legacy spelling "all".
'protocol' => (string) $row->protocol === 'all' ? 'any' : (string) $row->protocol,
'source_cidr' => (string) $row->source_cidr,
'destination_cidr' => (string) $row->destination_cidr,
];
if ($row->port_from !== null) {
$aclValue['port_from'] = (int) $row->port_from;
$aclValue['port_to'] = (int) $row->port_to;
}
$aclRows[] = $aclValue;
}
return self::canonicalize([
'schema_version' => 1,
'vpc_id' => (string) $vpc->vpc_key,
'region' => $fabricRegion,
'fabric_id' => (string) $vpc->fabric_id,
'fabric_revision' => (int) $vpc->fabric_revision,
'cidr' => (string) $vpc->cidr,
'desired_revision' => (int) $vpc->desired_revision,
'hosts' => $hostRows,
'subnets' => array_map(static fn ($row): array => [
'subnet_id' => (string) $row->subnet_key, 'cidr' => (string) $row->cidr,
], $subnets->all()),
'members' => $memberRows,
'routes' => $routeRows,
'acls' => $aclRows,
]);
}
/** Build the signed terminal target used only by the root delete lane. */
private static function deletionDocument(CloudVpc $vpc): array
{
$document = self::desiredDocument($vpc);
foreach (['subnets', 'members', 'routes', 'acls'] as $field) {
if (($document[$field] ?? null) !== []) {
throw new CloudError('VPC 删除目标仍包含活动资源', 409);
}
}
$retiringMembers = self::retiringMembersForDeletion($vpc);
// Only unresolved deployments are removal targets in the desired
// plan. A historical `deleted` host has already supplied exact
// absence proof and must not be reintroduced as a normal empty host
// by the engine parser. The final receipt must cover every pending
// host and may repeat, but need not repeat, a prior historical proof;
// recordDeleted() still rejects any host PHP has never deployed.
$hostIds = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->where('state', '<>', 'deleted')
->orderBy('host_id')->pluck('host_id')->map(
static fn ($hostId): string => (string) $hostId
)->unique()->values()->all();
// Python canonicalizes the typed host_id as a string, so numeric SQL
// ordering (2, 11) would otherwise produce a different signed digest
// from the engine's lexical ordering (11, 2).
sort($hostIds, SORT_STRING);
$hostSet = array_fill_keys($hostIds, true);
foreach ($retiringMembers as $member) {
if (!isset($hostSet[(string) $member['host_id']])) {
throw new CloudError('VPC 删除成员缺少宿主机部署账本', 409);
}
}
$document['hosts'] = array_map(static fn (string $hostId): array => [
'host_id' => $hostId, 'members' => [],
], $hostIds);
$document['retiring_members'] = $retiringMembers;
return self::canonicalize($document);
}
/**
* Preserve the exact private NIC identities that may have reached a host
* before an earlier engine response became durable. Root deletion signs
* this closed set so the engine can remove/read back every possible NIC.
*/
private static function retiringMembersForDeletion(CloudVpc $vpc): array
{
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->where('state', '<>', 'deleted')->orderBy('member_key')->get();
if ($members->isEmpty()) {
return [];
}
$instances = CloudInstance::whereIn(
'id', $members->pluck('instance_id')->map(
static fn ($id): int => (int) $id
)->unique()->values()->all()
)->get()->keyBy('id');
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('member_id', $members->pluck('id')->map(
static fn ($id): int => (int) $id
)->all())->get()->keyBy('member_id');
$result = [];
$macs = [];
foreach ($members as $member) {
$memberKey = (string) $member->member_key;
$instance = $instances[(int) $member->instance_id] ?? null;
$privateIp = $privateIps[(int) $member->id] ?? null;
$uuid = strtolower((string) ($instance->uuid ?? ''));
$mac = self::privateMacForMember((string) $vpc->vpc_key, $memberKey);
if (preg_match(self::KEY_PATTERN, $memberKey) !== 1
|| preg_match('/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/D',
$uuid) !== 1
|| $privateIp === null
|| (int) $member->private_ip_id !== (int) $privateIp->id
|| (int) $privateIp->member_id !== (int) $member->id
|| (int) $privateIp->instance_id !== (int) $member->instance_id
|| (string) $privateIp->private_ip !== (string) $member->private_ip
|| (string) $privateIp->state === 'deleted'
|| filter_var((string) $member->private_ip,
FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false
|| $mac === null || isset($macs[$mac])) {
throw new CloudError('VPC 删除成员身份账本不一致', 409);
}
$macs[$mac] = true;
$result[] = [
'member_id' => $memberKey,
'instance_uuid' => $uuid,
'host_id' => (string) $member->host_id,
'private_ip_cidr' => (string) $member->private_ip . '/32',
'private_mac' => $mac,
];
}
usort($result, static fn (array $left, array $right): int =>
strcmp($left['member_id'], $right['member_id'])
);
return $result;
}
/**
* A VM cannot enter destructive deletion while a VPC member row still
* exists. A `deleting` row is an explicit tombstone that remains
* unusable and blocks re-attachment until future data-plane readback;
* deleting the VM first would leave the host-side removal unproven.
*/
public static function hasBlockingMembership(int $instanceId): bool
{
if ($instanceId < 1) {
return false;
}
// Keep the lifecycle guard compatible with staged migrations, while
// checking every installed ledger independently. A partial deploy
// must never turn an existing private-address row into a free delete.
$memberConnection = (new CloudVpcMember())->getConnection();
if ($memberConnection->getSchemaBuilder()->hasTable('cloud_vpc_members')
&& CloudVpcMember::where('instance_id', $instanceId)
->whereNotIn('state', ['deleted'])->exists()) {
return true;
}
$privateIpConnection = (new CloudVpcPrivateIp())->getConnection();
return $privateIpConnection->getSchemaBuilder()->hasTable('cloud_vpc_private_ips')
&& CloudVpcPrivateIp::where('instance_id', $instanceId)
->whereNotIn('state', ['deleted'])->exists();
}
public static function assertInstanceCanBeDeleted(CloudInstance $instance): void
{
if (self::hasBlockingMembership((int) $instance->id)) {
throw new CloudError('虚拟机仍加入 VPC,请先移除私网成员', 409);
}
}
/**
* Return the private-network expectation that belongs to one VM job.
*
* This deliberately reads the existing VPC ledger instead of copying a
* second target into cloud_instances/spec_json. A missing VPC schema is
* treated as the legacy "no private network" deployment; once the ledger
* exists, malformed rows are an explicit uncertain expectation and cannot
* be silently interpreted as an attached network.
*/
public static function instancePrivateExpectation(?int $instanceId): array
{
$disabled = [
'required' => false, 'state' => 'disabled', 'desired_state' => 'disabled',
'vpc_id' => null, 'member_id' => null, 'private_ip_cidr' => null,
'private_mac' => null, 'desired_revision' => 0, 'desired_digest' => null,
'reason_code' => null,
];
if ($instanceId === null || $instanceId < 1) {
return $disabled;
}
try {
$memberConnection = (new CloudVpcMember())->getConnection();
$schema = $memberConnection->getSchemaBuilder();
if (!$schema->hasTable('cloud_vpc_members')) {
return $disabled;
}
if (!$schema->hasTable('cloud_vpc_private_ips')
|| !$schema->hasTable('cloud_vpcs')) {
return [
'required' => true, 'state' => 'uncertain',
'desired_state' => 'active', 'vpc_id' => null,
'member_id' => null, 'private_ip_cidr' => null,
'private_mac' => null, 'desired_revision' => 0,
'desired_digest' => null,
'reason_code' => 'vpc_private_expectation_invalid',
];
}
$member = CloudVpcMember::where('instance_id', $instanceId)
->whereNotIn('state', ['deleted'])->orderByDesc('id')->first();
if ($member === null) {
// A private-IP lease without a live member is still a
// control-plane residue. Treat it as an uncertain target so
// lifecycle workers cannot publish a successful/public-only
// result while the orphan may remain attached on a host.
$orphanLease = CloudVpcPrivateIp::where('instance_id', $instanceId)
->whereNotIn('state', ['deleted'])->exists();
if ($orphanLease) {
return [
'required' => true, 'state' => 'uncertain',
'desired_state' => 'active', 'vpc_id' => null,
'member_id' => null, 'private_ip_cidr' => null,
'private_mac' => null, 'desired_revision' => 0,
'desired_digest' => null,
'reason_code' => 'vpc_private_expectation_invalid',
];
}
return $disabled;
}
$vpc = CloudVpc::find((int) $member->vpc_id);
$privateIp = $member->private_ip_id === null ? null
: CloudVpcPrivateIp::where('id', (int) $member->private_ip_id)->first();
$state = (string) $member->state;
$desiredState = $state === 'deleting' ? 'removed' : 'active';
// The member and its lease are one desired-state tuple. Falling
// back to the root revision/digest can hide a partially-written
// child row and would let a VM job capture a target that the VPC
// document never actually requested.
$revision = (int) ($member->desired_revision ?? 0);
$digest = self::safeDigest($member->desired_digest);
$rootRevision = (int) ($vpc?->desired_revision ?? 0);
$rootDigest = self::safeDigest($vpc?->desired_digest);
$leaseRevision = (int) ($privateIp?->desired_revision ?? 0);
$leaseDigest = self::safeDigest($privateIp?->desired_digest);
$validIp = is_string($member->private_ip)
&& filter_var($member->private_ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) !== false;
// `deleting` is an in-flight lease state, not proof that the
// dataplane has converged. Keep the expectation uncertain until
// the row is removed (and a fresh member is observed).
$leaseState = (string) ($privateIp?->state ?? '');
$stateMatches = $privateIp !== null && $leaseState === $state;
$ledgerMatches = $privateIp !== null
&& (int) $privateIp->vpc_id === (int) $member->vpc_id
&& (int) $privateIp->subnet_id === (int) $member->subnet_id
&& (int) ($privateIp->member_id ?? 0) === (int) $member->id
&& (int) ($privateIp->instance_id ?? 0) === $instanceId
&& (string) $privateIp->private_ip === (string) $member->private_ip
&& $stateMatches
&& !in_array($leaseState, ['deleted', 'deleting'], true);
$validRevision = $revision > 0;
$validDigest = $digest !== null;
$desiredLedgerMatches = $vpc !== null
&& $rootRevision === $revision
&& $rootDigest !== null && $digest !== null
&& self::digestMatches($rootDigest, $digest)
&& $leaseRevision === $revision
&& $leaseDigest !== null
&& self::digestMatches($digest, $leaseDigest);
if (!$validIp || !$ledgerMatches || !$validRevision || !$validDigest
|| !$desiredLedgerMatches
|| !is_string($member->member_key)
|| preg_match(self::KEY_PATTERN, (string) $member->member_key) !== 1
|| !is_string($vpc?->vpc_key)
|| preg_match(self::KEY_PATTERN, (string) $vpc->vpc_key) !== 1) {
return [
'required' => true, 'state' => 'uncertain',
'desired_state' => $desiredState,
'vpc_id' => is_string($vpc?->vpc_key) ? $vpc->vpc_key : null,
'member_id' => is_string($member->member_key) ? $member->member_key : null,
'private_ip_cidr' => $validIp ? $member->private_ip . '/32' : null,
'private_mac' => null, 'desired_revision' => max(0, $revision),
'desired_digest' => $validDigest ? $digest : null,
'reason_code' => 'vpc_private_expectation_invalid',
];
}
$privateMac = self::privateMacForMember(
(string) $vpc->vpc_key, (string) $member->member_key
);
if ($privateMac === null) {
return [
'required' => true, 'state' => 'uncertain',
'desired_state' => $desiredState,
'vpc_id' => (string) $vpc->vpc_key,
'member_id' => (string) $member->member_key,
'private_ip_cidr' => $validIp ? $member->private_ip . '/32' : null,
'private_mac' => null, 'desired_revision' => max(0, $revision),
'desired_digest' => $validDigest ? $digest : null,
'reason_code' => 'vpc_private_expectation_invalid',
];
}
return [
'required' => true, 'state' => $state,
'desired_state' => $desiredState,
'vpc_id' => (string) $vpc->vpc_key,
'member_id' => (string) $member->member_key,
'private_ip_cidr' => $member->private_ip . '/32',
'private_mac' => $privateMac,
'desired_revision' => $revision,
'desired_digest' => $digest,
'reason_code' => null,
];
} catch (\Throwable $error) {
// A live ledger that cannot be read is different from an
// installation that predates VPC tables. Fail closed for the
// former so a worker cannot publish a stale successful result.
return [
'required' => true, 'state' => 'uncertain',
'desired_state' => 'active', 'vpc_id' => null, 'member_id' => null,
'private_ip_cidr' => null, 'private_mac' => null,
'desired_revision' => 0, 'desired_digest' => null,
'reason_code' => 'vpc_private_expectation_unavailable',
];
}
}
/** Compare a job's captured target with the current ledger under a lock. */
public static function privateExpectationMatches(int $instanceId, array $captured): bool
{
if ($instanceId < 1 || $captured === []) {
return true;
}
$current = self::instancePrivateExpectation($instanceId);
// `state` is observed/transient (for example applying -> active) and
// may advance while a VM lifecycle job is running. The immutable
// target is bound by desired_state, identity, IP, revision and digest;
// removal remains strict because it changes desired_state to removed.
foreach (['required', 'desired_state', 'vpc_id', 'member_id',
'private_ip_cidr', 'private_mac', 'desired_revision', 'desired_digest'] as $key) {
if ((string) ($captured[$key] ?? null) !== (string) ($current[$key] ?? null)) {
return false;
}
}
return true;
}
/** Build a bounded instance projection for page/runtime responses. */
public static function instancePrivateProjection(int $instanceId): array
{
$expectation = self::instancePrivateExpectation($instanceId);
$base = [
'version' => 1, 'required' => (bool) $expectation['required'],
'vm_uuid' => null, 'vpc_id' => $expectation['vpc_id'] ?? null,
'member_id' => $expectation['member_id'] ?? null,
'interface' => $expectation['required'] ? 'private0' : null,
'state' => $expectation['required'] ? 'uncertain' : 'disabled',
'desired_state' => $expectation['desired_state'] ?? 'disabled',
'desired_revision' => (int) ($expectation['desired_revision'] ?? 0),
'observed_revision' => 0,
'desired_digest' => $expectation['desired_digest'] ?? null,
'observed_digest' => null, 'readback' => $expectation['required'] ? 'missing' : 'confirmed',
'link_state' => $expectation['required'] ? 'absent' : 'absent',
'private_ip_cidr' => $expectation['private_ip_cidr'] ?? null,
'private_mac' => $expectation['private_mac'] ?? null,
'reason_code' => $expectation['reason_code']
?? ($expectation['required'] ? 'vpc_private_observation_missing' : null),
'observed_at' => 0,
];
if (!$expectation['required']) {
return $base;
}
try {
$vpcKey = is_string($expectation['vpc_id'] ?? null)
? (string) $expectation['vpc_id'] : '';
$memberKey = is_string($expectation['member_id'] ?? null)
? (string) $expectation['member_id'] : '';
if (preg_match(self::KEY_PATTERN, $vpcKey) !== 1
|| preg_match(self::KEY_PATTERN, $memberKey) !== 1) {
return $base;
}
// member_key is only unique inside a VPC. Binding the instance
// and VPC roots here prevents a stale/cross-tenant row from
// becoming a usable private projection.
$vpc = CloudVpc::where('vpc_key', $vpcKey)->first([
'id', 'vpc_key', 'state', 'sync_state', 'desired_revision',
'observed_revision', 'desired_digest', 'observed_digest',
'last_operation_id', 'last_success_at', 'updated_at',
]);
if ($vpc === null) {
return $base;
}
$member = CloudVpcMember::where('instance_id', $instanceId)
->where('vpc_id', (int) $vpc->id)
->where('member_key', $memberKey)
->whereNotIn('state', ['deleted'])
->first([
'id', 'vpc_id', 'subnet_id', 'private_ip_id', 'instance_id',
'private_ip', 'state', 'desired_revision', 'observed_revision',
'desired_digest', 'observed_digest', 'last_error_code',
'last_operation_id', 'updated_at',
]);
if ($member === null || $member->private_ip_id === null) {
return $base;
}
// A member row is not proof that its independent lease exists.
// Read back and bind every lease identity before considering the
// member's revision or digest.
$privateIp = CloudVpcPrivateIp::where('id', (int) $member->private_ip_id)
->where('vpc_id', (int) $vpc->id)
->where('member_id', (int) $member->id)
->where('instance_id', $instanceId)
->first([
'id', 'vpc_id', 'subnet_id', 'member_id', 'instance_id',
'private_ip', 'state', 'desired_revision', 'observed_revision',
'desired_digest', 'observed_digest', 'last_error_code', 'updated_at',
]);
if ($privateIp === null
|| (int) $privateIp->subnet_id !== (int) $member->subnet_id
|| (string) $privateIp->private_ip !== (string) $member->private_ip) {
return $base;
}
$observedRevision = max(0, (int) $member->observed_revision);
$observedDigest = self::safeDigest($member->observed_digest);
$privateObservedRevision = max(0, (int) $privateIp->observed_revision);
$privateObservedDigest = self::safeDigest($privateIp->observed_digest);
$privateDesiredRevision = max(0, (int) $privateIp->desired_revision);
$privateDesiredDigest = self::safeDigest($privateIp->desired_digest);
$rootDesiredRevision = max(0, (int) $vpc->desired_revision);
$rootObservedRevision = max(0, (int) $vpc->observed_revision);
$rootDesiredDigest = self::safeDigest($vpc->desired_digest);
$rootObservedDigest = self::safeDigest($vpc->observed_digest);
$rootOperationId = (string) ($vpc->last_operation_id ?? '');
// A VM job operation ID is not a VPC activation proof. The
// marker must be the current root operation that advanced the
// all-host VPC gate, and that operation must have succeeded.
$proofMarker = preg_match(self::KEY_PATTERN, $rootOperationId) === 1
&& hash_equals($rootOperationId,
(string) ($member->last_operation_id ?? ''));
$operation = $proofMarker
? CloudVpcOperation::where('vpc_id', (int) $vpc->id)
->where('operation_id', $rootOperationId)
->where('status', 'succeeded')
->first([
'operation_id', 'desired_revision', 'evidence_version',
'created_at', 'finished_at',
])
: null;
$operationFresh = $operation !== null
&& (int) $operation->evidence_version
>= self::OBSERVATION_EVIDENCE_VERSION
&& (int) $operation->desired_revision === (int) $base['desired_revision']
&& (int) ($operation->finished_at ?? 0) > 0
&& (int) ($operation->finished_at ?? 0)
>= (int) ($operation->created_at ?? 0)
&& (int) ($vpc->last_success_at ?? 0) > 0
&& (int) ($vpc->last_success_at ?? 0)
>= (int) ($operation->created_at ?? 0)
&& (int) ($member->updated_at ?? 0) > 0
&& (int) ($privateIp->updated_at ?? 0) > 0
&& (int) ($member->updated_at ?? 0) >= (int) ($operation->created_at ?? 0)
&& (int) ($privateIp->updated_at ?? 0) >= (int) ($operation->created_at ?? 0);
// Root state is the aggregate runtime view. A different member
// may still be stopped or suspended while this member has exact
// guest proof, so bind to the current configuration revision
// without requiring every sibling to be runtime-active.
$rootExact = in_array((string) $vpc->state, ['active', 'degraded'], true)
&& in_array((string) $vpc->sync_state, ['applied', 'waiting'], true)
&& $rootDesiredRevision === (int) $base['desired_revision']
&& $rootObservedRevision === $rootDesiredRevision
&& $rootDesiredDigest !== null && $rootObservedDigest !== null
&& self::digestMatches($rootDesiredDigest, $rootObservedDigest)
&& self::digestMatches((string) $base['desired_digest'], $rootDesiredDigest);
$memberRevisionExact = $observedRevision === (int) $base['desired_revision']
&& $observedDigest !== null
&& self::digestMatches((string) $base['desired_digest'], $observedDigest)
&& (int) $member->desired_revision === (int) $base['desired_revision']
&& self::digestMatches((string) $base['desired_digest'],
(string) $member->desired_digest);
$privateRevisionExact = $privateDesiredRevision === (int) $base['desired_revision']
&& $privateObservedRevision === $privateDesiredRevision
&& $privateDesiredDigest !== null
&& $privateObservedDigest !== null
&& self::digestMatches((string) $base['desired_digest'], $privateDesiredDigest)
&& self::digestMatches($privateDesiredDigest, $privateObservedDigest);
$activeExact = (string) $member->state === 'active'
&& (string) $privateIp->state === 'active';
$suspendedExact = (string) $member->state === 'suspended'
&& (string) $privateIp->state === 'suspended';
$stoppingExact = (string) $member->state === 'stopping'
&& (string) $privateIp->state === 'stopping';
$stoppedExact = (string) $member->state === 'stopped'
&& (string) $privateIp->state === 'stopped';
$confirmed = $proofMarker && $operationFresh && $rootExact
&& $memberRevisionExact && $privateRevisionExact
&& ($activeExact || $suspendedExact || $stoppingExact
|| $stoppedExact);
$base['observed_revision'] = $observedRevision;
$base['observed_digest'] = $observedDigest;
// Keep the stable desired identity in the projection even before
// a host readback is confirmed. The observation validator below
// still requires the engine to echo the exact same MAC.
$base['private_mac'] = $expectation['private_mac'] ?? null;
$base['state'] = $confirmed
? ($stoppedExact ? 'stopped'
: ($stoppingExact ? 'stopping'
: ($suspendedExact ? 'suspended' : 'active')))
: ((string) $member->state === 'degraded'
|| (string) $privateIp->state === 'degraded'
? 'degraded' : 'uncertain');
$base['readback'] = $confirmed ? 'confirmed' : 'missing';
$base['reason_code'] = $confirmed
? ($stoppedExact ? 'vpc_private_guest_stopped'
: ($stoppingExact ? 'vpc_private_guest_shutdown_pending'
: ($suspendedExact ? 'vpc_private_network_suspended' : null)))
: (self::safeErrorCode((string) ($privateIp->last_error_code
?? $member->last_error_code ?? ''))
?? 'vpc_private_observation_missing');
$freshness = array_values(array_filter([
(int) ($member->updated_at ?? 0),
(int) ($privateIp->updated_at ?? 0),
(int) ($vpc->last_success_at ?? 0),
], static fn (int $value): bool => $value > 0));
$base['observed_at'] = $freshness === [] ? 0 : min($freshness);
if ($confirmed && $suspendedExact) {
$base['link_state'] = 'down';
} elseif ($confirmed && ($stoppingExact || $stoppedExact)) {
// A stopping/stopped domain has no usable runtime link, but
// its persistent XML may deliberately retain either policy value.
// The instance policy ledger is the durable source for that
// configured value until the next start supplies fresh QGA
// evidence.
$networkStatus = (string) (CloudInstance::where('id', $instanceId)
->value('network_status') ?? '');
if (in_array($networkStatus, [
'blocking', 'blocking_expired',
'blocked_traffic', 'blocked_expired',
], true)) {
$base['link_state'] = 'down';
} elseif ($networkStatus === 'active') {
$base['link_state'] = 'up';
} else {
$base['link_state'] = 'absent';
}
} elseif ($confirmed) {
// The member ledger proves the VPC revision, while the
// instance network policy records whether the last gated
// operation intentionally disconnected all NICs. Pending or
// failed policy transitions must remain uncertain until the
// next engine readback, even when the previous member digest
// was exact.
$networkStatus = (string) (CloudInstance::where('id', $instanceId)
->value('network_status') ?? '');
if (in_array($networkStatus,
['blocking', 'blocking_expired', 'restore_pending', 'restoring'], true)) {
$base['state'] = 'uncertain';
$base['readback'] = 'missing';
$base['reason_code'] = 'vpc_private_observation_missing';
} elseif (in_array($networkStatus,
['blocked_traffic', 'blocked_expired'], true)) {
$base['state'] = 'suspended';
$base['link_state'] = 'down';
} else {
$base['link_state'] = 'up';
}
}
} catch (\Throwable) {
// Keep the fail-closed default projection.
}
return $base;
}
/**
* Validate one engine private_state at a mutation commit boundary.
*
* The engine's XML observation is necessary but not sufficient for an
* attached VPC: the member identity, stable MAC, desired revision and
* digest must be echoed by the VPC data-plane readback. A lifecycle
* reconcile may additionally bind the observation to its requested VM
* UUID through $expectedVmUuid.
*/
public static function validatePrivateObservation(
array $expectation, ?array $observation, string $kind,
?string $expectedVmUuid = null
): array {
$fallback = [
'version' => 1, 'required' => (bool) ($expectation['required'] ?? false),
'vm_uuid' => null, 'vpc_id' => $expectation['vpc_id'] ?? null,
'member_id' => $expectation['member_id'] ?? null,
'interface' => null, 'state' => 'uncertain',
'desired_state' => (string) ($expectation['desired_state'] ?? 'disabled'),
'desired_revision' => (int) ($expectation['desired_revision'] ?? 0),
'observed_revision' => 0,
'desired_digest' => $expectation['desired_digest'] ?? null,
'observed_digest' => null, 'readback' => 'missing',
'link_state' => 'absent', 'private_ip_cidr' => null,
'private_mac' => $expectation['private_mac'] ?? null,
'xml_verified' => false, 'config_verified' => false,
'seed_verified' => false,
'domain_running' => false, 'restart_required' => null,
'guest_network_verified' => false,
'guest_network_readback' => 'missing',
'guest_link_state' => null,
'reason_code' => 'vpc_private_observation_missing',
'observed_at' => time(),
];
if (!is_array($observation)) {
return ['ok' => false, 'state' => $fallback,
'error_code' => $fallback['reason_code']];
}
if ((int) ($observation['version'] ?? 0) !== 1) {
$fallback['reason_code'] = 'vpc_private_observation_mismatch';
return ['ok' => false, 'state' => $fallback,
'error_code' => $fallback['reason_code']];
}
if ($expectedVmUuid !== null) {
$observedVmUuid = $observation['vm_uuid'] ?? null;
if (!is_string($observedVmUuid)
|| !hash_equals(strtolower($expectedVmUuid), strtolower($observedVmUuid))) {
$fallback['reason_code'] = 'vpc_private_observation_mismatch';
return ['ok' => false, 'state' => $fallback,
'error_code' => $fallback['reason_code']];
}
}
$state = $fallback;
foreach (['version', 'required', 'vm_uuid', 'vpc_id', 'member_id',
'interface', 'state', 'desired_revision', 'observed_revision',
'desired_digest', 'observed_digest', 'readback', 'link_state',
'private_ip_cidr', 'private_mac', 'xml_verified',
'config_verified', 'seed_verified', 'domain_running',
'restart_required',
'guest_network_verified', 'guest_network_readback',
'guest_link_state',
'reason_code', 'observed_at'] as $key) {
if (array_key_exists($key, $observation)) {
$state[$key] = $observation[$key];
}
}
$state['required'] = (bool) $state['required'];
$state['desired_revision'] = max(0, (int) $state['desired_revision']);
$state['observed_revision'] = max(0, (int) $state['observed_revision']);
$state['desired_digest'] = self::safeDigest($state['desired_digest']);
$state['observed_digest'] = self::safeDigest($state['observed_digest']);
$expectedRequired = (bool) ($expectation['required'] ?? false);
$expectedState = (string) ($expectation['desired_state'] ?? 'disabled');
$state['required'] = $expectedRequired;
$state['desired_state'] = $expectedState;
$observedVpcId = is_string($observation['vpc_id'] ?? null)
? (string) $observation['vpc_id'] : null;
$observedMemberId = is_string($observation['member_id'] ?? null)
? (string) $observation['member_id'] : null;
$state['vpc_id'] = $expectation['vpc_id'] ?? null;
$state['member_id'] = $expectation['member_id'] ?? null;
$state['desired_revision'] = (int) ($expectation['desired_revision'] ?? 0);
$state['desired_digest'] = self::safeDigest($expectation['desired_digest'] ?? null);
$state['private_ip_cidr'] = is_string($observation['private_ip_cidr'] ?? null)
? trim($observation['private_ip_cidr']) : null;
$state['private_mac'] = is_string($observation['private_mac'] ?? null)
? strtolower(trim($observation['private_mac'])) : null;
$state['state'] = is_string($observation['state'] ?? null)
? strtolower(trim($observation['state'])) : 'uncertain';
$state['readback'] = is_string($observation['readback'] ?? null)
? strtolower(trim($observation['readback'])) : 'missing';
$state['xml_verified'] = ($observation['xml_verified'] ?? false) === true;
$state['config_verified'] =
($observation['config_verified'] ?? false) === true;
$state['seed_verified'] =
($observation['seed_verified'] ?? false) === true;
$state['domain_running'] =
($observation['domain_running'] ?? false) === true;
$state['restart_required'] = $observation['restart_required'] ?? null;
$state['guest_network_verified'] =
($observation['guest_network_verified'] ?? false) === true;
$state['guest_network_readback'] = is_string(
$observation['guest_network_readback'] ?? null
) ? strtolower(trim((string) $observation['guest_network_readback']))
: 'missing';
$state['guest_link_state'] = is_string(
$observation['guest_link_state'] ?? null
) ? strtolower(trim((string) $observation['guest_link_state'])) : null;
if (!$expectedRequired) {
// When a structured observation is available, a legacy VM is
// successful only when the host readback proves that no private
// NIC exists. An unexpected private interface, even if its XML
// looks healthy, is topology drift and must not be hidden behind
// a successful public-only operation. The worker compatibility
// gate handles older responses that omit private_state entirely.
$ok = $state['state'] === 'disabled'
&& $state['readback'] === 'confirmed'
&& ($observation['required'] ?? false) === false;
if (!$ok) {
$state['state'] = 'uncertain';
$state['reason_code'] = 'vpc_private_observation_missing';
}
return ['ok' => $ok, 'state' => $state,
'error_code' => $ok ? null : $state['reason_code']];
}
$policyActive = str_ends_with($kind, '_policy_active');
$policyBlocked = str_ends_with($kind, '_policy_blocked');
$policyUnready = str_ends_with($kind, '_policy_unready');
$gracefulShutdownTarget = str_starts_with(
$kind, 'action_shutdown_policy_'
);
$stoppedTarget = str_starts_with($kind, 'action_poweroff_policy_')
|| str_starts_with($kind, 'service_suspend_policy_')
|| str_starts_with($kind, 'service_resume_stopped_policy_');
$runningTarget = str_starts_with($kind, 'action_start_policy_')
|| str_starts_with($kind, 'action_reboot_policy_')
|| str_starts_with($kind, 'action_reset_policy_')
|| str_starts_with($kind, 'service_resume_start_policy_');
$unboundResume = str_starts_with(
$kind, 'service_resume_unbound_policy_'
);
$preserveTarget = $kind === 'policy_skipped';
$linkExpected = $expectedState === 'removed'
? 'absent'
: match ($kind) {
'network_suspend' => 'down',
'network_resume' => 'up',
default => null,
};
if ($expectedState !== 'removed'
&& ($gracefulShutdownTarget || $stoppedTarget || $runningTarget)) {
$linkExpected = $policyActive ? 'up'
: ($policyBlocked ? 'down' : null);
}
$identity = is_string($expectation['vpc_id'] ?? null)
&& is_string($expectation['member_id'] ?? null)
&& $observedVpcId !== null && $observedMemberId !== null
&& hash_equals((string) $expectation['vpc_id'], $observedVpcId)
&& hash_equals((string) $expectation['member_id'], $observedMemberId);
$shape = ($observation['required'] ?? false) === true;
if ($expectedState === 'removed') {
// Teardown evidence is allowed to omit the interface/MAC only
// when it explicitly reports the removed state. Identity,
// revision and digest below still bind the tombstone to the
// original VPC member.
$shape = $shape && in_array($state['state'], ['disabled', 'removed'], true);
} else {
$shape = $shape && ($state['interface'] ?? null) === 'private0'
&& is_string($state['private_mac'] ?? null)
&& preg_match('/^[0-9a-f]{2}(?::[0-9a-f]{2}){5}$/Di',
(string) $state['private_mac']) === 1;
}
$revision = $state['observed_revision'] === $state['desired_revision']
&& $state['desired_revision'] > 0;
$digest = is_string($state['observed_digest'])
&& is_string($state['desired_digest'])
&& hash_equals($state['desired_digest'], $state['observed_digest']);
$ip = $expectedState === 'removed'
|| (is_string($expectation['private_ip_cidr'])
&& hash_equals((string) $expectation['private_ip_cidr'], (string) $state['private_ip_cidr']));
$mac = $expectedState === 'removed'
|| (is_string($expectation['private_mac'] ?? null)
&& is_string($observation['private_mac'] ?? null)
&& is_string($state['private_mac'] ?? null)
&& hash_equals(strtolower((string) $expectation['private_mac']),
strtolower((string) $state['private_mac'])));
$stoppedEvidence = $state['state'] === 'stopped';
if ($expectedState === 'removed') {
$desired = in_array($state['state'], ['disabled', 'removed'], true);
} elseif ($policyUnready || $unboundResume) {
$desired = false;
} elseif ($stoppedTarget) {
$desired = $stoppedEvidence;
} elseif ($gracefulShutdownTarget) {
$desired = $stoppedEvidence
|| ($policyActive && $state['state'] === 'active')
|| ($policyBlocked && $state['state'] === 'suspended');
} elseif ($runningTarget) {
$desired = $policyActive
? $state['state'] === 'active'
: ($policyBlocked && $state['state'] === 'suspended');
} elseif ($preserveTarget) {
$desired = in_array(
$state['state'], ['active', 'suspended', 'stopped'], true
);
} elseif ($kind === 'network_resume') {
$desired = in_array($state['state'], ['active', 'stopped'], true);
} elseif ($kind === 'network_suspend') {
$desired = in_array($state['state'], ['suspended', 'stopped'], true);
} else {
$desired = in_array($state['state'], ['active', 'suspended'], true);
}
$link = $linkExpected === null || $state['link_state'] === $linkExpected;
$stoppedConfigExact = !$stoppedEvidence || (
$state['xml_verified'] === true
&& $state['config_verified'] === true
&& $state['seed_verified'] === true
&& $state['domain_running'] === false
&& $state['restart_required'] === false
&& in_array($state['link_state'], ['up', 'down'], true)
);
// Every active result crosses the same guest-visible readiness
// boundary. Do not let a rolling/preview engine make a generic
// lifecycle job successful with the older XML-only observation
// shape merely because that job is not a start/resume operation.
$freshRunningProofRequired = $state['state'] === 'active';
$freshRunningProof = !$freshRunningProofRequired || (
$state['xml_verified'] === true
&& $state['config_verified'] === true
&& $state['seed_verified'] === true
&& $state['domain_running'] === true
&& $state['restart_required'] === false
&& $state['guest_network_verified'] === true
&& $state['guest_network_readback'] === 'confirmed'
&& $state['guest_link_state'] === 'up'
);
$intentionalSuspendedProof = $state['state'] !== 'suspended'
|| (
$state['xml_verified'] === true
&& $state['config_verified'] === true
&& $state['seed_verified'] === true
&& $state['domain_running'] === true
&& $state['restart_required'] === false
&& $state['link_state'] === 'down'
);
$ok = $shape && $identity && $revision && $digest && $ip && $mac
&& $desired && $link && $stoppedConfigExact && $freshRunningProof
&& $intentionalSuspendedProof && $state['readback'] === 'confirmed';
if (!$ok) {
$state['state'] = $state['state'] === 'degraded' ? 'degraded' : 'uncertain';
$state['readback'] = $state['readback'] === 'mismatch' ? 'mismatch' : 'missing';
$state['reason_code'] = $expectedState === 'removed'
? 'vpc_private_teardown_uncertain' : 'vpc_private_observation_mismatch';
} elseif ($stoppedEvidence) {
$state['reason_code'] = 'vpc_private_guest_stopped';
} elseif ($gracefulShutdownTarget) {
// ACPI shutdown success confirms request acceptance, not immediate
// domain inactivity. Persist a non-usable transition and let the
// VPC/runtime observers replace it with exact stopped evidence.
$state['state'] = 'stopping';
$state['reason_code'] = 'vpc_private_guest_shutdown_pending';
}
return ['ok' => $ok, 'state' => $state,
'error_code' => $ok ? null : $state['reason_code']];
}
/** Persist the latest VM-side observation without advancing a VPC root. */
public static function recordPrivateObservation(
int $instanceId, array $validation, string $operationId
): bool {
if ($instanceId < 1 || preg_match(self::KEY_PATTERN, $operationId) !== 1) {
return false;
}
$connection = (new CloudVpcMember())->getConnection();
$schema = $connection->getSchemaBuilder();
if (!$schema->hasTable('cloud_vpc_members')
|| !$schema->hasTable('cloud_vpc_private_ips')
|| !$schema->hasTable('cloud_vpcs')) {
return false;
}
return (bool) $connection->transaction(function () use (
$instanceId, $validation, $operationId
): bool {
// Match the VPC -> member lock order used by control-plane
// mutations. A lifecycle readback from an older desired revision
// must never be written into a newer member row.
$probe = CloudVpcMember::where('instance_id', $instanceId)
->whereNotIn('state', ['deleted'])->first();
if ($probe === null) {
return false;
}
$vpc = CloudVpc::where('id', (int) $probe->vpc_id)
->lockForUpdate()->first();
if ($vpc === null) {
return false;
}
$member = CloudVpcMember::where('id', (int) $probe->id)
->whereNotIn('state', ['deleted'])->lockForUpdate()->first();
if ($member === null) {
return false;
}
// Lock and validate the independent lease before changing either
// side of the member/lease pair. A VM readback must never copy
// its revision into a lease belonging to another member.
if ($member->private_ip_id === null) {
return false;
}
$private = CloudVpcPrivateIp::where('id', (int) $member->private_ip_id)
->where('vpc_id', (int) $vpc->id)
->where('member_id', (int) $member->id)
->where('instance_id', $instanceId)
->lockForUpdate()->first();
if ($private === null
|| (int) $private->subnet_id !== (int) $member->subnet_id
|| (string) $private->private_ip !== (string) $member->private_ip) {
return false;
}
$state = is_array($validation['state'] ?? null)
? $validation['state'] : [];
$ok = ($validation['ok'] ?? false) === true;
$desired = (string) ($state['desired_state'] ?? 'active');
$expectedRevision = max(0, (int) ($state['desired_revision'] ?? 0));
$expectedDigest = self::safeDigest($state['desired_digest'] ?? null);
$memberDigest = self::safeDigest($member->desired_digest);
if ((int) $member->desired_revision !== $expectedRevision
|| $memberDigest !== $expectedDigest) {
return false;
}
if ((string) $vpc->state === 'deleting') {
// Root deletion owns the terminal transition and its signed
// retiring_members closure must remain immutable until the
// dedicated engine receipt is finalized. A concurrent VM
// power/delete worker may still contribute useful exact
// readback evidence, but it cannot shrink that manifest by
// closing the member/lease tombstones independently.
$member->observed_revision = max(
0, (int) ($state['observed_revision'] ?? 0)
);
$member->observed_digest = self::safeDigest(
$state['observed_digest'] ?? null
);
$member->state = 'deleting';
$member->last_error_code = $ok ? null
: (is_string($validation['error_code'] ?? null)
? self::safeErrorCode((string) $validation['error_code'])
: 'vpc_private_observation_missing');
$member->updated_at = time();
$member->save();
$private->state = 'deleting';
$private->observed_revision = $member->observed_revision;
$private->observed_digest = $member->observed_digest;
$private->last_error_code = $member->last_error_code;
$private->updated_at = time();
$private->save();
return true;
}
// `last_operation_id` on a member is the VPC proof marker. A
// VM lifecycle job may refresh the private lease, but must not
// replace a successful root operation marker with its unrelated
// job ID; doing so would make an already-proven VPC appear stale.
$rootOperationId = (string) ($vpc->last_operation_id ?? '');
if ($rootOperationId === '' || $rootOperationId === $operationId) {
$member->last_operation_id = $operationId;
}
$member->observed_revision = max(0, (int) ($state['observed_revision'] ?? 0));
$member->observed_digest = self::safeDigest($state['observed_digest'] ?? null);
$runtimeSuspended = $ok && $desired !== 'removed'
&& (string) ($state['state'] ?? '') === 'suspended'
&& (string) ($state['link_state'] ?? '') === 'down';
$runtimeStopped = $ok && $desired !== 'removed'
&& (string) ($state['state'] ?? '') === 'stopped';
$runtimeStopping = $ok && $desired !== 'removed'
&& (string) ($state['state'] ?? '') === 'stopping';
// Mirror the member outcome into its lease row. A private-IP
// state left at `deleting` or `active` after readback would make
// the next expectation disagree with the member ledger.
$privateState = $ok
? ($desired === 'removed' ? 'deleted'
: ($runtimeStopped ? 'stopped'
: ($runtimeStopping ? 'stopping'
: ($runtimeSuspended ? 'suspended' : 'active'))))
: ($desired === 'removed' ? 'deleting' : 'uncertain');
if ($ok && $desired === 'removed') {
$member->state = 'deleted';
$member->last_error_code = null;
$private->state = $privateState;
$private->observed_revision = $member->observed_revision;
$private->observed_digest = $member->observed_digest;
$private->last_error_code = null;
$private->updated_at = time();
$private->save();
} elseif ($ok) {
$member->state = $runtimeStopped ? 'stopped'
: ($runtimeStopping ? 'stopping'
: ($runtimeSuspended ? 'suspended' : 'active'));
$member->last_error_code = $runtimeStopped
? 'vpc_private_guest_stopped'
: ($runtimeStopping ? 'vpc_private_guest_shutdown_pending'
: ($runtimeSuspended ? 'vpc_private_network_suspended' : null));
} else {
$member->state = $desired === 'removed' ? 'deleting' : 'uncertain';
$member->last_error_code = is_string($validation['error_code'] ?? null)
? self::safeErrorCode((string) $validation['error_code']) : 'vpc_private_observation_missing';
}
$member->updated_at = time();
$member->save();
$private->state = $privateState;
$private->observed_revision = $member->observed_revision;
$private->observed_digest = $member->observed_digest;
$private->last_error_code = $member->last_error_code;
$private->updated_at = time();
$private->save();
self::refreshVpcRuntimeAggregate($vpc, (int) $member->host_id);
return true;
}, 3);
}
/** Refresh host/root runtime state without changing exact config proof. */
private static function refreshVpcRuntimeAggregate(CloudVpc $vpc, int $hostId): void
{
$now = time();
$host = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->where('host_id', $hostId)->lockForUpdate()->first();
if ($host !== null && (string) $host->state !== 'deleting'
&& (string) $host->state !== 'deleted') {
$hostMembers = CloudVpcMember::where('vpc_id', $vpc->id)
->where('host_id', $hostId)
->whereNotIn('state', ['deleting', 'deleted'])->get();
$hostReady = !$hostMembers->isEmpty()
&& $hostMembers->every(static fn ($row): bool =>
(string) $row->state === 'active');
$hostError = null;
foreach ($hostMembers as $hostMember) {
if ((string) $hostMember->state === 'active') {
continue;
}
$hostError = self::safeErrorCode(
(string) ($hostMember->last_error_code ?? '')
) ?? 'vpc_private_observation_missing';
break;
}
$host->state = $hostReady ? 'active' : 'degraded';
$host->last_error_code = $hostReady ? null : $hostError;
$host->updated_at = $now;
if ($hostReady) {
$host->last_success_at = $now;
} else {
$host->last_failure_at = $now;
}
$host->save();
}
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->get();
$memberIds = $members->pluck('id')->map(
static fn ($id): int => (int) $id
)->values()->all();
$leases = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('member_id', $memberIds)->get()->keyBy('member_id');
$runtimeReady = !$members->isEmpty();
$rootError = null;
foreach ($members as $member) {
$lease = $leases->get((int) $member->id);
if ((string) $member->state === 'active'
&& $lease !== null && (string) $lease->state === 'active') {
continue;
}
$runtimeReady = false;
$runtimeError = self::safeErrorCode(
(string) ($member->last_error_code ?? '')
);
if ($runtimeError === null && $lease !== null) {
$runtimeError = self::safeErrorCode(
(string) ($lease->last_error_code ?? '')
);
}
$rootError ??= self::safeErrorCode(
(string) ($runtimeError ?? '')
) ?? 'vpc_private_observation_missing';
}
$hostsReady = !CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->whereNotIn('state', ['active', 'deleted'])->exists();
$runtimeReady = $runtimeReady && $hostsReady;
$configExact = (int) $vpc->desired_revision === (int) $vpc->observed_revision
&& self::digestMatches(
(string) $vpc->desired_digest,
(string) $vpc->observed_digest
);
if ($configExact && (string) $vpc->state !== 'deleting'
&& (string) $vpc->state !== 'deleted') {
$vpc->state = $runtimeReady ? 'active' : 'degraded';
if ($runtimeReady) {
$vpc->sync_state = 'applied';
$vpc->last_error_code = null;
$vpc->last_success_at = $now;
} else {
// An intentional lifecycle link-down does not invalidate the
// shared host configuration receipt. Preserve an applied
// config state; other runtime gaps retain their waiting lane.
if ((string) $vpc->sync_state === 'applied') {
$vpc->sync_state = 'applied';
}
$vpc->last_error_code = $rootError
?? 'vpc_private_observation_missing';
$vpc->last_failure_at = $now;
}
$vpc->updated_at = $now;
$vpc->save();
}
}
private static function safeDigest($value): ?string
{
return is_string($value) && preg_match('/^[a-f0-9]{64}$/Di', $value) === 1
? strtolower($value) : null;
}
/**
* Reap legacy terminal identities before an attach reserves new unique
* keys. Source and target roots are locked in numeric order so two
* opposite cross-VPC moves cannot acquire them in an ABBA order.
*/
private static function releasePersistedDeletedMembershipsBeforeAttach(
CloudVpc $targetVpc, CloudInstance $instance, array $actor
): void {
$sourceVpcId = CloudVpcMember::where('instance_id', (int) $instance->id)
->where('state', 'deleted')->value('vpc_id');
$vpcIds = array_values(array_unique(array_filter([
(int) $targetVpc->id,
$sourceVpcId === null ? null : (int) $sourceVpcId,
], static fn ($value): bool => is_int($value) && $value > 0)));
sort($vpcIds, SORT_NUMERIC);
$connection = (new CloudVpc())->getConnection();
$connection->transaction(function () use (
$vpcIds, $targetVpc, $instance, $actor
): void {
$roots = [];
foreach ($vpcIds as $vpcId) {
$root = CloudVpc::where('id', $vpcId)->lockForUpdate()->first();
if ($root !== null) {
$roots[$vpcId] = $root;
}
}
foreach ($roots as $vpcId => $root) {
$isTarget = $vpcId === (int) $targetVpc->id;
// A tenant may garbage-collect only its own historical VPC
// identities. Super administrators retain the existing
// cross-account attach capability.
if (!$isTarget && !self::isGlobal($actor)
&& (int) $root->user_id !== (int) $instance->user_id) {
continue;
}
self::releasePersistedDeletedMemberTombstonesLocked($root);
}
}, 3);
}
/**
* Physically release old `deleted` rows only when the durable root,
* current operation and complete historical host ledger prove absence.
* Invalid/orphan rows remain reserved and therefore fail closed.
*/
private static function releasePersistedDeletedMemberTombstonesLocked(
CloudVpc $vpc
): int {
if (in_array((string) $vpc->state, ['deleting', 'deleted'], true)) {
// Root deletion owns every child identity and its signed retiring
// manifest. Never shrink that set from the ordinary attach lane.
return 0;
}
// Preserve the common VPC -> operation -> deployment -> child lock
// order used by recordObserved()/control-plane mutations. The root is
// already locked by the caller, so this unlocked revision probe cannot
// change until this transaction completes.
$deletedProofRows = CloudVpcMember::where('vpc_id', $vpc->id)
->where('state', 'deleted')->get(['observed_revision', 'host_id']);
$proofRevisions = $deletedProofRows->pluck('observed_revision')->map(
static fn ($value): int => (int) $value
)->filter(static fn (int $value): bool => $value > 0)->all();
$ownerHostIds = $deletedProofRows->pluck('host_id')->map(
static fn ($value): int => (int) $value
)->filter(static fn (int $value): bool => $value > 0)
->unique()->values()->all();
// The root observed marker is the latest globally succeeded revision,
// even while a newer desired revision is pending/uncertain. Absence of
// an identity is monotonic because its retained unique row prevents a
// later desired document from adding it back.
$rootProof = self::rootObservedProof($vpc);
if ($rootProof !== null) {
$proofRevisions[] = $rootProof['revision'];
}
// A VM lifecycle readback may have marked the pair deleted before the
// all-host operation that actually removed its owner. Keep that exact
// deployment revision as a candidate and replay its canonical
// operation instead of trusting the mutable deployment row alone.
if ($ownerHostIds !== []) {
$proofRevisions = array_merge($proofRevisions,
CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->whereIn('host_id', $ownerHostIds)
->where('state', 'deleted')->pluck('desired_revision')->map(
static fn ($value): int => (int) $value
)->filter(static fn (int $value): bool => $value > 0)->all()
);
}
$proofRevisions = array_values(array_unique($proofRevisions));
if ($proofRevisions === []) {
return 0;
}
$operations = CloudVpcOperation::where('vpc_id', $vpc->id)
->whereIn('desired_revision', $proofRevisions)
->where('status', 'succeeded')->orderBy('id')
->lockForUpdate()->get();
$deployments = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->orderBy('host_id')->lockForUpdate()->get()->keyBy(
static fn ($row): int => (int) $row->host_id
);
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->where('state', 'deleted')->orderBy('id')->lockForUpdate()->get();
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->where('state', 'deleted')->orderBy('id')->lockForUpdate()->get()
->keyBy(static fn ($row): int => (int) $row->id);
if ($members->isEmpty()) {
return 0;
}
$memberRouteRefs = CloudVpcRoute::whereIn('member_id',
$members->pluck('id')->map(static fn ($value): int => (int) $value)->all())
->whereNotIn('state', ['deleted'])->pluck('member_id')->mapWithKeys(
static fn ($value): array => [(int) $value => true]
)->all();
$addressRouteRefs = CloudVpcRoute::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted'])
->get(['next_hop_ip', 'destination_cidr']);
$nextHopIps = $addressRouteRefs->pluck('next_hop_ip')->mapWithKeys(
static fn ($value): array => [(string) $value => true]
)->all();
$routeDestinations = $addressRouteRefs->pluck('destination_cidr')->mapWithKeys(
static fn ($value): array => [(string) $value => true]
)->all();
$instances = CloudInstance::whereIn('id', $members->pluck('instance_id')->all())
->get(['id', 'uuid'])->keyBy(static fn ($row): int => (int) $row->id);
// Decode, hash and replay each candidate operation only once while the
// root/deployment ledger is locked. Pair checks below are then O(1).
$proofSummaries = self::historicalOperationProofSummaries(
$vpc, $operations, $deployments
);
$memberIds = [];
$privateIds = [];
foreach ($members as $member) {
$privateId = (int) ($member->private_ip_id ?? 0);
$private = $privateIps->get($privateId);
$pairExact = $private !== null
&& preg_match(self::KEY_PATTERN, (string) $member->member_key) === 1
&& (int) $member->host_id > 0
&& filter_var((string) $member->private_ip,
FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) !== false
&& (int) $member->observed_revision > 0
&& (int) $private->observed_revision
=== (int) $member->observed_revision
&& self::digestMatches(
(string) $member->observed_digest,
(string) $private->observed_digest
)
&& ($member->last_error_code ?? null) === null
&& ($private->last_error_code ?? null) === null
&& (int) $private->member_id === (int) $member->id
&& (int) $private->instance_id === (int) $member->instance_id
&& (int) $private->subnet_id === (int) $member->subnet_id
&& (string) $private->private_ip === (string) $member->private_ip
&& (int) $private->private_ip_int === (int) $member->private_ip_int;
if (!$pairExact
|| isset($memberRouteRefs[(int) $member->id])
|| isset($nextHopIps[(string) $private->private_ip])
|| isset($routeDestinations[(string) $private->private_ip . '/32'])
|| !self::persistedDeletedPairProofValid(
$member, $private,
strtolower((string) ($instances->get(
(int) $member->instance_id
)?->uuid ?? '')),
$deployments->get((int) $member->host_id),
$rootProof, $proofSummaries
)) {
continue;
}
$memberIds[] = (int) $member->id;
$privateIds[] = $privateId;
}
if ($memberIds === []) {
return 0;
}
CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('id', $privateIds)->delete();
CloudVpcMember::where('vpc_id', $vpc->id)
->whereIn('id', $memberIds)->delete();
return count($memberIds);
}
/** Validate one pair against precomputed immutable operation proofs. */
private static function persistedDeletedPairProofValid(
CloudVpcMember $member, CloudVpcPrivateIp $private,
string $instanceUuid, $ownerDeployment, ?array $rootProof,
array $proofSummaries
): bool {
$pairRevision = (int) $member->observed_revision;
$pairDigest = self::safeDigest($member->observed_digest);
$memberCreatedAt = (int) ($member->created_at ?? 0);
$privateCreatedAt = (int) ($private->created_at ?? 0);
if ($pairRevision < 1 || $pairDigest === null
|| $memberCreatedAt < 1 || $privateCreatedAt < 1) {
return false;
}
$pairCreatedAt = max($memberCreatedAt, $privateCreatedAt);
$ownerProof = null;
if (self::hostDeploymentRemovalProven($ownerDeployment)) {
$ownerDigest = self::safeDigest($ownerDeployment->desired_digest);
if ($ownerDigest !== null) {
$ownerProof = [
'revision' => (int) $ownerDeployment->desired_revision,
'digest' => $ownerDigest,
];
}
}
$retiredCidr = (string) $private->private_ip . '/32';
$candidateRevisions = [$pairRevision];
if ($rootProof !== null) {
$candidateRevisions[] = (int) $rootProof['revision'];
}
if ($ownerProof !== null) {
$candidateRevisions[] = (int) $ownerProof['revision'];
}
$candidateRevisions = array_values(array_unique($candidateRevisions));
rsort($candidateRevisions, SORT_NUMERIC);
foreach ($candidateRevisions as $revision) {
$summary = $proofSummaries[$revision] ?? null;
if (!is_array($summary)) {
continue;
}
$digest = (string) ($summary['digest'] ?? '');
if ($revision < $pairRevision
|| (int) ($summary['created_at'] ?? 0) < $pairCreatedAt) {
continue;
}
$pairBound = $revision === $pairRevision
&& hash_equals($pairDigest, $digest);
$rootBound = $rootProof !== null
&& $revision === (int) $rootProof['revision']
&& hash_equals((string) $rootProof['digest'], $digest);
$ownerBound = $ownerProof !== null
&& $revision === (int) $ownerProof['revision']
&& hash_equals((string) $ownerProof['digest'], $digest);
if (!$pairBound && !$rootBound && !$ownerBound) {
continue;
}
$ownerCovered = isset($summary['covered_host_ids'][
(int) $member->host_id
]);
if (!$ownerCovered) {
$omittedOwnerProof = $summary['omitted_removed_hosts'][
(int) $member->host_id
] ?? null;
$ownerCovered = is_array($omittedOwnerProof)
&& (int) ($omittedOwnerProof['revision'] ?? 0)
=== $pairRevision
&& (int) ($omittedOwnerProof['proved_at'] ?? 0)
>= $pairCreatedAt
&& self::digestMatches(
$pairDigest,
(string) ($omittedOwnerProof['digest'] ?? '')
);
}
if (isset($summary['member_ids'][(string) $member->member_key])
|| isset($summary['private_ip_cidrs'][$retiredCidr])
|| ($instanceUuid !== ''
&& isset($summary['instance_uuids'][$instanceUuid]))
|| isset($summary['route_destinations'][$retiredCidr])
|| isset($summary['route_next_members'][
(string) $member->member_key
])
|| !$ownerCovered) {
continue;
}
return true;
}
return false;
}
/** Latest globally succeeded root marker, including under a newer pending target. */
private static function rootObservedProof(CloudVpc $vpc): ?array
{
$revision = (int) $vpc->observed_revision;
$digest = self::safeDigest($vpc->observed_digest);
return $revision > 0 && $digest !== null
&& (int) ($vpc->last_success_at ?? 0) > 0
? ['revision' => $revision, 'digest' => $digest] : null;
}
/** Build each expensive all-host proof once per locked cleanup transaction. */
private static function historicalOperationProofSummaries(
CloudVpc $vpc, $operations, $deployments
): array {
$summaries = [];
foreach ($operations as $operation) {
$summary = self::historicalOperationProofSummary(
$vpc, $operation, $deployments
);
if ($summary !== null) {
$summaries[(int) $summary['revision']] = $summary;
}
}
krsort($summaries, SORT_NUMERIC);
return $summaries;
}
/**
* Rebuild one signed target and verify its complete immutable host
* observation, returning compact presence/coverage sets for O(1) pair
* checks. Mutable omitted deployment receipts close the global ledger but
* never count as owner coverage unless they are bound to this operation.
*/
private static function historicalOperationProofSummary(
CloudVpc $vpc, CloudVpcOperation $operation, $deployments
): ?array {
$createdAt = (int) ($operation->created_at ?? 0);
$finishedAt = (int) ($operation->finished_at ?? 0);
$revision = (int) $operation->desired_revision;
if ((string) $operation->status !== 'succeeded'
|| ($operation->error_code ?? null) !== null
|| (int) ($operation->evidence_version ?? 0)
< self::OBSERVATION_EVIDENCE_VERSION
|| $revision < 1 || $createdAt < 1 || $finishedAt < $createdAt) {
return null;
}
$payload = json_decode((string) $operation->payload_json, true);
$observed = json_decode((string) ($operation->observed_json ?? ''), true);
$digest = is_array($payload)
? self::safeDigest($payload['desired_digest'] ?? null) : null;
if (!is_array($payload) || !is_array($observed) || $digest === null
|| (string) ($payload['operation_id'] ?? '')
!== (string) $operation->operation_id
|| (string) ($payload['vpc_id'] ?? '') !== (string) $vpc->vpc_key
|| (int) ($payload['desired_revision'] ?? 0) !== $revision) {
return null;
}
try {
$document = $payload;
unset($document['operation_id'], $document['desired_digest']);
if (!hash_equals(
$digest, hash('sha256', self::canonicalJson($document))
)) {
return null;
}
} catch (\Throwable) {
return null;
}
$payloadMembers = $payload['members'] ?? null;
$payloadHosts = $payload['hosts'] ?? null;
$desiredRoutes = $payload['routes'] ?? null;
if (!is_array($payloadMembers) || !array_is_list($payloadMembers)
|| !is_array($payloadHosts) || !array_is_list($payloadHosts)
|| !is_array($desiredRoutes) || !array_is_list($desiredRoutes)) {
return null;
}
try {
$expectedVpcCidr = self::cidr(
$payload['cidr'] ?? null, 16, 24, 'VPC CIDR'
)['cidr'];
} catch (\Throwable) {
return null;
}
if (!is_string($payload['cidr'] ?? null)
|| !hash_equals($expectedVpcCidr, (string) $payload['cidr'])) {
return null;
}
$expectedMembersByHost = [];
$allMembers = [];
$memberIds = [];
$privateIpCidrs = [];
$instanceUuids = [];
$expectedDestinations = [];
foreach ($payloadMembers as $row) {
if (!is_array($row)
|| !is_string($row['member_id'] ?? null)
|| preg_match(self::KEY_PATTERN, (string) $row['member_id']) !== 1
|| !is_string($row['host_id'] ?? null)
|| preg_match('/^[1-9][0-9]*$/D', (string) $row['host_id']) !== 1
|| (int) $row['host_id'] > 1000000000
|| !is_string($row['private_ip_cidr'] ?? null)) {
return null;
}
$memberId = (string) $row['member_id'];
$hostId = (string) $row['host_id'];
if (isset($allMembers[$memberId])) {
return null;
}
$row['private_mac'] = strtolower((string) ($row['private_mac'] ?? ''));
$expectedMembersByHost[$hostId][$memberId] = $row;
$allMembers[$memberId] = $row;
$memberIds[$memberId] = true;
$privateIpCidrs[(string) $row['private_ip_cidr']] = true;
if (is_string($row['instance_uuid'] ?? null)
&& (string) $row['instance_uuid'] !== '') {
$instanceUuids[strtolower((string) $row['instance_uuid'])] = true;
}
$expectedDestinations[] = (string) $row['private_ip_cidr'];
}
$routeDestinations = [];
$routeNextMembers = [];
foreach ($desiredRoutes as $route) {
if (!is_array($route)
|| !is_string($route['destination_cidr'] ?? null)
|| !is_string($route['next_hop_member_id'] ?? null)
|| !isset($allMembers[(string) $route['next_hop_member_id']])) {
return null;
}
$destination = (string) $route['destination_cidr'];
$nextMember = (string) $route['next_hop_member_id'];
$routeDestinations[$destination] = true;
$routeNextMembers[$nextMember] = true;
$expectedDestinations[] = $destination;
}
$expectedDestinations = array_values(array_unique($expectedDestinations));
$expectedHosts = [];
foreach ($payloadHosts as $host) {
if (!is_array($host)
|| !is_string($host['host_id'] ?? null)
|| preg_match('/^[1-9][0-9]*$/D', (string) $host['host_id']) !== 1
|| (int) $host['host_id'] > 1000000000
|| !is_array($host['members'] ?? null)
|| !array_is_list($host['members'])) {
return null;
}
$hostId = (string) $host['host_id'];
if (isset($expectedHosts[$hostId])) {
return null;
}
$declared = [];
foreach ($host['members'] as $declaredMember) {
if (!is_string($declaredMember)
|| preg_match(self::KEY_PATTERN, $declaredMember) !== 1) {
return null;
}
$declared[] = $declaredMember;
}
$calculated = array_keys($expectedMembersByHost[$hostId] ?? []);
sort($declared, SORT_STRING);
sort($calculated, SORT_STRING);
if ($declared !== $calculated) {
return null;
}
$expectedHosts[$hostId] = true;
}
foreach (array_keys($expectedMembersByHost) as $hostId) {
if (!isset($expectedHosts[(string) $hostId])) {
return null;
}
}
$observedHosts = [];
foreach (is_array($observed['hosts'] ?? null) ? $observed['hosts'] : []
as $key => $item) {
if (!is_array($item)) {
return null;
}
$hostId = (string) ($item['host_id'] ?? $key);
if (preg_match('/^[1-9][0-9]*$/D', $hostId) !== 1
|| (int) $hostId > 1000000000
|| isset($observedHosts[$hostId])) {
return null;
}
$observedHosts[$hostId] = $item;
}
$coveredHostIds = [];
$omittedRemovedHosts = [];
$typedObservationUsed = false;
foreach ($expectedHosts as $hostId => $_present) {
$item = $observedHosts[$hostId] ?? null;
$localMembers = $expectedMembersByHost[$hostId] ?? [];
$exact = is_array($item)
&& ($item['transport_verified'] ?? false) === true
&& ($item['private_dataplane_verified'] ?? false) === true
&& ($localMembers !== [] || ($item['removed'] ?? false) === true)
&& self::validateHostDataplaneEvidence(
$item, $hostId, $localMembers,
array_values($allMembers), $expectedDestinations,
$expectedVpcCidr, $desiredRoutes,
(string) $vpc->vpc_key,
$revision, $digest
) === null;
if ($exact) {
$typedObservationUsed = true;
$coveredHostIds[(int) $hostId] = true;
continue;
}
$deployment = $deployments->get((int) $hostId);
if ($localMembers !== []
|| !self::deploymentRemovalMatchesProof(
$deployment, $revision, $digest
)) {
return null;
}
$coveredHostIds[(int) $hostId] = true;
}
foreach ($observedHosts as $hostId => $item) {
if (isset($expectedHosts[$hostId])) {
continue;
}
$deployment = $deployments->get((int) $hostId);
if (($item['removed'] ?? false) !== true
|| ($item['transport_verified'] ?? false) !== true
|| ($item['private_dataplane_verified'] ?? false) !== true
|| !self::deploymentRemovalMatchesProof(
$deployment, $revision, $digest
)
|| self::validateHostDataplaneEvidence(
$item, $hostId, [], array_values($allMembers),
$expectedDestinations, $expectedVpcCidr, $desiredRoutes,
(string) $vpc->vpc_key, $revision, $digest
) !== null) {
return null;
}
$typedObservationUsed = true;
$coveredHostIds[(int) $hostId] = true;
}
foreach ($deployments as $hostId => $deployment) {
if (isset($expectedHosts[(string) $hostId])) {
continue;
}
if ((int) $deployment->created_at <= $createdAt) {
if (!self::hostDeploymentRemovalProven($deployment)) {
return null;
}
$removalDigest = self::safeDigest($deployment->desired_digest);
if ($removalDigest === null) {
return null;
}
// This closes the later operation's global host ledger, but
// pair ownership may use it only when its own exact local
// observation has the same revision and digest.
$omittedRemovedHosts[(int) $hostId] = [
'revision' => (int) $deployment->desired_revision,
'digest' => $removalDigest,
'proved_at' => (int) $deployment->last_success_at,
];
}
}
if (!$typedObservationUsed) {
$terminal = $observed['no_data_plane_terminal_proof'] ?? null;
if (!is_array($terminal)
|| (int) ($terminal['revision'] ?? 0) !== $revision
|| !self::digestMatches(
$digest, (string) ($terminal['digest'] ?? '')
)
|| !in_array((string) ($terminal['gate'] ?? ''), [
'vpc_no_members', 'vpc_no_participating_hosts',
], true)) {
return null;
}
}
return [
'operation_id' => (string) $operation->operation_id,
'revision' => $revision,
'digest' => $digest,
'created_at' => $createdAt,
'finished_at' => $finishedAt,
'member_ids' => $memberIds,
'private_ip_cidrs' => $privateIpCidrs,
'instance_uuids' => $instanceUuids,
'route_destinations' => $routeDestinations,
'route_next_members' => $routeNextMembers,
'covered_host_ids' => $coveredHostIds,
'omitted_removed_hosts' => $omittedRemovedHosts,
];
}
/** A stored host absence proof bound to one historical operation target. */
private static function deploymentRemovalMatchesProof(
$deployment, int $revision, string $digest
): bool {
return self::hostDeploymentRemovalProven($deployment)
&& (int) $deployment->desired_revision === $revision
&& (int) $deployment->observed_revision === $revision
&& self::digestMatches($digest, (string) $deployment->desired_digest)
&& self::digestMatches($digest, (string) $deployment->observed_digest);
}
/**
* Release member and lease tombstones after the complete host set has
* supplied exact persistent libvirt/host configuration readback for this
* desired revision. Guest readiness is a separate usability gate and must
* not keep a proven-absent historical NIC/address identity allocated.
*
* Keeping terminal rows would continue to occupy the global instance and
* private-address unique keys. Validate the one-to-one ledger under the
* VPC transaction before deleting either side so a corrupt/orphan lease can
* never be mistaken for safely reusable capacity.
*/
private static function releaseMemberTombstones(
CloudVpc $vpc, int $revision, string $digest, bool $includeDeleting,
array $currentConfigExactHostIds
): int {
$states = $includeDeleting ? ['deleting', 'deleted'] : ['deleted'];
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->whereIn('state', $states)->orderBy('id')->lockForUpdate()->get();
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('state', $states)->orderBy('id')->lockForUpdate()->get();
if ($members->isEmpty() && $privateIps->isEmpty()) {
return 0;
}
if ($members->count() !== $privateIps->count()) {
throw new CloudError('VPC 待释放成员与私网地址账本数量不一致', 409);
}
$privateById = $privateIps->keyBy(
static fn ($row): int => (int) $row->id
);
$ownerHostIds = $members->pluck('host_id')->map(
static fn ($id): int => (int) $id
)->unique()->values()->all();
$owners = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->whereIn('host_id', $ownerHostIds)->lockForUpdate()->get()->keyBy(
static fn ($row): int => (int) $row->host_id
);
$usedPrivateIds = [];
$memberIds = [];
foreach ($members as $member) {
$privateId = (int) ($member->private_ip_id ?? 0);
$private = $privateById[$privateId] ?? null;
$memberState = (string) $member->state;
$owner = $owners->get((int) $member->host_id);
$ownerConfigCurrent = isset(
$currentConfigExactHostIds[(int) $member->host_id]
) && $owner !== null
&& (int) $owner->desired_revision === $revision
&& self::digestMatches($digest, (string) $owner->desired_digest);
$ownerRemoved = $owner !== null
&& self::hostDeploymentRemovalProven($owner);
$deletedPairProven = $memberState !== 'deleted' || (
(int) $member->observed_revision > 0
&& (int) $member->observed_revision === (int) $private?->observed_revision
&& self::digestMatches(
(string) $member->observed_digest,
(string) $private?->observed_digest
)
);
if ($privateId < 1 || $private === null || isset($usedPrivateIds[$privateId])
|| (string) $private->state !== $memberState
|| (int) $member->desired_revision !== $revision
|| !self::digestMatches($digest, (string) $member->desired_digest)
|| (int) $private->desired_revision !== $revision
|| !self::digestMatches($digest, (string) $private->desired_digest)
|| (int) $private->member_id !== (int) $member->id
|| (int) $private->instance_id !== (int) $member->instance_id
|| (int) $private->subnet_id !== (int) $member->subnet_id
|| (string) $private->private_ip !== (string) $member->private_ip
|| !$deletedPairProven
|| (!$ownerConfigCurrent && !$ownerRemoved)) {
throw new CloudError('VPC 待释放成员与私网地址账本不一致', 409);
}
$usedPrivateIds[$privateId] = true;
$memberIds[] = (int) $member->id;
}
if (count($usedPrivateIds) !== $privateIps->count()) {
throw new CloudError('VPC 待释放私网地址存在孤立账本', 409);
}
$privateIds = array_map('intval', array_keys($usedPrivateIds));
CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('id', $privateIds)->delete();
CloudVpcMember::where('vpc_id', $vpc->id)
->whereIn('id', $memberIds)->delete();
return count($memberIds);
}
/** Whether a deployment row retains a complete monotonic absence proof. */
private static function hostDeploymentRemovalProven($deployment): bool
{
if ($deployment === null || (string) $deployment->state !== 'deleted') {
return false;
}
$revision = (int) $deployment->desired_revision;
$desiredDigest = (string) ($deployment->desired_digest ?? '');
return $revision > 0
&& (int) $deployment->observed_revision === $revision
&& self::digestMatches($desiredDigest, (string) $deployment->observed_digest)
&& ($deployment->last_error_code ?? null) === null
&& (int) ($deployment->last_success_at ?? 0) > 0;
}
/** Release empty subnet identity rows after an exact current proof. */
private static function releaseSubnetTombstones(
CloudVpc $vpc, int $revision, string $digest
): int {
$subnets = CloudVpcSubnet::where('vpc_id', $vpc->id)
->where('state', 'deleting')->orderBy('id')->lockForUpdate()->get();
if ($subnets->isEmpty()) {
return 0;
}
$subnetIds = [];
foreach ($subnets as $subnet) {
if ((int) $subnet->desired_revision !== $revision
|| !self::digestMatches($digest, (string) $subnet->desired_digest)) {
throw new CloudError('VPC 待释放子网版本与当前目标不一致', 409);
}
$subnetIds[] = (int) $subnet->id;
}
if (CloudVpcMember::where('vpc_id', $vpc->id)
->whereIn('subnet_id', $subnetIds)->exists()
|| CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('subnet_id', $subnetIds)->exists()) {
throw new CloudError('VPC 待释放子网仍被成员或地址账本引用', 409);
}
CloudVpcSubnet::where('vpc_id', $vpc->id)
->whereIn('id', $subnetIds)->delete();
return count($subnetIds);
}
/**
* Persist runtime readiness independently for each live member/lease.
* Host configuration is already exact when this method is called; only a
* matching guest proof may advance one pair to active for this revision.
*/
private static function persistMemberGuestEvidence(
CloudVpc $vpc,
int $revision,
string $digest,
string $operationId,
array $expectedMembers,
array $memberGuestEvidence,
int $observedAt
): void {
$members = CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])
->orderBy('id')->lockForUpdate()->get()
->keyBy(static fn ($row): string => (string) $row->member_key);
if ($members->count() !== count($expectedMembers)) {
throw new CloudError('VPC 成员来宾证据账本不一致', 409);
}
$privateIds = $members->pluck('private_ip_id')->map(
static fn ($id): int => (int) $id
)->filter(static fn (int $id): bool => $id > 0)->values()->all();
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('id', $privateIds)->orderBy('id')->lockForUpdate()->get()->keyBy('id');
foreach ($expectedMembers as $memberId => $expected) {
$member = $members->get((string) $memberId);
$private = $member === null ? null
: $privateIps->get((int) $member->private_ip_id);
$expectedIp = is_array($expected)
? preg_replace('/\/32$/D', '', (string) ($expected['private_ip_cidr'] ?? ''))
: null;
if ($member === null || $private === null || !is_array($expected)
|| $expectedIp === null || $expectedIp === ''
|| (int) $member->host_id !== (int) ($expected['host_id'] ?? 0)
|| (string) $member->private_ip !== $expectedIp
|| (int) $private->member_id !== (int) $member->id
|| (int) $private->instance_id !== (int) $member->instance_id
|| (int) $private->subnet_id !== (int) $member->subnet_id
|| (string) $private->private_ip !== (string) $member->private_ip
|| (int) $member->desired_revision !== $revision
|| (int) $private->desired_revision !== $revision
|| !self::digestMatches($digest, (string) $member->desired_digest)
|| !self::digestMatches($digest, (string) $private->desired_digest)) {
throw new CloudError('VPC 成员来宾证据账本不一致', 409);
}
$runtimeEvidence = $memberGuestEvidence[(string) $memberId] ?? null;
$runtimeState = is_array($runtimeEvidence)
? (string) ($runtimeEvidence['state'] ?? 'degraded') : 'degraded';
$errorCode = is_array($runtimeEvidence)
? ($runtimeEvidence['error_code'] ?? null)
: 'vpc_private_observation_missing';
$configShapeExact = is_array($runtimeEvidence)
&& ($runtimeEvidence['xml_verified'] ?? false) === true
&& ($runtimeEvidence['config_verified'] ?? false) === true
&& ($runtimeEvidence['seed_verified'] ?? false) === true
&& ($runtimeEvidence['restart_required'] ?? null) === false;
$activeExact = $runtimeState === 'active' && $configShapeExact
&& ($runtimeEvidence['domain_running'] ?? false) === true
&& ($runtimeEvidence['guest_exact'] ?? false) === true
&& ($runtimeEvidence['guest_network_verified'] ?? false) === true
&& ($runtimeEvidence['guest_network_readback'] ?? null) === 'confirmed'
&& ($runtimeEvidence['link_state'] ?? null) === 'up'
&& ($runtimeEvidence['guest_link_state'] ?? null) === 'up';
$suspendedExact = $runtimeState === 'suspended' && $configShapeExact
&& ($runtimeEvidence['domain_running'] ?? false) === true
&& ($runtimeEvidence['link_state'] ?? null) === 'down';
$stoppingExact = $runtimeState === 'stopping' && $configShapeExact
&& ($runtimeEvidence['domain_running'] ?? false) === true
&& in_array(($runtimeEvidence['link_state'] ?? null),
['up', 'down'], true);
$stoppedExact = $runtimeState === 'stopped' && $configShapeExact
&& ($runtimeEvidence['domain_running'] ?? null) === false
&& in_array(($runtimeEvidence['link_state'] ?? null),
['up', 'down'], true);
$exact = $activeExact || $suspendedExact || $stoppingExact
|| $stoppedExact;
if ($exact) {
$member->observed_revision = $revision;
$member->observed_digest = $digest;
$member->state = $stoppedExact ? 'stopped'
: ($stoppingExact ? 'stopping'
: ($suspendedExact ? 'suspended' : 'active'));
$member->last_operation_id = $operationId;
$member->last_error_code = $stoppedExact
? 'vpc_private_guest_stopped'
: ($stoppingExact ? 'vpc_private_guest_shutdown_pending'
: ($suspendedExact ? 'vpc_private_network_suspended' : null));
$private->observed_revision = $revision;
$private->observed_digest = $digest;
$private->state = $member->state;
$private->last_error_code = $member->last_error_code;
} else {
$safeError = self::deferredEvidenceError($errorCode)
?? 'vpc_private_observation_mismatch';
$member->state = 'degraded';
$member->last_error_code = $safeError;
$private->state = 'degraded';
$private->last_error_code = $safeError;
}
$member->updated_at = $observedAt;
$member->save();
$private->updated_at = $observedAt;
$private->save();
}
}
private static function touchDesiredLocked(CloudVpc $vpc, string $kind,
string $requestKey, string $requestHash): array
{
$vpc = CloudVpc::where('id', $vpc->id)->lockForUpdate()->firstOrFail();
$existing = CloudVpcOperation::where('vpc_id', $vpc->id)
->where('idempotency_key', $requestKey)->lockForUpdate()->first();
if ($existing !== null) {
if ((string) $existing->kind !== $kind
|| !hash_equals((string) $existing->request_hash, $requestHash)) {
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
return ['vpc' => $vpc, 'operation' => $existing, 'unchanged' => true];
}
$revision = (int) $vpc->desired_revision + 1;
$vpc->desired_revision = $revision;
$vpc->state = $kind === 'vpc_delete' ? 'deleting' : 'applying';
$vpc->sync_state = 'pending';
$vpc->last_error_code = null;
$vpc->updated_at = time();
$vpc->save();
// A VPC mutation replaces the complete typed document. Keep older
// queued/running/uncertain rows only as audit history; they must never
// be retried after this revision becomes the current target.
$now = time();
CloudVpcOperation::where('vpc_id', $vpc->id)
->whereIn('status', ['queued', 'running', 'uncertain', 'waiting_observed'])
->where('desired_revision', '<', $revision)
->update([
'status' => 'superseded',
'error_code' => 'vpc_revision_superseded',
'finished_at' => $now,
'lease_token' => null,
'lease_until' => 0,
'updated_at' => $now,
]);
$children = [
CloudVpcSubnet::where('vpc_id', $vpc->id)->get(),
CloudVpcPrivateIp::where('vpc_id', $vpc->id)->get(),
CloudVpcMember::where('vpc_id', $vpc->id)->get(),
CloudVpcRoute::where('vpc_id', $vpc->id)->get(),
CloudVpcAclRule::where('vpc_id', $vpc->id)->get(),
];
foreach ($children as $rows) {
foreach ($rows as $row) {
$row->desired_revision = $revision;
$row->desired_digest = null;
$row->updated_at = time();
$row->save();
}
}
$hostIds = CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted', 'deleting'])
->orderBy('host_id')->pluck('host_id')->unique()->values()->all();
$hostIdSet = array_fill_keys(array_map('intval', $hostIds), true);
$existingHosts = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->lockForUpdate()->get()->keyBy('host_id');
foreach ($hostIds as $hostId) {
$row = $existingHosts[(int) $hostId] ?? new CloudVpcHostDeployment();
if ($row->exists === false) {
$row->vpc_id = $vpc->id;
$row->host_id = (int) $hostId;
$row->created_at = time();
}
$row->fabric_revision = (int) $vpc->fabric_revision;
$row->desired_revision = $revision;
$row->desired_digest = null;
$row->state = 'applying';
$row->last_operation_id = null;
$row->updated_at = time();
$row->save();
}
foreach ($existingHosts as $hostId => $row) {
if ((string) $row->state === 'deleted') {
continue;
}
if (!isset($hostIdSet[(int) $hostId])) {
$row->state = 'deleting';
$row->desired_revision = $revision;
$row->updated_at = time();
$row->save();
}
}
$document = $kind === 'vpc_delete'
? self::deletionDocument($vpc) : self::desiredDocument($vpc);
$digest = hash('sha256', self::canonicalJson($document));
$vpc->desired_digest = $digest;
$vpc->updated_at = time();
$vpc->save();
$operationId = self::randomKey();
$document['desired_digest'] = $digest;
$document['operation_id'] = $operationId;
$operation = new CloudVpcOperation();
$operation->operation_id = $operationId;
$operation->vpc_id = $vpc->id;
$operation->user_id = $vpc->user_id;
$operation->kind = $kind;
$operation->desired_revision = $revision;
$operation->idempotency_key = $requestKey;
$operation->request_hash = $requestHash;
$operation->status = 'queued';
$operation->evidence_version = 0;
$operation->payload_json = json_encode($document,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$operation->created_at = $operation->updated_at = time();
$operation->save();
$vpc->last_operation_id = $operationId;
$vpc->save();
CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->where('desired_revision', $revision)->update([
'desired_digest' => $digest,
'last_operation_id' => $operationId,
'updated_at' => time(),
]);
foreach ($children as $rows) {
foreach ($rows as $row) {
$row->desired_digest = $digest;
$row->updated_at = time();
$row->save();
}
}
return ['vpc' => $vpc, 'operation' => $operation, 'unchanged' => false];
}
/** Lock and resolve the one platform-managed subnet used for member IPAM. */
private static function lockedAutomaticSubnet(CloudVpc $vpc): CloudVpcSubnet
{
$rows = CloudVpcSubnet::where('vpc_id', $vpc->id)
->orderBy('id')->lockForUpdate()->get();
$live = [];
$deleting = false;
foreach ($rows as $row) {
$state = (string) $row->state;
if ($state === 'deleted') {
continue;
}
if ($state === 'deleting') {
$deleting = true;
continue;
}
if (!in_array($state, self::LIVE_STATES, true)) {
throw new CloudError('VPC 自动子网账本状态无效,请联系管理员', 503);
}
$live[] = $row;
}
if ($deleting) {
throw new CloudError('VPC 自动子网正在清理,请稍后重试', 409);
}
if ($live === []) {
throw new CloudError('VPC 自动子网尚未可用', 409);
}
if (count($live) !== 1) {
throw new CloudError(
'VPC 存在多个活动子网,已停止自动分配,请联系管理员', 503
);
}
/** @var CloudVpcSubnet $subnet */
$subnet = $live[0];
if (!self::automaticSubnetRecordValid($vpc, $subnet)) {
throw new CloudError('VPC 自动子网账本无效,请联系管理员', 503);
}
return $subnet;
}
/** Validate one automatic-subnet row without taking a database lock. */
private static function automaticSubnetRecordValid(
CloudVpc $vpc,
CloudVpcSubnet $subnet
): bool {
if (!in_array((string) $subnet->state, self::LIVE_STATES, true)) {
return false;
}
try {
$root = self::cidr((string) $vpc->cidr, 16, 24, 'VPC CIDR');
$value = self::cidr(
(string) $subnet->cidr, (int) $root['prefix'], 30,
'自动子网 CIDR'
);
} catch (\Throwable) {
return false;
}
return (string) $subnet->cidr === $value['cidr']
&& preg_match(self::KEY_PATTERN, (string) $subnet->subnet_key) === 1
&& (int) $subnet->network_address === $value['network']
&& (int) $subnet->broadcast_address === $value['broadcast']
&& (int) $subnet->prefix_length === $value['prefix']
&& $value['network'] >= $root['network']
&& $value['broadcast'] <= $root['broadcast']
&& $subnet->gateway_ip === null;
}
/**
* Replay automatic member attachment before consulting mutable subnet or
* instance state. The immutable signed desired payload supplies the old
* subnet/IP fields needed to verify both former request hash shapes.
*/
private static function hasMemberAttachOperation(
CloudVpc $vpc,
string $requestKey,
int $instanceId,
?string $legacyRequestHash = null
): bool {
$operation = CloudVpcOperation::where('vpc_id', $vpc->id)
->where('idempotency_key', $requestKey)
->lockForUpdate()->first();
if ($operation === null) {
return false;
}
if ((string) $operation->kind !== 'member_attach') {
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
if ((int) $operation->user_id !== (int) $vpc->user_id) {
throw new CloudError('VPC 成员操作账本不完整,请联系管理员', 503);
}
if ($legacyRequestHash !== null) {
if (!hash_equals(
(string) $operation->request_hash, $legacyRequestHash
)) {
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
return true;
}
try {
$payload = json_decode(
(string) $operation->payload_json, true, 64, JSON_THROW_ON_ERROR
);
} catch (\Throwable) {
throw new CloudError('VPC 成员操作账本不完整,请联系管理员', 503);
}
if (!is_array($payload) || !is_array($payload['members'] ?? null)) {
throw new CloudError('VPC 成员操作账本不完整,请联系管理员', 503);
}
foreach ($payload['members'] as $member) {
if (!is_array($member)
|| !is_string($member['subnet_id'] ?? null)
|| preg_match(self::KEY_PATTERN, (string) $member['subnet_id']) !== 1) {
continue;
}
$privateCidr = $member['private_ip_cidr'] ?? null;
if (!is_string($privateCidr)
|| preg_match('/^([0-9.]+)\/32$/D', $privateCidr, $match) !== 1
|| filter_var($match[1], FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false) {
throw new CloudError('VPC 成员操作账本不完整,请联系管理员', 503);
}
$automaticHash = self::requestHash('member_attach', [
'subnet_key' => (string) $member['subnet_id'],
'instance_id' => $instanceId,
'private_ip' => null,
]);
$explicitHash = self::requestHash('member_attach', [
'subnet_key' => (string) $member['subnet_id'],
'instance_id' => $instanceId,
'private_ip' => $match[1],
]);
if (hash_equals((string) $operation->request_hash, $automaticHash)
|| hash_equals((string) $operation->request_hash, $explicitHash)) {
return true;
}
}
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
/** Check a request key while the VPC root row is already locked. */
private static function hasOperation(CloudVpc $vpc, string $requestKey,
string $kind, string $requestHash): bool
{
$operation = CloudVpcOperation::where('vpc_id', $vpc->id)
->where('idempotency_key', $requestKey)
->lockForUpdate()->first();
if ($operation === null) {
return false;
}
if ((string) $operation->kind !== $kind
|| !hash_equals((string) $operation->request_hash, $requestHash)) {
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
return true;
}
/**
* Return a previously committed create without consulting current policy.
*
* Historical create-operation hashes included platform-owned Fabric and
* CIDR defaults, so they cannot be compared with the stable tenant-intent
* hash introduced later. The deterministic root identity, immutable
* owner/name/region tuple, create operation and allocator linkage are the
* durable compatibility proof. Missing ledger rows fail closed.
*/
private static function replayCreateLocked(
CloudVpc $vpc,
array $actor,
int $userId,
int $regionId,
string $name,
string $requestKey,
string $allocationKey
): array {
if ((int) $vpc->user_id !== $userId
|| (int) ($actor['user_id'] ?? 0) !== $userId
|| (int) $vpc->region_id !== $regionId
|| !hash_equals((string) $vpc->name, $name)) {
throw new CloudError('同一请求幂等键的参数不一致', 409);
}
$operation = CloudVpcOperation::where('vpc_id', $vpc->id)
->where('idempotency_key', $requestKey)
->lockForUpdate()->first();
if ($operation === null
|| (string) $operation->kind !== 'vpc_create'
|| (int) $operation->user_id !== $userId) {
throw new CloudError('VPC 创建操作账本不完整,请联系管理员', 503);
}
$network = CloudPrivateNetwork::where(
'id', (int) $vpc->private_network_id
)->lockForUpdate()->first();
$deleted = (string) $vpc->state === 'deleted';
$networkStateValid = $network !== null && ($deleted
? ((string) $network->state === 'released'
&& $network->active_cidr === null)
: (in_array((string) $network->state,
['active', 'applying', 'degraded', 'uncertain'], true)
&& (string) $network->active_cidr === (string) $vpc->cidr));
if ($network === null
|| !$networkStateValid
|| (string) $network->allocation_key !== $allocationKey
|| (string) $network->vpc_key !== (string) $vpc->vpc_key
|| (int) $network->user_id !== $userId
|| (int) $network->region_id !== $regionId
|| (string) $network->cidr !== (string) $vpc->cidr
|| (!$deleted && CloudVpcSubnet::where('vpc_id', $vpc->id)
->orderBy('id')->lockForUpdate()->first() === null)) {
throw new CloudError('VPC 创建资源账本不完整,请联系管理员', 503);
}
CloudPrivateCidrAllocator::assertAllocationLedger($network);
return self::documentView($vpc, $actor);
}
/** Resolve the bounded deployment setting used by the account row lock. */
private static function accountVpcLimit(): int
{
$value = Config::get(
'cloud_max_vpcs_per_account', self::DEFAULT_MAX_VPCS_PER_ACCOUNT
);
$parsed = filter_var($value, FILTER_VALIDATE_INT, [
'options' => [
'min_range' => 1,
'max_range' => self::MAX_VPCS_PER_ACCOUNT,
],
]);
if ($parsed === false) {
throw new CloudError('账户 VPC 配额配置无效', 503);
}
return (int) $parsed;
}
private static function requestHash(string $kind, array $value): string
{
return hash('sha256', self::canonicalJson(['kind' => $kind, 'input' => $value]));
}
/** Match Python's json.dumps(sort_keys=True,separators=(',', ':')). */
private static function canonicalize($value)
{
if (!is_array($value)) {
return $value;
}
if (array_is_list($value)) {
return array_map(static fn ($item) => self::canonicalize($item), $value);
}
$keys = array_keys($value);
sort($keys, SORT_STRING);
$result = [];
foreach ($keys as $key) {
$result[$key] = self::canonicalize($value[$key]);
}
return $result;
}
private static function canonicalJson(array $value): string
{
return json_encode(self::canonicalize($value),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
}
private static function documentView(CloudVpc $vpc, array $actor = []): array
{
// Host placement is an administrator diagnostic. Ordinary tenants
// may see their VPC and member state, but must not learn the panel's
// host inventory or deployment revisions.
$includeHostDetails = self::canViewInfrastructure($actor);
$subnets = CloudVpcSubnet::where('vpc_id', $vpc->id)->orderBy('id')->get();
$members = CloudVpcMember::where('vpc_id', $vpc->id)->orderBy('id')->get();
$privateIps = CloudVpcPrivateIp::where('vpc_id', $vpc->id)->get()->keyBy('member_id');
$routes = CloudVpcRoute::where('vpc_id', $vpc->id)->orderBy('id')->get();
$acl = CloudVpcAclRule::where('vpc_id', $vpc->id)->orderBy('priority')->orderBy('id')->get();
$hosts = CloudVpcHostDeployment::where('vpc_id', $vpc->id)->orderBy('host_id')->get();
$operations = CloudVpcOperation::where('vpc_id', $vpc->id)->orderByDesc('id')->limit(20)->get();
return [
'vpc' => self::publicRoot($vpc, $includeHostDetails),
'subnets' => $subnets->map(static fn ($row): array => self::publicSubnet($row))->all(),
'members' => $members->map(static fn ($row): array => self::publicMember(
$row, $includeHostDetails, $privateIps[(int) $row->id] ?? null
))->all(),
'routes' => $routes->map(static fn ($row): array => self::publicRoute($row))->all(),
'acl_rules' => $acl->map(static fn ($row): array => self::publicAcl($row))->all(),
'hosts' => $includeHostDetails
? $hosts->map(static fn ($row): array => self::publicHost($row))->all()
: [],
'operations' => $operations->map(static fn ($row): array => self::publicOperation($row))->all(),
];
}
private static function publicRoot(CloudVpc $vpc, bool $includeInfrastructure = false): array
{
$desiredDigest = (string) ($vpc->desired_digest ?? '');
$observedDigest = (string) ($vpc->observed_digest ?? '');
$hostRows = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted'])->get();
$hostsReady = $hostRows->count() > 0;
$pendingTombstone = CloudVpcHostDeployment::where('vpc_id', $vpc->id)
->where('state', 'deleting')->exists();
foreach ([
CloudVpcSubnet::class,
CloudVpcPrivateIp::class,
CloudVpcMember::class,
CloudVpcRoute::class,
CloudVpcAclRule::class,
] as $childModel) {
if ($childModel::where('vpc_id', $vpc->id)->where('state', 'deleting')->exists()) {
$pendingTombstone = true;
break;
}
}
if ($pendingTombstone) {
$hostsReady = false;
}
// A VPC projection is not usable while any live member points at an
// instance that has left the active lifecycle state. This closes the
// window where a delete_failed/uncertain VM could leave an otherwise
// matching root digest looking healthy to the tenant UI.
$runtimeMembers = CloudVpcMember::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleted'])->get([
'id', 'instance_id', 'private_ip_id', 'state',
]);
$memberInstances = $runtimeMembers->pluck('instance_id')
->map(static fn ($id): int => (int) $id)
->unique()->values()->all();
if ($memberInstances !== []) {
$instanceStates = CloudInstance::whereIn('id', $memberInstances)
->get(['id', 'host_id', 'uuid', 'status', 'network_status'])
->keyBy('id');
$runtimeStates = CloudInstanceRuntimeService::forInstances(
$instanceStates->all()
);
$privateIds = $runtimeMembers->pluck('private_ip_id')
->map(static fn ($id): int => (int) $id)
->filter(static fn (int $id): bool => $id > 0)->values()->all();
$privateStates = CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereIn('id', $privateIds)->pluck('state', 'id');
foreach ($runtimeMembers as $runtimeMember) {
$runtime = $runtimeStates[
(string) ((int) $runtimeMember->instance_id)
] ?? null;
if ((string) $runtimeMember->state !== 'active'
|| (string) ($privateStates[(int) $runtimeMember->private_ip_id] ?? '')
!== 'active'
|| (string) ($instanceStates->get(
(int) $runtimeMember->instance_id
)?->status ?? '') !== 'active'
|| (string) ($instanceStates->get(
(int) $runtimeMember->instance_id
)?->network_status ?? '') !== 'active') {
$hostsReady = false;
break;
}
// Only a fresh, identity-bound running observation can support
// tenant usability. A graceful-shutdown transition, stopped,
// paused, crashed, unknown or stale cache is immediately
// non-usable even if the last VPC/QGA receipt was active.
if (!is_array($runtime)
|| ($runtime['state_fresh'] ?? false) !== true
|| (string) ($runtime['power_state'] ?? '') !== 'running') {
$hostsReady = false;
break;
}
}
}
foreach ($hostRows as $host) {
if ((string) $host->state !== 'active'
|| (int) $host->desired_revision !== (int) $vpc->desired_revision
|| (int) $host->observed_revision !== (int) $vpc->desired_revision
|| !self::digestMatches((string) $host->desired_digest, $desiredDigest)
|| !self::digestMatches((string) $host->observed_digest, $desiredDigest)) {
$hostsReady = false;
break;
}
}
$rootReady = self::digestMatches($desiredDigest, $observedDigest);
$currentOperation = null;
$currentOperationReady = false;
$lastOperationId = (string) ($vpc->last_operation_id ?? '');
if (preg_match(self::KEY_PATTERN, $lastOperationId) === 1) {
$currentOperation = CloudVpcOperation::where('vpc_id', $vpc->id)
->where('operation_id', $lastOperationId)
->where('desired_revision', (int) $vpc->desired_revision)
->first();
$currentOperationReady = $currentOperation !== null
&& (string) $currentOperation->status === 'succeeded'
&& (int) $currentOperation->evidence_version
>= self::OBSERVATION_EVIDENCE_VERSION;
}
$usable = (string) $vpc->state === 'active'
&& (string) $vpc->sync_state === 'applied'
&& (int) $vpc->desired_revision === (int) $vpc->observed_revision
&& $rootReady && $hostsReady && $currentOperationReady;
$rawErrorCode = trim((string) ($vpc->last_error_code ?? ''));
// setup_state is a read-only tenant projection. It also repairs the
// presentation of legacy empty roots that were persisted as failed
// with one of the two reviewed Fabric gate codes; GET never rewrites
// their operation or root ledger. First close every cheap structural
// gate. Successful exact revisions use the settled child ledger;
// only the legacy-failure fallback must rebuild and hash the current
// desired document.
$emptyGateErrors = ['vpc_no_members', 'vpc_no_participating_hosts'];
$successfulEmptyRevision = false;
$legacyEmptyFailure = false;
$awaitingMembers = !in_array((string) $vpc->state, ['deleting', 'deleted'], true)
&& $runtimeMembers->count() === 0
&& $hostRows->count() === 0
&& !$pendingTombstone
&& ($rawErrorCode === '' || in_array($rawErrorCode, $emptyGateErrors, true))
&& $currentOperation !== null;
if ($awaitingMembers) {
$successfulEmptyRevision = $currentOperationReady
&& (int) $vpc->observed_revision === (int) $vpc->desired_revision
&& self::digestMatches($desiredDigest, $observedDigest);
$legacyEmptyFailure = (string) $currentOperation->kind === 'vpc_create'
&& (string) $currentOperation->status === 'failed'
&& (int) $currentOperation->evidence_version
>= self::OBSERVATION_EVIDENCE_VERSION
&& in_array($rawErrorCode, $emptyGateErrors, true)
&& in_array(
(string) ($currentOperation->error_code ?? ''),
$emptyGateErrors,
true
);
$awaitingMembers = $successfulEmptyRevision || $legacyEmptyFailure;
}
if ($awaitingMembers) {
try {
$emptySubnets = CloudVpcSubnet::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])
->orderBy('id')->get();
$awaitingMembers = $emptySubnets->count() === 1
&& (int) $emptySubnets->first()->desired_revision
=== (int) $vpc->desired_revision
&& self::digestMatches(
(string) $emptySubnets->first()->desired_digest,
$desiredDigest
)
&& self::automaticSubnetRecordValid(
$vpc,
$emptySubnets->first()
)
&& !CloudVpcPrivateIp::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists()
&& !CloudVpcRoute::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists()
&& !CloudVpcAclRule::where('vpc_id', $vpc->id)
->whereNotIn('state', ['deleting', 'deleted'])->exists();
// A successful exact operation is already the signed proof
// for its revision. Rehashing the current document would
// reject a valid last-member detach because the released
// host/member tombstones are intentionally absent afterward.
// Legacy failed creates have no such success proof, so retain
// the stricter current-document digest validation for them.
if ($awaitingMembers && $legacyEmptyFailure) {
$emptyDesired = self::desiredDocument($vpc);
$awaitingMembers =
(int) ($emptyDesired['desired_revision'] ?? 0)
=== (int) $vpc->desired_revision
&& ($emptyDesired['hosts'] ?? null) === []
&& ($emptyDesired['members'] ?? null) === []
&& ($emptyDesired['routes'] ?? null) === []
&& ($emptyDesired['acls'] ?? null) === []
&& is_array($emptyDesired['subnets'] ?? null)
&& count($emptyDesired['subnets']) === 1
&& self::digestMatches(
$desiredDigest,
hash('sha256', self::canonicalJson($emptyDesired))
);
}
} catch (\Throwable) {
$awaitingMembers = false;
}
}
$result = [
'vpc_key' => (string) $vpc->vpc_key, 'name' => (string) $vpc->name,
'region_id' => (int) $vpc->region_id, 'cidr' => (string) $vpc->cidr,
'max_members' => (int) $vpc->max_members, 'state' => (string) $vpc->state,
'sync_state' => (string) $vpc->sync_state,
'desired_revision' => (int) $vpc->desired_revision,
'observed_revision' => (int) $vpc->observed_revision,
'usable' => $usable,
'member_count' => $runtimeMembers->count(),
'setup_state' => $awaitingMembers ? 'awaiting_members' : null,
'last_operation_id' => $vpc->last_operation_id,
'last_error_code' => self::safeErrorCode($rawErrorCode),
'created_at' => (int) $vpc->created_at, 'updated_at' => (int) $vpc->updated_at,
];
if ($includeInfrastructure) {
$result['fabric_id'] = (string) $vpc->fabric_id;
$result['fabric_region'] = (string) ($vpc->fabric_region ?? '');
$result['fabric_revision'] = (int) $vpc->fabric_revision;
}
return $result;
}
private static function publicSubnet($row): array
{
return ['subnet_key' => (string) $row->subnet_key, 'cidr' => (string) $row->cidr,
'gateway_ip' => $row->gateway_ip, 'state' => (string) $row->state,
'desired_revision' => (int) $row->desired_revision,
'observed_revision' => (int) $row->observed_revision,
'last_error_code' => self::safeErrorCode((string) ($row->last_error_code ?? ''))];
}
private static function publicMember($row, bool $includeHostDetails = false, $privateIp = null): array
{
$result = ['member_key' => (string) $row->member_key,
'instance_id' => (int) $row->instance_id,
'private_ip' => $privateIp === null
? (string) $row->private_ip : (string) $privateIp->private_ip,
'state' => (string) $row->state, 'desired_revision' => (int) $row->desired_revision,
'observed_revision' => (int) $row->observed_revision,
'last_error_code' => self::safeErrorCode((string) ($row->last_error_code ?? ''))];
if ($includeHostDetails) {
$result['host_id'] = (int) $row->host_id;
}
return $result;
}
private static function publicRoute($row): array
{
return ['route_key' => (string) $row->route_key,
'destination_cidr' => (string) $row->destination_cidr,
'next_hop_ip' => (string) $row->next_hop_ip, 'metric' => (int) $row->metric,
'state' => (string) $row->state, 'desired_revision' => (int) $row->desired_revision,
'observed_revision' => (int) $row->observed_revision];
}
private static function publicAcl($row): array
{
return ['rule_key' => (string) $row->rule_key, 'priority' => (int) $row->priority,
'direction' => (string) $row->direction, 'action' => (string) $row->action,
'protocol' => (string) $row->protocol, 'source_cidr' => (string) $row->source_cidr,
'destination_cidr' => (string) $row->destination_cidr,
'port_from' => $row->port_from === null ? null : (int) $row->port_from,
'port_to' => $row->port_to === null ? null : (int) $row->port_to,
'state' => (string) $row->state];
}
private static function publicHost($row): array
{
return ['host_id' => (int) $row->host_id, 'state' => (string) $row->state,
'fabric_revision' => (int) $row->fabric_revision,
'desired_revision' => (int) $row->desired_revision,
'observed_revision' => (int) $row->observed_revision,
'last_error_code' => self::safeErrorCode((string) ($row->last_error_code ?? ''))];
}
private static function publicOperation($row): array
{
return ['operation_id' => (string) $row->operation_id, 'kind' => (string) $row->kind,
'desired_revision' => (int) $row->desired_revision, 'status' => (string) $row->status,
'evidence_version' => (int) ($row->evidence_version ?? 0),
'error_code' => self::safeErrorCode((string) ($row->error_code ?? '')),
'created_at' => (int) $row->created_at, 'updated_at' => (int) $row->updated_at,
'finished_at' => $row->finished_at === null ? null : (int) $row->finished_at];
}
private static function findOwned(string $key, array $actor, bool $write): CloudVpc
{
self::assertKey($key, 'VPC');
$query = CloudVpc::where('vpc_key', $key);
if (!self::isGlobal($actor)) {
$query->where('user_id', (int) ($actor['user_id'] ?? 0));
} elseif ($write && !($actor['can_manage'] ?? false)) {
throw new CloudError('无权修改该 VPC', 403);
}
$vpc = $query->first();
if ($vpc === null) {
throw new CloudError('VPC 不存在或无权访问', 404);
}
return $vpc;
}
private static function lockOwned(string $key, array $actor): CloudVpc
{
self::assertKey($key, 'VPC');
$query = CloudVpc::where('vpc_key', $key);
if (!self::isGlobal($actor)) {
$query->where('user_id', (int) ($actor['user_id'] ?? 0));
}
$vpc = $query->lockForUpdate()->first()
?? throw new CloudError('VPC 不存在或无权访问', 404);
if (!in_array((string) $vpc->state, self::LIVE_STATES, true)) {
throw new CloudError(
(string) $vpc->state === 'deleted'
? 'VPC 已删除' : 'VPC 正在删除,不能再修改',
409
);
}
return $vpc;
}
/** Lock a root for the delete state machine without reopening mutation. */
private static function lockOwnedForDelete(string $key, array $actor): CloudVpc
{
self::assertKey($key, 'VPC');
$query = CloudVpc::where('vpc_key', $key);
if (!self::isGlobal($actor)) {
$query->where('user_id', (int) ($actor['user_id'] ?? 0));
}
return $query->lockForUpdate()->first()
?? throw new CloudError('VPC 不存在或无权访问', 404);
}
private static function isGlobal(array $actor): bool
{
return ($actor['is_admin'] ?? false) === true
&& ($actor['is_super_admin'] ?? false) === true
&& ($actor['can_manage'] ?? false) === true;
}
private static function canViewInfrastructure(array $actor): bool
{
return ($actor['is_admin'] ?? false) === true
&& ($actor['can_manage'] ?? false) === true;
}
private static function assertKey($value, string $label): string
{
if (!is_string($value) || preg_match(self::KEY_PATTERN, $value) !== 1) {
throw new CloudError($label . '标识无效');
}
return strtolower($value);
}
private static function randomKey(): string
{
return bin2hex(random_bytes(16));
}
private static function requestKey($value): string
{
if (!is_string($value) || preg_match(self::REQUEST_KEY_PATTERN, $value) !== 1) {
throw new CloudError('请求幂等键无效');
}
return $value;
}
private static function fabricId($value): string
{
if (!is_string($value) || preg_match(self::FABRIC_KEY_PATTERN, $value) !== 1) {
throw new CloudError('Fabric 标识无效');
}
return $value;
}
private static function positiveInt($value, int $min, int $max, string $message): int
{
$parsed = filter_var($value, FILTER_VALIDATE_INT,
['options' => ['min_range' => $min, 'max_range' => $max]]);
if ($parsed === false) {
throw new CloudError($message);
}
return (int) $parsed;
}
private static function nonNegativeInt($value, int $max, string $message): int
{
return self::positiveInt($value, 0, $max, $message);
}
/** Strict canonical IPv4 CIDR parser with RFC1918 enforcement. */
private static function cidr($value, int $minPrefix, int $maxPrefix, string $label): array
{
if (!is_string($value)) {
throw new CloudError($label . '格式无效');
}
$parts = explode('/', trim($value), 2);
if (count($parts) !== 2 || filter_var($parts[0], FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false
|| !preg_match('/^(?:[0-9]|[12][0-9]|3[0-2])$/D', $parts[1])) {
throw new CloudError($label . '必须使用有效 IPv4 CIDR');
}
$prefix = (int) $parts[1];
if ($prefix < $minPrefix || $prefix > $maxPrefix) {
throw new CloudError($label . '前缀长度不在允许范围内');
}
$ip = self::ipToInt($parts[0]);
$block = (int) (2 ** (32 - $prefix));
$network = intdiv($ip, $block) * $block;
$broadcast = $network + $block - 1;
if (!self::isRfc1918($network, $broadcast)) {
throw new CloudError($label . '必须使用 RFC1918 私网地址');
}
return ['cidr' => self::intToIp($network) . '/' . $prefix,
'network' => $network, 'broadcast' => $broadcast, 'prefix' => $prefix];
}
private static function ipv4($value, string $label): string
{
if (!is_string($value) || filter_var(trim($value), FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false) {
throw new CloudError($label . '必须是 IPv4 地址');
}
return self::intToIp(self::ipToInt(trim($value)));
}
private static function ipToInt(string $ip): int
{
$packed = inet_pton($ip);
if ($packed === false || strlen($packed) !== 4) {
throw new CloudError('IPv4 地址无效');
}
$unpacked = unpack('Nvalue', $packed);
return (int) sprintf('%u', (int) $unpacked['value']);
}
private static function intToIp(int $value): string
{
$packed = pack('N', $value);
$ip = inet_ntop($packed);
if ($ip === false) {
throw new CloudError('IPv4 地址转换失败', 500);
}
return $ip;
}
private static function isRfc1918(int $network, int $broadcast): bool
{
return ($network >= self::ipToInt('10.0.0.0') && $broadcast <= self::ipToInt('10.255.255.255'))
|| ($network >= self::ipToInt('172.16.0.0') && $broadcast <= self::ipToInt('172.31.255.255'))
|| ($network >= self::ipToInt('192.168.0.0') && $broadcast <= self::ipToInt('192.168.255.255'));
}
private static function contains(int $outerNetwork, int $outerBroadcast,
int $network, int $broadcast): bool
{
return $network >= $outerNetwork && $broadcast <= $outerBroadcast;
}
/**
* Return the first address absent from durable leases and live routes.
*
* Deleted rows are intentionally still occupied here. The data-plane
* phase has not yet supplied an exact removal readback, so reusing a
* tombstoned address could make an old host rule select a new VM. A live
* custom destination/next hop also owns its /32 until route convergence.
*/
private static function firstFreeIp(
$subnet, $privateIps, array $reservedRouteIps = []
): string
{
$used = [];
foreach ($privateIps as $privateIp) {
$used[(int) $privateIp->private_ip_int] = true;
}
$start = (int) $subnet->network_address + 1;
$end = (int) $subnet->broadcast_address - 1;
// Scan the complete usable subnet. A valid VPC can place up to
// MAX_MEMBERS leases and MAX_ROUTES distinct /32 reservations before
// the first free address (plus an optional gateway), so a member-only
// bound can report a false exhaustion while later addresses are free.
// The widest accepted subnet is /16, keeping this bounded at 65,534
// candidates with O(1) set lookups.
for ($ip = $start; $ip <= $end; $ip++) {
$candidate = self::intToIp($ip);
if (!isset($used[$ip]) && !isset($reservedRouteIps[$candidate])
&& (string) $subnet->gateway_ip !== $candidate) {
return $candidate;
}
}
throw new CloudError('子网可用私网 IP 已耗尽', 409);
}
/**
* Lock and validate the one independent address lease owned by a member.
* A missing or mismatched row is a control-plane integrity failure; fail
* closed instead of reconstructing the address from the member duplicate.
*/
private static function lockedPrivateIpForMember(CloudVpcMember $member): CloudVpcPrivateIp
{
$privateIp = CloudVpcPrivateIp::where('vpc_id', (int) $member->vpc_id)
->where('member_id', (int) $member->id)
->lockForUpdate()->first();
if ($privateIp === null || (int) $member->private_ip_id !== (int) $privateIp->id) {
throw new CloudError('VPC 私网地址账本缺失,请联系管理员', 503);
}
return $privateIp;
}
private static function assertInstanceRegion(CloudInstance $instance, int $regionId): void
{
$fabricConnection = (new CloudRegionFabric())->getConnection();
if (!$fabricConnection->getSchemaBuilder()->hasTable('cloud_region_fabrics')) {
throw new CloudError('VPC Fabric 映射表尚未安装', 503);
}
$region = CloudRegion::find($regionId);
$host = CloudHost::find((int) $instance->host_id);
$fabric = CloudRegionFabric::where('region_id', $regionId)
->where('state', 'active')->first();
if ($region === null || $host === null || $fabric === null) {
throw new CloudError('虚拟机宿主机地区信息缺失', 409);
}
$schema = (new CloudHostResourcePoolMembership())->getConnection()
->getSchemaBuilder();
foreach (['cloud_host_resource_pool_memberships',
'cloud_resource_pools', 'cloud_network_lines'] as $table) {
if (!$schema->hasTable($table)) {
throw new CloudError('VPC 宿主机地区关系表尚未安装', 503);
}
}
$placements = CloudHostResourcePoolMembership::query()
->leftJoin('cloud_resource_pools as vpc_pool', 'vpc_pool.id', '=',
'cloud_host_resource_pool_memberships.resource_pool_id')
->leftJoin('cloud_network_lines as vpc_line', 'vpc_line.id', '=',
'vpc_pool.line_id')
->leftJoin('cloud_regions as vpc_region', 'vpc_region.id', '=',
'vpc_line.region_id')
->where('cloud_host_resource_pool_memberships.host_id',
(int) $instance->host_id)
->whereIn('cloud_host_resource_pool_memberships.scheduler_state',
['active', 'draining'])
->get([
'cloud_host_resource_pool_memberships.resource_pool_id '
. 'as membership_pool_id',
'vpc_pool.id as pool_id', 'vpc_line.id as line_id',
'vpc_region.id as resolved_region_id',
]);
foreach ($placements as $candidate) {
if ($candidate->pool_id === null || $candidate->line_id === null
|| $candidate->resolved_region_id === null) {
throw new CloudError('VPC 宿主机地区关系不完整', 503);
}
}
if ($placements->count() !== 1) {
throw new CloudError('VPC 与虚拟机必须位于同一地区', 409);
}
$placement = $placements->first();
$instancePoolId = (int) ($instance->resource_pool_id ?? 0);
if (($instancePoolId > 0
&& (int) $placement->membership_pool_id !== $instancePoolId)
|| (int) $placement->resolved_region_id !== $regionId) {
throw new CloudError('VPC 与虚拟机必须位于同一地区', 409);
}
}
private static function routeInput($value): array
{
if (!is_array($value) || !array_is_list($value) || count($value) > self::MAX_ROUTES) {
throw new CloudError('路由列表无效或超过上限');
}
$result = [];
foreach ($value as $item) {
if (!is_array($item) || array_is_list($item)) {
throw new CloudError('路由规则格式无效');
}
CloudInput::only($item, ['route_key', 'destination_cidr', 'next_hop_ip', 'metric']);
$key = self::assertKey($item['route_key'] ?? null, '路由');
// The host data plane is intentionally routed as exact /32s.
// Accepting a wider prefix here would let a tenant's route
// replace the per-member cryptokey and nft boundary, even though
// the engine later rejects it. Reject it at the PHP boundary so
// the API and engine cannot disagree about a usable target.
$destination = self::cidr($item['destination_cidr'] ?? null, 32, 32, '路由目标');
$next = self::ipv4($item['next_hop_ip'] ?? null, '路由下一跳');
$metric = self::positiveInt($item['metric'] ?? 100, 1, 65535, '路由 metric 无效');
$result[] = ['route_key' => $key, 'destination' => $destination,
'next_hop_ip' => $next, 'metric' => $metric];
}
return $result;
}
private static function aclInput($value): array
{
if (!is_array($value) || !array_is_list($value) || count($value) > self::MAX_ACL_RULES) {
throw new CloudError('ACL 规则列表无效或超过上限');
}
$result = [];
$priorities = [];
foreach ($value as $item) {
if (!is_array($item) || array_is_list($item)) {
throw new CloudError('ACL 规则格式无效');
}
CloudInput::only($item, [
'rule_key', 'priority', 'direction', 'action', 'protocol',
'source_cidr', 'destination_cidr', 'port_from', 'port_to',
]);
$key = self::assertKey($item['rule_key'] ?? null, 'ACL 规则');
$priority = self::positiveInt($item['priority'] ?? null, 1, 1000000, 'ACL 优先级无效');
if (isset($priorities[$priority])) {
throw new CloudError('ACL 优先级不能重复');
}
$priorities[$priority] = true;
$direction = $item['direction'] ?? null;
$action = $item['action'] ?? null;
$protocol = $item['protocol'] ?? null;
if (!is_string($direction) || !in_array($direction, self::DIRECTIONS, true)
|| !is_string($action) || !in_array($action, self::ACTIONS, true)
|| !is_string($protocol) || !in_array($protocol, self::PROTOCOLS, true)) {
throw new CloudError('ACL 方向、动作或协议无效');
}
$source = self::cidr($item['source_cidr'] ?? null, 8, 32, 'ACL 源地址');
$destination = self::cidr($item['destination_cidr'] ?? null, 8, 32, 'ACL 目标地址');
$from = $item['port_from'] ?? null;
$to = $item['port_to'] ?? null;
if ($from !== null || $to !== null) {
if (!in_array($protocol, ['tcp', 'udp'], true)) {
throw new CloudError('只有 TCP/UDP ACL 可以设置端口');
}
$from = self::positiveInt($from, 1, 65535, 'ACL 起始端口无效');
$to = self::positiveInt($to, $from, 65535, 'ACL 结束端口无效');
}
$result[] = ['rule_key' => $key, 'priority' => $priority,
'direction' => $direction, 'action' => $action, 'protocol' => $protocol,
'source' => $source, 'destination' => $destination,
'port_from' => $from, 'port_to' => $to];
}
return $result;
}
private static function safeErrorCode(string $value): ?string
{
return preg_match('/^[a-z0-9_]{1,64}$/D', $value) === 1 ? $value : null;
}
private static function digestMatches(string $left, string $right): bool
{
return preg_match('/^[a-f0-9]{64}$/D', $left) === 1
&& preg_match('/^[a-f0-9]{64}$/D', $right) === 1
&& hash_equals($left, $right);
}
/**
* Derive the stable locally-administered MAC used by one VPC member.
*
* Member keys are scoped to a VPC, so binding both identities prevents a
* key reused in another tenant from receiving the same NIC identity. The
* first octet is forced to unicast/local-administered (02/06/0a/0e
* families) and the remaining bytes are cryptographic hash material.
*/
private static function privateMacForMember(string $vpcKey, string $memberKey): ?string
{
if (preg_match(self::KEY_PATTERN, $vpcKey) !== 1
|| preg_match(self::KEY_PATTERN, $memberKey) !== 1) {
return null;
}
$digest = hash('sha256', 'virt-cloud:vpc-private0:' . $vpcKey . ':' . $memberKey);
$octets = [];
for ($index = 0; $index < 6; $index++) {
$octets[] = hexdec(substr($digest, $index * 2, 2));
}
$octets[0] = ($octets[0] & 0xfc) | 0x02;
return implode(':', array_map(
static fn (int $octet): string => sprintf('%02x', $octet), $octets
));
}
private static function privateBridgeForVpc(string $vpcKey): ?string
{
return preg_match(self::KEY_PATTERN, $vpcKey) === 1
? 'vcv-' . substr(hash('sha256', $vpcKey), 0, 11) : null;
}
private static function privateNftTableForVpc(string $vpcKey): ?string
{
return preg_match(self::KEY_PATTERN, $vpcKey) === 1
? 'virt_cloud_vpc_' . substr(hash('sha256', $vpcKey), 0, 12) : null;
}
private static function privateRouteTableForVpc(string $vpcKey): ?int
{
if (preg_match(self::KEY_PATTERN, $vpcKey) !== 1) {
return null;
}
$digest = hash('sha256', $vpcKey);
return 10000 + (hexdec(substr($digest, 12, 8)) % 10000);
}
/**
* Propagate one actionable guest-readback reason without allowing an
* arbitrary host string, or one host's reason, to mask a different host.
*/
private static function singleDeferredEvidenceError(array $hostEvidence): ?string
{
$codes = [];
foreach ($hostEvidence as $evidence) {
if (!is_array($evidence)) {
continue;
}
$code = self::deferredEvidenceError(
$evidence['last_error_code'] ?? null
);
if (($evidence['active'] ?? false) === true && $code === null) {
continue;
}
if ($code === null) {
return null;
}
$codes[$code] = true;
}
return count($codes) === 1 ? (string) array_key_first($codes) : null;
}
/** Accept only reviewed reasons; syntactically valid engine text is not enough. */
private static function deferredEvidenceError($value): ?string
{
return is_string($value)
&& in_array($value, self::DEFERRED_EVIDENCE_ERRORS, true)
? $value : null;
}
/** Validate one member NIC without coupling it to sibling guest state. */
private static function validateMemberNicEvidence(
array $nic,
array $expected,
string $expectedVpcCidr,
bool $requireGuestEvidence
): ?string {
$memberId = (string) ($expected['member_id'] ?? '');
$observedMac = strtolower((string) ($nic['private_mac'] ?? ''));
if ($memberId === ''
|| (string) ($nic['member_id'] ?? '') !== $memberId
|| (string) ($nic['interface'] ?? '') !== self::PRIVATE_INTERFACE
|| strtolower((string) ($nic['instance_uuid'] ?? ''))
!== strtolower((string) ($expected['instance_uuid'] ?? ''))
|| (string) ($nic['private_ip_cidr'] ?? '')
!== (string) ($expected['private_ip_cidr'] ?? '')
|| $observedMac !== strtolower((string) ($expected['private_mac'] ?? ''))
|| ($nic['config_verified'] ?? false) !== true
|| ($nic['seed_verified'] ?? false) !== true) {
return 'vpc_private_nic_readback_mismatch';
}
if (($nic['xml_verified'] ?? false) !== true) {
return 'vpc_private_nic_readback_mismatch';
}
if (!$requireGuestEvidence) {
return null;
}
if (($nic['restart_required'] ?? null) === true
|| ($nic['domain_running'] ?? null) === false) {
return 'vpc_private_guest_restart_required';
}
if (($nic['restart_required'] ?? null) !== false
|| ($nic['domain_running'] ?? null) !== true) {
return 'vpc_private_guest_agent_unavailable';
}
if (($nic['guest_network_verified'] ?? false) !== true) {
return self::deferredEvidenceError(
$nic['guest_reason_code'] ?? null
) ?? 'vpc_private_guest_probe_uncertain';
}
try {
$canonicalVpcCidr = self::cidr(
$expectedVpcCidr, 16, 24, 'VPC CIDR'
)['cidr'];
} catch (\Throwable) {
return 'vpc_private_guest_route_mismatch';
}
if (!hash_equals($canonicalVpcCidr, $expectedVpcCidr)) {
return 'vpc_private_guest_route_mismatch';
}
$guestRoutes = $nic['guest_routes'] ?? null;
if (!is_array($guestRoutes) || count($guestRoutes) !== 1) {
return 'vpc_private_guest_route_mismatch';
}
$normalizedGuestRoutes = [];
foreach ($guestRoutes as $guestRoute) {
if (!is_string($guestRoute) || strlen($guestRoute) > 64) {
return 'vpc_private_guest_route_mismatch';
}
$normalizedGuestRoutes[] = $guestRoute;
}
if (count(array_unique($normalizedGuestRoutes))
!== count($normalizedGuestRoutes)) {
return 'vpc_private_guest_route_mismatch';
}
if ((string) ($nic['guest_network_readback'] ?? '') !== 'confirmed') {
return 'vpc_private_guest_probe_uncertain';
}
if (($nic['link_state'] ?? null) !== 'up'
|| ($nic['guest_link_state'] ?? null) !== 'up') {
return 'vpc_private_guest_link_mismatch';
}
if (strtolower((string) ($nic['guest_private_mac'] ?? ''))
!== strtolower((string) ($expected['private_mac'] ?? ''))
|| (string) ($nic['guest_private_ip_cidr'] ?? '')
!== (string) ($expected['private_ip_cidr'] ?? '')) {
return 'vpc_private_guest_address_mismatch';
}
return $normalizedGuestRoutes === [$expectedVpcCidr]
? null : 'vpc_private_guest_route_mismatch';
}
/**
* Validate typed host-side private dataplane evidence. Raw command output
* is deliberately ignored: only bounded identity, route, ACL and XML
* readback fields can open the PHP VPC gate.
*
* A null return means the evidence is exact; otherwise the returned code
* is safe to persist as a diagnostic and keeps the host degraded.
*/
private static function validateHostDataplaneEvidence(
array $item,
string $hostId,
array $expectedMembers,
array $allMembers,
array $expectedDestinations,
string $expectedVpcCidr,
array $desiredRoutes,
string $vpcKey,
int $revision,
string $digest,
bool $requireGuestEvidence = true
): ?string {
// These fields are identity evidence, not optional status hints. A
// compact/legacy host projection must therefore stay closed until a
// full typed readback is supplied by the engine.
if (!array_key_exists('vpc_id', $item)
|| !array_key_exists('host_id', $item)
|| !array_key_exists('desired_revision', $item)
|| !array_key_exists('desired_digest', $item)
|| !array_key_exists('observed_revision', $item)
|| !array_key_exists('observed_digest', $item)
|| (string) $item['vpc_id'] !== $vpcKey
|| !self::digestMatches($digest, (string) $item['desired_digest'])
|| (string) $item['host_id'] !== $hostId
|| (int) $item['desired_revision'] !== $revision) {
return 'vpc_private_readback_mismatch';
}
// A host removal is a distinct typed proof. It must not be treated
// as an empty successful apply: all panel-owned resources and
// tenant-facing evidence must be absent before a deleting deployment
// can be finalized.
if (($item['removed'] ?? false) === true) {
$readback = $item['readback'] ?? null;
$readbackState = is_string($readback) ? strtolower($readback)
: (is_array($readback)
? strtolower((string) ($readback['state'] ?? $readback['status'] ?? ''))
: '');
foreach (['member_nics', 'routes', 'wg_allowed_ips', 'proxy_ips'] as $field) {
if (!is_array($item[$field] ?? null) || $item[$field] !== []) {
return 'vpc_private_removal_readback_mismatch';
}
}
if ($expectedMembers !== []
|| $readbackState !== 'confirmed'
|| (string) ($item['state'] ?? '') !== 'active'
|| (int) $item['observed_revision'] !== $revision
|| !self::digestMatches($digest, (string) $item['observed_digest'])
|| ($item['bridge'] ?? null) !== null
|| ($item['bridge_owner'] ?? null) !== null
|| ($item['nft_table'] ?? null) !== null
|| !in_array((string) ($item['rollback'] ?? ''), ['none', 'ok'], true)) {
return 'vpc_private_removal_readback_mismatch';
}
return null;
}
if (($item['config_verified'] ?? false) !== true
|| (int) ($item['config_observed_revision'] ?? 0) !== $revision
|| !self::digestMatches(
$digest, (string) ($item['config_observed_digest'] ?? '')
)) {
return 'vpc_private_dataplane_unverified';
}
if ($requireGuestEvidence
&& ((string) ($item['state'] ?? '') !== 'active'
|| (int) $item['observed_revision'] !== $revision
|| !self::digestMatches(
$digest, (string) ($item['observed_digest'] ?? '')
))) {
return 'vpc_private_readback_mismatch';
}
if (!$requireGuestEvidence
&& !in_array((string) ($item['state'] ?? ''), [
'applying', 'active', 'degraded',
], true)) {
return 'vpc_private_readback_mismatch';
}
$bridge = self::privateBridgeForVpc($vpcKey);
$nftTable = self::privateNftTableForVpc($vpcKey);
$routeTable = self::privateRouteTableForVpc($vpcKey);
if ($bridge === null || $nftTable === null
|| $routeTable === null
|| (string) ($item['bridge'] ?? '') !== $bridge
|| (string) ($item['bridge_owner'] ?? '') !== self::PRIVATE_DATAPLANE_OWNER
|| (string) ($item['nft_table'] ?? '') !== $nftTable
|| ($item['anti_spoof'] ?? false) !== true
|| (int) ($item['rp_filter'] ?? -1) !== 2
|| (int) ($item['proxy_arp'] ?? -1) !== 0
|| (int) ($item['proxy_arp_pvlan'] ?? -1) !== 1
|| (int) ($item['acl_revision'] ?? 0) !== $revision
|| !array_key_exists('rollback', $item)
|| !in_array((string) $item['rollback'], ['none', 'ok'], true)) {
return 'vpc_private_dataplane_unverified';
}
$readback = $item['readback'] ?? null;
$readbackState = is_string($readback) ? strtolower($readback)
: (is_array($readback)
? strtolower((string) ($readback['state'] ?? $readback['status'] ?? ''))
: '');
if ($requireGuestEvidence && $readbackState !== 'confirmed') {
return 'vpc_private_readback_missing';
}
// The host bridge routes each guest address as an exact /32. Generic
// proxy ARP stays off;
// only exact panel-owned proxy-neighbour entries (with pvlan enabled
// for same-bridge next hops) may answer. A missing or broadened
// proxy set keeps the host degraded.
$proxyIps = $item['proxy_ips'] ?? null;
if (!is_array($proxyIps)) {
return 'vpc_private_proxy_arp_readback_missing';
}
$expectedProxyIps = [];
foreach ($expectedDestinations as $destination) {
if (!is_string($destination)
|| !preg_match('/^([0-9]{1,3}(?:\.[0-9]{1,3}){3})\/32$/D', $destination, $match)
|| filter_var($match[1], FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false) {
return 'vpc_private_proxy_arp_readback_mismatch';
}
$expectedProxyIps[] = $match[1];
}
$expectedProxyIps = array_values(array_unique($expectedProxyIps));
sort($expectedProxyIps, SORT_STRING);
$observedProxyIps = [];
foreach ($proxyIps as $proxyIp) {
if (!is_string($proxyIp)
|| filter_var($proxyIp, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) === false) {
return 'vpc_private_proxy_arp_readback_mismatch';
}
$observedProxyIps[] = $proxyIp;
}
$observedProxyIps = array_values(array_unique($observedProxyIps));
sort($observedProxyIps, SORT_STRING);
if ($observedProxyIps !== $expectedProxyIps) {
return 'vpc_private_proxy_arp_readback_mismatch';
}
$nics = $item['member_nics'] ?? null;
if (!is_array($nics) || count($nics) !== count($expectedMembers)) {
return 'vpc_private_nic_readback_mismatch';
}
$seen = [];
foreach ($nics as $nic) {
if (!is_array($nic)) {
return 'vpc_private_nic_readback_mismatch';
}
$memberId = (string) ($nic['member_id'] ?? '');
if ($memberId === '' || isset($seen[$memberId])
|| !isset($expectedMembers[$memberId])) {
return 'vpc_private_nic_readback_mismatch';
}
$expected = $expectedMembers[$memberId];
$memberError = self::validateMemberNicEvidence(
$nic,
$expected,
$expectedVpcCidr,
$requireGuestEvidence
);
if ($memberError !== null) {
return $memberError;
}
$seen[$memberId] = true;
}
if (count($seen) !== count($expectedMembers)) {
return 'vpc_private_nic_readback_mismatch';
}
// Routes are checked against the exact host-specific next hop and
// metric. A dataplane readback must never install a default or
// otherwise broad route owned by a different subsystem.
$routes = $item['routes'] ?? null;
if (!is_array($routes)) {
return 'vpc_private_route_readback_missing';
}
$memberById = [];
foreach ($allMembers as $member) {
if (is_array($member) && isset($member['member_id'])) {
$memberById[(string) $member['member_id']] = $member;
}
}
$expectedRouteRows = [];
foreach ($allMembers as $member) {
if (!is_array($member) || !isset($member['private_ip_cidr'])) {
continue;
}
$expectedRouteRows[] = [
'destination_cidr' => (string) $member['private_ip_cidr'],
'device' => (string) (($member['host_id'] ?? '') === $hostId
? $bridge : self::FABRIC_INTERFACE),
'via' => null,
'metric' => 100,
];
}
foreach ($desiredRoutes as $desiredRoute) {
if (!is_array($desiredRoute)
|| !isset($desiredRoute['destination_cidr'])) {
return 'vpc_private_route_readback_mismatch';
}
$nextMemberId = isset($desiredRoute['next_hop_member_id'])
? (string) $desiredRoute['next_hop_member_id'] : '';
$nextMember = $nextMemberId !== ''
? ($memberById[$nextMemberId] ?? null) : null;
$nextHost = is_array($nextMember)
? (string) ($nextMember['host_id'] ?? '')
: (string) ($desiredRoute['next_hop_host_id'] ?? '');
if ($nextHost === '') {
return 'vpc_private_route_readback_mismatch';
}
$expectedRouteRows[] = [
'destination_cidr' => (string) $desiredRoute['destination_cidr'],
'device' => $nextHost === $hostId ? $bridge : self::FABRIC_INTERFACE,
'via' => $nextHost === $hostId && is_array($nextMember)
? (string) preg_replace(
'/\/32$/D', '',
(string) ($nextMember['private_ip']
?? $nextMember['private_ip_cidr'] ?? '')
)
: null,
'metric' => (int) ($desiredRoute['metric'] ?? 100),
];
}
$expectedRouteMap = [];
foreach ($expectedRouteRows as $expectedRoute) {
$via = (string) ($expectedRoute['via'] ?? '');
$key = $expectedRoute['destination_cidr'] . '|'
. $expectedRoute['device'] . '|' . $via . '|'
. (string) $expectedRoute['metric'];
if (isset($expectedRouteMap[$key])) {
return 'vpc_private_route_readback_mismatch';
}
$expectedRouteMap[$key] = true;
}
$seenRoutes = [];
foreach ($routes as $route) {
if (!is_array($route)
|| !is_string($route['destination_cidr'] ?? null)
|| !isset($route['device'])
|| !is_string($route['device'])
|| $route['device'] === ''
|| !array_key_exists('table', $route)
|| !in_array($route['device'], [$bridge, self::FABRIC_INTERFACE], true)
|| (string) ($route['owner'] ?? '') !== self::PRIVATE_DATAPLANE_OWNER) {
return 'vpc_private_route_readback_mismatch';
}
$destination = (string) $route['destination_cidr'];
if (in_array($destination, ['0.0.0.0/0', '::/0'], true)
|| !in_array($destination, $expectedDestinations, true)) {
return 'vpc_private_route_readback_mismatch';
}
$via = $route['via'] ?? null;
if ($via !== null && !is_string($via)) {
return 'vpc_private_route_readback_mismatch';
}
$metric = $route['metric'] ?? null;
if ((is_string($metric) && !ctype_digit($metric))
|| (!is_int($metric) && !is_string($metric))) {
return 'vpc_private_route_readback_mismatch';
}
$metric = (int) $metric;
$key = $destination . '|' . (string) $route['device'] . '|'
. (string) ($via ?? '') . '|' . (string) $metric;
if (isset($seenRoutes[$key])) {
return 'vpc_private_route_readback_mismatch';
}
if (!isset($expectedRouteMap[$key])) {
return 'vpc_private_route_readback_mismatch';
}
$seenRoutes[$key] = true;
if ((!is_int($route['table'])
&& !(is_string($route['table']) && is_numeric($route['table'])))
|| (int) $route['table'] !== $routeTable) {
return 'vpc_private_route_readback_mismatch';
}
}
$expectedRouteSet = array_keys($expectedRouteMap);
$observedRouteSet = array_keys($seenRoutes);
sort($expectedRouteSet, SORT_STRING);
sort($observedRouteSet, SORT_STRING);
if ($observedRouteSet !== $expectedRouteSet) {
return 'vpc_private_route_readback_mismatch';
}
// The engine reports tenant AllowedIPs separately from Fabric overlay
// addresses. Require an exact remote-member /32 set, preventing a
// broad prefix from crossing a host or VPC boundary.
$expectedPeers = [];
foreach ($allMembers as $member) {
if ((string) ($member['host_id'] ?? '') === $hostId) {
continue;
}
$peerHost = (string) ($member['host_id'] ?? '');
$expectedPeers[$peerHost][] = (string) $member['private_ip_cidr'];
}
foreach ($desiredRoutes as $route) {
if (!is_array($route)) {
return 'vpc_private_wireguard_readback_mismatch';
}
$target = null;
if (isset($route['next_hop_member_id'])) {
$target = $memberById[(string) $route['next_hop_member_id']] ?? null;
}
$peerHost = is_array($target)
? (string) ($target['host_id'] ?? '')
: (string) ($route['next_hop_host_id'] ?? '');
if ($peerHost !== '' && $peerHost !== $hostId
&& isset($route['destination_cidr'])) {
$expectedPeers[$peerHost][] = (string) $route['destination_cidr'];
}
}
foreach ($expectedPeers as &$ips) {
$ips = array_values(array_unique($ips));
sort($ips, SORT_STRING);
}
unset($ips);
$wg = $item['wg_allowed_ips'] ?? null;
if (!is_array($wg)) {
return 'vpc_private_wireguard_readback_missing';
}
$seenPeers = [];
foreach ($wg as $peer) {
if (!is_array($peer)) {
return 'vpc_private_wireguard_readback_mismatch';
}
$peerHost = (string) ($peer['peer_host_id'] ?? '');
$tenantIps = $peer['tenant_allowed_ips'] ?? $peer['allowed_ips'] ?? null;
$publicKey = $peer['public_key'] ?? null;
if ($peerHost === '' || isset($seenPeers[$peerHost])
|| !array_key_exists($peerHost, $expectedPeers)
|| !is_array($tenantIps)
|| !is_string($publicKey)
|| preg_match('/^[A-Za-z0-9+\/]{42}[A-Za-z0-9+\/]==$|^[A-Za-z0-9+\/]{43}=$/D',
$publicKey) !== 1) {
return 'vpc_private_wireguard_readback_mismatch';
}
$decodedKey = base64_decode($publicKey, true);
if ($decodedKey === false || strlen($decodedKey) !== 32
|| trim($decodedKey, "\0") === '') {
return 'vpc_private_wireguard_readback_mismatch';
}
$normalizedIps = [];
foreach ($tenantIps as $ip) {
if (!is_string($ip)) {
return 'vpc_private_wireguard_readback_mismatch';
}
$normalizedIps[] = $ip;
}
$normalizedIps = array_values(array_unique($normalizedIps));
sort($normalizedIps, SORT_STRING);
foreach ($normalizedIps as $ip) {
if (!preg_match('/^[0-9.]+\/32$/D', $ip)) {
return 'vpc_private_wireguard_readback_mismatch';
}
}
if ($normalizedIps !== $expectedPeers[$peerHost]) {
return 'vpc_private_wireguard_readback_mismatch';
}
$seenPeers[$peerHost] = true;
}
if (count($seenPeers) !== count($expectedPeers)) {
return 'vpc_private_wireguard_readback_mismatch';
}
return null;
}
private static function boundedObserved(array $value): array
{
$hosts = [];
$terminalProof = null;
$proof = $value['no_data_plane_terminal_proof'] ?? null;
if (is_array($proof)
&& (int) ($proof['revision'] ?? 0) > 0
&& preg_match('/^[a-f0-9]{64}$/D', (string) ($proof['digest'] ?? '')) === 1
&& in_array((string) ($proof['gate'] ?? ''), [
'vpc_no_members', 'vpc_no_participating_hosts',
], true)) {
$terminalProof = [
'revision' => (int) $proof['revision'],
'digest' => strtolower((string) $proof['digest']),
'gate' => (string) $proof['gate'],
];
}
foreach (is_array($value['hosts'] ?? null) ? $value['hosts'] : [] as $key => $host) {
if (!is_array($host) || count($hosts) >= self::MAX_MEMBERS) {
continue;
}
$bounded = [
'host_id' => is_string($host['host_id'] ?? null)
? substr($host['host_id'], 0, 64) : (string) $key,
'vpc_id' => is_string($host['vpc_id'] ?? null)
? substr($host['vpc_id'], 0, 64) : null,
'desired_revision' => max(0, (int) ($host['desired_revision'] ?? 0)),
'desired_digest' => is_string($host['desired_digest'] ?? null)
? substr($host['desired_digest'], 0, 64) : null,
'state' => is_string($host['state'] ?? null) ? substr($host['state'], 0, 16) : 'unknown',
'observed_revision' => max(0, (int) ($host['observed_revision'] ?? $host['revision'] ?? 0)),
'observed_digest' => is_string($host['observed_digest'] ?? $host['digest'] ?? null)
? substr((string) ($host['observed_digest'] ?? $host['digest']), 0, 64) : null,
'transport_verified' => ($host['transport_verified'] ?? false) === true,
'private_dataplane_verified' => (
($host['private_dataplane_verified'] ?? false) === true
),
'config_verified' => ($host['config_verified'] ?? false) === true,
'config_observed_revision' => max(0,
(int) ($host['config_observed_revision'] ?? 0)),
'config_observed_digest' => is_string(
$host['config_observed_digest'] ?? null
) ? substr((string) $host['config_observed_digest'], 0, 64) : null,
'removed' => ($host['removed'] ?? false) === true,
'retiring' => ($host['retiring'] ?? false) === true,
'next_stage_allowed' => ($host['next_stage_allowed'] ?? false) === true,
];
if (is_string($host['last_error_code'] ?? null)) {
$bounded['last_error_code'] = substr($host['last_error_code'], 0, 64);
}
foreach (['bridge', 'bridge_owner', 'nft_table', 'readback', 'rollback'] as $field) {
if (is_string($host[$field] ?? null)) {
$bounded[$field] = substr($host[$field], 0, 128);
}
}
if (isset($host['anti_spoof'])) {
$bounded['anti_spoof'] = $host['anti_spoof'] === true;
}
if (isset($host['acl_revision'])) {
$bounded['acl_revision'] = max(0, (int) $host['acl_revision']);
}
if (isset($host['rp_filter'])) {
$bounded['rp_filter'] = max(0, (int) $host['rp_filter']);
}
if (isset($host['proxy_arp'])) {
$bounded['proxy_arp'] = max(0, (int) $host['proxy_arp']);
}
if (isset($host['proxy_arp_pvlan'])) {
$bounded['proxy_arp_pvlan'] = max(0, (int) $host['proxy_arp_pvlan']);
}
if (is_array($host['proxy_ips'] ?? null)) {
$bounded['proxy_ips'] = array_values(array_slice(array_map(
static fn ($ip): string => substr((string) $ip, 0, 64),
$host['proxy_ips']
), 0, self::MAX_OBSERVED_DESTINATIONS));
}
if (is_array($host['member_nics'] ?? null)) {
$bounded['member_nics'] = [];
foreach (array_slice($host['member_nics'], 0, self::MAX_MEMBERS) as $nic) {
if (!is_array($nic)) {
continue;
}
$guestRoutes = [];
foreach (array_slice(
is_array($nic['guest_routes'] ?? null)
? $nic['guest_routes'] : [],
0,
self::MAX_OBSERVED_DESTINATIONS
) as $guestRoute) {
if (is_string($guestRoute)) {
$guestRoutes[] = substr($guestRoute, 0, 64);
}
}
$bounded['member_nics'][] = [
'member_id' => is_string($nic['member_id'] ?? null)
? substr($nic['member_id'], 0, 64) : null,
'instance_uuid' => is_string($nic['instance_uuid'] ?? null)
? substr($nic['instance_uuid'], 0, 64) : null,
'interface' => is_string($nic['interface'] ?? null)
? substr($nic['interface'], 0, 32) : null,
'private_ip_cidr' => is_string($nic['private_ip_cidr'] ?? null)
? substr($nic['private_ip_cidr'], 0, 64) : null,
'private_mac' => is_string($nic['private_mac'] ?? null)
? substr(strtolower($nic['private_mac']), 0, 32) : null,
'xml_verified' => ($nic['xml_verified'] ?? false) === true,
'config_verified' =>
($nic['config_verified'] ?? false) === true,
'seed_verified' =>
($nic['seed_verified'] ?? false) === true,
// Missing on an older engine response is unsafe: it
// cannot prove that this boot-only NoCloud generation
// was loaded by the running domain.
'restart_required' =>
($nic['restart_required'] ?? true) !== false,
'domain_running' => ($nic['domain_running'] ?? false) === true,
'guest_network_verified' =>
($nic['guest_network_verified'] ?? false) === true,
'guest_network_readback' => is_string(
$nic['guest_network_readback'] ?? null
) ? substr($nic['guest_network_readback'], 0, 32) : 'missing',
'guest_link_state' => is_string(
$nic['guest_link_state'] ?? null
) && in_array($nic['guest_link_state'], ['up', 'down'], true)
? $nic['guest_link_state'] : null,
'guest_reason_code' => is_string(
$nic['guest_reason_code'] ?? null
) && preg_match('/^[a-z0-9_]{1,64}$/D',
$nic['guest_reason_code']) === 1
? $nic['guest_reason_code'] : null,
'guest_private_mac' => is_string(
$nic['guest_private_mac'] ?? null
) ? substr(strtolower($nic['guest_private_mac']), 0, 32) : null,
'guest_private_ip_cidr' => is_string(
$nic['guest_private_ip_cidr'] ?? null
) ? substr($nic['guest_private_ip_cidr'], 0, 64) : null,
'link_state' => is_string($nic['link_state'] ?? null)
&& in_array($nic['link_state'], ['up', 'down'], true)
? $nic['link_state'] : null,
'guest_routes' => $guestRoutes,
];
}
}
if (is_array($host['routes'] ?? null)) {
$bounded['routes'] = [];
foreach (array_slice(
$host['routes'], 0, self::MAX_OBSERVED_DESTINATIONS
) as $route) {
if (!is_array($route)) {
continue;
}
$bounded['routes'][] = [
'destination_cidr' => is_string($route['destination_cidr'] ?? null)
? substr($route['destination_cidr'], 0, 64) : null,
'device' => is_string($route['device'] ?? null)
? substr($route['device'], 0, 64) : null,
'table' => is_scalar($route['table'] ?? null)
? substr((string) $route['table'], 0, 32) : null,
'owner' => is_string($route['owner'] ?? null)
? substr($route['owner'], 0, 64) : null,
'via' => is_string($route['via'] ?? null)
? substr($route['via'], 0, 64) : null,
'metric' => is_scalar($route['metric'] ?? null)
? substr((string) $route['metric'], 0, 16) : null,
];
}
}
if (is_array($host['wg_allowed_ips'] ?? null)) {
$bounded['wg_allowed_ips'] = [];
foreach (array_slice(
$host['wg_allowed_ips'], 0, self::MAX_MEMBERS
) as $peer) {
if (!is_array($peer)) {
continue;
}
$ips = $peer['tenant_allowed_ips'] ?? $peer['allowed_ips'] ?? [];
$bounded['wg_allowed_ips'][] = [
'peer_host_id' => is_string($peer['peer_host_id'] ?? null)
? substr($peer['peer_host_id'], 0, 64) : null,
'public_key' => is_string($peer['public_key'] ?? null)
? substr($peer['public_key'], 0, 64) : null,
'tenant_allowed_ips' => is_array($ips)
? array_values(array_slice(array_map(
static fn ($ip): string => substr((string) $ip, 0, 64), $ips
), 0, self::MAX_OBSERVED_DESTINATIONS)) : [],
];
}
}
$hosts[(string) $key] = $bounded;
}
$result = [
'evidence_version' => max(0, (int) ($value['evidence_version']
?? $value['observation_version'] ?? 0)),
'hosts' => $hosts,
];
if ($terminalProof !== null) {
$result['no_data_plane_terminal_proof'] = $terminalProof;
}
return $result;
}
}