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/CloudPortableRestoreTargetP...

367 lines
13 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Canonical, immutable evidence for one advisory portable-restore target.
* It contains no Eloquent models, concrete addresses, credentials or URLs.
*/
final class CloudPortableRestoreTargetPlan
{
private const GIB = 1073741824;
private readonly array $plan;
private readonly string $json;
private readonly string $sha256;
private function __construct(array $plan)
{
$this->plan = CloudCanonicalJson::normalize($plan);
$this->json = json_encode(
$this->plan,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$this->sha256 = hash('sha256', $this->json);
}
/**
* Validate and freeze the complete advisory-evidence contract. The target
* scheduler is the only production caller; accepting arbitrary arrays here
* would make a forged value indistinguishable from scheduler evidence.
*/
public static function fromEvidence(array $plan): self
{
return self::fromEvidenceContract($plan, true);
}
/** Validate a plan while choosing whether current runtime support matters. */
private static function fromEvidenceContract(
array $plan,
bool $requireCurrentCompatibility
): self
{
self::exactKeys($plan, [
'contract', 'backup', 'target', 'resources', 'capacity',
'public_network', 'vpc_inherited',
]);
if (($plan['contract'] ?? null) !== 1
|| ($plan['vpc_inherited'] ?? null) !== false) {
throw new \InvalidArgumentException(
'Portable restore plan contract is invalid'
);
}
$backup = self::object($plan['backup'] ?? null, [
'id', 'backup_key', 'object_size_bytes', 'object_sha256',
'object_identity_sha256', 'source_contract_sha256',
'source_spec_sha256', 'restore_request_sha256',
'source_public_network_sha256', 'source_host_id',
'source_line_id', 'source_storage_revision',
'virtual_size_bytes',
]);
self::positiveInt($backup['id']);
self::hex($backup['backup_key'], 32);
self::positiveInt($backup['object_size_bytes']);
self::hex($backup['object_sha256'], 64);
self::hex($backup['object_identity_sha256'], 64);
self::hex($backup['source_contract_sha256'], 64);
self::hex($backup['source_spec_sha256'], 64);
self::hex($backup['restore_request_sha256'], 64);
self::hex($backup['source_public_network_sha256'], 64);
self::positiveInt($backup['source_host_id']);
self::positiveInt($backup['source_line_id']);
self::nonNegativeInt($backup['source_storage_revision']);
self::positiveInt($backup['virtual_size_bytes']);
$target = self::object($plan['target'] ?? null, [
'host_id', 'host_name', 'is_source_host', 'resource_pool_id',
'resource_pool_name', 'membership_revision', 'line_id',
'line_name', 'region_id', 'region_name', 'country_code',
'agent_revision', 'agent_contract_sha256', 'storage_revision',
]);
foreach (['host_id', 'resource_pool_id', 'membership_revision',
'line_id', 'region_id', 'agent_revision', 'storage_revision']
as $field) {
self::positiveInt($target[$field]);
}
foreach (['host_name', 'resource_pool_name', 'line_name',
'region_name'] as $field) {
self::nonEmptyString($target[$field]);
}
if (!is_bool($target['is_source_host'])
|| $target['is_source_host'] !==
($target['host_id'] === $backup['source_host_id'])
|| !is_string($target['country_code'])
|| preg_match('/^[A-Z]{2}$/D', $target['country_code']) !== 1) {
throw new \InvalidArgumentException(
'Portable restore target identity is invalid'
);
}
self::hex($target['agent_contract_sha256'], 64);
$supportedContractSha256 =
CloudPortableRestoreCompatibility::supported()->sha256();
if (!hash_equals(
$backup['source_contract_sha256'],
$target['agent_contract_sha256']
) || ($requireCurrentCompatibility && !hash_equals(
$supportedContractSha256,
$backup['source_contract_sha256']
))) {
throw new \InvalidArgumentException(
'Portable restore contracts do not match'
);
}
$resources = self::object($plan['resources'] ?? null, [
'cpu_cores', 'memory_mib', 'disk_gib', 'bandwidth_mbps',
'system_disk_virtual_size_bytes',
]);
foreach ($resources as $value) {
self::positiveInt($value);
}
if ($resources['disk_gib'] > intdiv(PHP_INT_MAX, self::GIB)
|| $resources['system_disk_virtual_size_bytes']
> $resources['disk_gib'] * self::GIB
|| $resources['system_disk_virtual_size_bytes']
!== $backup['virtual_size_bytes']) {
throw new \InvalidArgumentException(
'Portable restore disk evidence is invalid'
);
}
$capacity = self::object($plan['capacity'] ?? null, [
'policy_updated_at', 'requested', 'used', 'limits',
]);
self::positiveInt($capacity['policy_updated_at']);
$requested = self::object($capacity['requested'], [
'cpu_cores', 'memory_mib', 'disk_gib',
]);
$used = self::object($capacity['used'], [
'instance_count', 'cpu_cores', 'memory_mib', 'disk_gib',
]);
$limits = self::object($capacity['limits'], [
'instance_count', 'cpu_cores', 'memory_mib', 'disk_gib',
]);
foreach ($requested as $field => $value) {
self::positiveInt($value);
if ($value !== $resources[$field]) {
throw new \InvalidArgumentException(
'Portable restore capacity request drifted'
);
}
}
foreach ($used as $value) {
self::nonNegativeInt($value);
}
self::nonNegativeInt($limits['instance_count']);
foreach (['cpu_cores', 'memory_mib', 'disk_gib'] as $field) {
self::positiveInt($limits[$field]);
if ($requested[$field] > $limits[$field]
|| $used[$field] > $limits[$field] - $requested[$field]) {
throw new \InvalidArgumentException(
'Portable restore capacity is insufficient'
);
}
}
if ($limits['instance_count'] > 0
&& $used['instance_count'] + 1 > $limits['instance_count']) {
throw new \InvalidArgumentException(
'Portable restore instance capacity is insufficient'
);
}
$network = self::object($plan['public_network'] ?? null, [
'mode', 'host_id', 'line_id', 'network_attachment_id',
'attachment_key', 'network_selector',
'attachment_config_revision',
'attachment_verified_agent_revision', 'ipv4_pool', 'ipv6_pool',
]);
if (($network['mode'] ?? null) !== 'fresh_dual_stack') {
throw new \InvalidArgumentException(
'Portable restore network mode is invalid'
);
}
foreach (['host_id', 'line_id', 'network_attachment_id',
'attachment_config_revision',
'attachment_verified_agent_revision'] as $field) {
self::positiveInt($network[$field]);
}
self::hex($network['attachment_key'], 32);
if (!CloudNetworkSelector::isValid($network['network_selector'])
|| $network['host_id'] !== $target['host_id']
|| $network['line_id'] !== $target['line_id']
|| $network['attachment_verified_agent_revision']
!== $target['agent_revision']) {
throw new \InvalidArgumentException(
'Portable restore network attachment is inconsistent'
);
}
$ipv4 = self::pool($network['ipv4_pool'], 4,
$network['network_attachment_id']);
$ipv6 = self::pool($network['ipv6_pool'], 6,
$network['network_attachment_id']);
if ($ipv4['public_ip_pool_id'] === $ipv6['public_ip_pool_id']
|| hash_equals($ipv4['pool_key'], $ipv6['pool_key'])) {
throw new \InvalidArgumentException(
'Portable restore network pools are not distinct'
);
}
return new self($plan);
}
/** Rehydrate only exact canonical scheduler output. */
public static function fromStored(string $json, string $sha256): self
{
return self::fromStoredContract($json, $sha256, true);
}
/**
* Rehydrate immutable historical evidence without requiring the current
* runtime to keep supporting that already-completed restore contract.
*/
public static function fromHistoricalStored(
string $json,
string $sha256
): self {
return self::fromStoredContract($json, $sha256, false);
}
private static function fromStoredContract(
string $json,
string $sha256,
bool $requireCurrentCompatibility
): self
{
if (preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1
|| !hash_equals(hash('sha256', $json), $sha256)) {
throw new \InvalidArgumentException(
'Portable restore plan digest is invalid'
);
}
try {
$decoded = json_decode($json, true, 64, JSON_THROW_ON_ERROR);
} catch (\JsonException $exception) {
throw new \InvalidArgumentException(
'Portable restore plan JSON is invalid',
0,
$exception
);
}
if (!is_array($decoded) || array_is_list($decoded)) {
throw new \InvalidArgumentException(
'Portable restore plan JSON is invalid'
);
}
$plan = self::fromEvidenceContract(
$decoded,
$requireCurrentCompatibility
);
if (!hash_equals($plan->sha256(), $sha256)
|| !hash_equals($plan->json(), $json)) {
throw new \InvalidArgumentException(
'Portable restore plan is not canonical'
);
}
return $plan;
}
public function toArray(): array
{
return $this->plan;
}
public function json(): string
{
return $this->json;
}
public function sha256(): string
{
return $this->sha256;
}
private static function object(mixed $value, array $keys): array
{
if (!is_array($value) || array_is_list($value)) {
throw new \InvalidArgumentException(
'Portable restore plan object is invalid'
);
}
self::exactKeys($value, $keys);
return $value;
}
private static function pool(mixed $value, int $family,
int $attachmentId): array
{
$pool = self::object($value, [
'public_ip_pool_id', 'pool_key', 'network_attachment_id',
'address_family', 'desired_revision', 'observed_revision',
'available_units',
]);
foreach (['public_ip_pool_id', 'network_attachment_id',
'address_family', 'desired_revision', 'observed_revision',
'available_units'] as $field) {
self::positiveInt($pool[$field]);
}
self::hex($pool['pool_key'], 32);
if ($pool['address_family'] !== $family
|| $pool['network_attachment_id'] !== $attachmentId
|| $pool['observed_revision'] !== $pool['desired_revision']) {
throw new \InvalidArgumentException(
'Portable restore public pool evidence is inconsistent'
);
}
return $pool;
}
private static function exactKeys(array $value, array $expected): void
{
$actual = array_keys($value);
sort($actual, SORT_STRING);
sort($expected, SORT_STRING);
if ($actual !== $expected) {
throw new \InvalidArgumentException(
'Portable restore plan fields are invalid'
);
}
}
private static function positiveInt(mixed $value): void
{
if (!is_int($value) || $value < 1) {
throw new \InvalidArgumentException(
'Portable restore positive integer is invalid'
);
}
}
private static function nonNegativeInt(mixed $value): void
{
if (!is_int($value) || $value < 0) {
throw new \InvalidArgumentException(
'Portable restore non-negative integer is invalid'
);
}
}
private static function hex(mixed $value, int $length): void
{
if (!is_string($value)
|| preg_match('/^[a-f0-9]{' . $length . '}$/D', $value) !== 1) {
throw new \InvalidArgumentException(
'Portable restore digest or key is invalid'
);
}
}
private static function nonEmptyString(mixed $value): void
{
if (!is_string($value) || trim($value) === ''
|| strlen($value) > 255) {
throw new \InvalidArgumentException(
'Portable restore label is invalid'
);
}
}
}