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

134 lines
4.7 KiB
PHP

<?php
namespace App\Services\Cloud;
/** Pure policy for two-backend placement and replica-coverage projection. */
final class CloudStorageDurabilityPolicy
{
/** @return array{policy:string,desired_copies:int,required_copies:int} */
public static function forKind(string $kind): array
{
return match ($kind) {
'backup' => [
'policy' => 'mirror_async_2',
'desired_copies' => 2,
'required_copies' => 1,
],
'template', 'rescue' => [
'policy' => 'mirror_required_2',
'desired_copies' => 2,
'required_copies' => 2,
],
default => throw new \InvalidArgumentException(
'Unsupported storage artifact kind'
),
};
}
/**
* Project one logical artifact from exact, verified replica evidence.
*
* @param array<string,mixed> $artifact
* @param list<array<string,mixed>> $replicas
* @return array{state:string,ready_copies:int,pending_copies:int,
* attention_copies:int,meets_publication_requirement:bool,
* can_read:bool,protected:bool}
*/
public static function project(array $artifact, array $replicas): array
{
$desired = self::positiveCopyCount(
$artifact['desired_copies'] ?? null,
'desired_copies'
);
$required = self::positiveCopyCount(
$artifact['required_copies'] ?? null,
'required_copies'
);
if ($desired > 2 || $required > $desired) {
throw new \InvalidArgumentException(
'Storage artifact copy policy is invalid'
);
}
$size = $artifact['size_bytes'] ?? null;
$sha256 = $artifact['sha256'] ?? null;
if (!is_int($size) || $size < 1 || !is_string($sha256)
|| preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new \InvalidArgumentException(
'Storage artifact identity is invalid'
);
}
$ready = 0;
$pending = 0;
$attention = 0;
$seenBackends = [];
foreach ($replicas as $replica) {
$backendId = $replica['backend_id'] ?? null;
if (!is_int($backendId) || $backendId < 1
|| isset($seenBackends[$backendId])) {
throw new \InvalidArgumentException(
'Storage replica backend identity is invalid'
);
}
$seenBackends[$backendId] = true;
$state = is_string($replica['state'] ?? null)
? $replica['state'] : '';
if ($state === 'ready'
&& ($replica['size_bytes'] ?? null) === $size
&& is_string($replica['sha256'] ?? null)
&& hash_equals($sha256, $replica['sha256'])
&& is_int($replica['verified_at'] ?? null)
&& $replica['verified_at'] > 0) {
$ready++;
continue;
}
if (in_array($state, ['reserved', 'publishing', 'copying'], true)) {
$pending++;
} elseif ($state !== 'deleted') {
$attention++;
}
}
$current = is_string($artifact['state'] ?? null)
? $artifact['state'] : 'publishing';
if (in_array($current,
['retiring', 'delete_attention', 'deleted'], true)) {
$state = $current;
} elseif ($ready >= $desired) {
$state = 'protected';
} elseif ($ready >= $required) {
$state = 'available';
} elseif ($pending > 0) {
$state = 'publishing';
} else {
$state = 'degraded';
}
return [
'state' => $state,
'ready_copies' => $ready,
'pending_copies' => $pending,
'attention_copies' => $attention,
// `required_copies` is a publication gate, not a permanent read
// quorum. Once an owner has finalized a required-two artifact, a
// later single-replica failure must not hide the remaining exact,
// verified copy while repair is pending.
'meets_publication_requirement' => $ready >= $required,
'can_read' => $ready >= 1
&& !in_array($state,
['retiring', 'delete_attention', 'deleted'], true),
'protected' => $ready >= $desired,
];
}
private static function positiveCopyCount($value, string $field): int
{
if (!is_int($value) || $value < 1) {
throw new \InvalidArgumentException(
'Storage artifact ' . $field . ' is invalid'
);
}
return $value;
}
}