docs(checksums): cross-reference the three checksum registries (#6024)

crates/checksums/src/http.rs

@@ -21,6 +21,13 @@ use crate::{
     Xxhash3, Xxhash64, Xxhash128,
 };
 
+// DELIBERATE DUPLICATION of the x-amz-checksum-* names that also exist as
+// AMZ_CHECKSUM_* in rustfs-utils' headers module (crates/utils/src/http/
+// headers.rs): this crate is a zero-internal-dependency leaf, so it cannot
+// import them, and it additionally owns the RustFS extension names
+// (sha512/xxhash*) that utils does not carry. Values are pinned by the S3
+// wire protocol; do not merge without a maintainer decision on the leaf
+// boundary (backlog#1833).
 pub const CRC_32_HEADER_NAME: &str = "x-amz-checksum-crc32";
 pub const CRC_32_C_HEADER_NAME: &str = "x-amz-checksum-crc32c";
 pub const SHA_1_HEADER_NAME: &str = "x-amz-checksum-sha1";

crates/checksums/src/lib.rs

@@ -41,6 +41,14 @@ pub const XXHASH_64_NAME: &str = "xxhash64";
 pub const XXHASH_128_NAME: &str = "xxhash128";
 pub const MD5_NAME: &str = "md5";
 
+/// One of three deliberately separate checksum registries (backlog#1833):
+/// this enum owns the **streaming-hash algorithm registry**, including the
+/// RustFS extensions (sha512, xxhash3/64/128). The on-disk xl.meta bitset
+/// lives in `rustfs_rio::ChecksumType` (crates/rio/src/checksum.rs, varint
+/// bits are append-only), and the MinIO-port client keeps its own
+/// `ChecksumMode` (crates/ecstore/src/client/checksum.rs). When adding an
+/// algorithm, extend all three (or record why not) — they do not derive from
+/// each other.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 #[non_exhaustive]
 pub enum ChecksumAlgorithm {

crates/ecstore/src/client/checksum.rs

@@ -27,12 +27,24 @@ use crate::client::utils::base64_decode;
 use crate::client::utils::base64_encode;
 use crate::client::{api_put_object::PutObjectOptions, api_s3_datatypes::ObjectPart};
 use crate::{disk::DiskAPI, object_api::GetObjectReader};
+// s3s::header has no CRC64NVME constant yet; the canonical RustFS copy lives
+// in rustfs-utils' headers module.
+use rustfs_utils::http::headers::AMZ_CHECKSUM_CRC64NVME;
 use s3s::header::{
     X_AMZ_CHECKSUM_ALGORITHM, X_AMZ_CHECKSUM_CRC32, X_AMZ_CHECKSUM_CRC32C, X_AMZ_CHECKSUM_SHA1, X_AMZ_CHECKSUM_SHA256,
 };
 
 use enumset::{EnumSet, EnumSetType, enum_set};
 
+/// One of three deliberately separate checksum registries (backlog#1833):
+/// this enum is the MinIO-port client's wire vocabulary and stops at the
+/// standard S3 set (CRC64NVME is its newest member; the RustFS extensions do
+/// not exist on this client path). The streaming-hash registry lives in
+/// `rustfs_checksums::ChecksumAlgorithm` (crates/checksums/src/lib.rs) and
+/// the on-disk xl.meta bitset in `rustfs_rio::ChecksumType`
+/// (crates/rio/src/checksum.rs, varint bits are append-only). When adding an
+/// algorithm, extend all three (or record why not) — they do not derive from
+/// each other.
 #[derive(Debug, EnumSetType, Default)]
 #[enumset(repr = "u8")]
 pub enum ChecksumMode {
@@ -57,8 +69,6 @@ lazy_static! {
     static ref C_ChecksumFullObjectCRC32C: EnumSet<ChecksumMode> =
         enum_set!(ChecksumMode::ChecksumCRC32C | ChecksumMode::ChecksumFullObject);
 }
-const AMZ_CHECKSUM_CRC64NVME: &str = "x-amz-checksum-crc64nvme";
-
 impl ChecksumMode {
     //pub const CRC64_NVME_POLYNOMIAL: i64 = 0xad93d23594c93659;
 

crates/rio/src/checksum.rs

@@ -30,6 +30,15 @@ pub const RUSTFS_MULTIPART_CHECKSUM: &str = "x-rustfs-multipart-checksum";
 pub const RUSTFS_MULTIPART_CHECKSUM_TYPE: &str = "x-rustfs-multipart-checksum-type";
 
 /// Checksum type enumeration with flags
+///
+/// One of three deliberately separate checksum registries (backlog#1833):
+/// this bitset owns the **on-disk xl.meta encoding** — the raw `u32` is
+/// varint-serialized into xl.meta (see `append_to`), so bits are append-only
+/// and must never be renumbered. `rustfs_checksums::ChecksumAlgorithm`
+/// (crates/checksums/src/lib.rs) owns the streaming-hash algorithm registry,
+/// and the MinIO-port client keeps its own `ChecksumMode`
+/// (crates/ecstore/src/client/checksum.rs). When adding an algorithm, extend
+/// all three (or record why not) — they do not derive from each other.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct ChecksumType(pub u32);
 

crates/utils/src/http/headers.rs

@@ -156,7 +156,11 @@ pub const REQUEST_ID_HEADER: &str = "x-request-id";
 pub const AMZ_REQUEST_ID: &str = "x-amz-request-id";
 pub const AMZ_REQUEST_HOST_ID: &str = "x-amz-id-2";
 
-// Content Checksums
+// Content Checksums. The standard five x-amz-checksum-* names also exist in
+// the zero-internal-dependency rustfs-checksums leaf crate
+// (crates/checksums/src/http.rs, which additionally owns the RustFS
+// extension names); values are pinned by the S3 wire protocol — keep both
+// sides in sync (backlog#1833).
 pub const AMZ_CHECKSUM_ALGO: &str = "x-amz-checksum-algorithm";
 pub const AMZ_CHECKSUM_CRC32: &str = "x-amz-checksum-crc32";
 pub const AMZ_CHECKSUM_CRC32C: &str = "x-amz-checksum-crc32c";