storage 4.0: streams-only I/O, one-word upload verbs, copy replaces transfer

[loks0n]

Summary

Implements the agreed direction for CLO-4257: streaming is the only I/O path — no parallel string/stream API families. File contents move as PSR-7 streams end to end, so PHP memory stays bounded regardless of file size (the primary driver of the worker OOM incidents).

API (breaking — next release is storage/4.0.0)

• read() returns StreamInterface. Getting bytes into memory is now explicit ((string) / getContents()) at the call site.
• write() and uploads take StreamInterface. Strings wrap for free (new Stream($data)); file handles wrap without buffering (Stream::fromResource($handle)).
• uploadData() + uploadChunk() collapse into one public upload() (whole file = single-chunk default); prepareUpload()/finalizeUpload() become prepare()/finalize(). Public chunked-upload surface is four one-word verbs: prepare / upload / finalize / abort. The per-chunk write is a protected hook, mirroring how the S3 wire verbs are already non-public.
• transfer() is replaced by copy($source, $target, ?Device $to = null, $chunkSize) — one concrete base implementation (the two near-identical per-device copies are deleted), with the multipart abort-on-failure logic hoisted along with it. move() = copy() + delete() on every adapter; Local keeps its same-device rename() override, and a future S3 server-side CopyObject (CLO-4268) slots in as a copy() override with no caller changes.
• TRANSFER_CHUNK_SIZE → COPY_CHUNK_SIZE.

Transport

• S3 downloads stream through StreamingClientInterface::stream() into a temporary stream (php://temp, spills to disk past 2 MB). A capped 16 KB head buffer keeps error XML parseable without buffering success bodies.
• S3 uploads hash the stream for SigV4 (incremental MD5+SHA-256, rewind, send) — validated against the AWS SDK's approach (SignatureV4::getPayload requires seekable and hashes with position restore; UNSIGNED-PAYLOAD is not their default either). Seekable streams are required; the curl adapter already streams request bodies via CURLOPT_UPLOAD/CURLOPT_READFUNCTION.
• Known tradeoff: streamed GETs don't retry after bytes reach the sink (the Retry decorator correctly refuses to duplicate delivered bytes).

Docs

README examples updated and an "Upgrading from 3.x" section added mapping every removed API to its replacement.

Test plan

• Full suite green: 75 unit + 26 e2e against MinIO — e2e now exercises real streamed uploads (including multipart and out-of-order parts), ranged streamed reads, and cross-device copy over the wire.
• PHPStan level max clean, Pint clean, Vale clean, bin/monorepo validate passes.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR moves storage operations to stream-only I/O and updates the public API for storage 4.0. The main changes are:

• PSR-7 streams for reads, writes, and uploads.
• Unified multipart upload verbs.
• Shared copy and move behavior across adapters.
• Streamed S3 downloads, signed uploads, and server-side copies.
• Updated tests and migration documentation.

Confidence Score: 5/5

The latest fixes look safe to merge.

• Zero-length S3 reads now return an empty stream without an invalid request.
• Local writes and S3 download buffering now handle partial writes.
• Seekable streams are rewound consistently before upload.

Important Files Changed

Filename	Overview
packages/storage/src/Storage/Device.php	Defines the stream-only API and shared copy and move behavior.
packages/storage/src/Storage/Device/Local.php	Adds streamed reads and writes, seekable-stream rewinding, and checked partial-write handling.
packages/storage/src/Storage/Device/S3.php	Adds streamed downloads, stream hashing, zero-length range handling, and server-side copy support.
packages/storage/src/Storage/Device/Telemetry.php	Updates telemetry delegation for the renamed stream-based API.

_{Reviews (4): Last reviewed commit: "Address review: full-write loops, zero-l..." | Re-trigger Greptile}