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

1267 lines
48 KiB
PHP

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?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
);
}
/** 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
): string {
$url = self::objectUrl($config, $objectKey) . '?uploads=';
$headers = CloudS3Signer::sign(
'POST', $url, (string) $config['region'],
$credentials['access_key_id'], $credentials['secret_access_key'],
$timestamp
);
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 . '/';
}
}