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

2873 lines
112 KiB
PHP

<?php
namespace App\Services\Cloud;
use App\Models\CloudStorageArtifact;
use App\Models\CloudStorageBackend;
use App\Models\CloudInstanceBackup;
use App\Models\CloudStorageOperation;
use App\Models\CloudStoragePublication;
use App\Models\CloudStorageReplica;
/**
* Durable control plane for one logical object and its provider replicas.
*
* This module records intent before remote I/O. Callers must fence a primary
* publish through markPrimaryDispatching() before contacting a provider, then
* settle that same operation through completePrimary() or failPrimary().
*/
final class CloudStorageArtifactService
{
/** Secondary work stays dormant until the primary is durably verified. */
private const COPY_BLOCKED_UNTIL_PRIMARY = 253402300799;
/** @var list<string> */
private const REPLICA_ATTENTION_ERRORS = [
'replica_multipart_identity_ambiguous',
'replica_multipart_identity_mismatch',
'replica_multipart_identity_untrusted',
];
/** CreateMultipartUpload effects that need bounded operator attention. */
private const PRIMARY_PREPARATION_ATTENTION_ERRORS = [
'primary_multipart_identity_ambiguous',
'primary_multipart_identity_mismatch',
'primary_multipart_identity_untrusted',
];
/** @return list<string> */
public static function replicaAttentionErrors(): array
{
return self::REPLICA_ATTENTION_ERRORS;
}
/** @return list<string> */
public static function primaryPreparationAttentionErrors(): array
{
return self::PRIMARY_PREPARATION_ATTENTION_ERRORS;
}
/**
* Reserve one immutable artifact and every currently eligible replica.
* No provider request is made here.
*
* @return array<string,mixed>
*/
public static function beginPublication(
string $kind,
string $objectSuffix,
int $sizeBytes,
string $sha256,
string $requestIdempotencyKey,
string $requestFingerprint,
array $owner
): array {
self::assertObjectIdentity($sizeBytes, $sha256);
return self::reservePublication(
$kind,
$objectSuffix,
$sizeBytes,
$sha256,
$sizeBytes,
$requestIdempotencyKey,
$requestFingerprint,
$owner
);
}
/** Reserve an Agent upload before its exact receipt identity is known. */
public static function beginAgentPublication(
string $kind,
string $objectSuffix,
int $maximumSizeBytes,
string $requestIdempotencyKey,
string $requestFingerprint,
array $owner
): array {
if ($maximumSizeBytes < 1) {
throw new CloudError('对象存储制品最大容量无效', 422);
}
return self::reservePublication(
$kind,
$objectSuffix,
0,
'',
$maximumSizeBytes,
$requestIdempotencyKey,
$requestFingerprint,
$owner
);
}
/** @return array<string,mixed> */
private static function reservePublication(
string $kind,
string $objectSuffix,
int $sizeBytes,
string $sha256,
int $maximumSizeBytes,
string $requestIdempotencyKey,
string $requestFingerprint,
array $owner
): array {
$policy = CloudStorageDurabilityPolicy::forKind($kind);
$objectSuffix = self::objectSuffix($objectSuffix);
$owner = self::owner($kind, $owner);
self::assertRequestIdentity(
$requestIdempotencyKey,
$requestFingerprint
);
$connection = (new CloudStorageArtifact())->getConnection();
$operationId = $connection->transaction(static function () use (
$connection,
$kind,
$objectSuffix,
$sizeBytes,
$sha256,
$maximumSizeBytes,
$requestIdempotencyKey,
$requestFingerprint,
$policy,
$owner
): string {
$existing = CloudStorageOperation::query()
->where('request_idempotency_key', $requestIdempotencyKey)
->lockForUpdate()->first();
if ($existing instanceof CloudStorageOperation) {
if ((string) $existing->kind !== 'publish'
|| !hash_equals(
(string) $existing->request_fingerprint,
$requestFingerprint
)) {
throw new CloudError(
'对象存储发布幂等键已用于其他请求',
409
);
}
self::assertExistingOwner($existing, $owner);
return (string) $existing->operation_id;
}
$backends = CloudStorageBackend::query()
->where('admin_state', '<>', 'retired')
->orderBy('write_priority')->orderBy('id')
->lockForUpdate()->get()->map(
static fn (CloudStorageBackend $backend): array => [
'id' => (int) $backend->id,
'config_revision' => (int) $backend->config_revision,
'tested_revision' => (int) $backend->tested_revision,
'admin_state' => (string) $backend->admin_state,
'health_state' => (string) $backend->health_state,
'write_priority' => (int) $backend->write_priority,
'failure_domain' => (string) $backend->failure_domain,
'prefix' => (string) $backend->prefix,
]
)->values()->all();
$selected = CloudStoragePlacementPolicy::select(
$backends,
$policy['desired_copies'],
$policy['required_copies']
);
$now = time();
$artifact = new CloudStorageArtifact();
$artifact->artifact_key = bin2hex(random_bytes(16));
$artifact->kind = $kind;
$artifact->maximum_size_bytes = $maximumSizeBytes;
$artifact->size_bytes = $sizeBytes;
$artifact->sha256 = $sha256;
$artifact->durability_policy = $policy['policy'];
$artifact->desired_copies = $policy['desired_copies'];
$artifact->required_copies = $policy['required_copies'];
$artifact->state = 'publishing';
$artifact->last_operation_id = null;
$artifact->verified_at = 0;
$artifact->created_at = $now;
$artifact->updated_at = $now;
$artifact->save();
$publication = new CloudStoragePublication();
$publication->publication_key = bin2hex(random_bytes(16));
$publication->artifact_id = (int) $artifact->id;
$publication->backup_id = $owner['backup_id'];
$publication->template_import_intent_id =
$owner['template_import_intent_id'];
$publication->rescue_template_id = $owner['rescue_template_id'];
$publication->state = 'waiting_primary';
$publication->attempts = 0;
$publication->available_at = 0;
$publication->lease_token = null;
$publication->lease_until = 0;
$publication->last_error_code = '';
$publication->coverage_ready_at = null;
$publication->finalized_at = null;
$publication->created_at = $now;
$publication->updated_at = $now;
$publication->save();
$primaryOperationId = bin2hex(random_bytes(16));
$primaryBackendId = (int) $selected[0]['id'];
foreach ($selected as $index => $backend) {
$replica = new CloudStorageReplica();
$replica->replica_key = bin2hex(random_bytes(16));
$replica->artifact_id = (int) $artifact->id;
$replica->backend_id = (int) $backend['id'];
$replica->role = $index === 0 ? 'primary' : 'secondary';
$replica->object_key = self::objectKey(
(string) $backend['prefix'],
$objectSuffix
);
$replica->object_version_id = '';
$replica->object_etag = '';
$replica->size_bytes = 0;
$replica->sha256 = '';
$replica->state = 'reserved';
$replica->publish_operation_id = null;
$replica->delete_operation_id = null;
$replica->delete_generation = 0;
$replica->delete_cycle_attempts = 0;
$replica->delete_presence_confirmations = 0;
$replica->delete_last_checked_at = 0;
$replica->delete_next_check_at = 0;
$replica->delete_attention_at = null;
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = '';
$replica->verified_at = 0;
$replica->created_at = $now;
$replica->updated_at = $now;
$replica->save();
$operation = new CloudStorageOperation();
$operation->operation_id = $index === 0
? $primaryOperationId : bin2hex(random_bytes(16));
$operation->request_idempotency_key = $index === 0
? $requestIdempotencyKey
: self::copyIdempotencyKey(
$requestIdempotencyKey,
(int) $backend['id']
);
$operation->request_fingerprint = $index === 0
? $requestFingerprint : hash('sha256', implode('|', [
'copy', (string) $artifact->artifact_key,
(string) $primaryBackendId,
(string) $backend['id'], $objectSuffix,
]));
$operation->artifact_id = (int) $artifact->id;
$operation->replica_id = (int) $replica->id;
$operation->source_backend_id = $index === 0
? null : $primaryBackendId;
$operation->target_backend_id = (int) $backend['id'];
$operation->kind = $index === 0 ? 'publish' : 'copy';
self::initializeOperation($operation, $now);
if ($index === 0) {
$operation->result_json = json_encode([
'maximum_size_bytes' => $maximumSizeBytes,
'object_suffix' => $objectSuffix,
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
} else {
$operation->available_at =
self::COPY_BLOCKED_UNTIL_PRIMARY;
}
$operation->save();
$replica->publish_operation_id = $operation->operation_id;
$replica->save();
}
$artifact->last_operation_id = $primaryOperationId;
$artifact->save();
return $primaryOperationId;
});
return self::publicationView($operationId);
}
/** Internal runtime; credentials must never enter a response or log. */
public static function primaryRuntime(string $operationId): array
{
$view = self::publicationView($operationId);
return CloudObjectStorageBackendRegistry::runtime(
(int) $view['backend_id'],
true
);
}
/** Fence the primary operation immediately before remote publish I/O. */
public static function markPrimaryDispatching(string $operationId): array
{
self::assertOperationId($operationId);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use ($operationId): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase !== 'accepted'
|| (string) $replica->state !== 'reserved'
|| (string) $artifact->state !== 'publishing') {
throw new CloudError(
'对象存储发布操作已经派发或结束,禁止再次提交',
409
);
}
$now = time();
$operation->phase = 'dispatching';
$operation->attempts = (int) $operation->attempts + 1;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'publishing';
$replica->updated_at = $now;
$replica->save();
});
return self::publicationView($operationId);
}
/** @param array<string,mixed> $identity */
public static function completePrimary(
string $operationId,
int $expectedArtifactId,
array $identity
): array {
self::assertOperationId($operationId);
if ($expectedArtifactId < 1) {
throw new CloudError('对象存储制品身份无效', 422);
}
$size = self::positiveInt($identity['size_bytes'] ?? null);
$receiptSha = $identity['sha256'] ?? null;
if (!is_string($receiptSha)
|| preg_match('/^[a-f0-9]{64}$/D', $receiptSha) !== 1) {
throw new CloudError('对象存储主副本哈希身份无效', 502);
}
$etag = self::providerIdentity($identity['etag'] ?? null, 256);
$versionId = self::providerVersionIdentity(
$identity['version_id'] ?? null,
1024
);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$expectedArtifactId,
$size,
$receiptSha,
$etag,
$versionId
): void {
$operation = self::primaryOperationLocked($operationId);
if ((int) $operation->artifact_id !== $expectedArtifactId) {
throw new CloudError('对象存储发布操作与制品身份不一致', 409);
}
$copyOperations = self::copyOperationsLocked(
(int) $operation->artifact_id
);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'terminal') {
if ((string) $operation->outcome === 'succeeded') {
self::assertSettledReplicaIdentity(
$artifact,
$replica,
$size,
$receiptSha,
$etag,
$versionId,
'对象存储重复主副本回执身份不一致'
);
return;
}
throw new CloudError('对象存储发布操作已失败,禁止覆盖结算', 409);
}
if (!in_array((string) $operation->phase,
['dispatching', 'awaiting_receipt', 'reconciling'], true)) {
throw new CloudError('对象存储发布操作尚未派发', 409);
}
$pendingIdentity = (int) $artifact->size_bytes === 0
&& (string) $artifact->sha256 === '';
if ($pendingIdentity) {
if ($size > (int) $artifact->maximum_size_bytes) {
throw new CloudError(
'对象存储返回的主副本身份超出预留边界',
409
);
}
$artifact->size_bytes = $size;
$artifact->sha256 = $receiptSha;
} elseif ($size !== (int) $artifact->size_bytes
|| !hash_equals(
(string) $artifact->sha256,
$receiptSha
)) {
throw new CloudError('对象存储返回的主副本身份不一致', 409);
}
$now = time();
$replica->size_bytes = $size;
$replica->sha256 = (string) $artifact->sha256;
$replica->object_etag = $etag;
$replica->object_version_id = $versionId;
$replica->state = 'ready';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = '';
$replica->verified_at = $now;
$replica->updated_at = $now;
$replica->save();
self::settleSucceeded($operation, [
'size_bytes' => $size,
'sha256' => (string) $artifact->sha256,
'etag' => $etag,
'version_id' => $versionId,
], $now);
foreach ($copyOperations as $copyOperation) {
if ((string) $copyOperation->phase === 'accepted') {
$copyOperation->available_at = $now;
$copyOperation->updated_at = $now;
$copyOperation->save();
}
}
self::projectArtifactLocked($artifact, $replicas, $now);
});
return self::publicationView($operationId);
}
public static function failPrimary(
string $operationId,
int $expectedArtifactId,
string $effectResolution,
string $errorCode
): array {
self::assertOperationId($operationId);
if ($expectedArtifactId < 1) {
throw new CloudError('对象存储制品身份无效', 422);
}
self::assertEffectResolution($effectResolution);
$errorCode = self::errorCode($errorCode);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$expectedArtifactId,
$effectResolution,
$errorCode
): void {
$operation = self::primaryOperationLocked($operationId);
if ((int) $operation->artifact_id !== $expectedArtifactId) {
throw new CloudError(
'对象存储发布操作与制品身份不一致',
409
);
}
if ((string) $operation->phase === 'terminal') {
if ($effectResolution !== 'not_applied') {
throw new CloudError(
'对象存储发布终态与失败回执冲突',
409
);
}
self::assertTerminalFailure(
$operation,
false,
true,
'not_applied',
$errorCode,
'对象存储发布终态与失败回执冲突'
);
return;
}
$copyOperations = self::copyOperationsLocked(
(int) $operation->artifact_id
);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
$now = time();
if ($effectResolution === 'not_applied') {
self::settleFailed($operation, false, true,
'not_applied', $errorCode, $now);
$replica->state = 'degraded';
foreach ($copyOperations as $copyOperation) {
if ((string) $copyOperation->phase !== 'terminal') {
self::settleFailed(
$copyOperation,
false,
false,
'not_applied',
'primary_publish_not_applied',
$now
);
$secondary = self::operationReplica(
$copyOperation,
$replicas
);
$secondary->state = 'degraded';
$secondary->lease_token = null;
$secondary->lease_until = 0;
$secondary->error_code =
'primary_publish_not_applied';
$secondary->updated_at = $now;
$secondary->save();
}
}
} else {
$operation->phase = 'reconciling';
$operation->outcome = null;
$operation->effect_resolution = $effectResolution;
$operation->effect_may_have_applied = null;
$operation->safe_to_resubmit = null;
$operation->next_check_at = $now + 60;
$operation->error_code = $errorCode;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'publishing';
}
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
$publication = CloudStoragePublication::query()
->where('artifact_id', $artifact->id)
->lockForUpdate()->firstOrFail();
if ($effectResolution === 'not_applied') {
$publication->state = 'failed';
$publication->last_error_code = $errorCode;
$publication->available_at = 0;
$publication->updated_at = $now;
$publication->save();
}
if ((int) $artifact->size_bytes > 0
&& (string) $artifact->sha256 !== '') {
self::projectArtifactLocked($artifact, $replicas, $now);
} elseif ($effectResolution === 'not_applied') {
// A pending identity may only exist in publishing state. The
// failed publication row is the durable terminal signal.
$artifact->state = 'publishing';
$artifact->updated_at = $now;
$artifact->save();
}
});
return self::publicationView($operationId);
}
/**
* Mint a read-only URL for one verified replica selected by health.
*
* @return array{url:string,artifact_id:int,replica_id:int,backend_id:int,
* size_bytes:int,sha256:string,expires_at:int}
*/
public static function presignedRead(
int $artifactId,
int $expiresSeconds = 3600,
?CloudObjectStorageS3Client $client = null
): array {
if ($artifactId < 1 || $expiresSeconds < 60
|| $expiresSeconds > 604800) {
throw new CloudError('对象存储读取参数无效', 422);
}
$artifact = CloudStorageArtifact::query()->whereKey($artifactId)->first();
if (!$artifact instanceof CloudStorageArtifact) {
throw new CloudError('对象存储制品不存在', 404);
}
$replicas = CloudStorageReplica::query()
->where('artifact_id', $artifactId)->get();
$backends = CloudStorageBackend::query()
->whereIn('id', $replicas->pluck('backend_id')->all())
->get()->keyBy('id');
$artifactData = self::artifactData($artifact);
$coverage = CloudStorageDurabilityPolicy::project(
$artifactData,
$replicas->map(static fn (CloudStorageReplica $replica): array =>
self::replicaData($replica))->values()->all()
);
if (!$coverage['can_read']) {
throw new CloudError('对象存储制品尚未达到可读取副本数', 503);
}
$selected = CloudStorageReadRouter::select(
$artifactData,
$replicas->map(static function (CloudStorageReplica $replica) use (
$backends
): array {
$backend = $backends->get((int) $replica->backend_id);
return self::replicaData($replica) + ['backend' => [
'admin_state' => (string) ($backend?->admin_state ?? ''),
'health_state' => (string) ($backend?->health_state ?? ''),
'write_priority' => (int) ($backend?->write_priority ?? -1),
]];
})->values()->all()
);
$replica = $replicas->firstWhere('id', (int) $selected['id']);
if (!$replica instanceof CloudStorageReplica) {
throw new CloudError('对象存储副本不存在', 503);
}
$runtime = CloudObjectStorageBackendRegistry::runtime(
(int) $replica->backend_id,
false
);
$url = ($client ?? new CloudObjectStorageS3Client())
->presignedVersionedGet(
$runtime['config'],
$runtime['credentials'],
(string) $replica->object_key,
(string) $replica->object_version_id,
$expiresSeconds
);
return [
'url' => $url,
'artifact_id' => (int) $artifact->id,
'replica_id' => (int) $replica->id,
'backend_id' => (int) $replica->backend_id,
'size_bytes' => (int) $artifact->size_bytes,
'sha256' => (string) $artifact->sha256,
'expires_at' => time() + $expiresSeconds,
];
}
/** @return array<string,mixed> */
public static function publicationView(string $operationId): array
{
self::assertOperationId($operationId);
$operation = CloudStorageOperation::query()
->where('operation_id', $operationId)->first();
if (!$operation instanceof CloudStorageOperation
|| (string) $operation->kind !== 'publish') {
throw new CloudError('对象存储发布操作不存在', 404);
}
$artifact = CloudStorageArtifact::query()
->whereKey((int) $operation->artifact_id)->firstOrFail();
$replica = CloudStorageReplica::query()
->whereKey((int) $operation->replica_id)->firstOrFail();
return [
'operation_id' => (string) $operation->operation_id,
'phase' => (string) $operation->phase,
'outcome' => $operation->outcome === null
? null : (string) $operation->outcome,
'effect_resolution' => (string) $operation->effect_resolution,
'artifact_id' => (int) $artifact->id,
'artifact_key' => (string) $artifact->artifact_key,
'artifact_state' => (string) $artifact->state,
'replica_id' => (int) $replica->id,
'backend_id' => (int) $replica->backend_id,
'object_key' => (string) $replica->object_key,
'can_publish' => (string) $operation->phase === 'accepted'
&& (string) $replica->state === 'reserved',
];
}
/** Resolve the original primary publication owned by one backup intent. */
public static function primaryOperationForBackup(int $backupId): ?string
{
if ($backupId < 1) {
throw new \InvalidArgumentException('Invalid backup id');
}
$publication = CloudStoragePublication::query()
->where('backup_id', $backupId)->first();
if (!$publication instanceof CloudStoragePublication) {
return null;
}
$operation = CloudStorageOperation::query()
->where('artifact_id', (int) $publication->artifact_id)
->where('kind', 'publish')->first();
return $operation instanceof CloudStorageOperation
? (string) $operation->operation_id : null;
}
/**
* Lease the original primary multipart preparation. No provider request is
* made while database locks are held. A stale pre-receipt lease always
* becomes reconciliation; an upload identity already persisted in
* awaiting_receipt can only be re-signed, never replaced.
*
* @return array<string,mixed>|null
*/
public static function claimPrimaryPreparation(
string $operationId,
int $now,
int $leaseSeconds = 300
): ?array {
self::assertOperationId($operationId);
if ($now < 1 || $leaseSeconds < 30 || $leaseSeconds > 3600) {
throw new \InvalidArgumentException(
'Invalid primary preparation lease'
);
}
$connection = (new CloudStorageOperation())->getConnection();
return $connection->transaction(static function () use (
$operationId,
$now,
$leaseSeconds
): ?array {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
$publication = self::publicationLocked((int) $artifact->id);
if (in_array((string) $publication->state,
['completed', 'failed', 'retired'], true)
|| (string) $operation->phase === 'terminal') {
return null;
}
if ((string) $artifact->state !== 'publishing'
|| !in_array((string) $replica->state,
['reserved', 'publishing'], true)) {
throw new CloudError(
'对象存储主副本准备账本状态不一致',
409
);
}
if (is_string($operation->lease_token)
&& $operation->lease_token !== ''
&& (int) $operation->lease_until > $now) {
return null;
}
$phase = (string) $operation->phase;
$metadata = self::primaryPreparationMetadata(
$operation->result_json
);
$mode = null;
if ($phase === 'accepted'
&& (int) $operation->available_at <= $now) {
$mode = 'dispatch';
$operation->phase = 'dispatching';
$operation->attempts = (int) $operation->attempts + 1;
$replica->state = 'publishing';
} elseif ($phase === 'reconciling'
&& (int) $operation->next_check_at <= $now) {
$mode = 'reconcile';
} elseif ($phase === 'dispatching'
&& (int) $operation->lease_until <= $now) {
$mode = 'reconcile';
$operation->phase = 'reconciling';
$operation->effect_resolution = 'unknown';
$operation->error_code =
'primary_preparation_lease_expired';
$operation->next_check_at = $now;
} elseif ($phase === 'awaiting_receipt'
&& (int) $operation->lease_until <= $now
&& isset($metadata['upload_id'])) {
$mode = 'sign';
}
if ($mode === null) {
return null;
}
$leaseToken = bin2hex(random_bytes(16));
$operation->lease_token = $leaseToken;
$operation->lease_until = $now + $leaseSeconds;
$operation->updated_at = $now;
$operation->save();
$replica->lease_token = $leaseToken;
$replica->lease_until = $now + $leaseSeconds;
$replica->updated_at = $now;
$replica->save();
return [
'operation_id' => (string) $operation->operation_id,
'lease_token' => $leaseToken,
'mode' => $mode,
'artifact_id' => (int) $artifact->id,
'replica_id' => (int) $replica->id,
'backend_id' => (int) $operation->target_backend_id,
'object_key' => (string) $replica->object_key,
'metadata' => $metadata,
'operation_created_at' => (int) $operation->created_at,
'operation_available_at' => (int) $operation->available_at,
'backup_id' => $publication->backup_id === null
? null : (int) $publication->backup_id,
];
});
}
/** Persist provider identity and geometry only; never capability URLs. */
public static function markPrimaryAwaitingReceipt(
string $operationId,
string $leaseToken,
array $metadata,
int $now
): void {
$metadata = self::sanitizePrimaryPreparationMetadata($metadata);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$metadata,
$now
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::publicationLocked((int) $artifact->id);
self::assertLeaseToken($operation, $leaseToken, $now);
$phase = (string) $operation->phase;
if (!in_array($phase,
['dispatching', 'reconciling', 'awaiting_receipt'], true)) {
throw new CloudError('主副本不在可准备阶段', 409);
}
$stored = self::primaryPreparationMetadata(
$operation->result_json
);
$metadata = self::mergePrimaryPreparationMetadata(
$stored,
$metadata
);
if (!isset($metadata['upload_id'])) {
throw new CloudError('主副本分段上传身份无效', 502);
}
self::assertPrimaryPreparationIdentity($stored, $metadata, $phase);
$operation->phase = 'awaiting_receipt';
$operation->effect_resolution = 'unknown';
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->next_check_at = (int) $operation->lease_until;
$operation->error_code = '';
$operation->updated_at = $now;
$operation->save();
$replica->state = 'publishing';
$replica->error_code = '';
$replica->updated_at = $now;
$replica->save();
});
}
/** Release preparation ownership only after the Agent job is committed. */
public static function releasePrimaryPreparationLease(
string $operationId,
string $leaseToken,
int $now
): void {
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$now
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::publicationLocked((int) $artifact->id);
self::assertLeaseToken($operation, $leaseToken, $now);
if ((string) $operation->phase !== 'awaiting_receipt') {
throw new CloudError('主副本上传计划尚未持久化', 409);
}
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->next_check_at = 0;
$operation->updated_at = $now;
$operation->save();
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->updated_at = $now;
$replica->save();
});
}
/** Preserve the same operation after an ambiguous provider response. */
public static function markPrimaryPreparationUnknown(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
int $delaySeconds,
array $metadata = []
): void {
$errorCode = self::errorCode($errorCode);
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException(
'Invalid primary reconciliation delay'
);
}
$metadata = self::sanitizePrimaryPreparationMetadata($metadata);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$delaySeconds,
$metadata
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::publicationLocked((int) $artifact->id);
self::assertLeaseToken($operation, $leaseToken, $now);
if (!in_array((string) $operation->phase,
['dispatching', 'awaiting_receipt', 'reconciling'], true)) {
throw new CloudError('主副本不在可核对阶段', 409);
}
$stored = self::primaryPreparationMetadata(
$operation->result_json
);
$metadata = self::mergePrimaryPreparationMetadata(
$stored,
$metadata
);
$operation->phase = 'reconciling';
$operation->effect_resolution = 'unknown';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->next_check_at = $now + $delaySeconds;
$operation->error_code = $errorCode;
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->updated_at = $now;
$operation->save();
$replica->state = 'publishing';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
});
}
/** Return a proven pre-side-effect preparation to the same operation. */
public static function deferPrimaryPreparation(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
int $delaySeconds
): void {
$errorCode = self::errorCode($errorCode);
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid primary delay');
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$delaySeconds
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::publicationLocked((int) $artifact->id);
self::assertLeaseToken($operation, $leaseToken, $now);
if ((string) $operation->phase !== 'dispatching') {
throw new CloudError(
'主副本准备已可能发生远端效果,不能直接重排',
409
);
}
$metadata = self::primaryPreparationMetadata(
$operation->result_json
);
if (isset($metadata['upload_id'])) {
throw new CloudError('主副本已有分段上传身份,不能重排', 409);
}
$operation->phase = 'accepted';
$operation->effect_resolution = 'not_applicable';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now + $delaySeconds;
$operation->next_check_at = 0;
$operation->error_code = $errorCode;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'reserved';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
});
}
/** Re-open only after two stable exact-key proofs of no multipart session. */
public static function reschedulePrimaryAfterStableAbsence(
string $operationId,
string $leaseToken,
array $evidence,
int $now,
int $delaySeconds = 60
): void {
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid primary retry delay');
}
$evidence = self::sanitizePrimaryPreparationMetadata($evidence);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$evidence,
$now,
$delaySeconds
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::publicationLocked((int) $artifact->id);
self::assertLeaseToken($operation, $leaseToken, $now);
if ((string) $operation->phase !== 'reconciling') {
throw new CloudError('主副本尚未完成效果核对', 409);
}
$stored = self::primaryPreparationMetadata(
$operation->result_json
);
$evidence = self::mergePrimaryPreparationMetadata(
$stored,
$evidence
);
$sameUpload = !isset($stored['upload_id'])
|| (isset($evidence['upload_id'])
&& hash_equals(
(string) $stored['upload_id'],
(string) $evidence['upload_id']
));
if (!$sameUpload
|| ($stored['absence_confirmations'] ?? 0) < 1
|| ($evidence['absence_confirmations'] ?? 0) < 2
|| ($stored['multipart_absence_confirmations'] ?? 0) < 1
|| ($evidence['multipart_absence_confirmations'] ?? 0) < 2) {
throw new CloudError('主副本缺少可安全重排的核对证据', 409);
}
self::assertPrimaryImmutableMetadata($stored, $evidence);
unset(
$evidence['upload_id'],
$evidence['part_size_bytes'],
$evidence['part_count'],
$evidence['initiated_at']
);
$evidence['absence_confirmations'] = 0;
$evidence['multipart_absence_confirmations'] = 0;
$evidence['multipart_presence_confirmations'] = 0;
$evidence['multipart_attention_confirmations'] = 0;
unset($evidence['multipart_attention_error_code']);
$operation->phase = 'accepted';
$operation->effect_resolution = 'not_applicable';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now + $delaySeconds;
$operation->next_check_at = 0;
$operation->error_code = '';
$operation->result_json = json_encode(
$evidence,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->updated_at = $now;
$operation->save();
$replica->state = 'reserved';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = '';
$replica->updated_at = $now;
$replica->save();
});
}
/** Stop automatic recovery after the same identity conflict is stable. */
public static function markPrimaryPreparationAttention(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
array $metadata
): void {
$errorCode = self::primaryPreparationAttentionError($errorCode);
$metadata = self::sanitizePrimaryPreparationMetadata($metadata);
if (($metadata['multipart_attention_confirmations'] ?? 0) < 2
|| ($metadata['multipart_attention_error_code'] ?? '')
!== $errorCode) {
throw new CloudError('主副本人工核对证据不足', 409);
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$metadata
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
$publication = self::publicationLocked((int) $artifact->id);
$backup = $publication->backup_id === null
? null
: self::primaryPreparationBackupLocked(
$publication,
$artifact
);
if ((string) $operation->phase === 'terminal') {
self::assertTerminalFailure(
$operation,
true,
false,
'unknown',
$errorCode,
'主副本人工核对终态冲突'
);
if ($backup instanceof CloudInstanceBackup) {
self::markPrimaryBackupAttentionLocked(
$backup,
$errorCode,
$now
);
}
return;
}
self::assertLeaseToken($operation, $leaseToken, $now);
if ((string) $operation->phase !== 'reconciling') {
throw new CloudError('主副本不在人工核对阶段', 409);
}
$stored = self::primaryPreparationMetadata(
$operation->result_json
);
$metadata = self::mergePrimaryPreparationMetadata(
$stored,
$metadata
);
if (($stored['multipart_attention_confirmations'] ?? 0) < 1
|| ($stored['multipart_attention_error_code'] ?? '')
!== $errorCode) {
throw new CloudError('主副本人工核对证据不稳定', 409);
}
self::assertPrimaryImmutableMetadata($stored, $metadata);
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
self::settleFailed(
$operation,
true,
false,
'unknown',
$errorCode,
$now
);
$replica->state = 'degraded';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
$publication->state = 'failed';
$publication->last_error_code = $errorCode;
$publication->available_at = 0;
$publication->updated_at = $now;
$publication->save();
if ($backup instanceof CloudInstanceBackup) {
self::markPrimaryBackupAttentionLocked(
$backup,
$errorCode,
$now
);
}
});
}
/**
* Re-open only the original primary operation after an administrator asks
* for another read-only reconciliation pass. This never aborts or creates
* a multipart upload and therefore cannot replay the unknown effect.
*/
public static function reopenPrimaryPreparationAttention(
string $operationId,
int $now
): void {
self::assertOperationId($operationId);
if ($now < 1) {
throw new \InvalidArgumentException('Invalid attention time');
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$now
): void {
$operation = self::primaryOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
$publication = self::publicationLocked((int) $artifact->id);
$backup = self::primaryPreparationBackupLocked(
$publication,
$artifact
);
if ((string) $operation->phase === 'reconciling'
&& (string) $operation->error_code
=== 'admin_reconcile_requested') {
self::markPrimaryBackupReopenedLocked($backup, $now);
return;
}
$attentionCode = self::primaryPreparationAttentionError(
(string) $operation->error_code
);
self::assertTerminalFailure(
$operation,
true,
false,
'unknown',
$attentionCode,
'主副本不在可重新核对的人工处理终态'
);
if ((string) $publication->state !== 'failed'
|| !hash_equals(
(string) $publication->last_error_code,
$attentionCode
)
|| $publication->backup_id === null) {
throw new CloudError('主副本人工核对归属已发生变化', 409);
}
if ((string) $replica->state !== 'degraded'
|| !hash_equals(
(string) $replica->error_code,
$attentionCode
)) {
throw new CloudError('主副本已不属于该人工核对操作', 409);
}
if (in_array((string) $artifact->state,
['retiring', 'delete_attention', 'deleted'], true)) {
throw new CloudError('对象已进入清理流程,不能重新核对', 409);
}
$metadata = self::primaryPreparationMetadata(
$operation->result_json
);
$metadata['absence_confirmations'] = 0;
$metadata['multipart_absence_confirmations'] = 0;
$metadata['multipart_presence_confirmations'] = 0;
$metadata['multipart_attention_confirmations'] = 0;
unset($metadata['multipart_attention_error_code']);
$operation->phase = 'reconciling';
$operation->outcome = null;
$operation->effect_resolution = 'unknown';
$operation->effect_may_have_applied = null;
$operation->safe_to_resubmit = null;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->next_check_at = $now;
$operation->error_code = 'admin_reconcile_requested';
$operation->result_json = json_encode(
self::sanitizePrimaryPreparationMetadata($metadata),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->terminal_at = null;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'publishing';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = 'admin_reconcile_requested';
$replica->updated_at = $now;
$replica->save();
$publication->state = 'waiting_primary';
$publication->available_at = 0;
$publication->last_error_code = 'admin_reconcile_requested';
$publication->lease_token = null;
$publication->lease_until = 0;
$publication->updated_at = $now;
$publication->save();
self::markPrimaryBackupReopenedLocked($backup, $now);
});
}
/**
* Lease one durable secondary-copy operation. The returned view contains
* immutable object identity only; provider capabilities and credentials
* are minted later by the worker and are never persisted.
*
* @return array<string,mixed>|null
*/
public static function claimReplicaWork(
int $now,
int $leaseSeconds = 21720
): ?array {
if ($now < 1 || $leaseSeconds < 30 || $leaseSeconds > 25200) {
throw new \InvalidArgumentException('Invalid replica lease');
}
$connection = (new CloudStorageOperation())->getConnection();
return $connection->transaction(static function () use (
$now,
$leaseSeconds
): ?array {
$operation = CloudStorageOperation::query()
->where('kind', 'copy')
->where(static function ($query) use ($now): void {
$query->where(static function ($accepted) use ($now): void {
$accepted->where('phase', 'accepted')
->where('available_at', '<=', $now);
})->orWhere(static function ($reconcile) use ($now): void {
$reconcile->where('phase', 'reconciling')
->where('next_check_at', '<=', $now);
})->orWhere(static function ($stale) use ($now): void {
$stale->whereIn('phase', [
'dispatching', 'awaiting_receipt',
])->where('lease_until', '<=', $now);
});
})
->where(static function ($query) use ($now): void {
$query->whereNull('lease_token')
->orWhere('lease_until', '<=', $now);
})
->orderBy('id')->lockForUpdate()->first();
if (!$operation instanceof CloudStorageOperation) {
return null;
}
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
$source = self::backendReplica(
$replicas,
(int) $operation->source_backend_id
);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return null;
}
$mode = (string) $operation->phase === 'accepted'
? 'dispatch' : 'reconcile';
if (in_array((string) $operation->phase,
['dispatching', 'awaiting_receipt'], true)) {
$operation->phase = 'reconciling';
$operation->effect_resolution = 'unknown';
$operation->error_code = 'replica_worker_lease_expired';
$operation->next_check_at = $now;
$mode = 'reconcile';
} elseif ($mode === 'dispatch') {
$operation->phase = 'dispatching';
$operation->attempts = (int) $operation->attempts + 1;
}
$leaseToken = bin2hex(random_bytes(16));
$operation->lease_token = $leaseToken;
$operation->lease_until = $now + $leaseSeconds;
$operation->updated_at = $now;
$operation->save();
$replica->lease_token = $leaseToken;
$replica->lease_until = $now + $leaseSeconds;
if ($mode === 'dispatch') {
$replica->state = 'copying';
}
$replica->updated_at = $now;
$replica->save();
return [
'operation_id' => (string) $operation->operation_id,
'lease_token' => $leaseToken,
'mode' => $mode,
'artifact_id' => (int) $artifact->id,
'size_bytes' => (int) $artifact->size_bytes,
'sha256' => (string) $artifact->sha256,
'source_backend_id' => (int) $operation->source_backend_id,
'source_object_key' => (string) $source->object_key,
'source_version_id' => (string) $source->object_version_id,
'source_state' => (string) $source->state,
'target_backend_id' => (int) $operation->target_backend_id,
'target_object_key' => (string) $replica->object_key,
'metadata' => self::copyMetadata($operation->result_json),
'operation_created_at' => (int) $operation->created_at,
'operation_available_at' => (int) $operation->available_at,
];
});
}
/** Persist only provider identifiers and multipart geometry, never URLs. */
public static function markReplicaAwaitingReceipt(
string $operationId,
string $leaseToken,
array $metadata,
int $now
): void {
$metadata = self::sanitizeCopyMetadata($metadata);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$metadata,
$now
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
$phase = (string) $operation->phase;
if ($phase === 'reconciling') {
$stored = self::copyMetadata($operation->result_json);
if (!isset($metadata['upload_id'])) {
throw new CloudError(
'对象副本精确分段会话不能被替换',
409
);
}
if (isset($stored['upload_id'])) {
if (!hash_equals(
(string) $stored['upload_id'],
(string) $metadata['upload_id']
)
|| ($stored['multipart_presence_confirmations'] ?? 0)
< 1
|| ($metadata['multipart_presence_confirmations'] ?? 0)
< 2) {
throw new CloudError(
'对象副本分段会话缺少稳定恢复证据',
409
);
}
}
} elseif ($phase !== 'dispatching') {
throw new CloudError('对象副本复制操作不在派发阶段', 409);
}
$operation->phase = 'awaiting_receipt';
$operation->effect_resolution = 'unknown';
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->next_check_at = (int) $operation->lease_until;
$operation->updated_at = $now;
$operation->save();
});
}
/** @param array<string,mixed> $identity */
public static function completeReplica(
string $operationId,
string $leaseToken,
array $identity,
int $now
): void {
$size = self::positiveInt($identity['size_bytes'] ?? null);
$sha256 = $identity['sha256'] ?? null;
if (!is_string($sha256)
|| preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new CloudError('对象副本哈希身份无效', 502);
}
$etag = self::providerIdentity($identity['etag'] ?? null, 256);
$versionId = self::providerVersionIdentity(
$identity['version_id'] ?? null,
1024
);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$size,
$sha256,
$etag,
$versionId,
$now
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'terminal') {
if ((string) $operation->outcome === 'succeeded') {
self::assertSettledReplicaIdentity(
$artifact,
$replica,
$size,
$sha256,
$etag,
$versionId,
'对象副本重复回执身份不一致'
);
return;
}
throw new CloudError('对象副本复制操作已失败', 409);
}
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
if ($size !== (int) $artifact->size_bytes
|| !hash_equals((string) $artifact->sha256, $sha256)) {
throw new CloudError('对象副本身份与制品不一致', 409);
}
if ((string) $replica->object_version_id !== ''
&& !hash_equals(
(string) $replica->object_version_id,
$versionId
)) {
throw new CloudError('对象副本版本身份不一致', 409);
}
$replica->size_bytes = $size;
$replica->sha256 = $sha256;
$replica->object_etag = $etag;
$replica->object_version_id = $versionId;
$replica->state = 'ready';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = '';
$replica->verified_at = $now;
$replica->updated_at = $now;
$replica->save();
self::settleSucceeded($operation, [
'size_bytes' => $size,
'sha256' => $sha256,
'etag' => $etag,
'version_id' => $versionId,
], $now);
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
public static function markReplicaUnknown(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
int $delaySeconds,
array $metadata = []
): void {
$errorCode = self::errorCode($errorCode);
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid reconciliation delay');
}
$metadata = self::sanitizeCopyMetadata($metadata);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$delaySeconds,
$metadata
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
$operation->phase = 'reconciling';
$operation->effect_resolution = 'unknown';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->next_check_at = $now + $delaySeconds;
$operation->error_code = $errorCode;
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->updated_at = $now;
$operation->save();
$replica->state = 'copying';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
});
}
/** Stop automatic reconciliation after stable multipart identity conflict. */
public static function markReplicaAttention(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
array $metadata
): void {
$errorCode = self::replicaAttentionError($errorCode);
$metadata = self::sanitizeCopyMetadata($metadata);
if (($metadata['multipart_attention_confirmations'] ?? 0) < 2
|| ($metadata['multipart_attention_error_code'] ?? '')
!== $errorCode) {
throw new CloudError('对象副本人工核对证据不足', 409);
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$metadata
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'terminal') {
self::assertTerminalFailure(
$operation,
true,
false,
'unknown',
$errorCode,
'对象副本人工核对终态冲突'
);
return;
}
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
$operation->result_json = json_encode(
$metadata,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
self::settleFailed(
$operation,
true,
false,
'unknown',
$errorCode,
$now
);
$replica->state = 'degraded';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
/** Re-open the same copy operation for read-only administrator reconciliation. */
public static function reopenReplicaAttention(
string $operationId,
int $now
): void {
self::assertOperationId($operationId);
if ($now < 1) {
throw new \InvalidArgumentException('Invalid attention time');
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$now
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'reconciling'
&& (string) $operation->error_code
=== 'admin_reconcile_requested') {
return;
}
$attentionCode = self::replicaAttentionError(
(string) $operation->error_code
);
self::assertTerminalFailure(
$operation,
true,
false,
'unknown',
$attentionCode,
'对象副本不在可重新核对的人工处理终态'
);
if ((string) $replica->state !== 'degraded'
|| !hash_equals(
(string) $replica->error_code,
$attentionCode
)) {
throw new CloudError(
'目标副本已不属于该人工核对操作',
409
);
}
if (in_array((string) $artifact->state,
['retiring', 'deleted'], true)) {
throw new CloudError('对象已进入清理流程,不能重新核对副本', 409);
}
$source = self::backendReplica(
$replicas,
(int) $operation->source_backend_id
);
if ((string) $source->state !== 'ready'
|| (int) $source->size_bytes !== (int) $artifact->size_bytes
|| !hash_equals(
(string) $artifact->sha256,
(string) $source->sha256
)) {
throw new CloudError('对象副本的可验证源已不可用', 409);
}
$metadata = self::copyMetadata($operation->result_json);
$metadata['absence_confirmations'] = 0;
$metadata['multipart_absence_confirmations'] = 0;
$metadata['multipart_presence_confirmations'] = 0;
$metadata['multipart_attention_confirmations'] = 0;
unset($metadata['multipart_attention_error_code']);
$operation->phase = 'reconciling';
$operation->outcome = null;
$operation->effect_resolution = 'unknown';
$operation->effect_may_have_applied = null;
$operation->safe_to_resubmit = null;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->next_check_at = $now;
$operation->error_code = 'admin_reconcile_requested';
$operation->result_json = json_encode(
self::sanitizeCopyMetadata($metadata),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->terminal_at = null;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'copying';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = 'admin_reconcile_requested';
$replica->updated_at = $now;
$replica->save();
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
public static function failReplicaNotApplied(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
bool $safeToResubmit = false
): void {
if ($safeToResubmit) {
self::rescheduleReplicaNotApplied(
$operationId,
$leaseToken,
$errorCode,
$now,
60
);
return;
}
$errorCode = self::errorCode($errorCode);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$safeToResubmit
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'terminal') {
self::assertTerminalFailure(
$operation,
false,
false,
'not_applied',
$errorCode,
'对象副本终态与失败回执冲突'
);
return;
}
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
self::settleFailed(
$operation,
false,
$safeToResubmit,
'not_applied',
$errorCode,
$now
);
$replica->state = 'degraded';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
/** Re-open the same copy intent after a definite no-effect receipt. */
public static function rescheduleReplicaNotApplied(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
int $delaySeconds = 60
): void {
$errorCode = self::errorCode($errorCode);
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid replica retry delay');
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$delaySeconds
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
if (!in_array((string) $operation->phase,
['dispatching', 'awaiting_receipt', 'reconciling'], true)) {
throw new CloudError(
'对象副本不在可安全重排的阶段',
409
);
}
$operation->phase = 'accepted';
$operation->outcome = null;
$operation->effect_resolution = 'not_applicable';
$operation->effect_may_have_applied = null;
$operation->safe_to_resubmit = null;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now + $delaySeconds;
$operation->next_check_at = 0;
$operation->error_code = $errorCode;
$operation->result_json = null;
$operation->terminal_at = null;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'reserved';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
/** Terminal mismatch after a target object is proven to exist. */
public static function failReplicaAppliedMismatch(
string $operationId,
string $leaseToken,
string $errorCode,
int $now
): void {
$errorCode = self::errorCode($errorCode);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
if ((string) $operation->phase === 'terminal') {
self::assertTerminalFailure(
$operation,
true,
false,
'applied',
$errorCode,
'对象副本终态与远端效果回执冲突'
);
return;
}
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
self::settleFailed(
$operation,
true,
false,
'applied',
$errorCode,
$now
);
$replica->state = 'degraded';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
self::projectArtifactLocked($artifact, $replicas, $now);
});
}
/** Re-open only after read-only proof of no object and no upload session. */
public static function rescheduleReplicaAfterProof(
string $operationId,
string $leaseToken,
array $evidence,
int $now,
int $delaySeconds = 60
): void {
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid replica retry delay');
}
$evidence = self::sanitizeCopyMetadata($evidence);
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$evidence,
$now,
$delaySeconds
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
if ((string) $operation->phase !== 'reconciling') {
throw new CloudError('对象副本尚未完成效果核对', 409);
}
$stored = self::copyMetadata($operation->result_json);
$sameSession = isset($evidence['upload_id'], $stored['upload_id'])
&& hash_equals(
(string) $stored['upload_id'],
(string) $evidence['upload_id']
);
$noSession = !isset($evidence['upload_id'])
&& !isset($stored['upload_id']);
if (($evidence['multipart_absence_confirmations'] ?? 0) < 2
|| ($stored['multipart_absence_confirmations'] ?? 0) < 1
|| (!$sameSession && !$noSession)) {
throw new CloudError('对象副本缺少可安全重排的核对证据', 409);
}
$operation->phase = 'accepted';
$operation->effect_resolution = 'not_applicable';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now + $delaySeconds;
$operation->next_check_at = 0;
$operation->error_code = '';
$operation->result_json = null;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'reserved';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = '';
$replica->updated_at = $now;
$replica->save();
});
}
/** Return pre-side-effect work to the same pinned operation. */
public static function deferReplica(
string $operationId,
string $leaseToken,
string $errorCode,
int $now,
int $delaySeconds
): void {
$errorCode = self::errorCode($errorCode);
if ($delaySeconds < 5 || $delaySeconds > 3600) {
throw new \InvalidArgumentException('Invalid replica delay');
}
$connection = (new CloudStorageOperation())->getConnection();
$connection->transaction(static function () use (
$operationId,
$leaseToken,
$errorCode,
$now,
$delaySeconds
): void {
$operation = self::copyOperationLocked($operationId);
[$artifact, $replicas] = self::artifactContextLocked($operation);
$replica = self::operationReplica($operation, $replicas);
self::assertLeaseToken($operation, $leaseToken, $now);
if (self::stopCopyIfArtifactNotCopyable(
$operation,
$artifact,
$replica,
$now
)) {
return;
}
if ((string) $operation->phase !== 'dispatching') {
throw new CloudError('对象副本复制已发生远端效果,不能延后重放', 409);
}
$operation->phase = 'accepted';
$operation->effect_resolution = 'not_applicable';
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now + $delaySeconds;
$operation->next_check_at = 0;
$operation->error_code = $errorCode;
$operation->updated_at = $now;
$operation->save();
$replica->state = 'reserved';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = $errorCode;
$replica->updated_at = $now;
$replica->save();
});
}
private static function primaryOperationLocked(
string $operationId
): CloudStorageOperation {
$operation = CloudStorageOperation::query()
->where('operation_id', $operationId)
->lockForUpdate()->first();
if (!$operation instanceof CloudStorageOperation
|| (string) $operation->kind !== 'publish') {
throw new CloudError('对象存储发布操作不存在', 404);
}
return $operation;
}
private static function copyOperationLocked(
string $operationId
): CloudStorageOperation {
self::assertOperationId($operationId);
$operation = CloudStorageOperation::query()
->where('operation_id', $operationId)
->lockForUpdate()->first();
if (!$operation instanceof CloudStorageOperation
|| (string) $operation->kind !== 'copy') {
throw new CloudError('对象副本复制操作不存在', 404);
}
return $operation;
}
/** @return array<int,CloudStorageOperation> */
private static function copyOperationsLocked(int $artifactId): array
{
return CloudStorageOperation::query()
->where('artifact_id', $artifactId)
->where('kind', 'copy')
->orderBy('id')
->lockForUpdate()
->get()
->all();
}
/**
* Every mutation uses the same lock order: operation, artifact, replicas
* by id, then publication. Callers that also need sibling operations lock
* those immediately after their primary operation and before this method.
*
* @return array{0:CloudStorageArtifact,1:array<int,CloudStorageReplica>}
*/
private static function artifactContextLocked(
CloudStorageOperation $operation
): array {
$artifact = CloudStorageArtifact::query()
->whereKey((int) $operation->artifact_id)
->lockForUpdate()
->firstOrFail();
$replicas = CloudStorageReplica::query()
->where('artifact_id', $artifact->id)
->orderBy('id')
->lockForUpdate()
->get()
->all();
return [$artifact, $replicas];
}
private static function publicationLocked(
int $artifactId
): CloudStoragePublication {
$publication = CloudStoragePublication::query()
->where('artifact_id', $artifactId)
->lockForUpdate()->first();
if (!$publication instanceof CloudStoragePublication) {
throw new CloudError('对象存储发布账本不存在', 409);
}
return $publication;
}
private static function primaryPreparationBackupLocked(
CloudStoragePublication $publication,
CloudStorageArtifact $artifact
): CloudInstanceBackup {
if ($publication->backup_id === null) {
throw new CloudError('主副本人工核对缺少备份归属', 409);
}
$backup = CloudInstanceBackup::query()
->whereKey((int) $publication->backup_id)
->lockForUpdate()->first();
if (!$backup instanceof CloudInstanceBackup
|| !in_array((string) $backup->state,
['creating', 'uncertain'], true)
|| $backup->active_job_id !== null
|| $backup->last_operation_id !== null
|| (int) $backup->storage_artifact_id !== (int) $artifact->id) {
throw new CloudError(
'备份已不属于可恢复的发布准备状态',
409
);
}
return $backup;
}
private static function markPrimaryBackupAttentionLocked(
CloudInstanceBackup $backup,
string $errorCode,
int $now
): void {
$backup->state = 'uncertain';
$backup->error_code = $errorCode;
$backup->updated_at = $now;
$backup->save();
}
private static function markPrimaryBackupReopenedLocked(
CloudInstanceBackup $backup,
int $now
): void {
$backup->state = 'creating';
$backup->error_code = 'admin_reconcile_requested';
$backup->updated_at = $now;
$backup->save();
}
/** @param array<int,CloudStorageReplica> $replicas */
private static function operationReplica(
CloudStorageOperation $operation,
array $replicas
): CloudStorageReplica {
foreach ($replicas as $replica) {
if ((int) $replica->id === (int) $operation->replica_id) {
return $replica;
}
}
throw new CloudError('对象副本记录不存在', 409);
}
/** @param array<int,CloudStorageReplica> $replicas */
private static function backendReplica(
array $replicas,
int $backendId
): CloudStorageReplica {
foreach ($replicas as $replica) {
if ((int) $replica->backend_id === $backendId) {
return $replica;
}
}
throw new CloudError('对象源副本记录不存在', 409);
}
private static function assertSettledReplicaIdentity(
CloudStorageArtifact $artifact,
CloudStorageReplica $replica,
int $size,
string $sha256,
string $etag,
string $versionId,
string $message
): void {
if ($size !== (int) $artifact->size_bytes
|| $size !== (int) $replica->size_bytes
|| !hash_equals((string) $artifact->sha256, $sha256)
|| !hash_equals((string) $replica->sha256, $sha256)
|| !hash_equals((string) $replica->object_etag, $etag)
|| !hash_equals(
(string) $replica->object_version_id,
$versionId
)) {
throw new CloudError($message, 409);
}
}
private static function stopCopyIfArtifactNotCopyable(
CloudStorageOperation $operation,
CloudStorageArtifact $artifact,
CloudStorageReplica $replica,
int $now
): bool {
if (!in_array((string) $artifact->state,
['retiring', 'delete_attention', 'deleted'], true)) {
return false;
}
// Only work that never crossed dispatch can be cancelled from the
// local ledger. An in-flight or unknown copy may still materialize an
// object, so its original operation must reconcile before deletion
// creates an exact per-replica delete generation.
if ((string) $operation->phase !== 'accepted') {
return false;
}
self::settleFailed(
$operation,
false,
false,
'not_applied',
'artifact_not_copyable',
$now
);
if ((string) $artifact->state === 'retiring'
&& in_array((string) $replica->state,
['reserved', 'copying'], true)) {
$replica->state = 'degraded';
$replica->lease_token = null;
$replica->lease_until = 0;
$replica->error_code = 'artifact_not_copyable';
$replica->updated_at = $now;
$replica->save();
}
return true;
}
private static function assertTerminalFailure(
CloudStorageOperation $operation,
bool $effectMayHaveApplied,
bool $safeToResubmit,
string $resolution,
string $errorCode,
string $message
): void {
if ((string) $operation->phase !== 'terminal'
|| (string) $operation->outcome !== 'failed'
|| (string) $operation->effect_resolution !== $resolution
|| (bool) $operation->effect_may_have_applied
!== $effectMayHaveApplied
|| (bool) $operation->safe_to_resubmit !== $safeToResubmit
|| !hash_equals((string) $operation->error_code, $errorCode)) {
throw new CloudError($message, 409);
}
}
private static function assertLeaseToken(
CloudStorageOperation $operation,
string $leaseToken,
int $now
): void {
if (preg_match('/^[a-f0-9]{32}$/D', $leaseToken) !== 1
|| !is_string($operation->lease_token)
|| !hash_equals((string) $operation->lease_token, $leaseToken)
|| (int) $operation->lease_until <= $now) {
throw new CloudError('对象副本复制租约已经失效', 409);
}
}
/** @return array<string,int|string> */
private static function primaryPreparationMetadata($json): array
{
if (!is_string($json) || $json === '') {
throw new CloudError('主副本准备元数据缺失', 409);
}
try {
$value = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
} catch (\JsonException) {
throw new CloudError('主副本准备元数据无效', 409);
}
if (!is_array($value)) {
throw new CloudError('主副本准备元数据无效', 409);
}
$metadata = self::sanitizePrimaryPreparationMetadata($value);
if (!isset($metadata['maximum_size_bytes'], $metadata['object_suffix'])) {
throw new CloudError('主副本准备身份不完整', 409);
}
return $metadata;
}
/** @return array<string,int|string> */
private static function sanitizePrimaryPreparationMetadata(
array $metadata
): array {
CloudInput::only($metadata, [
'object_suffix', 'upload_id', 'part_size_bytes', 'part_count',
'maximum_size_bytes', 'absence_confirmations',
'multipart_absence_confirmations',
'multipart_presence_confirmations',
'multipart_attention_confirmations',
'multipart_attention_error_code', 'initiated_at',
]);
if ($metadata === []) {
return [];
}
$result = [];
if (array_key_exists('object_suffix', $metadata)) {
if (!is_string($metadata['object_suffix'])) {
throw new CloudError('主副本对象路径无效', 502);
}
$result['object_suffix'] = self::objectSuffix(
$metadata['object_suffix']
);
}
if (array_key_exists('maximum_size_bytes', $metadata)) {
$maximum = $metadata['maximum_size_bytes'];
if (!is_int($maximum) || $maximum < 1) {
throw new CloudError('主副本最大容量无效', 502);
}
$result['maximum_size_bytes'] = $maximum;
}
$uploadId = $metadata['upload_id'] ?? null;
if ($uploadId !== null) {
if (!is_string($uploadId) || $uploadId === ''
|| strlen($uploadId) > 1024
|| preg_match('/[\x00-\x1f\x7f]/', $uploadId) === 1) {
throw new CloudError('主副本分段上传身份无效', 502);
}
$result['upload_id'] = $uploadId;
foreach (['part_size_bytes', 'part_count',
'maximum_size_bytes'] as $key) {
$value = $metadata[$key] ?? null;
if (!is_int($value) || $value < 1) {
throw new CloudError('主副本分段上传几何无效', 502);
}
$result[$key] = $value;
}
if (array_key_exists('initiated_at', $metadata)) {
$initiated = $metadata['initiated_at'];
if (!is_int($initiated) || $initiated < 1) {
throw new CloudError('主副本分段上传时间无效', 502);
}
$result['initiated_at'] = $initiated;
}
} elseif (array_intersect_key($metadata, array_flip([
'part_size_bytes', 'part_count', 'initiated_at',
])) !== []) {
throw new CloudError('主副本分段上传身份无效', 502);
}
foreach ([
'absence_confirmations',
'multipart_absence_confirmations',
'multipart_presence_confirmations',
'multipart_attention_confirmations',
] as $key) {
$value = $metadata[$key] ?? 0;
if (!is_int($value) || $value < 0 || $value > 2) {
throw new CloudError('主副本核对次数无效', 502);
}
$result[$key] = $value;
}
if (array_key_exists(
'multipart_attention_error_code',
$metadata
)) {
$result['multipart_attention_error_code'] =
self::primaryPreparationAttentionError(
$metadata['multipart_attention_error_code']
);
}
return $result;
}
/** @return array<string,int|string> */
private static function mergePrimaryPreparationMetadata(
array $stored,
array $updates
): array {
self::assertPrimaryImmutableMetadata($stored, $updates);
$merged = $stored;
foreach ($updates as $key => $value) {
$merged[$key] = $value;
}
$merged = self::sanitizePrimaryPreparationMetadata($merged);
if (isset($stored['upload_id'])) {
self::assertPrimaryPreparationIdentity(
$stored,
$merged,
'awaiting_receipt'
);
}
return $merged;
}
private static function assertPrimaryImmutableMetadata(
array $stored,
array $candidate
): void {
foreach (['maximum_size_bytes', 'object_suffix'] as $key) {
if (!array_key_exists($key, $stored)) {
throw new CloudError('主副本准备身份不完整', 409);
}
if (array_key_exists($key, $candidate)
&& $candidate[$key] !== $stored[$key]) {
throw new CloudError('主副本准备身份不能被替换', 409);
}
}
}
private static function assertPrimaryPreparationIdentity(
array $stored,
array $candidate,
string $phase
): void {
self::assertPrimaryImmutableMetadata($stored, $candidate);
if (isset($stored['upload_id'])) {
foreach (['upload_id', 'part_size_bytes', 'part_count'] as $key) {
if (!array_key_exists($key, $candidate)
|| (is_string($stored[$key] ?? null)
? !hash_equals(
(string) $stored[$key],
(string) $candidate[$key]
)
: (int) ($stored[$key] ?? 0)
!== (int) $candidate[$key])) {
throw new CloudError(
'主副本精确分段会话不能被替换',
409
);
}
}
if (array_key_exists('initiated_at', $stored)
&& (!array_key_exists('initiated_at', $candidate)
|| (int) $stored['initiated_at']
!== (int) $candidate['initiated_at'])) {
throw new CloudError(
'主副本分段上传时间不能被替换',
409
);
}
return;
}
if ($phase === 'reconciling'
&& ($candidate['multipart_presence_confirmations'] ?? 0) < 1) {
throw new CloudError('主副本分段会话缺少恢复证据', 409);
}
}
private static function primaryPreparationAttentionError(
$errorCode
): string {
if (!is_string($errorCode)
|| !in_array(
$errorCode,
self::PRIMARY_PREPARATION_ATTENTION_ERRORS,
true
)) {
throw new CloudError('主副本人工核对原因无效', 409);
}
return $errorCode;
}
/** @return array<string,mixed> */
private static function copyMetadata($json): array
{
if (!is_string($json) || $json === '') {
return [];
}
try {
$value = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
} catch (\JsonException) {
return [];
}
return is_array($value) ? self::sanitizeCopyMetadata($value) : [];
}
/** @return array<string,int|string> */
private static function sanitizeCopyMetadata(array $metadata): array
{
CloudInput::only($metadata, [
'upload_id', 'part_size_bytes', 'part_count',
'maximum_size_bytes', 'absence_confirmations',
'multipart_absence_confirmations',
'multipart_presence_confirmations',
'multipart_attention_confirmations',
'multipart_attention_error_code', 'initiated_at',
]);
if ($metadata === []) {
return [];
}
$uploadId = $metadata['upload_id'] ?? null;
$result = [];
if ($uploadId !== null) {
if (!is_string($uploadId) || $uploadId === ''
|| strlen($uploadId) > 1024
|| preg_match('/[\x00-\x1f\x7f]/', $uploadId) === 1) {
throw new CloudError('对象副本分段上传身份无效', 502);
}
$result['upload_id'] = $uploadId;
foreach (['part_size_bytes', 'part_count',
'maximum_size_bytes'] as $key) {
$value = $metadata[$key] ?? null;
if (!is_int($value) || $value < 1) {
throw new CloudError('对象副本分段上传几何无效', 502);
}
$result[$key] = $value;
}
if (array_key_exists('initiated_at', $metadata)) {
$initiatedAt = $metadata['initiated_at'];
if (!is_int($initiatedAt) || $initiatedAt < 1) {
throw new CloudError('对象副本分段上传时间无效', 502);
}
$result['initiated_at'] = $initiatedAt;
}
} elseif (array_intersect_key($metadata, array_flip([
'part_size_bytes', 'part_count', 'maximum_size_bytes',
'initiated_at',
])) !== []) {
throw new CloudError('对象副本分段上传身份无效', 502);
}
$absence = $metadata['absence_confirmations'] ?? 0;
if (!is_int($absence) || $absence < 0 || $absence > 2) {
throw new CloudError('对象副本核对次数无效', 502);
}
$result['absence_confirmations'] = $absence;
$multipartAbsence =
$metadata['multipart_absence_confirmations'] ?? 0;
if (!is_int($multipartAbsence)
|| $multipartAbsence < 0
|| $multipartAbsence > 2) {
throw new CloudError('对象副本分段会话核对次数无效', 502);
}
$result['multipart_absence_confirmations'] = $multipartAbsence;
$multipartPresence =
$metadata['multipart_presence_confirmations'] ?? 0;
if (!is_int($multipartPresence)
|| $multipartPresence < 0
|| $multipartPresence > 2) {
throw new CloudError('对象副本分段会话稳定次数无效', 502);
}
$result['multipart_presence_confirmations'] = $multipartPresence;
$multipartAttention =
$metadata['multipart_attention_confirmations'] ?? 0;
if (!is_int($multipartAttention)
|| $multipartAttention < 0
|| $multipartAttention > 2) {
throw new CloudError('对象副本人工核对次数无效', 502);
}
$result['multipart_attention_confirmations'] = $multipartAttention;
if (array_key_exists('multipart_attention_error_code', $metadata)) {
$result['multipart_attention_error_code'] =
self::replicaAttentionError(
$metadata['multipart_attention_error_code']
);
}
return $result;
}
private static function replicaAttentionError($errorCode): string
{
if (!is_string($errorCode)
|| !in_array($errorCode, self::REPLICA_ATTENTION_ERRORS, true)) {
throw new CloudError('对象副本人工核对原因无效', 409);
}
return $errorCode;
}
private static function projectArtifactLocked(
CloudStorageArtifact $artifact,
array $replicas,
int $now
): void {
$projection = CloudStorageDurabilityPolicy::project(
self::artifactData($artifact),
array_map(
static fn (CloudStorageReplica $replica): array =>
self::replicaData($replica),
$replicas
)
);
$artifact->state = $projection['state'];
if ($projection['can_read']) {
$artifact->verified_at = $now;
}
$artifact->updated_at = $now;
$artifact->save();
$publication = CloudStoragePublication::query()
->where('artifact_id', $artifact->id)
->lockForUpdate()->first();
if ($publication instanceof CloudStoragePublication
&& !in_array((string) $publication->state,
['finalizing', 'completed', 'failed', 'retired'], true)) {
if ($projection['meets_publication_requirement']) {
$publication->state = 'ready_to_finalize';
$publication->available_at = $now;
if ($publication->coverage_ready_at === null) {
$publication->coverage_ready_at = $now;
}
} else {
$publication->state = 'waiting_protection';
$publication->available_at = 0;
}
$publication->updated_at = $now;
$publication->save();
}
}
/** @return array<string,mixed> */
private static function artifactData(CloudStorageArtifact $artifact): array
{
return [
'id' => (int) $artifact->id,
'state' => (string) $artifact->state,
'size_bytes' => (int) $artifact->size_bytes,
'sha256' => (string) $artifact->sha256,
'desired_copies' => (int) $artifact->desired_copies,
'required_copies' => (int) $artifact->required_copies,
];
}
/** @return array<string,mixed> */
private static function replicaData(CloudStorageReplica $replica): array
{
return [
'id' => (int) $replica->id,
'backend_id' => (int) $replica->backend_id,
'role' => (string) $replica->role,
'state' => (string) $replica->state,
'size_bytes' => (int) $replica->size_bytes,
'sha256' => (string) $replica->sha256,
'verified_at' => (int) $replica->verified_at,
];
}
private static function settleSucceeded(
CloudStorageOperation $operation,
array $result,
int $now
): void {
$operation->phase = 'terminal';
$operation->outcome = 'succeeded';
$operation->effect_resolution = 'applied';
$operation->effect_may_have_applied = 0;
$operation->safe_to_resubmit = 0;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->error_code = '';
$operation->result_json = json_encode(
$result,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$operation->terminal_at = $now;
$operation->updated_at = $now;
$operation->save();
}
private static function settleFailed(
CloudStorageOperation $operation,
bool $effectMayHaveApplied,
bool $safeToResubmit,
string $resolution,
string $errorCode,
int $now
): void {
$operation->phase = 'terminal';
$operation->outcome = 'failed';
$operation->effect_resolution = $resolution;
$operation->effect_may_have_applied = $effectMayHaveApplied ? 1 : 0;
$operation->safe_to_resubmit = $safeToResubmit ? 1 : 0;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->error_code = $errorCode;
$operation->terminal_at = $now;
$operation->updated_at = $now;
$operation->save();
}
private static function initializeOperation(
CloudStorageOperation $operation,
int $now
): void {
$operation->phase = 'accepted';
$operation->outcome = null;
$operation->effect_resolution = 'not_applicable';
$operation->effect_may_have_applied = null;
$operation->safe_to_resubmit = null;
$operation->attempts = 0;
$operation->lease_token = null;
$operation->lease_until = 0;
$operation->available_at = $now;
$operation->next_check_at = 0;
$operation->error_code = '';
$operation->result_json = null;
$operation->terminal_at = null;
$operation->created_at = $now;
$operation->updated_at = $now;
}
private static function objectKey(string $prefix, string $suffix): string
{
$prefix = trim($prefix, '/');
$key = ($prefix === '' ? '' : $prefix . '/') . $suffix;
if (strlen($key) > 512) {
throw new CloudError('对象存储制品路径过长', 422);
}
return $key;
}
private static function objectSuffix(string $value): string
{
$value = trim($value, '/');
if ($value === '' || strlen($value) > 512
|| preg_match('/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/D', $value) !== 1
|| str_contains($value, '//')) {
throw new CloudError('对象存储制品路径无效', 422);
}
foreach (explode('/', $value) as $segment) {
if ($segment === '.' || $segment === '..') {
throw new CloudError('对象存储制品路径无效', 422);
}
}
return $value;
}
private static function copyIdempotencyKey(
string $requestKey,
int $backendId
): string {
return 'storage-copy-' . substr(hash(
'sha256',
$requestKey . '|' . $backendId
), 0, 48);
}
/** @return array{backup_id:?int,template_import_intent_id:?string,rescue_template_id:?string} */
private static function owner(string $kind, array $owner): array
{
CloudInput::only($owner, [
'backup_id', 'template_import_intent_id', 'rescue_template_id',
]);
$normalized = [
'backup_id' => null,
'template_import_intent_id' => null,
'rescue_template_id' => null,
];
if ($kind === 'backup') {
$value = filter_var($owner['backup_id'] ?? null,
FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if ($value === false) {
throw new CloudError('备份对象存储发布归属无效', 422);
}
$normalized['backup_id'] = (int) $value;
} elseif ($kind === 'template') {
$value = $owner['template_import_intent_id'] ?? null;
if (!is_string($value)
|| preg_match('/^[a-f0-9]{32}$/D', $value) !== 1) {
throw new CloudError('云模板对象存储发布归属无效', 422);
}
$normalized['template_import_intent_id'] = $value;
} elseif ($kind === 'rescue') {
$value = $owner['rescue_template_id'] ?? null;
if (!is_string($value)
|| preg_match('/^[a-f0-9]{32}$/D', $value) !== 1) {
throw new CloudError('救援镜像对象存储发布归属无效', 422);
}
$normalized['rescue_template_id'] = $value;
} else {
throw new CloudError('对象存储制品类型无效', 422);
}
$provided = array_filter($owner,
static fn ($value): bool => $value !== null && $value !== '');
if (count($provided) !== 1) {
throw new CloudError('对象存储发布必须且只能绑定一个归属', 422);
}
return $normalized;
}
private static function assertExistingOwner(
CloudStorageOperation $operation,
array $owner
): void {
$publication = CloudStoragePublication::query()
->where('artifact_id', $operation->artifact_id)
->lockForUpdate()->first();
if (!$publication instanceof CloudStoragePublication
|| (int) ($publication->backup_id ?? 0)
!== (int) ($owner['backup_id'] ?? 0)
|| (string) ($publication->template_import_intent_id ?? '')
!== (string) ($owner['template_import_intent_id'] ?? '')
|| (string) ($publication->rescue_template_id ?? '')
!== (string) ($owner['rescue_template_id'] ?? '')) {
throw new CloudError('对象存储发布幂等键归属不一致', 409);
}
}
private static function assertObjectIdentity(
int $sizeBytes,
string $sha256
): void {
if ($sizeBytes < 1
|| preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new CloudError('对象存储制品身份无效', 422);
}
}
private static function assertRequestIdentity(
string $requestKey,
string $fingerprint
): void {
if (preg_match('/^[A-Za-z0-9_.-]{16,128}$/D', $requestKey) !== 1
|| preg_match('/^[a-f0-9]{64}$/D', $fingerprint) !== 1) {
throw new CloudError('对象存储发布请求身份无效', 422);
}
}
private static function assertOperationId(string $operationId): void
{
if (preg_match('/^[a-f0-9]{32}$/D', $operationId) !== 1) {
throw new CloudError('对象存储操作身份无效', 422);
}
}
private static function assertEffectResolution(string $value): void
{
if (!in_array($value, ['unknown', 'not_applied'], true)) {
throw new CloudError('对象存储操作效果状态无效', 422);
}
}
private static function errorCode(string $value): string
{
if (preg_match('/^[a-z][a-z0-9_]{0,95}$/D', $value) !== 1) {
return 'storage_operation_failed';
}
return $value;
}
private static function positiveInt($value): int
{
if (!is_int($value) || $value < 1) {
throw new CloudError('对象存储返回的对象大小无效', 502);
}
return $value;
}
private static function providerIdentity($value, int $maximum): string
{
if (!is_string($value) || $value === '' || strlen($value) > $maximum
|| preg_match('/[\x00-\x1f\x7f]/', $value) === 1) {
throw new CloudError('对象存储返回的对象身份无效', 502);
}
return $value;
}
private static function providerVersionIdentity(
$value,
int $maximum
): string {
if ($value === null) {
$value = '';
}
if (!is_string($value) || strlen($value) > $maximum
|| preg_match('/[\x00-\x1f\x7f]/', $value) === 1) {
throw new CloudError('对象存储返回的版本身份无效', 502);
}
return $value;
}
}