$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 $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,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 $config * @param array{access_key_id:string,secret_access_key:string} $credentials * @return array */ 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 $config * @param array{access_key_id:string,secret_access_key:string} $credentials * @return list */ 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 */ 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 $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 = ''; $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 .= '' . $number . '' . htmlspecialchars($etag, ENT_XML1 | ENT_QUOTES, 'UTF-8') . ''; $previous = $number; } $body .= ''; $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 $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 $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 $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 $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 $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 $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 $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 $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>/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 $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 $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 $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 */ 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 . '/'; } }