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/CloudDispatchLedger.php

157 lines
5.6 KiB
PHP

<?php
namespace App\Services\Cloud;
/**
* Fail-closed interpretation of the immutable single-dispatch counter.
*
* Zero is the only counter-level proof that no Agent request was attempted.
* One is the only valid attempted generation. A generation-one request may
* still carry a separate, exact Agent transport proof that its durable
* operation journal was never entered. Any other counter value is corruption:
* callers must retain the resource fence and must not consume recovery proof
* until an operator repairs the ledger.
*/
final class CloudDispatchLedger
{
public const CONFLICT_CODE = 'recovery_dispatch_ledger_conflict';
public const TRANSPORT_NOT_DISPATCHED_REASON =
'worker_transport_not_dispatched';
private const REPAIR_INCIDENT_CODES = [
self::CONFLICT_CODE,
'recovery_dispatch_repair_completion_receipt_missing',
'recovery_dispatch_repair_receipt_invalid',
'recovery_dispatch_repair_aggregate_state_conflict',
'recovery_dispatch_repair_payload_unavailable',
'recovery_dispatch_repair_operation_identity_conflict',
'recovery_dispatch_repair_evidence_conflict',
'recovery_dispatch_repair_instance_state_conflict',
'recovery_dispatch_repair_ledger_conflict',
'recovery_dispatch_repair_internal_error',
];
public static function attempts(object $job): int
{
$value = $job->dispatch_attempts ?? null;
if (is_int($value)) {
return $value;
}
if (is_string($value)
&& preg_match('/^-?[0-9]+$/D', $value) === 1) {
return (int) $value;
}
// A missing, NULL or non-integral value is corruption rather than
// evidence that the mutation never crossed the dispatch boundary.
return PHP_INT_MIN;
}
public static function isNeverDispatched(object $job): bool
{
return self::attempts($job) === 0;
}
public static function isDispatched(object $job): bool
{
return self::attempts($job) === 1;
}
/**
* Exact durable proof created only from the Agent's strict
* dispatch_state=not_dispatched envelope after the dispatch CAS. The
* generation remains one forever; this marker authorizes only the PHP
* business finalizer and never a replay of the original Agent mutation.
*/
public static function hasTransportNotDispatchedProof(object $job): bool
{
return self::isDispatched($job)
&& (string) ($job->execution_mode ?? '') === 'agent'
&& (string) ($job->phase ?? '') === 'terminal'
&& (string) ($job->outcome ?? '') === 'failed'
&& (string) ($job->status ?? '') === 'failed'
&& (string) ($job->attempts ?? '') === '1'
&& (int) ($job->dispatch_started_at ?? 0) > 0
&& (int) ($job->dispatched_at ?? 0) > 0
&& ($job->agent_accepted_at ?? null) === null
&& (int) ($job->receipt_deadline_at ?? 0) > 0
&& ($job->completion_event_id ?? null) === null
&& in_array(
$job->effect_may_have_applied ?? null,
[0, '0', false],
true
)
&& in_array(
$job->safe_to_resubmit ?? null,
[0, '0', false],
true
)
&& (string) ($job->effect_resolution ?? '') === 'not_applied'
&& hash_equals(
self::TRANSPORT_NOT_DISPATCHED_REASON,
(string) ($job->effect_resolution_reason ?? '')
)
&& (string) ($job->error_code ?? '')
=== 'local_finalization_failed'
&& (bool) ($job->finalization_incident ?? false);
}
/** Proof accepted by the PHP-only finalizer; never authorizes Agent I/O. */
public static function isLocallyFinalizableNotDispatched(
object $job
): bool {
return self::isNeverDispatched($job)
|| self::hasTransportNotDispatchedProof($job);
}
public static function isInvalid(object $job): bool
{
return !in_array(self::attempts($job), [0, 1], true);
}
/** Invalid non-zero state is conservatively treated as possibly sent. */
public static function mayHaveDispatched(object $job): bool
{
return !self::isNeverDispatched($job);
}
public static function assertValid(object $job): void
{
if (self::isInvalid($job)) {
throw new CloudRecoveryDispatchLedgerConflict(
'任务单次派发计数账本异常',
409
);
}
}
public static function assertDispatched(object $job): void
{
self::assertValid($job);
if (!self::isDispatched($job)) {
throw new CloudError('任务没有跨越 Agent 派发边界', 409);
}
}
/** @return list<string> */
public static function repairIncidentCodes(): array
{
return self::REPAIR_INCIDENT_CODES;
}
/**
* A repaired counter remains sticky until the background coordinator has
* revalidated the immutable terminal row. This closes the brief window in
* which changing 2 to 0/1 could otherwise release the resource early.
*/
public static function hasRepairIncident(object $job): bool
{
return (string) ($job->execution_mode ?? '') === 'agent'
&& (string) ($job->phase ?? '') === 'terminal'
&& (bool) ($job->finalization_incident ?? false)
&& in_array(
(string) ($job->finalization_error_code ?? ''),
self::REPAIR_INCIDENT_CODES,
true
);
}
}