feat(storage)!: 3.0 — immutable coroutine-safe devices, enums, max static analysis

[loks0n]

Summary

Prepares the next major release of utopia-php/storage (3.0.0 — latest tag is storage/2.0.7), modernising the interface in line with newer utopia libraries such as dns.

No global state

• The static device registry (Storage::setDevice/getDevice/exists/$devices) is removed. Devices are constructed directly and passed around; Storage shrinks to the pure human() helper.
• The static S3::setRetryAttempts()/setRetryDelay() are gone (see below).

Immutability

• All configuration moves to readonly constructor promotion. setTelemetry(), setHttpVersion(), and setTransferChunkSize() are replaced by telemetry, httpVersion, retryAttempts, retryDelay constructor arguments; transfer chunk size becomes a per-call argument: transfer($path, $dest, $device, $chunkSize).
• Secret keys are marked #[\SensitiveParameter].

Coroutine safety

• The S3 adapter previously mutated shared $this->headers/$this->amzHeaders on every operation — two concurrent requests on one device instance (e.g. Swoole coroutines) would race and corrupt each other's SigV4 signatures. Headers are now built locally per call and passed through call()/getSignatureV4(); a device instance holds no request state.
• Side fixes: the old code signed empty headers it never sent (now it signs exactly what it sends), and retries appended to the previous attempt's response buffer (now reset per attempt).

Enums over string constants

• Storage::DEVICE_* → Utopia\Storage\DeviceType (string-backed), returned by Device::getType().
• S3::ACL_* → Utopia\Storage\Acl, taken as a typed constructor parameter.
• Region constants stay strings: providers add clusters faster than releases, and custom values are valid.

Maximum static analysis

• packages/storage/phpstan.neon pins level max (root baseline is level 5); packages/storage/rector.php extends the root baseline with the remaining stable prepared sets (typeDeclarationDocblocks, privatization, instanceOf, rectorPreset).
• src and tests fully conform: the S3 response is a typed readonly value object instead of stdClass, decoded XML is honestly narrowed, the chunked-upload &$metadata contract is a shared UploadMetadata array shape, and the Telemetry decorator uses a generic closure-based measure() instead of magic dispatch.

Docs

• README rewritten around direct construction, with an "Upgrading from 2.x" migration section; also corrects methods that never existed (listFiles/deleteDirectory → getFiles/deletePath).

PSR-18 HTTP client

• The S3 adapter no longer talks to cURL directly: requests are built as PSR-7 messages and sent through any PSR-18 client, injected via the new client constructor argument. The default is utopia-php/client with the cURL adapter and no request timeout (matching the old behavior for large chunk uploads); the Swoole coroutine adapter or any other PSR-18 client drops in.
• The httpVersion option and HTTP_VERSION_* constants are gone — transport concerns (timeouts, TLS, HTTP version, connection reuse) belong to the injected client.
• Retries use the utopia-php/client Retry decorator with a new S3\RetryStrategy that encodes the S3-specific transient-error policy (SlowDown/ServiceUnavailable/Throttling/RequestThrottled XML codes, 429/503 fallback). The default client wraps the cURL adapter in it; injecting a client controls the whole retry policy, so the retryAttempts/retryDelay constructor arguments are gone.
• New S3ClientTest unit-tests signing, retries, retry exhaustion, NoSuchKey mapping, and XML decoding against a scripted PSR-18 stub.

Simplification pass (net −656 lines)

• Storage class deleted entirely (registry was already gone; human() removed too). The stub File validator, unused getPath() $prefix parameter, S3::METHOD_* constants (PSR-7 Method used instead), and the unused utopia-php/system + ext-zlib dependencies are gone.
• One telemetry mechanism: the Telemetry decorator. S3 no longer has an internal histogram or telemetry constructor argument, so wrapped devices are not double-counted.
• One upload flow: upload($sourcePath) removed, uploadChunk() takes chunk contents, and uploadData() is now a concrete base-class method composing prepareUpload → uploadChunk → finalizeUpload (previously duplicated in each adapter).
• Filesystem-only methods (createDirectory, getDirectorySize, getPartitionFreeSpace/TotalSpace, getFiles) left the abstract Device contract — Local keeps them, S3 keeps its own getFiles, the -1/no-op S3 stubs are deleted. getName()/getDescription() removed; getType() identifies adapters. abort($extra) renamed abort($uploadId).

Consumer PoC feedback (Appwrite + Appwrite Cloud)

• Telemetry::getDevice() added: both consumers wrap every injected device in the decorator, which made adapter-specific methods (Local partition metrics, S3 object listing) unreachable after the contract shrink. Consumers should inject the concrete adapter type where adapter-specific methods are needed (e.g. an S3-typed resource); the accessor is the escape hatch for call sites that receive an already-wrapped device.
• listFiles(prefix, max, cursor) replaces the inconsistent getFiles() (path strings on Local vs raw ListObjectsV2 array on S3): typed FileList/FileInfo readonly value objects, identical on every adapter, back on the base Device contract and forwarded by the decorator. The S3 single-object Contents quirk is normalized inside the adapter instead of by every consumer.

Typed exceptions

• Every runtime failure extends Utopia\Storage\Exception\StorageException: NotFoundException (missing files, now consistent across adapters and methods — S3 HEAD 404s previously threw a generic exception with an empty message), TransportException (PSR-18 delivery failures, previous chained), RemoteException (service errors; HTTP status as code, service error identifier such as SlowDown as a readonly errorCode), and UploadException (invalid chunked-upload state). Programmer errors throw SPL \InvalidArgumentException. Existing catch (\Exception) blocks keep working.

Test plan

• bin/monorepo check storage — pint, PHPStan (level max), rector all pass
• bin/monorepo test storage — 57 unit + 31 e2e tests pass; the e2e suite runs against a real MinIO container and exercises the rewritten per-request SigV4 signing, multipart, retry, and transfer paths end to end
• vale README.md docs — no errors
• bin/monorepo validate — package conventions hold

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR modernizes the storage package for the next major release. The main changes are:

• Removes the static storage registry and mutable device configuration.
• Moves S3 requests to PSR-18 clients with per-request signing state.
• Replaces string constants with typed enums for device types and ACLs.
• Adds typed file listing and shared upload flow abstractions.
• Updates docs, tests, dependency metadata, and static analysis settings.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.
• Non-positive transfer chunk sizes now fail before chunk math or writes.
• The telemetry wrapper passes the value through to the guarded device implementation.

Important Files Changed

Filename	Overview
packages/storage/src/Storage/Device/Local.php	Adds a runtime guard before Local transfer chunk arithmetic.
packages/storage/src/Storage/Device/S3.php	Adds a runtime guard before S3 transfer chunk arithmetic and ranged reads.
packages/storage/src/Storage/Device/Telemetry.php	Forwards the transfer chunk size to the wrapped device.
packages/storage/tests/Storage/Device/LocalTest.php	Adds test coverage for rejecting an invalid Local transfer chunk size.

_{Reviews (13): Last reviewed commit: "feat(storage): typed exception hierarchy..." | Re-trigger Greptile}