From ee54f1e61824a2c00b0ba0dd55f3bc7a2de474a7 Mon Sep 17 00:00:00 2001 From: Zhengchao An Date: Thu, 13 Aug 2026 08:06:00 +0800 Subject: [PATCH] docs(checksums): cross-reference the three checksum registries (#6024) --- crates/checksums/src/http.rs | 7 +++++++ crates/checksums/src/lib.rs | 8 ++++++++ crates/ecstore/src/client/checksum.rs | 14 ++++++++++++-- crates/rio/src/checksum.rs | 9 +++++++++ crates/utils/src/http/headers.rs | 6 +++++- 5 files changed, 41 insertions(+), 3 deletions(-) diff --git a/crates/checksums/src/http.rs b/crates/checksums/src/http.rs index e54340530..1a369a42d 100644 --- a/crates/checksums/src/http.rs +++ b/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"; diff --git a/crates/checksums/src/lib.rs b/crates/checksums/src/lib.rs index 2c97a82e7..a8da44545 100644 --- a/crates/checksums/src/lib.rs +++ b/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 { diff --git a/crates/ecstore/src/client/checksum.rs b/crates/ecstore/src/client/checksum.rs index 4d845fd66..09f438822 100644 --- a/crates/ecstore/src/client/checksum.rs +++ b/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 = enum_set!(ChecksumMode::ChecksumCRC32C | ChecksumMode::ChecksumFullObject); } -const AMZ_CHECKSUM_CRC64NVME: &str = "x-amz-checksum-crc64nvme"; - impl ChecksumMode { //pub const CRC64_NVME_POLYNOMIAL: i64 = 0xad93d23594c93659; diff --git a/crates/rio/src/checksum.rs b/crates/rio/src/checksum.rs index dee358b0b..cd50db57b 100644 --- a/crates/rio/src/checksum.rs +++ b/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); diff --git a/crates/utils/src/http/headers.rs b/crates/utils/src/http/headers.rs index a881692ac..b983218c0 100644 --- a/crates/utils/src/http/headers.rs +++ b/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";