mirror of
https://github.com/rustfs/rustfs.git
synced 2026-08-02 19:39:17 +00:00
Zhengchao An
34f1d2c0cd
* docs: state that MinIO-encrypted objects are not readable by RustFS Operators evaluating a MinIO migration had no warning that objects MinIO wrote with SSE-S3, SSE-KMS, or SSE-C cannot be read back. The container formats interoperate, so the limitation is easy to discover only after the data has moved. Document the limitation where a migration decision is actually made: - minio-file-format-compat.md gains Part C, covering which object classes transfer, the three seams that block each SSE mode with file:line evidence, the reverse direction, and the current workarounds. It also records that the `rio-v2` MinIO sealed-key parser does not close the gap: the feature is absent from released artifacts, and the managed-SSE detection gate is not feature-gated and returns before the parser runs. - kms-backend-security.md gains an operator-facing warning next to the backend comparison table, since configuring the static backend with MinIO's key material looks like it should work and does not. - s3-compatibility-matrix.md scopes its SSE row to RustFS's own round-trip. The read path treats an undetected MinIO-encrypted object as unencrypted rather than failing, so all three notes tell operators to verify migrated objects by content instead of by status code. Refs rustfs/backlog#1638. * docs: correct the failure mode for MinIO-encrypted objects The read path does fail closed; the earlier text claimed ciphertext was served as plaintext. MinIO's internal headers mark the object encrypted, so the reader refuses when no material resolves. What is actually wrong is the diagnosis: the refusal surfaces as a 500 InternalError.
Architecture Documentation
Durable architecture reference for RustFS: migration guardrails, runtime contracts, boundary rules, and support matrices.
Two rules keep this directory healthy:
- Durable reference only. One-shot implementation plans, task trackers, and PR templates do not belong in the repository — keep them in the issue tracker or your local worktree. When their work closes, delete them rather than archiving them here.
- No copies of other sources of truth. Crate lists come from
Cargo.toml, CI steps from.github/workflows/ci.yml, code structure from the code.scripts/check_doc_paths.shfails the pre-commit gate when a doc here references a file path that no longer exists.
Start here
- overview.md — migration baseline, phase order, core principles
CI-enforced core (required by scripts/check_architecture_migration_rules.sh)
- crate-boundaries.md — dependency direction, PR types, re-export contracts
- runtime-lifecycle.md — startup/shutdown sequencing, readiness guarantees
- readiness-matrix.md — request/dependency behavior, probe semantics
- storage-control-data-plane.md — storage API contracts, control-plane boundaries
- global-state-crate-split-plan.md — remaining global-state owners and split evaluation
- ecstore-module-split-plan.md — ECStore decomposition rules and facade contracts
Contracts & invariants
- erasure-coding.md — normative erasure-coding algorithm and on-disk (
xl.meta) compatibility contract; the frozen invariants for all user-data read/write, encode/decode, quorum, heal, and decode tolerance - placement-repair-invariants.md
- unified-object-generation.md — single per-object generation authority (fencing epoch, transport/encoding/proto/mixed-version contracts)
- runtime-capability-contracts.md
- workload-admission-contracts.md
- background-controller-contract.md
- config-model-boundary-adr.md
- ecstore-layout-boundary.md
- decommission-compatibility.md
Support matrices (release-facing, keep current)
- s3-compatibility-matrix.md
- s3-tables-support-matrix.md
- minio-rustfs-router-compatibility.md
- minio-file-format-compat.md
Inventories & baselines (snapshots that feed migration work)
- global-state-inventory.md
- ecstore-api-facade-inventory.md
- ecstore-config-consumer-inventory.md
- obs-ecstore-dependency-inventory.md
- background-services-inventory.md
- admin-route-action-snapshot.md
- compat-cleanup-register.md
Historical plans and trackers (rebalance/decommission phases, migration-progress ledger, and the one-shot migration snapshots that fed it — startup timeline, scheduler baseline, profiling/NUMA capability inventory, KMS development defaults inventory) were retired in 2026-07 once the architecture-review ledger they served closed out (backlog#660/#665). Planning documents are no longer kept in the repository.