'https://objects.example.test',
'region' => 'us-east-1',
'bucket' => 'virt-backups',
'path_style' => true,
];
$credentials = [
'access_key_id' => 'LOOKUPACCESSKEY',
'secret_access_key' => 'lookup-secret-never-log',
];
$objectKey = 'vm-backups/fixture/system.qcow2';
$client = static function (array $responses, array &$history): CloudObjectStorageS3Client {
$stack = HandlerStack::create(new MockHandler($responses));
$stack->push(Middleware::history($history));
return new CloudObjectStorageS3Client(new Client(['handler' => $stack]));
};
$expectUnknown = static function (callable $callback) use ($assert): void {
try {
$callback();
} catch (CloudObjectStorageTransferError $error) {
$assert($error->publicCode === 'multipart_lookup_unknown'
&& $error->effectMayHaveApplied,
'Multipart lookup did not preserve unknown-effect semantics.');
return;
}
throw new RuntimeException('Expected multipart lookup failure was not raised.');
};
$history = [];
$lookup = $client([
new Response(200, ['Content-Type' => 'application/xml'],
''
. ''
. 'true'
. 'vm-backups/fixture/system.qcow2'
. 'marker-one'
. 'vm-backups/fixture/system.qcow2-extra'
. 'unrelated-upload'
. '2026-11-06T00:00:01Z'
. 'vm-backups/fixture/system.qcow2'
. 'upload-b'
. '2026-11-06T00:00:02.123Z'
. ''),
new Response(200, ['Content-Type' => 'application/xml'],
''
. ''
. 'false'
. 'vm-backups/fixture/system.qcow2'
. 'upload-a'
. '2026-11-05T23:59:59.123456Z'
. ''),
], $history);
$matches = $lookup->findMultipartUploadsByExactObjectKey(
$config,
$credentials,
$objectKey
);
$assert(array_column($matches, 'upload_id') === ['upload-a', 'upload-b']
&& $matches[0]['initiated_at'] === 1793923199
&& $matches[1]['initiated_at'] === 1793923202,
'Exact multipart lookup lost matches, ordering, or initiation time.');
$assert(count($history) === 2
&& $history[0]['request']->getMethod() === 'GET'
&& $history[1]['request']->getMethod() === 'GET',
'Multipart lookup did not use bounded read-only requests.');
parse_str((string) $history[0]['request']->getUri()->getQuery(), $firstQuery);
parse_str((string) $history[1]['request']->getUri()->getQuery(), $secondQuery);
$assert(($firstQuery['prefix'] ?? null) === $objectKey
&& ($firstQuery['max-uploads'] ?? null) === '100'
&& array_key_exists('uploads', $firstQuery)
&& ($secondQuery['key-marker'] ?? null) === $objectKey
&& ($secondQuery['upload-id-marker'] ?? null) === 'marker-one'
&& !str_contains(
json_encode($history, JSON_THROW_ON_ERROR),
$credentials['secret_access_key']
),
'Multipart lookup lost exact-prefix pagination or exposed credentials.');
$emptyHistory = [];
$empty = $client([
new Response(200, [], ''
. 'false'
. ''),
], $emptyHistory);
$assert($empty->findMultipartUploadsByExactObjectKey(
$config,
$credentials,
$objectKey
) === [],
'A complete empty multipart listing was not accepted as absence evidence.');
$invalidTimeHistory = [];
$invalidTime = $client([
new Response(200, [], ''
. 'false'
. 'vm-backups/fixture/system.qcow2'
. 'upload-invalid-time'
. '2026-02-30T25:00:00Z'
. ''),
], $invalidTimeHistory);
$expectUnknown(static fn () => $invalidTime->
findMultipartUploadsByExactObjectKey($config, $credentials, $objectKey));
$missingMarkerHistory = [];
$missingMarker = $client([
new Response(200, [], ''
. 'true'
. ''),
], $missingMarkerHistory);
$expectUnknown(static fn () => $missingMarker->
findMultipartUploadsByExactObjectKey($config, $credentials, $objectKey));
$capHistory = [];
$capResponses = [];
for ($index = 1; $index <= 4; $index++) {
$capResponses[] = new Response(200, [],
''
. 'true'
. 'vm-backups/fixture/system.qcow2-'
. $index . ''
. 'marker-' . $index
. ''
. '');
}
$capped = $client($capResponses, $capHistory);
$expectUnknown(static fn () => $capped->
findMultipartUploadsByExactObjectKey($config, $credentials, $objectKey));
$assert(count($capHistory) === 4,
'Multipart lookup exceeded its strict page cap.');
$transportHistory = [];
$transport = $client([
new ConnectException(
'network unavailable',
new Request('GET', 'https://objects.example.test')
),
], $transportHistory);
$expectUnknown(static fn () => $transport->
findMultipartUploadsByExactObjectKey($config, $credentials, $objectKey));
echo "Object-storage exact multipart lookup contracts passed.\n";