From a71dae20af14923fc1c4c2b8b25d8985c820fbbd Mon Sep 17 00:00:00 2001 From: patrickZWY <154947644+patrickZWY@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:16:08 -0800 Subject: [PATCH 1/4] feat: add exact decoded length and validation APIs Co-authored-by: Codex --- CHANGELOG.md | 1 + bases/README.md | 10 +- bases/src/backend/base16.rs | 44 ++- bases/src/backend/base32.rs | 65 ++- bases/src/backend/base64.rs | 71 +++- bases/src/backend/base64/arch/mod.rs | 21 + bases/src/backend/base64/arch/x86.rs | 371 +++++++++++++++++- bases/src/backend/mod.rs | 34 ++ bases/src/base16.rs | 35 ++ bases/src/base32.rs | 54 +++ bases/src/base64.rs | 35 ++ bases/src/codec.rs | 67 ++++ bases/src/lib.rs | 11 +- tests-integration/tests/contracts.rs | 13 +- tests-integration/tests/contracts/buffers.rs | 9 +- tests-integration/tests/contracts/lengths.rs | 43 ++ .../tests/contracts/malformed.rs | 74 +++- 17 files changed, 893 insertions(+), 65 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c1adcc..9b2665f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All significant changes to this project will be documented in this file. ### Features +* Add `decoded_len` for exact buffer sizing and `check` for validation without decoded output to all profiles and the `Codec` trait. `decoded_len` checks length and trailing padding shape without fully validating the input; `check` preserves decoding errors and byte offsets. * Add `policy::PaddedOptional` and `policy::UnpaddedOptional` for Base32 and Base64. Both accept complete padding or none when decoding and emit padded and unpadded output, respectively. * Add `encode_into_uninit` and `decode_into_uninit` to all profiles and the `Codec` trait. They write into caller-provided `MaybeUninit` storage and return the initialized prefix. diff --git a/bases/README.md b/bases/README.md index 6fb14b0..49eabb5 100644 --- a/bases/README.md +++ b/bases/README.md @@ -52,7 +52,7 @@ For example, use `base64::Base64` fo ## API layers and features -- **Caller buffers (`no_std`):** `encoded_len`, `max_decoded_len`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` operate without allocation. Concrete profiles provide `const fn` constructors and sizing methods. +- **Sizing, validation, and caller buffers (`no_std`):** `encoded_len`, `max_decoded_len`, `decoded_len`, `check`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` operate without allocation. Concrete profiles provide `const fn` constructors, `encoded_len`, and `max_decoded_len`. - **Owned output (`alloc`):** `encode` and `decode` return `String` and `Vec`; `encode_append` and transactional `decode_append` extend existing buffers. - **Streaming (`no_std` / `std`):** `Encoder` and `Decoder` process arbitrarily chunked input while retaining at most one partial quantum. The `std` feature adds `io::EncoderWriter` and `io::DecoderReader` for `std::io::Write` and `std::io::Read`. - **Formatting (`no_std`):** `display` (`EncodedDisplay`) and `HexDisplay` (`{:x}` and `{:X}` only) write encoded text through `core::fmt` without an intermediate string. @@ -65,6 +65,14 @@ For example, use `base64::Base64` fo | `std` | Enables `alloc`, I/O adapters, and runtime x86/x86_64 CPU feature detection. | | `serde` | Adds `serde_core` serialization and fixed-array deserialization, including without an allocator. | +## Decoding buffer sizes and validation + +Use `max_decoded_len(input.len())` for an upper bound based only on the encoded length, or `decoded_len(input)` to inspect the input's length and trailing padding shape for exact sizing. For example, `Base64::max_decoded_len(4)` returns `3`, while `Base64::decoded_len("Zg==")` returns `Ok(1)`. + +A successful `decoded_len` result guarantees the exact length only if decoding succeeds. It does not fully validate the input: invalid alphabet symbols, misplaced padding, and non-zero unused bits can go undetected. Decoding still performs full validation. + +Use `check(input)` when only validation is needed, for example before storing or forwarding an encoded field. It applies the selected profile's complete decoding rules without allocating or writing decoded bytes, and returns the same errors and byte offsets as decoding with sufficient output capacity. `Base64::check("Zg==")` succeeds, while `Base64::check("Zh==")` reports `DecodeError::NonCanonical { index: 1 }`. Calling `check` immediately before decoding normally duplicates validation work. + ## Uninitialized output buffers Use `encode_into_uninit` or `decode_into_uninit` when the destination is an uninitialized stack buffer or a vector's spare capacity. Use the returned slice to access the result. For padded Base64, it can be shorter than the decoding size estimate. diff --git a/bases/src/backend/base16.rs b/bases/src/backend/base16.rs index b6e56a3..e2eafba 100644 --- a/bases/src/backend/base16.rs +++ b/bases/src/backend/base16.rs @@ -89,6 +89,27 @@ pub fn decode_plan(input: &[u8]) -> Result { }) } +/// Checks alphabet symbols after input length has been validated. +#[inline] +pub fn check_with_plan( + input: &[u8], + plan: DecodePlan, +) -> Result<(), DecodeError> { + debug_assert_eq!(plan.data_len, input.len()); + let lut = select_decode_lut::(); + if input.len() < 32 { + for (index, &byte) in input.iter().enumerate() { + decode_value(byte, index, lut)?; + } + } else if let Some(index) = backend::find_invalid(input, lut) { + return Err(DecodeError::InvalidByte { + index, + byte: input[index], + }); + } + Ok(()) +} + /// Encodes `input` into `output` using Base16, returning the number of bytes written. #[inline(always)] pub fn encode(input: &[u8], output: &mut [MaybeUninit]) -> usize { @@ -206,20 +227,21 @@ fn decode_chunk_8(lut: &[u8; 256], chunk: &[u8; 8]) -> Option<[u8; 4]> { #[inline] fn decode_pair(lut: &[u8; 256], b0: u8, b1: u8, index: usize) -> Result { - let d0 = lut[usize::from(b0)]; - if d0 & 0xf0 != 0 { - return Err(DecodeError::InvalidByte { index, byte: b0 }); - } - let d1 = lut[usize::from(b1)]; - if d1 & 0xf0 != 0 { - return Err(DecodeError::InvalidByte { - index: index + 1, - byte: b1, - }); - } + let d0 = decode_value(b0, index, lut)?; + let d1 = decode_value(b1, index + 1, lut)?; Ok((d0 << 4) | d1) } +#[inline] +fn decode_value(byte: u8, index: usize, lut: &[u8; 256]) -> Result { + let value = lut[usize::from(byte)]; + if value & 0xf0 == 0 { + Ok(value) + } else { + Err(DecodeError::InvalidByte { index, byte }) + } +} + #[inline] fn decode_scalar_from( input: &[u8], diff --git a/bases/src/backend/base32.rs b/bases/src/backend/base32.rs index a879329..2c97dec 100644 --- a/bases/src/backend/base32.rs +++ b/bases/src/backend/base32.rs @@ -210,6 +210,31 @@ pub fn decode_plan(input: &[u8]) -> Result( + input: &[u8], + plan: DecodePlan, +) -> Result<(), DecodeError> { + let lut = select_decode_lut::(); + let last = if plan.data_len < 32 { + let mut last = 0; + for (index, &byte) in input[..plan.data_len].iter().enumerate() { + last = decode_value(byte, index, lut)?; + } + last + } else { + if let Some(index) = backend::find_invalid(&input[..plan.data_len], lut) { + return Err(backend::invalid_byte_error(input[index], index)); + } + lut[usize::from(input[plan.data_len - 1])] + }; + if plan.complete_len != plan.data_len { + check_tail_bits(last, plan.data_len - plan.complete_len, plan.data_len - 1)?; + } + Ok(()) +} + /// Encodes `input` into `output` using Base32, returning the number of bytes written. #[inline] pub fn encode( @@ -606,11 +631,7 @@ fn decode_tail { let v0 = decode_value(*b0, base_index, lut)?; let v1 = decode_value(*b1, base_index + 1, lut)?; - if v1 & 0x03 != 0 { - return Err(DecodeError::NonCanonical { - index: base_index + 1, - }); - } + check_tail_bits(v1, trailing.len(), base_index + 1)?; output[0].write((v0 << 3) | (v1 >> 2)); Ok(1) } @@ -619,11 +640,7 @@ fn decode_tail> 2)); output[1].write((v1 << 6) | (v2 << 1) | (v3 >> 4)); Ok(2) @@ -634,11 +651,7 @@ fn decode_tail> 2)); output[1].write((v1 << 6) | (v2 << 1) | (v3 >> 4)); output[2].write((v3 << 4) | (v4 >> 1)); @@ -652,11 +665,7 @@ fn decode_tail> 2)); output[1].write((v1 << 6) | (v2 << 1) | (v3 >> 4)); output[2].write((v3 << 4) | (v4 >> 1)); @@ -667,6 +676,22 @@ fn decode_tail Result<(), DecodeError> { + let mask = match tail_len { + 2 => 0x03, + 4 => 0x0f, + 5 => 0x01, + 7 => 0x07, + _ => unreachable!("decode plan guarantees a valid tail length"), + }; + if value & mask == 0 { + Ok(()) + } else { + Err(DecodeError::NonCanonical { index }) + } +} + fn find_invalid_in_quantum(quantum: &[u8], base_index: usize, lut: &[u8; 256]) -> DecodeError { for (offset, &byte) in quantum.iter().enumerate() { if lut[usize::from(byte)] & 0xe0 != 0 { diff --git a/bases/src/backend/base64.rs b/bases/src/backend/base64.rs index 55ddbfe..bbcd236 100644 --- a/bases/src/backend/base64.rs +++ b/bases/src/backend/base64.rs @@ -28,6 +28,7 @@ const STANDARD: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwx const URL_SAFE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"; const INVALID_SYMBOL: u8 = 0xff; +const CHECK_SIMD_MIN: usize = 16; const STD_DECODE_LUTS: [[i32; 256]; 4] = make_decode_luts(false); const URL_DECODE_LUTS: [[i32; 256]; 4] = make_decode_luts(true); const STD_DECODE_BYTE_LUT: [u8; 256] = make_decode_byte_lut(false); @@ -149,6 +150,50 @@ pub fn decode_plan(input: &[u8]) -> Result( + input: &[u8], + plan: DecodePlan, +) -> Result<(), DecodeError> { + let lut = if URL_SAFE_ALPHABET { + &URL_DECODE_BYTE_LUT + } else { + &STD_DECODE_BYTE_LUT + }; + if plan.complete_len < CHECK_SIMD_MIN { + let mut last = 0; + for (index, &byte) in input[..plan.data_len].iter().enumerate() { + last = decode_value(byte, index, lut)?; + } + if plan.complete_len != plan.data_len { + check_tail_bits(last, plan.data_len - plan.complete_len, plan.data_len - 1)?; + } + return Ok(()); + } + decode_value(input[0], 0, lut)?; + let checked = arch::check::(&input[..plan.complete_len]) + .map_err(|index| backend::invalid_byte_error(input[index], index))?; + let remaining = &input[checked..plan.data_len]; + let last = if remaining.len() < 32 { + let mut last = 0; + for (index, &byte) in remaining.iter().enumerate() { + last = decode_value(byte, checked + index, lut)?; + } + last + } else { + if let Some(index) = backend::find_invalid(remaining, lut) { + let index = checked + index; + return Err(backend::invalid_byte_error(input[index], index)); + } + lut[usize::from(input[plan.data_len - 1])] + }; + if plan.complete_len != plan.data_len { + check_tail_bits(last, plan.data_len - plan.complete_len, plan.data_len - 1)?; + } + Ok(()) +} + /// Encodes `input` into `output` using Base64, returning the number of bytes written. #[inline] pub fn encode( @@ -611,11 +656,7 @@ fn decode_tail( [first, second] => { let v0 = decode_value(*first, base_index, lut)?; let v1 = decode_value(*second, base_index + 1, lut)?; - if v1 & 0x0f != 0 { - return Err(DecodeError::NonCanonical { - index: base_index + 1, - }); - } + check_tail_bits(v1, trailing.len(), base_index + 1)?; output[0].write((v0 << 2) | (v1 >> 4)); Ok(1) } @@ -623,11 +664,7 @@ fn decode_tail( let v0 = decode_value(*first, base_index, lut)?; let v1 = decode_value(*second, base_index + 1, lut)?; let v2 = decode_value(*third, base_index + 2, lut)?; - if v2 & 0x03 != 0 { - return Err(DecodeError::NonCanonical { - index: base_index + 2, - }); - } + check_tail_bits(v2, trailing.len(), base_index + 2)?; output[0].write((v0 << 2) | (v1 >> 4)); output[1].write((v1 << 4) | (v2 >> 2)); Ok(2) @@ -636,6 +673,20 @@ fn decode_tail( } } +#[inline] +fn check_tail_bits(value: u8, tail_len: usize, index: usize) -> Result<(), DecodeError> { + let mask = match tail_len { + 2 => 0x0f, + 3 => 0x03, + _ => unreachable!("decode plan guarantees a valid tail length"), + }; + if value & mask == 0 { + Ok(()) + } else { + Err(DecodeError::NonCanonical { index }) + } +} + #[inline] fn find_invalid_in_slice(slice: &[u8], base_index: usize, lut: &[u8; 256]) -> DecodeError { for (offset, &byte) in slice.iter().enumerate() { diff --git a/bases/src/backend/base64/arch/mod.rs b/bases/src/backend/base64/arch/mod.rs index a863f62..0b2298a 100644 --- a/bases/src/backend/base64/arch/mod.rs +++ b/bases/src/backend/base64/arch/mod.rs @@ -26,6 +26,27 @@ mod wasm32; ))] mod x86; +/// Checks a SIMD prefix, returning its length or the first invalid byte offset. +#[inline] +pub fn check(input: &[u8]) -> Result { + if cfg!(miri) { + return Ok(0); + } + + #[cfg(all( + any(target_arch = "x86", target_arch = "x86_64"), + any(feature = "std", target_feature = "avx2", target_feature = "ssse3") + ))] + { + return x86::check::(input); + } + + #[allow(unreachable_code)] + let _ = input; + #[allow(unreachable_code)] + Ok(0) +} + #[inline] pub fn encode( input: &[u8], diff --git a/bases/src/backend/base64/arch/x86.rs b/bases/src/backend/base64/arch/x86.rs index 30895b1..20546ed 100644 --- a/bases/src/backend/base64/arch/x86.rs +++ b/bases/src/backend/base64/arch/x86.rs @@ -68,6 +68,8 @@ use x86_arch::_mm256_madd_epi16; #[cfg(any(feature = "std", target_feature = "avx2"))] use x86_arch::_mm256_maddubs_epi16; #[cfg(any(feature = "std", target_feature = "avx2"))] +use x86_arch::_mm256_min_epu8; +#[cfg(any(feature = "std", target_feature = "avx2"))] use x86_arch::_mm256_movemask_epi8; #[cfg(any(feature = "std", target_feature = "avx2"))] use x86_arch::_mm256_mulhi_epu16; @@ -108,6 +110,45 @@ const LO_MASK_URL: [i8; 16] = [ const ROLL_STD: [i8; 16] = [0, 0, 19, 4, -65, -65, -71, -71, 0, 0, 0, 0, 0, 0, 0, 0]; const ROLL_URL: [i8; 16] = [0, 0, 17, 4, -65, -65, -71, -71, 0, 0, 0, 0, 0, 0, 0, 0]; +#[cfg(any(feature = "std", target_feature = "avx2"))] +const CHECK_AVX2_BATCH_LEN: usize = 256; + +#[inline] +pub fn check(input: &[u8]) -> Result { + if input.len() < 16 { + return Ok(0); + } + + #[cfg(target_feature = "avx2")] + { + // SAFETY: AVX2 is enabled at compile time; the kernels bound every load by `input`. + unsafe { check_avx2::(input) } + } + + #[cfg(all(not(target_feature = "avx2"), feature = "std"))] + { + if is_x86_feature_detected!("avx2") { + // SAFETY: Runtime detection confirmed AVX2; all loads are bounded by `input`. + unsafe { check_avx2::(input) } + } else if is_x86_feature_detected!("ssse3") { + // SAFETY: Runtime detection confirmed SSSE3; all loads are bounded by `input`. + unsafe { check_ssse3::(input) } + } else { + Ok(0) + } + } + + #[cfg(all( + not(target_feature = "avx2"), + not(feature = "std"), + target_feature = "ssse3" + ))] + { + // SAFETY: SSSE3 is enabled at compile time; every load is bounded by `input`. + unsafe { check_ssse3::(input) } + } +} + #[inline] pub fn encode( input: &[u8], @@ -475,6 +516,49 @@ unsafe fn decode_128_tables() ) } +/// # Safety +/// +/// Requires SSSE3 support on the current CPU. +#[inline] +#[target_feature(enable = "ssse3")] +unsafe fn classify_16( + v: __m128i, + hi_mask: __m128i, + lo_mask: __m128i, + mask_0f: __m128i, + zero: __m128i, +) -> (__m128i, u32) { + let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); + // PSHUFB selects the low nibble for ASCII and yields zero for any high-bit byte. + let chk = _mm_and_si128(_mm_shuffle_epi8(hi_mask, hi), _mm_shuffle_epi8(lo_mask, v)); + let invalid = _mm_movemask_epi8(_mm_cmpeq_epi8(chk, zero)) as u32; + (hi, invalid) +} + +/// # Safety +/// +/// Requires SSSE3 support on the current CPU. +#[cfg(not(target_feature = "avx2"))] +#[target_feature(enable = "ssse3")] +unsafe fn check_ssse3(input: &[u8]) -> Result { + let mut checked = 0; + // SAFETY: SSSE3 is enabled by the caller and every chunk contains 16 readable bytes. + unsafe { + let (hi_mask, lo_mask, _, _, _, _) = decode_128_tables::(); + let mask_0f = _mm_set1_epi8(0x0f); + let zero = _mm_setzero_si128(); + for chunk in input.as_chunks::<16>().0 { + let v = _mm_loadu_si128(chunk.as_ptr().cast()); + let (_, invalid) = classify_16(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(checked + invalid.trailing_zeros() as usize); + } + checked += 16; + } + } + Ok(checked) +} + /// # Safety /// /// Caller must ensure `in_ptr` is valid for 16 reads and SSSE3 is enabled. @@ -497,10 +581,8 @@ unsafe fn decode_chunk_16( // SAFETY: Caller guarantees `in_ptr` is valid for 16 readable bytes and SSSE3 is enabled. unsafe { let v = _mm_loadu_si128(in_ptr.cast()); - let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); - let lo = _mm_and_si128(v, mask_0f); - let chk = _mm_and_si128(_mm_shuffle_epi8(hi_mask, hi), _mm_shuffle_epi8(lo_mask, lo)); - if _mm_movemask_epi8(_mm_cmpeq_epi8(chk, zero)) != 0 { + let (hi, invalid) = classify_16(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { return None; } @@ -605,6 +687,188 @@ unsafe fn decode_ssse3( (done, false) } +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[inline] +#[target_feature(enable = "avx2")] +unsafe fn classify_32_bytes( + v: __m256i, + hi_mask: __m256i, + lo_mask: __m256i, + mask_0f: __m256i, +) -> (__m256i, __m256i) { + let hi = _mm256_and_si256(_mm256_srli_epi16(v, 4), mask_0f); + // PSHUFB selects the low nibble for ASCII and yields zero for any high-bit byte. + let chk = _mm256_and_si256( + _mm256_shuffle_epi8(hi_mask, hi), + _mm256_shuffle_epi8(lo_mask, v), + ); + (hi, chk) +} + +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[inline] +#[target_feature(enable = "avx2")] +unsafe fn classify_32( + v: __m256i, + hi_mask: __m256i, + lo_mask: __m256i, + mask_0f: __m256i, + zero: __m256i, +) -> (__m256i, u32) { + // SAFETY: AVX2 is enabled by this function's target features. + let (hi, chk) = unsafe { classify_32_bytes(v, hi_mask, lo_mask, mask_0f) }; + let invalid = _mm256_movemask_epi8(_mm256_cmpeq_epi8(chk, zero)) as u32; + (hi, invalid) +} + +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[inline] +unsafe fn check_avx2(input: &[u8]) -> Result { + // SAFETY: The caller guarantees AVX2 support; both kernels bound every load by `input`. + unsafe { + if input.len() < 32 { + match input.first_chunk::<16>() { + Some(first) => check_avx2_16::(first), + None => Ok(0), + } + } else if input.len() >= CHECK_AVX2_BATCH_LEN { + check_avx2_bulk::(input) + } else { + check_avx2_short::(input) + } + } +} + +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[target_feature(enable = "avx2")] +#[inline(never)] +unsafe fn check_avx2_bulk(input: &[u8]) -> Result { + // SAFETY: AVX2 is enabled by the caller; slice chunks and guarded tails bound every load. + unsafe { + let (hi_128, lo_128, _, _, _, _) = decode_128_tables::(); + let hi_mask = _mm256_set_m128i(hi_128, hi_128); + let lo_mask = _mm256_set_m128i(lo_128, lo_128); + let mask_0f = _mm256_set1_epi8(0x0f); + let zero = _mm256_setzero_si256(); + // Check leading vectors before advancing to an aligned, possibly overlapping prefix. + for (index, block) in input[..64].as_chunks::<32>().0.iter().enumerate() { + let v = _mm256_loadu_si256(block.as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(index * 32 + invalid.trailing_zeros() as usize); + } + } + let mut checked = 32 + input.as_ptr().align_offset(32); + if checked == 32 { + checked = 64; + } + for chunk in input[checked..].as_chunks::().0 { + // Valid classifications are nonzero; unsigned min preserves a zero from any block. + let mut aggregate = _mm256_set1_epi8(-1); + for block in chunk.as_chunks::<32>().0 { + let v = _mm256_loadu_si256(block.as_ptr().cast()); + let (_, chk) = classify_32_bytes(v, hi_mask, lo_mask, mask_0f); + aggregate = _mm256_min_epu8(aggregate, chk); + } + if _mm256_movemask_epi8(_mm256_cmpeq_epi8(aggregate, zero)) != 0 { + // Revisit a failing batch in order to preserve the exact first error offset. + for (index, block) in chunk.as_chunks::<32>().0.iter().enumerate() { + let v = _mm256_loadu_si256(block.as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(checked + index * 32 + invalid.trailing_zeros() as usize); + } + } + } + checked += CHECK_AVX2_BATCH_LEN; + } + for chunk in input[checked..].as_chunks::<32>().0 { + let v = _mm256_loadu_si256(chunk.as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(checked + invalid.trailing_zeros() as usize); + } + checked += 32; + } + if checked != input.len() { + // The prefix is valid, so an overlapping final vector cannot hide an earlier error. + let start = input.len() - 32; + let v = _mm256_loadu_si256(input[start..].as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(start + invalid.trailing_zeros() as usize); + } + } + } + Ok(input.len()) +} + +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[target_feature(enable = "avx2")] +unsafe fn check_avx2_short(input: &[u8]) -> Result { + let mut checked = 0; + // SAFETY: AVX2 is enabled by the caller; full chunks and the guarded tail bound every load. + unsafe { + let (hi_128, lo_128, _, _, _, _) = decode_128_tables::(); + let hi_mask = _mm256_set_m128i(hi_128, hi_128); + let lo_mask = _mm256_set_m128i(lo_128, lo_128); + let mask_0f = _mm256_set1_epi8(0x0f); + let zero = _mm256_setzero_si256(); + for chunk in input.as_chunks::<32>().0 { + let v = _mm256_loadu_si256(chunk.as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(checked + invalid.trailing_zeros() as usize); + } + checked += 32; + } + if input.len() >= 32 && checked != input.len() { + let start = input.len() - 32; + let v = _mm256_loadu_si256(input[start..].as_ptr().cast()); + let (_, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { + return Err(start + invalid.trailing_zeros() as usize); + } + return Ok(input.len()); + } + } + Ok(checked) +} + +/// # Safety +/// +/// Requires AVX2 support on the current CPU. +#[cfg(any(feature = "std", target_feature = "avx2"))] +#[target_feature(enable = "avx2")] +unsafe fn check_avx2_16(input: &[u8; 16]) -> Result { + // SAFETY: AVX2 is enabled and the array contains sixteen readable bytes. + unsafe { + let (hi, lo, _, _, _, _) = decode_128_tables::(); + let v = _mm_loadu_si128(input.as_ptr().cast()); + let (_, invalid) = classify_16(v, hi, lo, _mm_set1_epi8(0x0f), _mm_setzero_si128()); + if invalid != 0 { + Err(invalid.trailing_zeros() as usize) + } else { + Ok(16) + } + } +} + /// # Safety /// /// Caller must ensure `in_ptr` is valid for 32 reads and AVX2 is enabled. Returns un-permuted @@ -629,13 +893,8 @@ unsafe fn decode_chunk_32( // SAFETY: Caller guarantees `in_ptr` is valid for 32 readable bytes and AVX2 is enabled. unsafe { let v = _mm256_loadu_si256(in_ptr.cast()); - let hi = _mm256_and_si256(_mm256_srli_epi16(v, 4), mask_0f); - let lo = _mm256_and_si256(v, mask_0f); - let chk = _mm256_and_si256( - _mm256_shuffle_epi8(hi_mask, hi), - _mm256_shuffle_epi8(lo_mask, lo), - ); - if _mm256_movemask_epi8(_mm256_cmpeq_epi8(chk, zero)) != 0 { + let (hi, invalid) = classify_32(v, hi_mask, lo_mask, mask_0f, zero); + if invalid != 0 { return None; } @@ -784,3 +1043,93 @@ unsafe fn decode_avx2( (done_16, had_invalid) } } + +#[cfg(all(test, feature = "std", not(miri)))] +mod tests { + use core::array; + use std::arch::is_x86_feature_detected; + use std::vec; + + use super::*; + + fn check_all_bytes( + check: impl Fn(&[u8]) -> Result, + ) { + let alphabet: &[u8] = if URL_SAFE_ALPHABET { + b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_" + } else { + b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" + }; + let all_bytes: [u8; 256] = array::from_fn(|byte| byte as u8); + for len in [ + 0, 1, 15, 16, 17, 31, 32, 33, 47, 48, 49, 63, 64, 65, 95, 96, 97, 127, 128, 129, 159, + 160, 161, 255, 256, 257, 511, 512, 513, 543, 544, 545, 1055, 1056, 1057, + ] { + // Exhaust every byte value in every lane; longer cases exercise each bulk position. + let bytes: &[u8] = if len <= 65 { + &all_bytes + } else { + b"Aaz09+/-_=!\0\x7f\x80\xff" + }; + for offset in [0, 1, 7, 15, 16, 31] { + let mut storage = vec![0xff; offset + len + 16]; + let input = &mut storage[offset..offset + len]; + input.fill(b'A'); + let processed = check(input).unwrap(); + assert!(processed <= len && len - processed < 16); + for index in 0..len { + for &byte in bytes { + input[index] = byte; + let expected = if index < processed && !alphabet.contains(&byte) { + Err(index) + } else { + Ok(processed) + }; + assert_eq!( + check(input), + expected, + "length {len}, offset {offset}, index {index}, byte {byte}" + ); + } + input[index] = b'A'; + } + if processed != 0 { + input[processed / 2] = b'!'; + input[processed - 1] = 0xff; + assert_eq!(check(input), Err(processed / 2)); + } + } + } + } + + #[cfg(not(target_feature = "avx2"))] + #[test] + fn ssse3_validation_finds_first_invalid_byte() { + if !is_x86_feature_detected!("ssse3") { + return; + } + check_all_bytes::(|input| { + // SAFETY: Runtime feature detection above confirmed SSSE3 support. + unsafe { check_ssse3::(input) } + }); + check_all_bytes::(|input| { + // SAFETY: Runtime feature detection above confirmed SSSE3 support. + unsafe { check_ssse3::(input) } + }); + } + + #[test] + fn avx2_validation_finds_first_invalid_byte() { + if !is_x86_feature_detected!("avx2") { + return; + } + check_all_bytes::(|input| { + // SAFETY: Runtime feature detection above confirmed AVX2 support. + unsafe { check_avx2::(input) } + }); + check_all_bytes::(|input| { + // SAFETY: Runtime feature detection above confirmed AVX2 support. + unsafe { check_avx2::(input) } + }); + } +} diff --git a/bases/src/backend/mod.rs b/bases/src/backend/mod.rs index 1b46569..e6e4416 100644 --- a/bases/src/backend/mod.rs +++ b/bases/src/backend/mod.rs @@ -26,6 +26,8 @@ use core::mem::MaybeUninit; use crate::DecodeError; +const CHECK_CHUNK_LEN: usize = 8; + #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub struct DecodePlan { pub required: usize, @@ -48,6 +50,38 @@ pub fn invalid_byte_error(byte: u8, index: usize) -> DecodeError { } } +/// Finds the first invalid symbol using a table with the high bit set only for invalid entries. +#[inline] +pub fn find_invalid(input: &[u8], lut: &[u8; 256]) -> Option { + if input + .first() + .is_some_and(|&byte| lut[usize::from(byte)] & 0x80 != 0) + { + return Some(0); + } + find_invalid_blocks(input, lut) +} + +// Keep block scanning out of line so early errors avoid its register pressure. +#[inline(never)] +fn find_invalid_blocks(input: &[u8], lut: &[u8; 256]) -> Option { + let (chunks, tail) = input.as_chunks::(); + for (chunk_index, chunk) in chunks.iter().enumerate() { + let values = chunk + .iter() + .fold(0, |values, &byte| values | lut[usize::from(byte)]); + if values & 0x80 != 0 { + return chunk + .iter() + .position(|&byte| lut[usize::from(byte)] & 0x80 != 0) + .map(|offset| chunk_index * CHECK_CHUNK_LEN + offset); + } + } + tail.iter() + .position(|&byte| lut[usize::from(byte)] & 0x80 != 0) + .map(|offset| chunks.len() * CHECK_CHUNK_LEN + offset) +} + #[inline] pub fn trailing_padding(input: &[u8]) -> usize { input.iter().rev().take_while(|byte| **byte == b'=').count() diff --git a/bases/src/base16.rs b/bases/src/base16.rs index 558a3ed..20ddb6a 100644 --- a/bases/src/base16.rs +++ b/bases/src/base16.rs @@ -144,6 +144,31 @@ where backend::base16::max_decoded_len(input_len) } + /// Computes the exact decoded length if `input` can be decoded successfully. + /// + /// This does not fully validate the input. See + /// [`Codec::decoded_len`](crate::Codec::decoded_len). + /// + /// # Errors + /// + /// Returns [`DecodeError::InvalidLength`] if the input length is odd. + #[inline] + pub fn decoded_len(input: impl AsRef<[u8]>) -> Result { + codec::decoded_len::(input.as_ref()) + } + + /// Validates encoded input without allocating or writing decoded bytes. + /// + /// See [`Codec::check`](crate::Codec::check) for details. + /// + /// # Errors + /// + /// Returns the same [`DecodeError`] as decoding with sufficient output capacity. + #[inline] + pub fn check(input: impl AsRef<[u8]>) -> Result<(), DecodeError> { + codec::check::(input.as_ref()) + } + /// Encodes `input` into `output`, returning the written prefix. /// /// # Errors @@ -373,6 +398,16 @@ where backend::base16::decode_plan(input) } + #[inline] + fn check_with_plan_impl(input: &[u8], plan: DecodePlan) -> Result<(), DecodeError> { + match (Case::UPPERCASE, DecodeCase::STRICT) { + (true, true) => backend::base16::check_with_plan::(input, plan), + (true, false) => backend::base16::check_with_plan::(input, plan), + (false, true) => backend::base16::check_with_plan::(input, plan), + (false, false) => backend::base16::check_with_plan::(input, plan), + } + } + #[inline(always)] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { if Case::UPPERCASE { diff --git a/bases/src/base32.rs b/bases/src/base32.rs index 578fece..501595e 100644 --- a/bases/src/base32.rs +++ b/bases/src/base32.rs @@ -189,6 +189,32 @@ where backend::base32::max_decoded_len(input_len) } + /// Computes the exact decoded length if `input` can be decoded successfully. + /// + /// This does not fully validate the input. See + /// [`Codec::decoded_len`](crate::Codec::decoded_len). + /// + /// # Errors + /// + /// Returns [`DecodeError::InvalidLength`] or [`DecodeError::InvalidPadding`] + /// for structural errors detected while computing the output size. + #[inline] + pub fn decoded_len(input: impl AsRef<[u8]>) -> Result { + codec::decoded_len::(input.as_ref()) + } + + /// Validates encoded input without allocating or writing decoded bytes. + /// + /// See [`Codec::check`](crate::Codec::check) for details. + /// + /// # Errors + /// + /// Returns the same [`DecodeError`] as decoding with sufficient output capacity. + #[inline] + pub fn check(input: impl AsRef<[u8]>) -> Result<(), DecodeError> { + codec::check::(input.as_ref()) + } + /// Encodes `input` into `output`, returning the written prefix. /// /// # Errors @@ -428,6 +454,34 @@ where } } + #[inline] + fn check_with_plan_impl(input: &[u8], plan: DecodePlan) -> Result<(), DecodeError> { + match (Alphabet::EXTENDED_HEX, Case::UPPERCASE, DecodeCase::STRICT) { + (false, false, false) => { + backend::base32::check_with_plan::(input, plan) + } + (false, false, true) => { + backend::base32::check_with_plan::(input, plan) + } + (false, true, false) => { + backend::base32::check_with_plan::(input, plan) + } + (false, true, true) => { + backend::base32::check_with_plan::(input, plan) + } + (true, false, false) => { + backend::base32::check_with_plan::(input, plan) + } + (true, false, true) => { + backend::base32::check_with_plan::(input, plan) + } + (true, true, false) => { + backend::base32::check_with_plan::(input, plan) + } + (true, true, true) => backend::base32::check_with_plan::(input, plan), + } + } + #[inline] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { match ( diff --git a/bases/src/base64.rs b/bases/src/base64.rs index 4cda078..3c41c91 100644 --- a/bases/src/base64.rs +++ b/bases/src/base64.rs @@ -169,6 +169,32 @@ where backend::base64::max_decoded_len(input_len) } + /// Computes the exact decoded length if `input` can be decoded successfully. + /// + /// This does not fully validate the input. See + /// [`Codec::decoded_len`](crate::Codec::decoded_len). + /// + /// # Errors + /// + /// Returns [`DecodeError::InvalidLength`] or [`DecodeError::InvalidPadding`] + /// for structural errors detected while computing the output size. + #[inline] + pub fn decoded_len(input: impl AsRef<[u8]>) -> Result { + codec::decoded_len::(input.as_ref()) + } + + /// Validates encoded input without allocating or writing decoded bytes. + /// + /// See [`Codec::check`](crate::Codec::check) for details. + /// + /// # Errors + /// + /// Returns the same [`DecodeError`] as decoding with sufficient output capacity. + #[inline] + pub fn check(input: impl AsRef<[u8]>) -> Result<(), DecodeError> { + codec::check::(input.as_ref()) + } + /// Encodes `input` into `output`, returning the written prefix. /// /// # Errors @@ -406,6 +432,15 @@ where } } + #[inline] + fn check_with_plan_impl(input: &[u8], plan: DecodePlan) -> Result<(), DecodeError> { + if Alphabet::URL_SAFE { + backend::base64::check_with_plan::(input, plan) + } else { + backend::base64::check_with_plan::(input, plan) + } + } + #[inline] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { match (Alphabet::URL_SAFE, Padding::ENCODE_PADDED) { diff --git a/bases/src/codec.rs b/bases/src/codec.rs index 0c39453..9d570c9 100644 --- a/bases/src/codec.rs +++ b/bases/src/codec.rs @@ -92,6 +92,61 @@ pub trait Codec: sealed::Sealed + Sized + 'static { Self::Profile::max_decoded_len_impl(input_len) } + /// Computes the exact decoded length if `input` can be decoded successfully. + /// + /// This checks the length and trailing padding shape needed to determine + /// the output size, but does not fully validate the input. Invalid symbols, + /// misplaced padding, and non-zero unused bits can go undetected. A successful + /// result does not guarantee that decoding will succeed. + /// + /// # Errors + /// + /// Returns [`DecodeError::InvalidLength`] or [`DecodeError::InvalidPadding`] + /// for structural errors detected while computing the output size. + /// + /// # Examples + /// + /// ``` + /// use bases::Base64; + /// + /// assert_eq!(Base64::max_decoded_len(4), 3); + /// assert_eq!(Base64::decoded_len("Zg=="), Ok(1)); + /// // Computing the size does not validate alphabet symbols. + /// assert_eq!(Base64::decoded_len("!g=="), Ok(1)); + /// ``` + #[inline] + fn decoded_len(input: impl AsRef<[u8]>) -> Result { + decoded_len::(input.as_ref()) + } + + /// Validates encoded input without allocating or writing decoded bytes. + /// + /// This applies the same alphabet, padding, case, and unused-bit rules as + /// decoding. Unlike [`decoded_len`](Self::decoded_len), success guarantees + /// that the input can be decoded successfully. + /// + /// # Errors + /// + /// Returns the same [`DecodeError`], including its byte offset and error + /// precedence, as decoding with sufficient output capacity. + /// + /// # Examples + /// + /// ``` + /// use bases::Base64; + /// use bases::DecodeError; + /// + /// assert_eq!(Base64::check("Zg=="), Ok(())); + /// assert_eq!( + /// Base64::check("Zh=="), + /// Err(DecodeError::NonCanonical { index: 1 }), + /// ); + /// ``` + #[inline] + fn check(input: impl AsRef<[u8]>) -> Result<(), DecodeError> { + check::(input.as_ref()) + } + /// Encodes `input` into `output`, returning the written prefix. /// /// # Errors @@ -462,6 +517,17 @@ pub fn encode_into_uninit<'output, C: Codec>( }) } +#[inline] +pub fn decoded_len(input: &[u8]) -> Result { + C::Profile::decode_plan_impl(input).map(|plan| plan.required) +} + +#[inline] +pub fn check(input: &[u8]) -> Result<(), DecodeError> { + let plan = C::Profile::decode_plan_impl(input)?; + C::Profile::check_with_plan_impl(input, plan) +} + #[inline] pub fn decode_into<'output, C: Codec>( input: &[u8], @@ -625,6 +691,7 @@ pub(crate) mod sealed { fn encoded_len_impl(input_len: usize) -> Option; fn max_decoded_len_impl(input_len: usize) -> usize; fn decode_plan_impl(input: &[u8]) -> Result; + fn check_with_plan_impl(input: &[u8], plan: DecodePlan) -> Result<(), DecodeError>; fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize; fn encode_quantum_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize; fn decode_with_plan_impl( diff --git a/bases/src/lib.rs b/bases/src/lib.rs index 1d4a17b..fe549cb 100644 --- a/bases/src/lib.rs +++ b/bases/src/lib.rs @@ -67,11 +67,12 @@ //! //! # API layers //! -//! - **Sizing and caller buffers (`no_std`)**: `encoded_len`, `max_decoded_len`, `encode_into`, -//! `decode_into`, `decode_in_place`, and `decode_array` operate without allocation, with `const -//! fn` support on concrete profile `new`, `name`, `encoded_len`, `max_decoded_len`, `display`, -//! `encoder`, and `decoder`. [`Codec::encode_into_uninit`] and [`Codec::decode_into_uninit`] -//! accept caller-provided `MaybeUninit` storage. +//! - **Sizing, validation, and caller buffers (`no_std`)**: `encoded_len`, `max_decoded_len`, +//! `decoded_len`, `check`, `encode_into`, `decode_into`, `decode_in_place`, and `decode_array` +//! operate without allocation, with `const fn` support on concrete profile `new`, `name`, +//! `encoded_len`, `max_decoded_len`, `display`, `encoder`, and `decoder`. +//! [`Codec::encode_into_uninit`] and [`Codec::decode_into_uninit`] accept caller-provided +//! `MaybeUninit` storage. //! - **Owned and append helpers (`alloc`)**: `encode`, `encode_append`, `decode`, and transactional //! `decode_append` return or extend `String` and `Vec`. //! - **Incremental streaming (`no_std` / `std`)**: [`Encoder`] and [`Decoder`] process arbitrarily diff --git a/tests-integration/tests/contracts.rs b/tests-integration/tests/contracts.rs index 7b0813d..48d0bec 100644 --- a/tests-integration/tests/contracts.rs +++ b/tests-integration/tests/contracts.rs @@ -26,6 +26,7 @@ mod serialization; mod streaming; use bases::Codec; +use bases::DecodeSliceError; use bases::base16; use bases::base32; use bases::base64; @@ -66,11 +67,19 @@ fn payload(len: usize) -> Vec { fn optional_padding_accepts_only_canonical_tail_lengths() { fn check_decode(wire: &str, expected: Option<&[u8]>) { let mut out = vec![0; C::max_decoded_len(wire.len())]; + let decoded = C::decode_into(wire, &mut out); assert_eq!( - C::decode_into(wire, &mut out).ok().as_deref(), - expected, + C::check(wire).map_err(DecodeSliceError::from), + decoded.as_ref().map(|_| ()).map_err(|&error| error), "{wire}" ); + assert_eq!(decoded.ok().as_deref(), expected, "{wire}"); + if let Some(raw) = expected { + let capacity = C::decoded_len(wire).unwrap(); + assert_eq!(capacity, raw.len(), "{wire}"); + let mut exact = vec![0; capacity]; + assert_eq!(C::decode_into(wire, &mut exact).unwrap(), raw); + } let mut in_place = wire.as_bytes().to_vec(); assert_eq!( C::decode_in_place(&mut in_place).ok().as_deref(), diff --git a/tests-integration/tests/contracts/buffers.rs b/tests-integration/tests/contracts/buffers.rs index 9db0e5f..77817a1 100644 --- a/tests-integration/tests/contracts/buffers.rs +++ b/tests-integration/tests/contracts/buffers.rs @@ -27,6 +27,9 @@ pub fn check(reference: &Encoding) { for len in (0..=1025).chain([4096]) { let raw = payload(len); let expected = reference.encode(&raw); + assert_eq!(C::check(&expected), Ok(())); + let decoded_len = C::decoded_len(&expected).unwrap(); + assert_eq!(decoded_len, len); assert_eq!(C::encoded_len(len).unwrap(), expected.len()); assert_that!(C::encode(&raw), eq(&expected)); assert_that!(C::decode(&expected), ok(eq(&raw))); @@ -55,7 +58,7 @@ pub fn check(reference: &Encoding) { assert_that!(&encoded[..offset], each(eq(&0xa5))); assert_that!(&encoded[offset + expected.len()..], each(eq(&0xa5))); - for capacity in [len, C::max_decoded_len(expected.len()), len + 32] { + for capacity in [decoded_len, C::max_decoded_len(expected.len()), len + 32] { let mut decoded = vec![0xa5; offset + capacity + 32]; assert_eq!( C::decode_into( @@ -97,10 +100,10 @@ pub fn check(reference: &Encoding) { // Exercise growth as well as spare capacity, with a non-ASCII string prefix. for reserve in [0, expected.len() + 64] { - let mut text = String::from("前缀:"); + let mut text = String::from("prefix:\u{e9}"); text.reserve(reserve); assert_eq!(C::encode_append(&raw, &mut text), expected); - assert_eq!(text, format!("前缀:{expected}")); + assert_eq!(text, format!("prefix:\u{e9}{expected}")); let mut decoded = vec![0, 0xff, 0x80]; decoded.reserve(reserve); assert_eq!(C::decode_append(&expected, &mut decoded).unwrap(), len); diff --git a/tests-integration/tests/contracts/lengths.rs b/tests-integration/tests/contracts/lengths.rs index 2dcf4a3..d3bdf1f 100644 --- a/tests-integration/tests/contracts/lengths.rs +++ b/tests-integration/tests/contracts/lengths.rs @@ -12,7 +12,12 @@ // See the License for the specific language governing permissions and // limitations under the License. +use bases::Base16Lower; +use bases::Base32; +use bases::Base64; +use bases::Base64Unpadded; use bases::Codec; +use bases::DecodeError; use bases::EncodeError; use data_encoding::Encoding; @@ -30,6 +35,44 @@ pub fn check(reference: &Encoding) { ); } +#[test] +fn decoded_length_reports_structural_errors() { + assert_eq!( + Base16Lower::decoded_len("6"), + Err(DecodeError::InvalidLength { length: 1 }), + ); + assert_eq!( + Base64::decoded_len("!"), + Err(DecodeError::InvalidLength { length: 1 }), + ); + assert_eq!( + Base64::decoded_len("A==="), + Err(DecodeError::InvalidPadding { index: 1 }), + ); + assert_eq!( + Base32::decoded_len("MZXW6Y=="), + Err(DecodeError::InvalidPadding { index: 6 }), + ); +} + +#[test] +fn decoded_length_does_not_fully_validate_input() { + fn check(wire: &str, capacity: usize) { + assert_eq!(C::decoded_len(wire), Ok(capacity)); + let mut output = vec![0; capacity]; + assert!(C::decode_into(wire, &mut output).is_err()); + } + + check::("g0", 1); + check::("!Y======", 1); + check::("my======", 1); + check::("MZ======", 1); + check::("!g==", 1); + check::("Zh==", 1); + check::("Zg==AAAA", 6); + check::("Zg==", 3); +} + fn assert_lengths(input_quantum: usize, encoded_quantum: usize, padded: bool) { let mut lengths: Vec = (0..=16).collect(); for boundary in [ diff --git a/tests-integration/tests/contracts/malformed.rs b/tests-integration/tests/contracts/malformed.rs index a2f7a14..b043c1d 100644 --- a/tests-integration/tests/contracts/malformed.rs +++ b/tests-integration/tests/contracts/malformed.rs @@ -14,6 +14,9 @@ use core::mem::MaybeUninit; +use bases::Base16Lower; +use bases::Base32; +use bases::Base64; use bases::Codec; use bases::DecodeError; use bases::DecodeSliceError; @@ -26,6 +29,40 @@ use googletest::prelude::*; use crate::payload; use crate::streaming; +#[test] +fn validation_preserves_structural_and_symbol_error_precedence() { + assert_eq!( + Base64::check("!"), + Err(DecodeError::InvalidLength { length: 1 }), + ); + assert_eq!( + Base64::check("!==="), + Err(DecodeError::InvalidPadding { index: 1 }), + ); + assert_eq!( + Base32::check("!Y====="), + Err(DecodeError::InvalidLength { length: 7 }), + ); + assert_eq!( + Base32::check("!Y====AA"), + Err(DecodeError::InvalidByte { + index: 0, + byte: b'!' + }), + ); + assert_eq!( + Base64::check("Zh==!!!!"), + Err(DecodeError::InvalidPadding { index: 2 }), + ); + assert_eq!( + Base16Lower::check("=="), + Err(DecodeError::InvalidByte { + index: 0, + byte: b'=' + }), + ); +} + #[test] fn optional_padding_preserves_alphabet_and_trailing_bit_errors() { type Base64 = base64::Base64; @@ -72,8 +109,17 @@ pub fn differential(reference: &Encoding) { } else { reference.decode(wire).map_err(|_| ()) }; - let actual = C::decode_into(wire, &mut output).map_err(|_| ()); - assert_eq!(actual.as_deref(), expected.as_deref(), "wire: {wire:?}"); + let decoded = C::decode_into(wire, &mut output); + assert_eq!( + C::check(wire).map_err(DecodeSliceError::from), + decoded.as_ref().map(|_| ()).map_err(|&error| error), + "validation wire: {wire:?}" + ); + assert_eq!( + decoded.map_err(|_| ()).as_deref(), + expected.as_deref(), + "wire: {wire:?}" + ); in_place.clear(); in_place.extend_from_slice(wire); let actual = C::decode_in_place(&mut in_place).map_err(|_| ()); @@ -109,6 +155,29 @@ pub fn differential(reference: &Encoding) { } pub fn errors(reference: &Encoding) { + for len in [ + 8, 15, 16, 17, 19, 20, 21, 23, 24, 25, 64, 159, 160, 164, 1024, + ] { + let mut bad = reference.encode(&payload(len)).into_bytes(); + let last = bad.iter().rposition(|&byte| byte != b'=').unwrap(); + for first in [0, last / 2] { + let original = bad[first]; + bad[first] = b'!'; + bad[last] = 0xff; + let expected = DecodeError::InvalidByte { + index: first, + byte: b'!', + }; + assert_eq!(C::check(&bad), Err(expected)); + let mut output = vec![0; C::max_decoded_len(bad.len())]; + assert_eq!( + C::decode_into(&bad, &mut output), + Err(DecodeSliceError::Decode(expected)), + ); + bad[first] = original; + } + } + let wire = reference.encode(&payload(65)); for index in 0..wire.trim_end_matches('=').len() { let mut bad = wire.as_bytes().to_vec(); @@ -148,6 +217,7 @@ pub fn errors(reference: &Encoding) { } fn assert_error(wire: &[u8], expected: DecodeError) { + assert_eq!(C::check(wire), Err(expected)); let mut output = vec![0; C::max_decoded_len(wire.len())]; assert_that!( C::decode_into(wire, &mut output), From 7080c0762b2c6e86f773f72a59ffda5ea3fccf83 Mon Sep 17 00:00:00 2001 From: patrickZWY <154947644+patrickZWY@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:19:20 -0800 Subject: [PATCH 2/4] refactor: make register-only SIMD helpers safe --- bases/src/backend/base16/arch/x86.rs | 19 +++---------------- bases/src/backend/base32/arch/x86.rs | 15 +++------------ bases/src/backend/base64/arch/x86.rs | 28 ++++++---------------------- 3 files changed, 12 insertions(+), 50 deletions(-) diff --git a/bases/src/backend/base16/arch/x86.rs b/bases/src/backend/base16/arch/x86.rs index 2ecac6b..cf6df8f 100644 --- a/bases/src/backend/base16/arch/x86.rs +++ b/bases/src/backend/base16/arch/x86.rs @@ -228,12 +228,9 @@ pub fn decode_in_place( (done_32 * 32, done_32 * 16) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn hex_table_128() -> __m128i { +fn hex_table_128() -> __m128i { if UPPERCASE { _mm_setr_epi8( b'0' as i8, b'1' as i8, b'2' as i8, b'3' as i8, b'4' as i8, b'5' as i8, b'6' as i8, @@ -351,14 +348,9 @@ unsafe fn encode_avx2( (input_index, output_index) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn decode_nibbles_128( - v: __m128i, -) -> __m128i { +fn decode_nibbles_128(v: __m128i) -> __m128i { // Saturation maps digits to 0-9 and letters to 10-15; all other bytes stay above 15. let digits = _mm_sub_epi8( _mm_subs_epu8( @@ -443,15 +435,10 @@ unsafe fn decode_ssse3( done } -/// # Safety -/// -/// Requires AVX2 support on the current CPU. #[cfg(any(feature = "std", target_feature = "avx2"))] #[inline] #[target_feature(enable = "avx2")] -unsafe fn decode_nibbles_256( - v: __m256i, -) -> __m256i { +fn decode_nibbles_256(v: __m256i) -> __m256i { let digits = _mm256_sub_epi8( _mm256_subs_epu8( _mm256_add_epi8(v, _mm256_set1_epi8(!b'9' as i8)), diff --git a/bases/src/backend/base32/arch/x86.rs b/bases/src/backend/base32/arch/x86.rs index 98ae1e8..10b0454 100644 --- a/bases/src/backend/base32/arch/x86.rs +++ b/bases/src/backend/base32/arch/x86.rs @@ -298,12 +298,9 @@ pub fn decode_in_place() -> ( +fn encode_128_consts() -> ( __m128i, __m128i, __m128i, @@ -500,16 +497,10 @@ unsafe fn encode_avx2( (input_index, output_index) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn decode_128_tables< - const EXTENDED_HEX: bool, - const UPPERCASE: bool, - const STRICT_CASE: bool, ->() -> (__m128i, __m128i, __m128i, __m128i) { +fn decode_128_tables() +-> (__m128i, __m128i, __m128i, __m128i) { let hi = select_hi_mask::(); let lo = if EXTENDED_HEX { LO_MASK_HEX diff --git a/bases/src/backend/base64/arch/x86.rs b/bases/src/backend/base64/arch/x86.rs index 20546ed..8239e1a 100644 --- a/bases/src/backend/base64/arch/x86.rs +++ b/bases/src/backend/base64/arch/x86.rs @@ -298,12 +298,9 @@ pub fn decode_in_place( (done_16 * 16, done_16 * 12, had_invalid) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn encode_128_consts() -> ( +fn encode_128_consts() -> ( __m128i, __m128i, __m128i, @@ -477,12 +474,9 @@ unsafe fn encode_avx2( (input_index, output_index) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn decode_128_tables() +fn decode_128_tables() -> (__m128i, __m128i, __m128i, __m128i, __m128i, __m128i) { let hi_mask = _mm_setr_epi8(0, 0, 1, 2, 4, 8, 4, 16, 0, 0, 0, 0, 0, 0, 0, 0); let lo = if URL_SAFE_ALPHABET { @@ -516,12 +510,9 @@ unsafe fn decode_128_tables() ) } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn classify_16( +fn classify_16( v: __m128i, hi_mask: __m128i, lo_mask: __m128i, @@ -687,13 +678,10 @@ unsafe fn decode_ssse3( (done, false) } -/// # Safety -/// -/// Requires AVX2 support on the current CPU. #[cfg(any(feature = "std", target_feature = "avx2"))] #[inline] #[target_feature(enable = "avx2")] -unsafe fn classify_32_bytes( +fn classify_32_bytes( v: __m256i, hi_mask: __m256i, lo_mask: __m256i, @@ -708,21 +696,17 @@ unsafe fn classify_32_bytes( (hi, chk) } -/// # Safety -/// -/// Requires AVX2 support on the current CPU. #[cfg(any(feature = "std", target_feature = "avx2"))] #[inline] #[target_feature(enable = "avx2")] -unsafe fn classify_32( +fn classify_32( v: __m256i, hi_mask: __m256i, lo_mask: __m256i, mask_0f: __m256i, zero: __m256i, ) -> (__m256i, u32) { - // SAFETY: AVX2 is enabled by this function's target features. - let (hi, chk) = unsafe { classify_32_bytes(v, hi_mask, lo_mask, mask_0f) }; + let (hi, chk) = classify_32_bytes(v, hi_mask, lo_mask, mask_0f); let invalid = _mm256_movemask_epi8(_mm256_cmpeq_epi8(chk, zero)) as u32; (hi, invalid) } From e59a6f38dafb1b702eb5095b43e3efbb2f08e776 Mon Sep 17 00:00:00 2001 From: patrickZWY <154947644+patrickZWY@users.noreply.github.com> Date: Sat, 21 Nov 2026 16:49:00 -0800 Subject: [PATCH 3/4] refactor: use bounded chunks for Base16 SIMD encoding --- bases/src/backend/base16/arch/x86.rs | 85 +++++++++++++++------------- 1 file changed, 45 insertions(+), 40 deletions(-) diff --git a/bases/src/backend/base16/arch/x86.rs b/bases/src/backend/base16/arch/x86.rs index cf6df8f..1c9bc8e 100644 --- a/bases/src/backend/base16/arch/x86.rs +++ b/bases/src/backend/base16/arch/x86.rs @@ -246,23 +246,27 @@ fn hex_table_128() -> __m128i { } } -/// # Safety -/// -/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -unsafe fn encode_chunk_16(in_ptr: *const u8, out_ptr: *mut u8, hex_tbl: __m128i, mask_0f: __m128i) { - // SAFETY: Caller guarantees `in_ptr` is valid for 16 reads and `out_ptr` for 32 writes. +fn encode_chunk_16( + input: &[u8; 16], + output: &mut [MaybeUninit; 32], + hex_tbl: __m128i, + mask_0f: __m128i, +) { + // SAFETY: The input array contains sixteen readable bytes; SSSE3 is enabled here. + let v = unsafe { _mm_loadu_si128(input.as_ptr().cast()) }; + let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); + let lo = _mm_and_si128(v, mask_0f); + let hi_ascii = _mm_shuffle_epi8(hex_tbl, hi); + let lo_ascii = _mm_shuffle_epi8(hex_tbl, lo); + let out0 = _mm_unpacklo_epi8(hi_ascii, lo_ascii); + let out1 = _mm_unpackhi_epi8(hi_ascii, lo_ascii); + let (first, second) = output.split_at_mut(16); + // SAFETY: Each disjoint half contains sixteen writable byte slots; SSSE3 is enabled here. unsafe { - let v = _mm_loadu_si128(in_ptr.cast()); - let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); - let lo = _mm_and_si128(v, mask_0f); - let hi_ascii = _mm_shuffle_epi8(hex_tbl, hi); - let lo_ascii = _mm_shuffle_epi8(hex_tbl, lo); - let out0 = _mm_unpacklo_epi8(hi_ascii, lo_ascii); - let out1 = _mm_unpackhi_epi8(hi_ascii, lo_ascii); - _mm_storeu_si128(out_ptr.cast(), out0); - _mm_storeu_si128(out_ptr.add(16).cast(), out1); + _mm_storeu_si128(first.as_mut_ptr().cast(), out0); + _mm_storeu_si128(second.as_mut_ptr().cast(), out1); } } @@ -280,17 +284,15 @@ unsafe fn encode_ssse3( return (0, 0); } - let mut in_ptr = input.as_ptr(); - let mut out_ptr = output.as_mut_ptr().cast::(); - // SAFETY: `chunks * 16 <= input.len()` and `chunks * 32 <= output.len()`, and SSSE3 is enabled. - unsafe { - let hex_tbl = hex_table_128::(); - let mask_0f = _mm_set1_epi8(0x0f); - for _ in 0..chunks { - encode_chunk_16(in_ptr, out_ptr, hex_tbl, mask_0f); - in_ptr = in_ptr.add(16); - out_ptr = out_ptr.add(32); - } + let hex_tbl = hex_table_128::(); + let mask_0f = _mm_set1_epi8(0x0f); + for (src, dst) in input + .as_chunks::<16>() + .0 + .iter() + .zip(output.as_chunks_mut::<32>().0) + { + encode_chunk_16(src, dst, hex_tbl, mask_0f); } (chunks * 16, chunks * 32) } @@ -315,10 +317,13 @@ unsafe fn encode_avx2( if chunks > 0 { let hex_tbl = _mm256_set_m128i(hex_128, hex_128); let mask_0f = _mm256_set1_epi8(0x0f); - let mut in_ptr = input.as_ptr(); - let mut out_ptr = output.as_mut_ptr().cast::(); - for _ in 0..chunks { - let v = _mm256_loadu_si256(in_ptr.cast()); + for (src, dst) in input + .as_chunks::<32>() + .0 + .iter() + .zip(output.as_chunks_mut::<64>().0) + { + let v = _mm256_loadu_si256(src.as_ptr().cast()); let hi = _mm256_and_si256(_mm256_srli_epi16(v, 4), mask_0f); let lo = _mm256_and_si256(v, mask_0f); let hi_ascii = _mm256_shuffle_epi8(hex_tbl, hi); @@ -327,20 +332,20 @@ unsafe fn encode_avx2( let unp_hi = _mm256_unpackhi_epi8(hi_ascii, lo_ascii); let out0 = _mm256_permute2x128_si256::<0x20>(unp_lo, unp_hi); let out1 = _mm256_permute2x128_si256::<0x31>(unp_lo, unp_hi); - _mm256_storeu_si256(out_ptr.cast(), out0); - _mm256_storeu_si256(out_ptr.add(32).cast(), out1); - in_ptr = in_ptr.add(32); - out_ptr = out_ptr.add(64); + let (first, second) = dst.split_at_mut(32); + _mm256_storeu_si256(first.as_mut_ptr().cast(), out0); + _mm256_storeu_si256(second.as_mut_ptr().cast(), out1); } } - if input_index + 16 <= input.len() && output_index + 32 <= output.len() { + if let Some(src) = input + .get(input_index..input_index + 16) + .and_then(|chunk| chunk.first_chunk::<16>()) + && let Some(dst) = output + .get_mut(output_index..output_index + 32) + .and_then(|chunk| chunk.first_chunk_mut::<32>()) + { let mask_0f = _mm_set1_epi8(0x0f); - encode_chunk_16( - input.as_ptr().add(input_index), - output.as_mut_ptr().cast::().add(output_index), - hex_128, - mask_0f, - ); + encode_chunk_16(src, dst, hex_128, mask_0f); input_index += 16; output_index += 32; } From 0ca1110f5e8c7c9b2484edac0812178fe3d4af19 Mon Sep 17 00:00:00 2001 From: patrickZWY <154947644+patrickZWY@users.noreply.github.com> Date: Sat, 21 Nov 2026 17:47:57 -0800 Subject: [PATCH 4/4] Revert "refactor: use bounded chunks for Base16 SIMD encoding" This reverts commit e59a6f38dafb1b702eb5095b43e3efbb2f08e776. --- bases/src/backend/base16/arch/x86.rs | 85 +++++++++++++--------------- 1 file changed, 40 insertions(+), 45 deletions(-) diff --git a/bases/src/backend/base16/arch/x86.rs b/bases/src/backend/base16/arch/x86.rs index 1c9bc8e..cf6df8f 100644 --- a/bases/src/backend/base16/arch/x86.rs +++ b/bases/src/backend/base16/arch/x86.rs @@ -246,27 +246,23 @@ fn hex_table_128() -> __m128i { } } +/// # Safety +/// +/// Requires SSSE3 support on the current CPU. #[inline] #[target_feature(enable = "ssse3")] -fn encode_chunk_16( - input: &[u8; 16], - output: &mut [MaybeUninit; 32], - hex_tbl: __m128i, - mask_0f: __m128i, -) { - // SAFETY: The input array contains sixteen readable bytes; SSSE3 is enabled here. - let v = unsafe { _mm_loadu_si128(input.as_ptr().cast()) }; - let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); - let lo = _mm_and_si128(v, mask_0f); - let hi_ascii = _mm_shuffle_epi8(hex_tbl, hi); - let lo_ascii = _mm_shuffle_epi8(hex_tbl, lo); - let out0 = _mm_unpacklo_epi8(hi_ascii, lo_ascii); - let out1 = _mm_unpackhi_epi8(hi_ascii, lo_ascii); - let (first, second) = output.split_at_mut(16); - // SAFETY: Each disjoint half contains sixteen writable byte slots; SSSE3 is enabled here. +unsafe fn encode_chunk_16(in_ptr: *const u8, out_ptr: *mut u8, hex_tbl: __m128i, mask_0f: __m128i) { + // SAFETY: Caller guarantees `in_ptr` is valid for 16 reads and `out_ptr` for 32 writes. unsafe { - _mm_storeu_si128(first.as_mut_ptr().cast(), out0); - _mm_storeu_si128(second.as_mut_ptr().cast(), out1); + let v = _mm_loadu_si128(in_ptr.cast()); + let hi = _mm_and_si128(_mm_srli_epi16(v, 4), mask_0f); + let lo = _mm_and_si128(v, mask_0f); + let hi_ascii = _mm_shuffle_epi8(hex_tbl, hi); + let lo_ascii = _mm_shuffle_epi8(hex_tbl, lo); + let out0 = _mm_unpacklo_epi8(hi_ascii, lo_ascii); + let out1 = _mm_unpackhi_epi8(hi_ascii, lo_ascii); + _mm_storeu_si128(out_ptr.cast(), out0); + _mm_storeu_si128(out_ptr.add(16).cast(), out1); } } @@ -284,15 +280,17 @@ unsafe fn encode_ssse3( return (0, 0); } - let hex_tbl = hex_table_128::(); - let mask_0f = _mm_set1_epi8(0x0f); - for (src, dst) in input - .as_chunks::<16>() - .0 - .iter() - .zip(output.as_chunks_mut::<32>().0) - { - encode_chunk_16(src, dst, hex_tbl, mask_0f); + let mut in_ptr = input.as_ptr(); + let mut out_ptr = output.as_mut_ptr().cast::(); + // SAFETY: `chunks * 16 <= input.len()` and `chunks * 32 <= output.len()`, and SSSE3 is enabled. + unsafe { + let hex_tbl = hex_table_128::(); + let mask_0f = _mm_set1_epi8(0x0f); + for _ in 0..chunks { + encode_chunk_16(in_ptr, out_ptr, hex_tbl, mask_0f); + in_ptr = in_ptr.add(16); + out_ptr = out_ptr.add(32); + } } (chunks * 16, chunks * 32) } @@ -317,13 +315,10 @@ unsafe fn encode_avx2( if chunks > 0 { let hex_tbl = _mm256_set_m128i(hex_128, hex_128); let mask_0f = _mm256_set1_epi8(0x0f); - for (src, dst) in input - .as_chunks::<32>() - .0 - .iter() - .zip(output.as_chunks_mut::<64>().0) - { - let v = _mm256_loadu_si256(src.as_ptr().cast()); + let mut in_ptr = input.as_ptr(); + let mut out_ptr = output.as_mut_ptr().cast::(); + for _ in 0..chunks { + let v = _mm256_loadu_si256(in_ptr.cast()); let hi = _mm256_and_si256(_mm256_srli_epi16(v, 4), mask_0f); let lo = _mm256_and_si256(v, mask_0f); let hi_ascii = _mm256_shuffle_epi8(hex_tbl, hi); @@ -332,20 +327,20 @@ unsafe fn encode_avx2( let unp_hi = _mm256_unpackhi_epi8(hi_ascii, lo_ascii); let out0 = _mm256_permute2x128_si256::<0x20>(unp_lo, unp_hi); let out1 = _mm256_permute2x128_si256::<0x31>(unp_lo, unp_hi); - let (first, second) = dst.split_at_mut(32); - _mm256_storeu_si256(first.as_mut_ptr().cast(), out0); - _mm256_storeu_si256(second.as_mut_ptr().cast(), out1); + _mm256_storeu_si256(out_ptr.cast(), out0); + _mm256_storeu_si256(out_ptr.add(32).cast(), out1); + in_ptr = in_ptr.add(32); + out_ptr = out_ptr.add(64); } } - if let Some(src) = input - .get(input_index..input_index + 16) - .and_then(|chunk| chunk.first_chunk::<16>()) - && let Some(dst) = output - .get_mut(output_index..output_index + 32) - .and_then(|chunk| chunk.first_chunk_mut::<32>()) - { + if input_index + 16 <= input.len() && output_index + 32 <= output.len() { let mask_0f = _mm_set1_epi8(0x0f); - encode_chunk_16(src, dst, hex_128, mask_0f); + encode_chunk_16( + input.as_ptr().add(input_index), + output.as_mut_ptr().cast::().add(output_index), + hex_128, + mask_0f, + ); input_index += 16; output_index += 32; }