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

1319 lines
49 KiB
PHTML

<?php
namespace App\Services\Cloud;
use GuzzleHttp\Client;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\GuzzleException;
use GuzzleHttp\Psr7\Utils;
/** Signed S3 control plane. VM image bytes never pass through this client. */
final class CloudObjectStorageS3Client
{
private const MIN_PART_BYTES = 67108864;
private const MAX_PART_BYTES = 5368709120;
private const MAX_PARTS = 512;
private const MAX_UPLOAD_ID_BYTES = 1024;
private const MAX_MULTIPART_LOOKUP_PAGES = 4;
private const MAX_MULTIPART_LOOKUP_PAGE_SIZE = 100;
public function __construct(private readonly ?ClientInterface $http = null)
{
}
/**
* @param array<string, mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array{status:string,http_status:int,region:string}
*/
public function headBucket(array $config, array $credentials): array
{
$url = self::bucketUrl(
(string) $config['endpoint'],
(string) $config['bucket'],
(bool) $config['path_style']
);
$headers = CloudS3Signer::sign(
'HEAD',
$url,
(string) $config['region'],
$credentials['access_key_id'],
$credentials['secret_access_key'],
time()
);
try {
$response = ($this->http ?? new Client())->request('HEAD', $url, [
'headers' => $headers,
'http_errors' => false,
'allow_redirects' => false,
'connect_timeout' => 5.0,
'timeout' => 15.0,
'verify' => true,
'proxy' => '',
]);
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTestError(
'无法连接对象存储,请检查地址、证书、DNS 和防火墙。',
'endpoint_unreachable'
);
}
$status = $response->getStatusCode();
$responseRegion = trim($response->getHeaderLine('x-amz-bucket-region'));
if ($status >= 200 && $status < 300) {
return [
'status' => 'healthy',
'http_status' => $status,
'region' => $responseRegion,
];
}
if (in_array($status, [301, 307], true)
|| ($status === 400 && $responseRegion !== '')) {
throw new CloudObjectStorageTestError(
'Bucket 区域不匹配,请按对象存储返回的区域修改配置。',
'region_mismatch'
);
}
if (in_array($status, [401, 403], true)) {
throw new CloudObjectStorageTestError(
'凭据或 s3:ListBucket 权限不正确,请同时检查面板服务器时间。',
'auth_or_permission_denied'
);
}
if ($status === 404) {
throw new CloudObjectStorageTestError(
'指定的 Bucket 不存在,或当前地址无法访问该 Bucket。',
'bucket_not_found'
);
}
if ($status === 429) {
throw new CloudObjectStorageTestError(
'对象存储暂时限制请求,请稍后重试。',
'rate_limited'
);
}
if ($status >= 500) {
throw new CloudObjectStorageTestError(
'对象存储服务暂时不可用,请稍后重试。',
'service_unavailable'
);
}
throw new CloudObjectStorageTestError(
'对象存储拒绝了兼容性检查,请核对 Endpoint、Region 和寻址方式。',
'request_rejected'
);
}
/**
* Start one multipart upload and mint bounded, method-specific capability
* URLs for an Agent. Long-lived S3 credentials never leave PHP.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array{object_key:string,upload_id:string,part_size_bytes:int,
* maximum_size_bytes:int,part_urls:list<string>,complete_url:string,
* abort_url:string,verify_url:string,expires_at:int}
*/
public function prepareMultipartUpload(
array $config,
array $credentials,
string $objectKey,
int $maximumSizeBytes,
?int $timestamp = null,
int $expiresSeconds = 86400
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
// Reject invalid geometry before CreateMultipartUpload so validation
// can never strand an untracked provider-side upload.
self::multipartGeometry($maximumSizeBytes);
$timestamp ??= time();
$uploadId = $this->createMultipartUpload(
$config, $credentials, $objectKey, $timestamp
);
return $this->resumeMultipartUpload(
$config,
$credentials,
$objectKey,
$uploadId,
$maximumSizeBytes,
$timestamp,
$expiresSeconds
);
}
/**
* Start a multipart upload whose immutable SHA-256 identity is already
* known. The digest is signed into CreateMultipartUpload metadata so a
* later exact-key HEAD proves the provider object identity.
*
* Existing Agent uploads intentionally keep using prepareMultipartUpload
* because their digest is not known until the Agent completes the image.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array<string,mixed>
*/
public function prepareKnownIdentityMultipartUpload(
array $config,
array $credentials,
string $objectKey,
int $sizeBytes,
string $sha256,
?int $timestamp = null,
int $expiresSeconds = 86400
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
if ($sizeBytes < 1
|| preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new \InvalidArgumentException(
'Invalid immutable multipart identity'
);
}
self::multipartGeometry($sizeBytes);
$timestamp ??= time();
$uploadId = $this->createMultipartUpload(
$config,
$credentials,
$objectKey,
$timestamp,
['virt-sha256' => $sha256]
);
return $this->resumeMultipartUpload(
$config,
$credentials,
$objectKey,
$uploadId,
$sizeBytes,
$timestamp,
$expiresSeconds
);
}
/** Re-sign one existing multipart upload without creating another one. */
public function resumeMultipartUpload(
array $config,
array $credentials,
string $objectKey,
string $uploadId,
int $maximumSizeBytes,
?int $timestamp = null,
int $expiresSeconds = 86400
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertUploadId($uploadId);
[$partSize, $partCount] = self::multipartGeometry(
$maximumSizeBytes
);
$timestamp ??= time();
$objectUrl = self::objectUrl($config, $objectKey);
$partUrls = [];
for ($part = 1; $part <= $partCount; $part++) {
$partUrls[] = CloudS3Signer::presign(
'PUT',
$objectUrl . '?' . http_build_query([
'partNumber' => $part,
'uploadId' => $uploadId,
], '', '&', PHP_QUERY_RFC3986),
(string) $config['region'],
$credentials['access_key_id'],
$credentials['secret_access_key'],
$timestamp,
$expiresSeconds
);
}
$uploadQuery = '?' . http_build_query(
['uploadId' => $uploadId], '', '&', PHP_QUERY_RFC3986
);
return [
'object_key' => $objectKey,
'upload_id' => $uploadId,
'part_size_bytes' => $partSize,
'maximum_size_bytes' => $maximumSizeBytes,
'part_urls' => $partUrls,
'complete_url' => CloudS3Signer::presign(
'POST', $objectUrl . $uploadQuery, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
$timestamp, $expiresSeconds
),
'abort_url' => CloudS3Signer::presign(
'DELETE', $objectUrl . $uploadQuery, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
$timestamp, $expiresSeconds
),
// CompleteMultipartUpload can commit even when its response is
// lost. The Agent may use this read-only capability exactly once
// to verify the committed object's size and SHA-256; it must never
// replay completion or abort after an ambiguous response.
'verify_url' => CloudS3Signer::presign(
'GET', $objectUrl, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
$timestamp, $expiresSeconds
),
'expires_at' => $timestamp + $expiresSeconds,
];
}
/**
* Find every still-open multipart session for one exact immutable key.
*
* This is a read-only recovery primitive for an ambiguous
* CreateMultipartUpload response. An empty result is trustworthy only
* after every bounded page was parsed successfully; any transport,
* authorization, pagination or XML anomaly remains an unknown effect.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return list<array{upload_id:string,initiated_at:int}>
*/
public function findMultipartUploadsByExactObjectKey(
array $config,
array $credentials,
string $objectKey
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
$keyMarker = null;
$uploadMarker = null;
$markerPairs = [];
$seenUploadIds = [];
$matches = [];
for ($page = 1; $page <= self::MAX_MULTIPART_LOOKUP_PAGES; $page++) {
$query = [
'uploads' => '',
'prefix' => $objectKey,
'max-uploads' => self::MAX_MULTIPART_LOOKUP_PAGE_SIZE,
];
if ($keyMarker !== null && $uploadMarker !== null) {
$query['key-marker'] = $keyMarker;
$query['upload-id-marker'] = $uploadMarker;
}
$url = self::bucketUrl(
(string) $config['endpoint'],
(string) $config['bucket'],
(bool) $config['path_style']
) . '?' . http_build_query(
$query,
'',
'&',
PHP_QUERY_RFC3986
);
$headers = CloudS3Signer::sign(
'GET',
$url,
(string) $config['region'],
$credentials['access_key_id'],
$credentials['secret_access_key'],
time()
);
try {
$response = $this->http()->request('GET', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw self::multipartLookupUnknown();
}
if ($response->getStatusCode() < 200
|| $response->getStatusCode() >= 300) {
throw self::multipartLookupUnknown();
}
$body = (string) $response->getBody();
if (strlen($body) > 1048576
|| !function_exists('simplexml_load_string')) {
throw self::multipartLookupUnknown();
}
$xml = @simplexml_load_string(
$body,
\SimpleXMLElement::class,
LIBXML_NONET | LIBXML_NOBLANKS
);
if (!$xml instanceof \SimpleXMLElement) {
throw self::multipartLookupUnknown();
}
$truncatedNodes = $xml->xpath(
'/*[local-name()="ListMultipartUploadsResult"]'
. '/*[local-name()="IsTruncated"]'
);
$truncatedText = is_array($truncatedNodes)
&& count($truncatedNodes) === 1
? strtolower(trim((string) $truncatedNodes[0])) : '';
if (!in_array($truncatedText, ['true', 'false'], true)) {
throw self::multipartLookupUnknown();
}
$uploads = $xml->xpath(
'/*[local-name()="ListMultipartUploadsResult"]'
. '/*[local-name()="Upload"]'
);
if (!is_array($uploads)
|| count($uploads) > self::MAX_MULTIPART_LOOKUP_PAGE_SIZE) {
throw self::multipartLookupUnknown();
}
foreach ($uploads as $upload) {
$keyNodes = $upload->xpath('./*[local-name()="Key"]');
$idNodes = $upload->xpath('./*[local-name()="UploadId"]');
$initiatedNodes = $upload->xpath(
'./*[local-name()="Initiated"]'
);
$key = is_array($keyNodes) && count($keyNodes) === 1
? (string) $keyNodes[0] : '';
$uploadId = is_array($idNodes) && count($idNodes) === 1
? (string) $idNodes[0] : '';
$initiated = is_array($initiatedNodes)
&& count($initiatedNodes) === 1
? trim((string) $initiatedNodes[0]) : '';
if ($key === '' || strlen($key) > 1024
|| preg_match('/[\x00-\x1f\x7f]/D', $key) === 1
|| isset($seenUploadIds[$uploadId])) {
throw self::multipartLookupUnknown();
}
try {
self::assertUploadId($uploadId);
$initiatedAt = self::multipartInitiatedAt($initiated);
} catch (\Throwable $error) {
throw self::multipartLookupUnknown();
}
$seenUploadIds[$uploadId] = true;
if (hash_equals($objectKey, $key)) {
$matches[] = [
'upload_id' => $uploadId,
'initiated_at' => $initiatedAt,
];
}
}
if ($truncatedText === 'false') {
usort($matches, static fn (array $left, array $right): int =>
[$left['initiated_at'], $left['upload_id']]
<=> [$right['initiated_at'], $right['upload_id']]);
return $matches;
}
if ($page === self::MAX_MULTIPART_LOOKUP_PAGES) {
throw self::multipartLookupUnknown();
}
$nextKeyNodes = $xml->xpath(
'/*[local-name()="ListMultipartUploadsResult"]'
. '/*[local-name()="NextKeyMarker"]'
);
$nextUploadNodes = $xml->xpath(
'/*[local-name()="ListMultipartUploadsResult"]'
. '/*[local-name()="NextUploadIdMarker"]'
);
$nextKey = is_array($nextKeyNodes)
&& count($nextKeyNodes) === 1
? (string) $nextKeyNodes[0] : '';
$nextUpload = is_array($nextUploadNodes)
&& count($nextUploadNodes) === 1
? (string) $nextUploadNodes[0] : '';
if ($nextKey === '' || strlen($nextKey) > 1024
|| preg_match('/[\x00-\x1f\x7f]/D', $nextKey) === 1) {
throw self::multipartLookupUnknown();
}
try {
self::assertUploadId($nextUpload);
} catch (\Throwable $error) {
throw self::multipartLookupUnknown();
}
$markerPair = $nextKey . "\0" . $nextUpload;
if (isset($markerPairs[$markerPair])) {
throw self::multipartLookupUnknown();
}
$markerPairs[$markerPair] = true;
$keyMarker = $nextKey;
$uploadMarker = $nextUpload;
}
throw self::multipartLookupUnknown();
}
/**
* Read the exact provider part ledger before accepting browser evidence.
*
* @return list<array{part_number:int,size_bytes:int,etag:string}>
*/
public function listMultipartParts(
array $config,
array $credentials,
string $objectKey,
string $uploadId
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertUploadId($uploadId);
$url = self::objectUrl($config, $objectKey) . '?'
. http_build_query([
'uploadId' => $uploadId,
'max-parts' => self::MAX_PARTS,
], '', '&', PHP_QUERY_RFC3986);
$headers = CloudS3Signer::sign(
'GET', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time()
);
try {
$response = $this->http()->request('GET', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法读取对象存储分片状态。',
'multipart_parts_unavailable'
);
}
if ($response->getStatusCode() === 404) {
throw new CloudObjectStorageTransferError(
'对象存储分段上传已经不存在。',
'multipart_upload_absent'
);
}
if ($response->getStatusCode() < 200
|| $response->getStatusCode() >= 300) {
throw new CloudObjectStorageTransferError(
'对象存储拒绝读取分片状态。',
'multipart_parts_rejected'
);
}
$body = (string) $response->getBody();
if (strlen($body) > 1048576 || !function_exists('simplexml_load_string')) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
$xml = @simplexml_load_string(
$body,
\SimpleXMLElement::class,
LIBXML_NONET | LIBXML_NOBLANKS
);
if (!$xml instanceof \SimpleXMLElement) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
$truncated = $xml->xpath(
'/*[local-name()="ListPartsResult"]/*[local-name()="IsTruncated"]'
);
if (!is_array($truncated) || count($truncated) !== 1
|| strtolower(trim((string) $truncated[0])) !== 'false') {
throw new CloudObjectStorageTransferError(
'对象存储分片数量超出受控范围。',
'multipart_parts_truncated'
);
}
$nodes = $xml->xpath(
'/*[local-name()="ListPartsResult"]/*[local-name()="Part"]'
);
if (!is_array($nodes) || count($nodes) > self::MAX_PARTS) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
$parts = [];
$seen = [];
foreach ($nodes as $node) {
$numberNode = $node->xpath('./*[local-name()="PartNumber"]');
$sizeNode = $node->xpath('./*[local-name()="Size"]');
$etagNode = $node->xpath('./*[local-name()="ETag"]');
$numberText = is_array($numberNode) && count($numberNode) === 1
? trim((string) $numberNode[0]) : '';
$sizeText = is_array($sizeNode) && count($sizeNode) === 1
? trim((string) $sizeNode[0]) : '';
$etag = is_array($etagNode) && count($etagNode) === 1
? trim((string) $etagNode[0]) : '';
if (preg_match('/^[1-9][0-9]*$/D', $numberText) !== 1
|| preg_match('/^[1-9][0-9]*$/D', $sizeText) !== 1) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
$number = (int) $numberText;
$size = (int) $sizeText;
try {
self::assertETag($etag);
} catch (\InvalidArgumentException $error) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
if ($number < 1 || $number > self::MAX_PARTS
|| $size < 1 || isset($seen[$number])) {
throw new CloudObjectStorageTransferError(
'对象存储返回的分片状态无效。',
'multipart_parts_invalid'
);
}
$seen[$number] = true;
$parts[] = [
'part_number' => $number,
'size_bytes' => $size,
'etag' => $etag,
];
}
usort($parts, static fn (array $left, array $right): int =>
$left['part_number'] <=> $right['part_number']);
return $parts;
}
/**
* Complete one exact multipart upload. A lost completion response remains
* unknown; callers must reconcile the immutable object and never replay
* completion blindly.
*
* @param list<array{part_number:int,etag:string}> $parts
* @return array{size_bytes:int,etag:string,version_id:string}
*/
public function completeMultipartUpload(
array $config,
array $credentials,
string $objectKey,
string $uploadId,
array $parts
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertUploadId($uploadId);
if ($parts === [] || count($parts) > self::MAX_PARTS) {
throw new \InvalidArgumentException('Invalid multipart completion parts');
}
$body = '<CompleteMultipartUpload>';
$previous = 0;
foreach ($parts as $part) {
$number = $part['part_number'] ?? null;
$etag = $part['etag'] ?? null;
if (!is_int($number) || $number !== $previous + 1
|| !is_string($etag)) {
throw new \InvalidArgumentException(
'Invalid multipart completion parts'
);
}
self::assertETag($etag);
$body .= '<Part><PartNumber>' . $number . '</PartNumber><ETag>'
. htmlspecialchars($etag, ENT_XML1 | ENT_QUOTES, 'UTF-8')
. '</ETag></Part>';
$previous = $number;
}
$body .= '</CompleteMultipartUpload>';
$url = self::objectUrl($config, $objectKey) . '?'
. http_build_query(['uploadId' => $uploadId], '', '&',
PHP_QUERY_RFC3986);
$headers = CloudS3Signer::sign(
'POST', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time(), hash('sha256', $body)
) + [
'Content-Type' => 'application/xml',
'Content-Length' => (string) strlen($body),
];
try {
$response = $this->http()->request('POST', $url, [
'headers' => $headers,
'body' => $body,
] + self::requestOptions(60.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法确认对象存储是否已完成分段上传。',
'multipart_complete_unknown',
true
);
}
$status = $response->getStatusCode();
if ($status < 200 || $status >= 300) {
$unknown = in_array($status, [408, 425, 429], true)
|| $status >= 500;
throw new CloudObjectStorageTransferError(
$unknown
? '无法确认对象存储是否已完成分段上传。'
: '对象存储拒绝完成分段上传。',
$unknown
? 'multipart_complete_unknown'
: 'multipart_complete_rejected',
$unknown
);
}
try {
return $this->headObject(
$config,
$credentials,
$objectKey
);
} catch (\Throwable $error) {
throw new CloudObjectStorageTransferError(
'分段上传完成,但无法确认对象身份。',
'multipart_complete_unknown',
true
);
}
}
/** Stable business-facing alias; objectKey already includes any prefix. */
public function beginMultipartPlan(
array $config,
array $credentials,
string $objectKey,
int $maximumSizeBytes,
int $expiresSeconds = 604800
): array {
return $this->prepareMultipartUpload(
$config,
$credentials,
$objectKey,
$maximumSizeBytes,
time(),
$expiresSeconds
);
}
/**
* Mint a read-only capability for one frozen backup object.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
*/
public function presignDownload(
array $config,
array $credentials,
string $objectKey,
?int $timestamp = null,
int $expiresSeconds = 86400
): string {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
return CloudS3Signer::presign(
'GET', self::objectUrl($config, $objectKey),
(string) $config['region'], $credentials['access_key_id'],
$credentials['secret_access_key'], $timestamp ?? time(),
$expiresSeconds
);
}
/** Stable business-facing alias; objectKey already includes any prefix. */
public function presignedGet(
array $config,
array $credentials,
string $objectKey,
int $expiresSeconds = 604800
): string {
return $this->presignDownload(
$config,
$credentials,
$objectKey,
time(),
$expiresSeconds
);
}
/** Mint a read capability for the exact immutable provider version. */
public function presignedVersionedGet(
array $config,
array $credentials,
string $objectKey,
string $versionId,
int $expiresSeconds = 604800
): string {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertVersionId($versionId);
return CloudS3Signer::presign(
'GET', self::versionedObjectUrl($config, $objectKey, $versionId),
(string) $config['region'], $credentials['access_key_id'],
$credentials['secret_access_key'], time(), $expiresSeconds
);
}
/**
* Publish one immutable local file with a payload-bound SigV4 request.
* The conditional write prevents a retry or concurrent publisher from
* replacing a previously frozen template generation.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array{size_bytes:int,sha256:string,etag:string,version_id:string}
*/
public function putImmutableFile(
array $config,
array $credentials,
string $objectKey,
string $path,
int $sizeBytes,
string $sha256
): array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
if ($sizeBytes < 1
|| preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1
|| !is_file($path) || !is_readable($path)
|| @filesize($path) !== $sizeBytes) {
throw new \InvalidArgumentException(
'Invalid immutable object source file'
);
}
$resource = @fopen($path, 'rb');
if ($resource === false) {
throw new CloudObjectStorageTransferError(
'无法读取待保存的模板主副本。', 'object_source_unreadable'
);
}
// Keep one StreamInterface owner alive until request() returns. Guzzle
// receives this same object, so close() remains idempotent even when a
// handler releases the request body before returning its response.
$body = Utils::streamFor($resource);
$url = self::objectUrl($config, $objectKey);
$headers = CloudS3Signer::sign(
'PUT', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time(), $sha256, ['virt-sha256' => $sha256]
) + [
'Content-Length' => (string) $sizeBytes,
'Content-Type' => 'application/octet-stream',
'If-None-Match' => '*',
];
try {
$response = $this->http()->request('PUT', $url, [
'headers' => $headers,
'body' => $body,
] + self::requestOptions(0.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法确认模板主副本是否已保存。',
'object_put_unknown',
true
);
} catch (\Throwable $exception) {
// request() was entered, so an unexpected handler/runtime error
// cannot prove that the remote write did not happen.
throw new CloudObjectStorageTransferError(
'无法确认模板主副本是否已保存。',
'object_put_unknown',
true
);
} finally {
$body->close();
}
$status = $response->getStatusCode();
if ($status === 409 || $status === 412) {
throw new CloudObjectStorageTransferError(
'模板主副本对象已经存在,禁止覆盖。',
'object_already_exists'
);
}
if ($status < 200 || $status >= 300) {
$unknown = in_array($status, [408, 425, 429], true)
|| $status >= 500;
throw new CloudObjectStorageTransferError(
$unknown
? '无法确认模板主副本是否已保存。'
: '对象存储拒绝保存模板主副本。',
$unknown ? 'object_put_unknown' : 'object_put_rejected',
$unknown
);
}
$etag = trim($response->getHeaderLine('ETag'));
if ($etag === '' || strlen($etag) > 256
|| preg_match('/[\x00-\x1f\x7f]/', $etag) === 1) {
throw new CloudObjectStorageTransferError(
'对象存储没有返回可信的模板对象标识。',
'object_put_invalid',
true
);
}
$versionId = trim($response->getHeaderLine('x-amz-version-id'));
try {
self::assertVersionId($versionId);
} catch (\InvalidArgumentException $exception) {
throw new CloudObjectStorageTransferError(
'对象存储没有返回可信的模板版本标识。',
'object_put_invalid',
true
);
}
return [
'size_bytes' => $sizeBytes,
'sha256' => $sha256,
'etag' => $etag,
'version_id' => $versionId,
];
}
/**
* Abort a multipart upload from PHP when non-dispatch is proven.
* A transport failure is explicitly unknown and must not authorize a
* second destructive action.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
*/
public function abortMultipartUpload(
array $config,
array $credentials,
string $objectKey,
string $uploadId
): void {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertUploadId($uploadId);
$url = self::objectUrl($config, $objectKey) . '?'
. http_build_query(['uploadId' => $uploadId], '', '&', PHP_QUERY_RFC3986);
$headers = CloudS3Signer::sign(
'DELETE', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time()
);
try {
$response = $this->http()->request('DELETE', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法确认对象存储是否已终止分段上传。',
'multipart_abort_unknown',
true
);
}
$status = $response->getStatusCode();
if ($status < 200 || $status >= 300) {
throw new CloudObjectStorageTransferError(
'对象存储拒绝终止分段上传。',
'multipart_abort_rejected'
);
}
}
/** Stable business-facing alias for proven non-dispatch cleanup. */
public function abortMultipart(
array $config,
array $credentials,
string $objectKey,
string $uploadId
): void {
$this->abortMultipartUpload(
$config,
$credentials,
$objectKey,
$uploadId
);
}
/**
* Read immutable object identity without transferring its contents.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array{size_bytes:int,sha256:string,etag:string,version_id:string}
*/
public function headObject(
array $config,
array $credentials,
string $objectKey,
string $versionId = ''
): array {
$identity = $this->inspectObject(
$config, $credentials, $objectKey, $versionId
);
if ($identity === null) {
throw new CloudObjectStorageTransferError(
'备份对象不存在或当前凭据无权读取。', 'object_head_rejected'
);
}
return $identity;
}
/**
* Inspect one exact object version. A 404 is a proven absence; transport,
* permission and provider failures remain distinguishable from absence.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return array{size_bytes:int,sha256:string,etag:string,version_id:string}|null
*/
public function inspectObject(
array $config,
array $credentials,
string $objectKey,
string $versionId = ''
): ?array {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertVersionId($versionId);
$url = self::versionedObjectUrl($config, $objectKey, $versionId);
$headers = CloudS3Signer::sign(
'HEAD', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time()
);
try {
$response = $this->http()->request('HEAD', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法读取备份对象状态。', 'object_head_unavailable'
);
}
if ($response->getStatusCode() === 404) {
return null;
}
if ($response->getStatusCode() < 200 || $response->getStatusCode() >= 300) {
throw new CloudObjectStorageTransferError(
'备份对象不存在或当前凭据无权读取。', 'object_head_rejected'
);
}
$length = trim($response->getHeaderLine('Content-Length'));
if (preg_match('/^(?:0|[1-9][0-9]*)$/D', $length) !== 1
|| (int) $length < 1) {
throw new CloudObjectStorageTransferError(
'备份对象缺少可信的大小信息。', 'object_head_invalid'
);
}
$etag = trim($response->getHeaderLine('ETag'));
if ($etag === '' || strlen($etag) > 256
|| preg_match('/[\x00-\x1f\x7f]/', $etag) === 1) {
throw new CloudObjectStorageTransferError(
'备份对象缺少可信的 ETag。', 'object_head_invalid'
);
}
$reportedVersion = trim($response->getHeaderLine('x-amz-version-id'));
self::assertVersionId($reportedVersion);
$sha256 = strtolower(trim(
$response->getHeaderLine('x-amz-meta-virt-sha256')
));
if ($sha256 !== ''
&& preg_match('/^[a-f0-9]{64}$/D', $sha256) !== 1) {
throw new CloudObjectStorageTransferError(
'备份对象缺少可信的 SHA-256 元数据。',
'object_head_invalid'
);
}
return [
'size_bytes' => (int) $length,
// Empty means a legacy/untrusted object. Callers reconciling an
// unknown PUT must require an exact match, never infer identity
// from ETag (multipart and provider ETags are not content hashes).
'sha256' => $sha256,
'etag' => $etag,
'version_id' => $reportedVersion,
];
}
/**
* Delete one exact backup object version. A transport failure has unknown
* effect; callers must reconcile it and may only create a new generation
* after independently stable identity evidence.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
*/
public function deleteObject(
array $config,
array $credentials,
string $objectKey,
string $versionId = ''
): void {
self::assertRuntime($config, $credentials);
self::assertObjectKey($objectKey);
self::assertVersionId($versionId);
$url = self::versionedObjectUrl($config, $objectKey, $versionId);
$headers = CloudS3Signer::sign(
'DELETE', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
time()
);
try {
$response = $this->http()->request('DELETE', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法确认备份对象是否已删除。',
'object_delete_unknown',
true
);
}
$status = $response->getStatusCode();
if ($status < 200 || $status >= 300) {
$unknown = in_array($status, [408, 425, 429], true)
|| $status >= 500;
throw new CloudObjectStorageTransferError(
$unknown
? '无法确认备份对象是否已删除。'
: '对象存储拒绝删除备份对象。',
$unknown ? 'object_delete_unknown' : 'object_delete_rejected',
$unknown
);
}
}
/**
* Read-only presence check for one exact object version.
*
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
* @return 'present'|'absent'
*/
public function objectPresence(
array $config,
array $credentials,
string $objectKey,
string $versionId = ''
): string {
return $this->inspectObject(
$config, $credentials, $objectKey, $versionId
) === null ? 'absent' : 'present';
}
/**
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
*/
private function createMultipartUpload(
array $config,
array $credentials,
string $objectKey,
int $timestamp,
array $metadata = []
): string {
$url = self::objectUrl($config, $objectKey) . '?uploads=';
$headers = CloudS3Signer::sign(
'POST', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
$timestamp,
null,
$metadata
);
try {
$response = $this->http()->request('POST', $url, [
'headers' => $headers,
] + self::requestOptions(30.0));
} catch (GuzzleException $exception) {
throw new CloudObjectStorageTransferError(
'无法确认对象存储是否已开始分段上传。',
'multipart_create_unknown',
true
);
}
$status = $response->getStatusCode();
if ($status < 200 || $status >= 300) {
$unknown = in_array($status, [408, 425, 429], true)
|| $status >= 500;
throw new CloudObjectStorageTransferError(
$unknown
? '无法确认对象存储是否已开始分段上传。'
: '对象存储拒绝创建分段上传。',
$unknown
? 'multipart_create_unknown'
: 'multipart_create_rejected',
$unknown
);
}
$body = (string) $response->getBody();
if (strlen($body) > 65536
|| preg_match('/<UploadId>([^<]+)<\/UploadId>/i', $body, $match) !== 1) {
throw new CloudObjectStorageTransferError(
'对象存储返回了无效的分段上传标识。',
'multipart_create_invalid',
true
);
}
$uploadId = html_entity_decode($match[1], ENT_QUOTES | ENT_XML1, 'UTF-8');
try {
self::assertUploadId($uploadId);
} catch (CloudObjectStorageTransferError $error) {
throw new CloudObjectStorageTransferError(
'对象存储返回了无效的分段上传标识。',
'multipart_create_invalid',
true
);
}
return $uploadId;
}
/** @param array<string,mixed> $config */
private static function objectUrl(array $config, string $objectKey): string
{
$base = self::bucketUrl(
(string) $config['endpoint'],
(string) $config['bucket'],
(bool) $config['path_style']
);
$encoded = implode('/', array_map(
static fn (string $segment): string => rawurlencode($segment),
explode('/', $objectKey)
));
return rtrim($base, '/') . '/' . $encoded;
}
/** @param array<string,mixed> $config */
private static function versionedObjectUrl(array $config,
string $objectKey, string $versionId): string
{
$url = self::objectUrl($config, $objectKey);
return $versionId === '' ? $url
: $url . '?versionId=' . rawurlencode($versionId);
}
private static function assertVersionId(string $versionId): void
{
if (strlen($versionId) > 1024
|| preg_match('/[\x00-\x1f\x7f]/D', $versionId) === 1) {
throw new \InvalidArgumentException('Invalid S3 object version identifier');
}
}
/**
* @param array<string,mixed> $config
* @param array{access_key_id:string,secret_access_key:string} $credentials
*/
private static function assertRuntime(array $config, array $credentials): void
{
foreach (['endpoint', 'region', 'bucket'] as $field) {
if (!is_string($config[$field] ?? null)
|| trim((string) $config[$field]) === '') {
throw new \InvalidArgumentException('Incomplete S3 runtime configuration');
}
}
if (!is_bool($config['path_style'] ?? null)
|| !is_string($credentials['access_key_id'] ?? null)
|| $credentials['access_key_id'] === ''
|| !is_string($credentials['secret_access_key'] ?? null)
|| $credentials['secret_access_key'] === '') {
throw new \InvalidArgumentException('Incomplete S3 runtime credentials');
}
}
private static function assertObjectKey(string $objectKey): void
{
if ($objectKey === '' || strlen($objectKey) > 1024
|| str_starts_with($objectKey, '/') || str_ends_with($objectKey, '/')
|| str_contains($objectKey, '\\')
|| preg_match('/[\x00-\x1f\x7f]/D', $objectKey) === 1
|| in_array('', explode('/', $objectKey), true)) {
throw new \InvalidArgumentException('Invalid S3 object key');
}
}
private static function assertUploadId(string $uploadId): void
{
if ($uploadId === '' || strlen($uploadId) > self::MAX_UPLOAD_ID_BYTES
|| preg_match('/^[\x21-\x7e]+$/D', $uploadId) !== 1) {
throw new CloudObjectStorageTransferError(
'对象存储返回了无效的分段上传标识。', 'multipart_create_invalid'
);
}
}
private static function multipartInitiatedAt(string $value): int
{
if (preg_match(
'/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:'
. '[0-9]{2}(?:\.[0-9]{1,6})?Z$/D',
$value
) !== 1) {
throw new \InvalidArgumentException(
'Invalid S3 multipart initiation timestamp'
);
}
$format = str_contains($value, '.')
? '!Y-m-d\TH:i:s.u\Z' : '!Y-m-d\TH:i:s\Z';
$date = \DateTimeImmutable::createFromFormat(
$format,
$value,
new \DateTimeZone('UTC')
);
$errors = \DateTimeImmutable::getLastErrors();
if (!$date instanceof \DateTimeImmutable
|| (is_array($errors)
&& (($errors['warning_count'] ?? 0) > 0
|| ($errors['error_count'] ?? 0) > 0))) {
throw new \InvalidArgumentException(
'Invalid S3 multipart initiation timestamp'
);
}
return $date->getTimestamp();
}
private static function multipartLookupUnknown(): CloudObjectStorageTransferError
{
return new CloudObjectStorageTransferError(
'无法确认对象存储分段上传会话。',
'multipart_lookup_unknown',
true
);
}
/** @return array{0:int,1:int} */
private static function multipartGeometry(int $maximumSizeBytes): array
{
if ($maximumSizeBytes < 1
|| $maximumSizeBytes > self::MAX_PARTS * self::MAX_PART_BYTES) {
throw new \InvalidArgumentException(
'S3 multipart maximum size exceeds the 512-part control envelope'
);
}
$partSize = max(
self::MIN_PART_BYTES,
(int) ceil($maximumSizeBytes / self::MAX_PARTS)
);
$mib = 1048576;
$partSize = (int) (ceil($partSize / $mib) * $mib);
if ($partSize > self::MAX_PART_BYTES) {
throw new \InvalidArgumentException('S3 multipart part size is too large');
}
$partCount = (int) ceil($maximumSizeBytes / $partSize);
if ($partCount < 1 || $partCount > self::MAX_PARTS) {
throw new \InvalidArgumentException('S3 multipart part count is invalid');
}
return [$partSize, $partCount];
}
private static function assertETag(string $etag): void
{
if ($etag === '' || strlen($etag) > 256
|| preg_match('/[\x00-\x1f\x7f]/D', $etag) === 1) {
throw new \InvalidArgumentException('Invalid S3 multipart ETag');
}
}
private function http(): ClientInterface
{
return $this->http ?? new Client();
}
/** @return array<string,mixed> */
private static function requestOptions(float $timeout): array
{
return [
'http_errors' => false,
'allow_redirects' => false,
'connect_timeout' => 5.0,
'timeout' => $timeout,
'verify' => true,
'proxy' => '',
];
}
private static function bucketUrl(
string $endpoint,
string $bucket,
bool $pathStyle
): string {
if ($pathStyle) {
return rtrim($endpoint, '/') . '/' . rawurlencode($bucket) . '/';
}
$parts = parse_url($endpoint);
if (!is_array($parts) || !isset($parts['scheme'], $parts['host'])) {
throw new \InvalidArgumentException('Invalid S3 endpoint');
}
$authority = $bucket . '.' . strtolower((string) $parts['host']);
if (isset($parts['port'])) {
$authority .= ':' . (int) $parts['port'];
}
return strtolower((string) $parts['scheme']) . '://' . $authority . '/';
}
}