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

480 lines
18 KiB
PHP

<?php
namespace App\Services\Cloud;
use App\Models\User;
/**
* Polls one Agent and atomically applies its aggregate minutes to the compact
* main-database ledger. No raw sample, projection outbox or cross-database
* receipt is created.
*/
final class CloudAbuseObservationIngestService
{
private const PAGE_LIMIT = 64;
private const POLL_SECONDS = 15;
private const LEASE_SECONDS = 45;
private const MAX_BACKOFF_SECONDS = 300;
/** @var \Closure():array<int> */
private readonly \Closure $hostIds;
/** @var \Closure(int):object */
private readonly \Closure $clientFactory;
/** @var \Closure():int */
private readonly \Closure $clock;
/** @var \Closure():CloudAbusePolicySnapshot */
private readonly \Closure $policySnapshot;
private readonly CloudNetworkAbuseLedger $ledger;
/** @var list<string> */
private array $errors = [];
/**
* @param null|callable():array<int> $hostIds
* @param null|callable(int):object $clientFactory
* @param null|callable():int $clock
* @param null|callable():CloudAbusePolicySnapshot $policySnapshot
*/
public function __construct(
?callable $hostIds = null,
?callable $clientFactory = null,
?callable $clock = null,
?callable $policySnapshot = null,
?CloudNetworkAbuseLedger $ledger = null
) {
$this->hostIds = \Closure::fromCallable($hostIds
?? static fn (): array =>
CloudAgentSettingsService::enabledHostIds());
$this->clientFactory = \Closure::fromCallable($clientFactory
?? static fn (int $hostId): CloudAgentClient =>
CloudAgentSettingsService::clientForHost($hostId, 12.0));
$this->clock = \Closure::fromCallable($clock
?? static fn (): int => time());
$this->policySnapshot = \Closure::fromCallable($policySnapshot
?? static fn (): CloudAbusePolicySnapshot =>
(new CloudAbusePolicyService())->activeSnapshot());
$this->ledger = $ledger ?? new CloudNetworkAbuseLedger();
}
/** Poll at most one due host. */
public function tick(): bool
{
$this->errors = [];
$now = ($this->clock)();
if (!is_int($now) || $now < 1) {
throw new \LogicException('Abuse monitor clock is invalid');
}
$hostIds = self::normalizeHostIds(($this->hostIds)());
if ($hostIds === []) {
return false;
}
$claim = $this->claim($hostIds, $now);
if ($claim === null) {
return false;
}
try {
$client = ($this->clientFactory)($claim['host_id']);
if (!is_object($client)
|| !is_callable([$client, 'networkObservations'])) {
throw new \LogicException(
'Abuse monitor client does not implement observations'
);
}
$batch = $client->networkObservations(
self::systemActor(),
$claim['generation'],
$claim['cursor'],
self::PAGE_LIMIT
);
if (!is_array($batch)) {
throw self::invalidAgentContract();
}
$this->commitBatch($claim, $batch, $now);
} catch (\Throwable $error) {
$this->recordFailure($claim, $error, $now);
$this->errors[] = $error instanceof CloudAgentError
? $error->agentCode
: 'network_observation_collection_failed';
}
return true;
}
/** @return list<string> */
public function observationErrors(): array
{
return $this->errors;
}
/** @param array<int> $hostIds @return null|array<string,mixed> */
private function claim(array $hostIds, int $now): ?array
{
$database = User::getConnectionResolver()->connection('default');
return $database->transaction(static function () use (
$database,
$hostIds,
$now
): ?array {
foreach ($hostIds as $hostId) {
$database->table('cloud_network_monitor_hosts')
->insertOrIgnore([
'host_id' => $hostId,
'collector_generation' => null,
'cursor_value' => 0,
'oldest_cursor' => 0,
'gap_before' => 0,
'poll_revision' => 0,
'next_poll_at' => 0,
'poll_lease_token' => null,
'poll_lease_until' => 0,
'collection_state' => 'unknown',
'consecutive_failures' => 0,
'last_window_start' => null,
'last_success_at' => null,
'last_error_code' => '',
'updated_at' => $now,
]);
}
$row = $database->table('cloud_network_monitor_hosts')
->whereIn('host_id', $hostIds)
->where('next_poll_at', '<=', $now)
->where(static function ($lease) use ($now): void {
$lease->whereNull('poll_lease_token')
->orWhere('poll_lease_until', '<=', $now);
})
->orderBy('next_poll_at')->orderBy('host_id')
->lockForUpdate()->first();
if ($row === null) {
return null;
}
$token = bin2hex(random_bytes(16));
$revision = (int) $row->poll_revision + 1;
$updated = $database->table('cloud_network_monitor_hosts')
->where('host_id', (int) $row->host_id)
->where('poll_revision', (int) $row->poll_revision)
->update([
'poll_revision' => $revision,
'poll_lease_token' => $token,
'poll_lease_until' => $now + self::LEASE_SECONDS,
'updated_at' => $now,
]);
if ($updated !== 1) {
return null;
}
return [
'host_id' => (int) $row->host_id,
'generation' => is_string($row->collector_generation)
&& $row->collector_generation !== ''
? $row->collector_generation : null,
'cursor' => max(0, (int) $row->cursor_value),
'oldest_cursor' => max(0, (int) $row->oldest_cursor),
'gap_before' => (int) $row->gap_before === 1,
'revision' => $revision,
'lease_token' => $token,
'failures' => max(0, (int) $row->consecutive_failures),
'last_window_start' => $row->last_window_start === null
? null : max(0, (int) $row->last_window_start),
];
}, 3);
}
/** @param array<string,mixed> $claim @param array<string,mixed> $batch */
private function commitBatch(array $claim, array $batch, int $now): void
{
self::assertBatch($batch);
$generation = (string) $batch['collector_generation'];
$windows = $batch['windows'];
$snapshot = null;
if ($windows !== []) {
$snapshot = ($this->policySnapshot)();
if (!$snapshot instanceof CloudAbusePolicySnapshot) {
throw new \LogicException(
'Abuse monitor policy snapshot is invalid'
);
}
}
$hostId = (int) $claim['host_id'];
$sameGeneration = is_string($claim['generation'])
&& hash_equals($claim['generation'], $generation);
$uuids = [];
foreach ($windows as $window) {
if (!is_array($window)) {
throw self::invalidAgentContract();
}
$uuid = strtolower((string) ($window['vm_uuid'] ?? ''));
if (preg_match(
'/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/D',
$uuid
) !== 1) {
throw self::invalidAgentContract();
}
$uuids[$uuid] = $uuid;
}
$database = User::getConnectionResolver()->connection('default');
$database->transaction(function () use (
$database,
$claim,
$batch,
$generation,
$hostId,
$sameGeneration,
$uuids,
$windows,
$snapshot,
$now
): void {
$host = $database->table('cloud_network_monitor_hosts')
->where('host_id', $hostId)
->where('poll_revision', (int) $claim['revision'])
->where('poll_lease_token', (string) $claim['lease_token'])
->lockForUpdate()->first();
if ($host === null) {
throw new \RuntimeException(
'Abuse monitor poll lease was lost before commit'
);
}
$instances = $uuids === [] ? collect() : $database
->table('cloud_instances')
->where('host_id', $hostId)
->whereIn('uuid', array_values($uuids))
->orderBy('id')->lockForUpdate()->get()->keyBy(
static fn (object $row): string =>
strtolower((string) $row->uuid)
);
$mappingMiss = count($instances) !== count($uuids);
$gapActive = ($batch['gap_before'] ?? false) === true
|| ($sameGeneration
&& ($claim['gap_before'] ?? false) === true);
foreach ($windows as $window) {
$uuid = strtolower((string) $window['vm_uuid']);
$instance = $instances->get($uuid);
if ($instance === null) {
continue;
}
$quality = self::qualityFlags($window['quality_flags'] ?? null);
$complete = ($window['complete'] ?? null) === true;
if ($gapActive) {
$complete = false;
$quality[] = 'incomplete';
$quality[] = 'panel_ring_gap';
$quality = array_values(array_unique($quality));
sort($quality, SORT_STRING);
}
$sample = [
'bucket_start' => self::bucketEpoch(
(string) ($window['bucket_start'] ?? '')
),
'complete' => $complete,
'quality_flags' => $quality,
'metrics' => [
'interface' => $window['interface'] ?? null,
'ipv4' => $window['ipv4'] ?? null,
'ipv6' => $window['ipv6'] ?? null,
],
];
$this->ledger->apply(
$database,
(int) $instance->id,
$sample,
$snapshot,
$now
);
}
$cursor = $windows === [] && $sameGeneration
? (int) $claim['cursor'] : (int) $batch['next_cursor'];
$oldest = $windows === [] && $sameGeneration
? (int) $claim['oldest_cursor']
: (int) $batch['oldest_cursor'];
$lastWindow = $claim['last_window_start'];
if ($windows !== []) {
$last = $windows[array_key_last($windows)];
$lastWindow = self::bucketEpoch(
(string) $last['bucket_start']
);
}
$available = ($batch['capability']['available'] ?? false) === true;
$state = !$available ? 'unavailable'
: (($gapActive || $mappingMiss) ? 'degraded' : 'healthy');
$errorCode = !$available
? (string) ($batch['capability']['reason']
?? 'collection_unavailable')
: ($mappingMiss ? 'instance_mapping_missing'
: ($gapActive ? 'ring_gap' : ''));
if (preg_match('/^[a-z0-9_]{0,64}$/D', $errorCode) !== 1) {
$errorCode = 'collection_unavailable';
}
$gapPending = $gapActive
&& ($batch['has_more'] ?? false) === true;
$values = [
'collector_generation' => $generation,
'cursor_value' => $cursor,
'oldest_cursor' => $oldest,
'gap_before' => $gapPending ? 1 : 0,
'next_poll_at' => $batch['has_more']
? $now : $now + self::POLL_SECONDS,
'poll_lease_token' => null,
'poll_lease_until' => 0,
'collection_state' => $state,
'consecutive_failures' => 0,
'last_window_start' => $lastWindow,
'last_error_code' => $errorCode,
'updated_at' => $now,
];
if ($available) {
$values['last_success_at'] = $now;
}
$updated = $database->table('cloud_network_monitor_hosts')
->where('host_id', $hostId)
->where('poll_revision', (int) $claim['revision'])
->where('poll_lease_token', (string) $claim['lease_token'])
->update($values);
if ($updated !== 1) {
throw new \RuntimeException(
'Abuse monitor poll lease was lost before cursor commit'
);
}
}, 3);
}
/** @param array<string,mixed> $claim */
private function recordFailure(
array $claim,
\Throwable $error,
int $now
): void {
$failures = (int) $claim['failures'] + 1;
$code = $error instanceof CloudAgentError
? $error->agentCode : 'network_observation_collection_failed';
if (preg_match('/^[a-z0-9_]{3,64}$/D', $code) !== 1) {
$code = 'network_observation_collection_failed';
}
$backoff = min(
self::MAX_BACKOFF_SECONDS,
15 * (2 ** min(4, max(0, $failures - 1)))
);
User::getConnectionResolver()->connection('default')
->table('cloud_network_monitor_hosts')
->where('host_id', (int) $claim['host_id'])
->where('poll_revision', (int) $claim['revision'])
->where('poll_lease_token', (string) $claim['lease_token'])
->update([
'next_poll_at' => $now + $backoff,
'poll_lease_token' => null,
'poll_lease_until' => 0,
'collection_state' => $failures >= 3
? 'unavailable' : 'degraded',
'consecutive_failures' => $failures,
'last_error_code' => $code,
'updated_at' => $now,
]);
}
/** @param array<string,mixed> $batch */
private static function assertBatch(array $batch): void
{
if (($batch['contract_version'] ?? null) !== 1
|| preg_match(
'/^[a-f0-9]{32}$/D',
(string) ($batch['collector_generation'] ?? '')
) !== 1
|| !is_int($batch['oldest_cursor'] ?? null)
|| $batch['oldest_cursor'] < 0
|| !is_int($batch['next_cursor'] ?? null)
|| $batch['next_cursor'] < 0
|| !is_array($batch['windows'] ?? null)
|| !array_is_list($batch['windows'])
|| !is_bool($batch['gap_before'] ?? null)
|| !is_bool($batch['has_more'] ?? null)
|| !is_array($batch['capability'] ?? null)) {
throw self::invalidAgentContract();
}
}
/** @return list<string> */
private static function qualityFlags(mixed $value): array
{
if (!is_array($value) || !array_is_list($value)) {
throw self::invalidAgentContract();
}
$flags = [];
foreach ($value as $flag) {
if (!is_string($flag)) {
throw self::invalidAgentContract();
}
$flags[$flag] = $flag;
}
ksort($flags, SORT_STRING);
return array_values($flags);
}
private static function bucketEpoch(string $value): int
{
$parsed = \DateTimeImmutable::createFromFormat(
'!Y-m-d\TH:i:s\Z',
$value,
new \DateTimeZone('UTC')
);
$errors = \DateTimeImmutable::getLastErrors();
if ($parsed === false || ($errors !== false
&& ($errors['warning_count'] !== 0
|| $errors['error_count'] !== 0))
|| $parsed->format('Y-m-d\TH:i:s\Z') !== $value
|| $parsed->getTimestamp() < 1
|| $parsed->getTimestamp() % 60 !== 0) {
throw self::invalidAgentContract();
}
return $parsed->getTimestamp();
}
private static function invalidAgentContract(): CloudAgentError
{
return new CloudAgentError(
'宿主机 Agent 返回了无效的网络观测合同',
502,
'agent_invalid_network_observation',
true
);
}
/** @param mixed $values @return array<int> */
private static function normalizeHostIds(mixed $values): array
{
if (!is_array($values)) {
throw new \LogicException('Abuse monitor host list is invalid');
}
$result = [];
foreach ($values as $value) {
if (!is_int($value) && !ctype_digit((string) $value)) {
throw new \LogicException(
'Abuse monitor host ID is invalid'
);
}
$id = (int) $value;
if ($id < 1) {
throw new \LogicException(
'Abuse monitor host ID is invalid'
);
}
$result[$id] = $id;
}
ksort($result, SORT_NUMERIC);
return array_values($result);
}
/** Dedicated service actor for the signed, read-only inspection route. */
private static function systemActor(): array
{
return [
'user_id' => 1,
'is_admin' => true,
'is_super_admin' => true,
'can_manage' => true,
];
}
}