rustfs/crates/e2e_test/src/fake_s3_target/README.md

Programmable fake S3 target

This module is the shared failure-injection boundary for replication end-to-end tests. It runs an in-process, path-style S3 endpoint backed by s3s; no production crate depends on it.

FakeS3Target::start() creates the listener. Add target buckets with create_bucket, point a RustFS remote target at address(), use FAKE_ACCESS_KEY / FAKE_SECRET_KEY, then enqueue per-operation faults with inject. Faults for one operation are consumed in FIFO order and do not consume faults queued for another operation. A fault is consumed only after s3s verifies the full request signature, so anonymous, other-access-key, and bad-signature traffic cannot disturb a script.

Supported data operations are HeadBucket, GetBucketVersioning, PUT/GET/HEAD/DELETE Object, Get/Put/Delete ObjectTagging (tags live per version; Put replaces the whole set, Delete clears it), and create/upload/complete/abort multipart upload. create_bucket models general-purpose buckets in S3's shared global namespace; account-regional namespace buckets and their -an names are intentionally out of scope. Buckets are versioned: PUT creates a version, DELETE without versionId creates a delete marker, and DELETE with versionId removes exactly that version. Internal source version IDs must be UUIDs and are stored canonically. Source mtime is honored only for source-replication PUT/DELETE requests; absent or invalid values use receipt time, matching RustFS, while multipart completion always uses receipt time. Replicated versions are ordered newest-first by source mtime so late older versions and delete markers do not become current. Equal mtimes prefer objects over delete markers, then canonical UUID order; RustFS's internal FileMeta signature tie-break is intentionally out of scope because it is not part of the target S3 protocol. Multipart part numbers follow S3's 1..=10000 range, and every completed part except the final part must be at least 5 MiB.

Fault actions cover HTTP 401/403/503 responses, pre-dispatch delay, connection abort when a logical request-body threshold is reached, streaming slow drain, and a deliberately wrong response ETag (including multipart-complete XML). requests() returns the ordered, credential-free request journal for assertions. Each record also journals a ProxyHeaderSnapshot — the read-proxy anti-loop marker (x-{rustfs,minio}-source-proxy-request), the replication-check exemption header, and the client SSE-C header family (algorithm and key-MD5 values; for the key itself only its presence) — so proxy tests can pin the exact wire contract.

The listener is loopback-only. It admits at most 64 active connections and two concurrently buffered request bodies; authenticated multipart-complete XML collection and assembly take both body permits. Keep-alive is disabled, request-header reads are bounded to 30 seconds, a parsed request is bounded to 65 seconds, and the complete connection lifetime is bounded to 100 seconds. It retains at most 256 buckets, 4,096 journal entries, 4,096 scripted faults, 4,096 object versions, 256 multipart uploads, and 10,000 multipart parts. Retained identifiers are capped at 1 KiB, user metadata at 2 KiB, and content type at 1 KiB. A PUT or uploaded part is capped at 64 MiB; a completed multipart object and all stored object/part data are capped at 128 MiB. Body drain, body-permit waits, delay, and slow-drain execution are bounded to 30 seconds; each slow-drain slice delay must be below that bound.