From 1d33ddc044fd3527fe1eca2a8b8cef4be4139349 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 19:08:34 +0800 Subject: [PATCH 1/3] feat: accept optional padding in Base32 and Base64 decoding Protocols such as gRPC binary metadata emit unpadded Base64 but accept both canonical wire forms. The strict padded and unpadded profiles each reject one of those forms, so callers have to choose a decoder for each incoming value. Add policy::OptionalPadding in the existing padding parameter of both codec families. It emits unpadded text and selects the padded decode path when the input ends in '='. Each path validates its own length, alphabet and trailing bits. Streaming recognizes a padded final quantum during update and validates an unpadded fragment at finish. Exercise partial and excess padding across all four alphabets with an independent encoding oracle. Check in-place output and chunked input, including the error offset when more data follows a padded quantum. Refs #9 --- CHANGELOG.md | 1 + bases/ARCHITECTURE.md | 2 +- bases/README.md | 2 + bases/src/base16.rs | 2 +- bases/src/base32.rs | 62 ++++++++++++------- bases/src/base64.rs | 28 +++++---- bases/src/codec.rs | 2 +- bases/src/policy.rs | 50 ++++++++++++++- bases/src/stream.rs | 6 +- tests-integration/tests/contracts.rs | 48 ++++++++++++++ .../tests/contracts/malformed.rs | 35 +++++++++++ 11 files changed, 193 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dff2f4c..9bfdbe2 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 `policy::OptionalPadding` for Base32 and Base64 profiles that emit unpadded text and accept either canonical padding form when decoding. * 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. ## v0.1.1 (2026-11-17) diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md index 6d5215c..0e60951 100644 --- a/bases/ARCHITECTURE.md +++ b/bases/ARCHITECTURE.md @@ -4,7 +4,7 @@ Bases separates observable encoding semantics from execution strategy. ## Public layers -- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). +- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `OptionalPadding`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). - Concrete family types provide direct inherent methods, including `const fn` sizing and constructors (`new`, `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, `decoder`), while the sealed `Codec` trait provides the shared contract for generic `C: Codec` callers. - Caller-buffer operations accept initialized slices (`encode_into`, `decode_into`) or `MaybeUninit` slices (`encode_into_uninit`, `decode_into_uninit`). Both `decode_in_place` and `decode_array` also operate without allocation. The `alloc` feature adds `encode`, `encode_append`, `decode`, and transactional `decode_append`. The `serde` feature adds `serialize`, `deserialize_array`, and, with `alloc`, `deserialize`. - `Encoder` and `Decoder` preserve one partial quantum for incremental operation without allocation; `std` adds `bases::io::{EncoderWriter, DecoderReader}` over `std::io::{Write, Read}`. diff --git a/bases/README.md b/bases/README.md index 1763a0d..14f4b3a 100644 --- a/bases/README.md +++ b/bases/README.md @@ -39,6 +39,8 @@ Ten crate-root aliases cover standard encoding profiles: Every profile exposes inherent methods without requiring trait imports, and implements the sealed `Codec` trait for generic callers. Configurable zero-sized family types (`base16::Base16`, `base32::Base32`, and `base64::Base64`) accept `policy` markers for other combinations, such as strict single-case Base16 or RFC 5155 Base32Hex with lowercase output and case-insensitive decoding. See the [API reference](https://docs.rs/bases) for types, methods, and their contracts. +For gRPC binary metadata, use `base64::Base64`. It encodes `b"f"` as `Zg` and decodes both `Zg` and `Zg==`. Partial padding such as `Zg=` is invalid. The same marker works with Base64URL and both Base32 alphabets. + ## 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. diff --git a/bases/src/base16.rs b/bases/src/base16.rs index 41a8bec..e718f3f 100644 --- a/bases/src/base16.rs +++ b/bases/src/base16.rs @@ -355,7 +355,7 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 1; const ENCODED_QUANTUM: usize = 2; - const PADDED: bool = false; + const ACCEPTS_PADDING: bool = false; #[inline] fn encoded_len_impl(input_len: usize) -> Option { diff --git a/bases/src/base32.rs b/bases/src/base32.rs index 7bdd1cd..b4b2fd9 100644 --- a/bases/src/base32.rs +++ b/bases/src/base32.rs @@ -48,6 +48,7 @@ use crate::io::EncoderWriter; use crate::policy; use crate::policy::sealed::DecodeCasePolicy; use crate::policy::sealed::LetterCase; +use crate::policy::sealed::PaddingMode; use crate::policy::sealed::PaddingPolicy; #[cfg(feature = "serde")] use crate::serde; @@ -80,7 +81,8 @@ pub(crate) mod sealed { /// [`Standard`]), padding policy (`Padding`, defaulting to /// [`policy::Padded`]), encoded letter case (`Case`, defaulting to /// [`policy::Upper`]), and decoding case policy (`DecodeCase`, defaulting to -/// [`policy::Strict`]). +/// [`policy::Strict`]). Use [`policy::OptionalPadding`] to emit unpadded text and accept +/// both canonical padding forms. pub struct Base32< Alphabet = Standard, Padding = policy::Padded, @@ -146,26 +148,34 @@ where pub const fn name() -> &'static str { match ( Alphabet::EXTENDED_HEX, - Padding::PADDED, + Padding::MODE, Case::UPPERCASE, DecodeCase::STRICT, ) { - (false, true, true, true) => "base32", - (false, false, true, true) => "base32-unpadded", - (false, true, false, true) => "base32-lower", - (false, false, false, true) => "base32-lower-unpadded", - (false, true, true, false) => "base32-mixed", - (false, false, true, false) => "base32-mixed-unpadded", - (false, true, false, false) => "base32-lower-mixed", - (false, false, false, false) => "base32-lower-mixed-unpadded", - (true, true, true, true) => "base32hex", - (true, false, true, true) => "base32hex-unpadded", - (true, true, false, true) => "base32hex-lower", - (true, false, false, true) => "base32hex-lower-unpadded", - (true, true, true, false) => "base32hex-mixed", - (true, false, true, false) => "base32hex-mixed-unpadded", - (true, true, false, false) => "base32hex-lower-mixed", - (true, false, false, false) => "base32hex-lower-mixed-unpadded", + (false, PaddingMode::Required, true, true) => "base32", + (false, PaddingMode::Forbidden, true, true) => "base32-unpadded", + (false, PaddingMode::Optional, true, true) => "base32-optional-padding", + (false, PaddingMode::Required, false, true) => "base32-lower", + (false, PaddingMode::Forbidden, false, true) => "base32-lower-unpadded", + (false, PaddingMode::Optional, false, true) => "base32-lower-optional-padding", + (false, PaddingMode::Required, true, false) => "base32-mixed", + (false, PaddingMode::Forbidden, true, false) => "base32-mixed-unpadded", + (false, PaddingMode::Optional, true, false) => "base32-mixed-optional-padding", + (false, PaddingMode::Required, false, false) => "base32-lower-mixed", + (false, PaddingMode::Forbidden, false, false) => "base32-lower-mixed-unpadded", + (false, PaddingMode::Optional, false, false) => "base32-lower-mixed-optional-padding", + (true, PaddingMode::Required, true, true) => "base32hex", + (true, PaddingMode::Forbidden, true, true) => "base32hex-unpadded", + (true, PaddingMode::Optional, true, true) => "base32hex-optional-padding", + (true, PaddingMode::Required, false, true) => "base32hex-lower", + (true, PaddingMode::Forbidden, false, true) => "base32hex-lower-unpadded", + (true, PaddingMode::Optional, false, true) => "base32hex-lower-optional-padding", + (true, PaddingMode::Required, true, false) => "base32hex-mixed", + (true, PaddingMode::Forbidden, true, false) => "base32hex-mixed-unpadded", + (true, PaddingMode::Optional, true, false) => "base32hex-mixed-optional-padding", + (true, PaddingMode::Required, false, false) => "base32hex-lower-mixed", + (true, PaddingMode::Forbidden, false, false) => "base32hex-lower-mixed-unpadded", + (true, PaddingMode::Optional, false, false) => "base32hex-lower-mixed-optional-padding", } } @@ -178,7 +188,7 @@ where /// that a buffer of that size can be allocated. #[inline] pub const fn encoded_len(input_len: usize) -> Result { - let len = if Padding::PADDED { + let len = if Padding::EMIT_PADDING { backend::base32::encoded_len::(input_len) } else { backend::base32::encoded_len::(input_len) @@ -413,11 +423,11 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 5; const ENCODED_QUANTUM: usize = 8; - const PADDED: bool = Padding::PADDED; + const ACCEPTS_PADDING: bool = !matches!(Padding::MODE, PaddingMode::Forbidden); #[inline] fn encoded_len_impl(input_len: usize) -> Option { - if Padding::PADDED { + if Padding::EMIT_PADDING { backend::base32::encoded_len::(input_len) } else { backend::base32::encoded_len::(input_len) @@ -431,7 +441,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::PADDED { + if Padding::MODE.decode_padded(input) { backend::base32::decode_plan::(input) } else { backend::base32::decode_plan::(input) @@ -440,7 +450,11 @@ where #[inline] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { - match (Alphabet::EXTENDED_HEX, Padding::PADDED, Case::UPPERCASE) { + match ( + Alphabet::EXTENDED_HEX, + Padding::EMIT_PADDING, + Case::UPPERCASE, + ) { (false, false, false) => backend::base32::encode::(input, output), (false, false, true) => backend::base32::encode::(input, output), (false, true, false) => backend::base32::encode::(input, output), @@ -533,7 +547,7 @@ where fn decode_in_place_impl(buf: &mut [u8]) -> Result { match ( Alphabet::EXTENDED_HEX, - Padding::PADDED, + Padding::MODE.decode_padded(buf), Case::UPPERCASE, DecodeCase::STRICT, ) { diff --git a/bases/src/base64.rs b/bases/src/base64.rs index a555f8e..d5bae73 100644 --- a/bases/src/base64.rs +++ b/bases/src/base64.rs @@ -46,6 +46,7 @@ use crate::io::DecoderReader; #[cfg(feature = "std")] use crate::io::EncoderWriter; use crate::policy; +use crate::policy::sealed::PaddingMode; use crate::policy::sealed::PaddingPolicy; #[cfg(feature = "serde")] use crate::serde; @@ -76,7 +77,8 @@ pub(crate) mod sealed { /// /// The type parameters select the alphabet (`Alphabet`, defaulting to /// [`Standard`]) and padding policy (`Padding`, defaulting to -/// [`policy::Padded`]). +/// [`policy::Padded`]). Use [`policy::OptionalPadding`] to emit unpadded text and accept +/// both canonical padding forms. pub struct Base64(PhantomData<(Alphabet, Padding)>); impl Clone for Base64 { @@ -129,11 +131,13 @@ where #[must_use] #[inline] pub const fn name() -> &'static str { - match (Alphabet::URL_SAFE, Padding::PADDED) { - (false, true) => "base64", - (false, false) => "base64-unpadded", - (true, true) => "base64url", - (true, false) => "base64url-unpadded", + match (Alphabet::URL_SAFE, Padding::MODE) { + (false, PaddingMode::Required) => "base64", + (false, PaddingMode::Forbidden) => "base64-unpadded", + (false, PaddingMode::Optional) => "base64-optional-padding", + (true, PaddingMode::Required) => "base64url", + (true, PaddingMode::Forbidden) => "base64url-unpadded", + (true, PaddingMode::Optional) => "base64url-optional-padding", } } @@ -146,7 +150,7 @@ where /// that a buffer of that size can be allocated. #[inline] pub const fn encoded_len(input_len: usize) -> Result { - let len = if Padding::PADDED { + let len = if Padding::EMIT_PADDING { backend::base64::encoded_len::(input_len) } else { backend::base64::encoded_len::(input_len) @@ -379,11 +383,11 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 3; const ENCODED_QUANTUM: usize = 4; - const PADDED: bool = Padding::PADDED; + const ACCEPTS_PADDING: bool = !matches!(Padding::MODE, PaddingMode::Forbidden); #[inline] fn encoded_len_impl(input_len: usize) -> Option { - if Padding::PADDED { + if Padding::EMIT_PADDING { backend::base64::encoded_len::(input_len) } else { backend::base64::encoded_len::(input_len) @@ -397,7 +401,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::PADDED { + if Padding::MODE.decode_padded(input) { backend::base64::decode_plan::(input) } else { backend::base64::decode_plan::(input) @@ -406,7 +410,7 @@ where #[inline] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { - match (Alphabet::URL_SAFE, Padding::PADDED) { + match (Alphabet::URL_SAFE, Padding::EMIT_PADDING) { (false, false) => backend::base64::encode::(input, output), (false, true) => backend::base64::encode::(input, output), (true, false) => backend::base64::encode::(input, output), @@ -450,7 +454,7 @@ where #[inline] fn decode_in_place_impl(buf: &mut [u8]) -> Result { - match (Alphabet::URL_SAFE, Padding::PADDED) { + match (Alphabet::URL_SAFE, Padding::MODE.decode_padded(buf)) { (false, false) => backend::base64::decode_in_place::(buf), (false, true) => backend::base64::decode_in_place::(buf), (true, false) => backend::base64::decode_in_place::(buf), diff --git a/bases/src/codec.rs b/bases/src/codec.rs index ac0e910..2dd7cf3 100644 --- a/bases/src/codec.rs +++ b/bases/src/codec.rs @@ -619,7 +619,7 @@ pub(crate) mod sealed { const NAME: &'static str; const INPUT_QUANTUM: usize; const ENCODED_QUANTUM: usize; - const PADDED: bool; + const ACCEPTS_PADDING: bool; fn encoded_len_impl(input_len: usize) -> Option; fn max_decoded_len_impl(input_len: usize) -> usize; diff --git a/bases/src/policy.rs b/bases/src/policy.rs index f8280e4..1dc62f0 100644 --- a/bases/src/policy.rs +++ b/bases/src/policy.rs @@ -14,6 +14,8 @@ //! Policy markers for encoding and decoding profiles. +use crate::policy::sealed::PaddingMode; + /// Padding policy that requires and emits canonical `=` padding. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] pub struct Padded; @@ -22,6 +24,25 @@ pub struct Padded; #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] pub struct Unpadded; +/// Omits padding when encoding and accepts either complete canonical padding or none when decoding. +/// +/// For example, gRPC binary metadata uses this policy with the standard Base64 alphabet. +/// +/// ``` +/// use bases::base64; +/// use bases::policy; +/// +/// type Metadata = base64::Base64; +/// +/// let mut output = [0; 4]; +/// assert_eq!(Metadata::encode_into(b"f", &mut output).unwrap(), "Zg"); +/// assert_eq!(Metadata::decode_array("Zg"), Ok(*b"f")); +/// assert_eq!(Metadata::decode_array("Zg=="), Ok(*b"f")); +/// assert!(Metadata::decode_array::<1>("Zg=").is_err()); +/// ``` +#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] +pub struct OptionalPadding; + /// Letter case policy that emits lowercase ASCII letters. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] pub struct Lower; @@ -39,11 +60,15 @@ pub struct Mixed; pub struct Strict; impl sealed::PaddingPolicy for Padded { - const PADDED: bool = true; + const MODE: PaddingMode = PaddingMode::Required; } impl sealed::PaddingPolicy for Unpadded { - const PADDED: bool = false; + const MODE: PaddingMode = PaddingMode::Forbidden; +} + +impl sealed::PaddingPolicy for OptionalPadding { + const MODE: PaddingMode = PaddingMode::Optional; } impl sealed::LetterCase for Lower { @@ -63,8 +88,27 @@ impl sealed::DecodeCasePolicy for Strict { } pub(crate) mod sealed { + #[derive(Clone, Copy)] + pub enum PaddingMode { + Required, + Forbidden, + Optional, + } + + impl PaddingMode { + #[inline] + pub fn decode_padded(self, input: &[u8]) -> bool { + match self { + Self::Required => true, + Self::Forbidden => false, + Self::Optional => input.last() == Some(&b'='), + } + } + } + pub trait PaddingPolicy: 'static { - const PADDED: bool; + const MODE: PaddingMode; + const EMIT_PADDING: bool = matches!(Self::MODE, PaddingMode::Required); } pub trait LetterCase: 'static { diff --git a/bases/src/stream.rs b/bases/src/stream.rs index 2429c0b..6db7695 100644 --- a/bases/src/stream.rs +++ b/bases/src/stream.rs @@ -349,7 +349,7 @@ impl Decoder { let process_len = combined_len / encoded_quantum * encoded_quantum; let pending_offset = self.pending_offset(); - let (padding, padding_reduction, padding_index) = if C::Profile::PADDED { + let (padding, padding_reduction, padding_index) = if C::Profile::ACCEPTS_PADDING { analyze_padding::( &self.pending[..self.pending_len], input, @@ -457,8 +457,8 @@ impl Decoder { /// On error, [`FinishError::into_inner`] recovers the unchanged decoder. /// Output contents are unspecified on error. /// - /// Padded profiles require a complete final quantum; unpadded profiles - /// accept the partial lengths defined by their encoding. + /// Profiles that require padding need a complete final quantum. Profiles + /// that allow padding to be omitted accept canonical unpadded fragments. /// /// # Errors /// diff --git a/tests-integration/tests/contracts.rs b/tests-integration/tests/contracts.rs index c6a81d6..92ae9ce 100644 --- a/tests-integration/tests/contracts.rs +++ b/tests-integration/tests/contracts.rs @@ -25,8 +25,10 @@ mod serialization; #[path = "contracts/streaming.rs"] mod streaming; +use bases::Codec; use bases::base16; use bases::base32; +use bases::base64; use bases::policy; use data_encoding::Encoding; use data_encoding::Specification; @@ -60,6 +62,52 @@ fn payload(len: usize) -> Vec { .collect() } +#[test] +fn optional_padding_accepts_only_canonical_tail_lengths() { + fn check(reference: &Encoding) { + for len in 0..=10 { + let raw = payload(len); + let padded = reference.encode(&raw); + let bare = padded.trim_end_matches('='); + assert_eq!(C::encode(&raw), bare); + + let required = padded.len() - bare.len(); + for count in 0..=required + 1 { + let wire = format!("{bare}{}", "=".repeat(count)); + let expected = (count == 0 || count == required).then_some(raw.as_slice()); + let mut out = vec![0; C::max_decoded_len(wire.len())]; + assert_eq!( + C::decode_into(&wire, &mut out).ok().as_deref(), + expected, + "{wire}" + ); + let mut in_place = wire.as_bytes().to_vec(); + assert_eq!( + C::decode_in_place(&mut in_place).ok().as_deref(), + expected, + "{wire}" + ); + for chunk in 1..=wire.len().max(1) { + assert_eq!( + streaming::decode::(wire.as_bytes(), chunk) + .ok() + .as_deref(), + expected, + "{wire}, chunk {chunk}" + ); + } + } + } + } + + check::>(&data_encoding::BASE64); + check::>(&data_encoding::BASE64URL); + check::>(&data_encoding::BASE32); + check::>( + &data_encoding::BASE32HEX, + ); +} + macro_rules! profile { ($name:ident, $codec:ty, $alphabet:expr, $padded:literal, $mixed:literal) => { mod $name { diff --git a/tests-integration/tests/contracts/malformed.rs b/tests-integration/tests/contracts/malformed.rs index 0bb5678..896fed8 100644 --- a/tests-integration/tests/contracts/malformed.rs +++ b/tests-integration/tests/contracts/malformed.rs @@ -17,12 +17,47 @@ use core::mem::MaybeUninit; use bases::Codec; use bases::DecodeError; use bases::DecodeSliceError; +use bases::base32; +use bases::base64; +use bases::policy; use data_encoding::Encoding; use googletest::prelude::*; use crate::payload; use crate::streaming; +#[test] +fn optional_padding_preserves_alphabet_and_trailing_bit_errors() { + type Base64 = base64::Base64; + type Base32 = base32::Base32; + + for wire in [b"Zm9vZh".as_slice(), b"Zm9vZh=="] { + assert_error::(wire, DecodeError::NonCanonical { index: 5 }); + } + assert_error::( + b"Z ==", + DecodeError::InvalidByte { + index: 1, + byte: b' ', + }, + ); + assert_error::(b"Zg==AAAA", DecodeError::InvalidPadding { index: 2 }); + for wire in [b"MZ".as_slice(), b"MZ======"] { + assert_error::(wire, DecodeError::NonCanonical { index: 1 }); + } + assert_error::( + b"my======", + DecodeError::InvalidByte { + index: 0, + byte: b'm', + }, + ); + assert_error::( + b"MY======AAAAAAAA", + DecodeError::InvalidPadding { index: 2 }, + ); +} + pub fn differential(reference: &Encoding) { let mut output = vec![0; 256]; let mut in_place = Vec::new(); From eec12b26aad494683c8e31452bb024ec5beed155 Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 21:05:19 +0800 Subject: [PATCH 2/3] feat: support both output forms with optional padding Base32 and Base64 callers can receive fully padded or unpadded input while still needing a predictable wire format for outgoing values. Expose PaddedOptional and UnpaddedOptional in the padding parameter so the profile name identifies the output form and Optional describes what the decoder accepts. Select encoding size and output from the emission policy. Share decode validation between both optional profiles, including in-place decoding and streamed tails. Compose the stable profile names from the alphabet, case and padding suffix so both families use the same naming rules. Document all four policies side by side. Check both output forms against an independent encoder across the four alphabets, including streamed output, and exercise partial and excess padding across chunk boundaries. Refs #9 --- CHANGELOG.md | 2 +- bases/ARCHITECTURE.md | 2 +- bases/README.md | 11 +- bases/src/base32.rs | 51 +++------ bases/src/base64.rs | 23 ++-- bases/src/lib.rs | 4 + bases/src/policy.rs | 102 +++++++++++------- tests-integration/tests/contracts.rs | 76 ++++++++----- .../tests/contracts/malformed.rs | 4 +- .../tests/contracts/streaming.rs | 2 +- 10 files changed, 157 insertions(+), 120 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bfdbe2..3c1adcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ All significant changes to this project will be documented in this file. ### Features -* Add `policy::OptionalPadding` for Base32 and Base64 profiles that emit unpadded text and accept either canonical padding form when decoding. +* 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. ## v0.1.1 (2026-11-17) diff --git a/bases/ARCHITECTURE.md b/bases/ARCHITECTURE.md index 0e60951..bc10327 100644 --- a/bases/ARCHITECTURE.md +++ b/bases/ARCHITECTURE.md @@ -4,7 +4,7 @@ Bases separates observable encoding semantics from execution strategy. ## Public layers -- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `OptionalPadding`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). +- Parameterized zero-sized family types (`base16::Base16`, `base32::Base32`, `base64::Base64`) combined with `policy` markers (`Padded`, `Unpadded`, `PaddedOptional`, `UnpaddedOptional`, `Lower`, `Upper`, `Mixed`, `Strict`) define an alphabet, padding policy, and case policy, alongside ten crate-root aliases (`Base16Lower`, `Base16Upper`, `Base32`, `Base32Unpadded`, `Base32Hex`, `Base32HexUnpadded`, `Base64`, `Base64Unpadded`, `Base64Url`, `Base64UrlUnpadded`). - Concrete family types provide direct inherent methods, including `const fn` sizing and constructors (`new`, `name`, `encoded_len`, `max_decoded_len`, `display`, `encoder`, `decoder`), while the sealed `Codec` trait provides the shared contract for generic `C: Codec` callers. - Caller-buffer operations accept initialized slices (`encode_into`, `decode_into`) or `MaybeUninit` slices (`encode_into_uninit`, `decode_into_uninit`). Both `decode_in_place` and `decode_array` also operate without allocation. The `alloc` feature adds `encode`, `encode_append`, `decode`, and transactional `decode_append`. The `serde` feature adds `serialize`, `deserialize_array`, and, with `alloc`, `deserialize`. - `Encoder` and `Decoder` preserve one partial quantum for incremental operation without allocation; `std` adds `bases::io::{EncoderWriter, DecoderReader}` over `std::io::{Write, Read}`. diff --git a/bases/README.md b/bases/README.md index 14f4b3a..6fb14b0 100644 --- a/bases/README.md +++ b/bases/README.md @@ -39,7 +39,16 @@ Ten crate-root aliases cover standard encoding profiles: Every profile exposes inherent methods without requiring trait imports, and implements the sealed `Codec` trait for generic callers. Configurable zero-sized family types (`base16::Base16`, `base32::Base32`, and `base64::Base64`) accept `policy` markers for other combinations, such as strict single-case Base16 or RFC 5155 Base32Hex with lowercase output and case-insensitive decoding. See the [API reference](https://docs.rs/bases) for types, methods, and their contracts. -For gRPC binary metadata, use `base64::Base64`. It encodes `b"f"` as `Zg` and decodes both `Zg` and `Zg==`. Partial padding such as `Zg=` is invalid. The same marker works with Base64URL and both Base32 alphabets. +For Base32 and Base64, the second type parameter selects the padding policy. The table shows how each policy handles the same byte with the standard Base64 alphabet. + +| Padding policy | Encodes `b"f"` as | Accepts for `b"f"` | +| -------------------------- | ----------------- | ------------------ | +| `policy::Padded` | `Zg==` | `Zg==` | +| `policy::Unpadded` | `Zg` | `Zg` | +| `policy::PaddedOptional` | `Zg==` | `Zg==`, `Zg` | +| `policy::UnpaddedOptional` | `Zg` | `Zg==`, `Zg` | + +For example, use `base64::Base64` for gRPC binary metadata. Both optional policies reject partial padding such as `Zg=`, excess padding, and non-zero unused trailing bits. ## API layers and features diff --git a/bases/src/base32.rs b/bases/src/base32.rs index b4b2fd9..0027206 100644 --- a/bases/src/base32.rs +++ b/bases/src/base32.rs @@ -48,8 +48,8 @@ use crate::io::EncoderWriter; use crate::policy; use crate::policy::sealed::DecodeCasePolicy; use crate::policy::sealed::LetterCase; -use crate::policy::sealed::PaddingMode; use crate::policy::sealed::PaddingPolicy; +use crate::policy::sealed::profile_name; #[cfg(feature = "serde")] use crate::serde; @@ -81,8 +81,8 @@ pub(crate) mod sealed { /// [`Standard`]), padding policy (`Padding`, defaulting to /// [`policy::Padded`]), encoded letter case (`Case`, defaulting to /// [`policy::Upper`]), and decoding case policy (`DecodeCase`, defaulting to -/// [`policy::Strict`]). Use [`policy::OptionalPadding`] to emit unpadded text and accept -/// both canonical padding forms. +/// [`policy::Strict`]). Use [`policy::PaddedOptional`] or [`policy::UnpaddedOptional`] to accept +/// both input forms while emitting padded or unpadded output, respectively. pub struct Base32< Alphabet = Standard, Padding = policy::Padded, @@ -146,36 +146,15 @@ where #[must_use] #[inline] pub const fn name() -> &'static str { - match ( - Alphabet::EXTENDED_HEX, - Padding::MODE, - Case::UPPERCASE, - DecodeCase::STRICT, - ) { - (false, PaddingMode::Required, true, true) => "base32", - (false, PaddingMode::Forbidden, true, true) => "base32-unpadded", - (false, PaddingMode::Optional, true, true) => "base32-optional-padding", - (false, PaddingMode::Required, false, true) => "base32-lower", - (false, PaddingMode::Forbidden, false, true) => "base32-lower-unpadded", - (false, PaddingMode::Optional, false, true) => "base32-lower-optional-padding", - (false, PaddingMode::Required, true, false) => "base32-mixed", - (false, PaddingMode::Forbidden, true, false) => "base32-mixed-unpadded", - (false, PaddingMode::Optional, true, false) => "base32-mixed-optional-padding", - (false, PaddingMode::Required, false, false) => "base32-lower-mixed", - (false, PaddingMode::Forbidden, false, false) => "base32-lower-mixed-unpadded", - (false, PaddingMode::Optional, false, false) => "base32-lower-mixed-optional-padding", - (true, PaddingMode::Required, true, true) => "base32hex", - (true, PaddingMode::Forbidden, true, true) => "base32hex-unpadded", - (true, PaddingMode::Optional, true, true) => "base32hex-optional-padding", - (true, PaddingMode::Required, false, true) => "base32hex-lower", - (true, PaddingMode::Forbidden, false, true) => "base32hex-lower-unpadded", - (true, PaddingMode::Optional, false, true) => "base32hex-lower-optional-padding", - (true, PaddingMode::Required, true, false) => "base32hex-mixed", - (true, PaddingMode::Forbidden, true, false) => "base32hex-mixed-unpadded", - (true, PaddingMode::Optional, true, false) => "base32hex-mixed-optional-padding", - (true, PaddingMode::Required, false, false) => "base32hex-lower-mixed", - (true, PaddingMode::Forbidden, false, false) => "base32hex-lower-mixed-unpadded", - (true, PaddingMode::Optional, false, false) => "base32hex-lower-mixed-optional-padding", + match (Alphabet::EXTENDED_HEX, Case::UPPERCASE, DecodeCase::STRICT) { + (false, true, true) => profile_name!("base32", Padding), + (false, false, true) => profile_name!("base32-lower", Padding), + (false, true, false) => profile_name!("base32-mixed", Padding), + (false, false, false) => profile_name!("base32-lower-mixed", Padding), + (true, true, true) => profile_name!("base32hex", Padding), + (true, false, true) => profile_name!("base32hex-lower", Padding), + (true, true, false) => profile_name!("base32hex-mixed", Padding), + (true, false, false) => profile_name!("base32hex-lower-mixed", Padding), } } @@ -423,7 +402,7 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 5; const ENCODED_QUANTUM: usize = 8; - const ACCEPTS_PADDING: bool = !matches!(Padding::MODE, PaddingMode::Forbidden); + const ACCEPTS_PADDING: bool = Padding::ACCEPTS_PADDING; #[inline] fn encoded_len_impl(input_len: usize) -> Option { @@ -441,7 +420,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::MODE.decode_padded(input) { + if Padding::decode_padded(input) { backend::base32::decode_plan::(input) } else { backend::base32::decode_plan::(input) @@ -547,7 +526,7 @@ where fn decode_in_place_impl(buf: &mut [u8]) -> Result { match ( Alphabet::EXTENDED_HEX, - Padding::MODE.decode_padded(buf), + Padding::decode_padded(buf), Case::UPPERCASE, DecodeCase::STRICT, ) { diff --git a/bases/src/base64.rs b/bases/src/base64.rs index d5bae73..104bffb 100644 --- a/bases/src/base64.rs +++ b/bases/src/base64.rs @@ -46,8 +46,8 @@ use crate::io::DecoderReader; #[cfg(feature = "std")] use crate::io::EncoderWriter; use crate::policy; -use crate::policy::sealed::PaddingMode; use crate::policy::sealed::PaddingPolicy; +use crate::policy::sealed::profile_name; #[cfg(feature = "serde")] use crate::serde; @@ -77,8 +77,8 @@ pub(crate) mod sealed { /// /// The type parameters select the alphabet (`Alphabet`, defaulting to /// [`Standard`]) and padding policy (`Padding`, defaulting to -/// [`policy::Padded`]). Use [`policy::OptionalPadding`] to emit unpadded text and accept -/// both canonical padding forms. +/// [`policy::Padded`]). Use [`policy::PaddedOptional`] or [`policy::UnpaddedOptional`] to accept +/// both input forms while emitting padded or unpadded output, respectively. pub struct Base64(PhantomData<(Alphabet, Padding)>); impl Clone for Base64 { @@ -131,13 +131,10 @@ where #[must_use] #[inline] pub const fn name() -> &'static str { - match (Alphabet::URL_SAFE, Padding::MODE) { - (false, PaddingMode::Required) => "base64", - (false, PaddingMode::Forbidden) => "base64-unpadded", - (false, PaddingMode::Optional) => "base64-optional-padding", - (true, PaddingMode::Required) => "base64url", - (true, PaddingMode::Forbidden) => "base64url-unpadded", - (true, PaddingMode::Optional) => "base64url-optional-padding", + if Alphabet::URL_SAFE { + profile_name!("base64url", Padding) + } else { + profile_name!("base64", Padding) } } @@ -383,7 +380,7 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 3; const ENCODED_QUANTUM: usize = 4; - const ACCEPTS_PADDING: bool = !matches!(Padding::MODE, PaddingMode::Forbidden); + const ACCEPTS_PADDING: bool = Padding::ACCEPTS_PADDING; #[inline] fn encoded_len_impl(input_len: usize) -> Option { @@ -401,7 +398,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::MODE.decode_padded(input) { + if Padding::decode_padded(input) { backend::base64::decode_plan::(input) } else { backend::base64::decode_plan::(input) @@ -454,7 +451,7 @@ where #[inline] fn decode_in_place_impl(buf: &mut [u8]) -> Result { - match (Alphabet::URL_SAFE, Padding::MODE.decode_padded(buf)) { + match (Alphabet::URL_SAFE, Padding::decode_padded(buf)) { (false, false) => backend::base64::decode_in_place::(buf), (false, true) => backend::base64::decode_in_place::(buf), (true, false) => backend::base64::decode_in_place::(buf), diff --git a/bases/src/lib.rs b/bases/src/lib.rs index 8fbe3e2..1d4a17b 100644 --- a/bases/src/lib.rs +++ b/bases/src/lib.rs @@ -61,6 +61,10 @@ //! profile exposes inherent methods directly without requiring trait imports, and implements the //! sealed [`Codec`] trait for generic callers. //! +//! To decode both fully padded and unpadded Base32 or Base64 input, choose +//! [`policy::PaddedOptional`] for padded output or [`policy::UnpaddedOptional`] for unpadded +//! output. +//! //! # API layers //! //! - **Sizing and caller buffers (`no_std`)**: `encoded_len`, `max_decoded_len`, `encode_into`, diff --git a/bases/src/policy.rs b/bases/src/policy.rs index 1dc62f0..f438877 100644 --- a/bases/src/policy.rs +++ b/bases/src/policy.rs @@ -13,8 +13,28 @@ // limitations under the License. //! Policy markers for encoding and decoding profiles. - -use crate::policy::sealed::PaddingMode; +//! +//! For Base32 and Base64, [`PaddedOptional`] and [`UnpaddedOptional`] select the encoded +//! output. Both accept input with complete padding or with the padding omitted. +//! +//! ``` +//! use bases::base64; +//! use bases::policy; +//! +//! type Padded = base64::Base64; +//! type Unpadded = base64::Base64; +//! +//! let mut output = [0; 4]; +//! assert_eq!(Padded::encode_into(b"f", &mut output).unwrap(), "Zg=="); +//! assert_eq!(Unpadded::encode_into(b"f", &mut output).unwrap(), "Zg"); +//! +//! for input in ["Zg", "Zg=="] { +//! assert_eq!(Padded::decode_array(input), Ok(*b"f")); +//! assert_eq!(Unpadded::decode_array(input), Ok(*b"f")); +//! } +//! assert!(Padded::decode_array::<1>("Zg=").is_err()); +//! assert!(Unpadded::decode_array::<1>("Zg=").is_err()); +//! ``` /// Padding policy that requires and emits canonical `=` padding. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] @@ -24,24 +44,19 @@ pub struct Padded; #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] pub struct Unpadded; -/// Omits padding when encoding and accepts either complete canonical padding or none when decoding. -/// -/// For example, gRPC binary metadata uses this policy with the standard Base64 alphabet. -/// -/// ``` -/// use bases::base64; -/// use bases::policy; +/// Emits canonical `=` padding. Decoding accepts complete padding or none. /// -/// type Metadata = base64::Base64; +/// For example, standard Base64 encodes `b"f"` as `Zg==` and accepts both `Zg==` and `Zg`. +/// Partial padding such as `Zg=` is invalid. See [`UnpaddedOptional`] for unpadded output. +#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] +pub struct PaddedOptional; + +/// Omits `=` padding. Decoding accepts complete padding or none. /// -/// let mut output = [0; 4]; -/// assert_eq!(Metadata::encode_into(b"f", &mut output).unwrap(), "Zg"); -/// assert_eq!(Metadata::decode_array("Zg"), Ok(*b"f")); -/// assert_eq!(Metadata::decode_array("Zg=="), Ok(*b"f")); -/// assert!(Metadata::decode_array::<1>("Zg=").is_err()); -/// ``` +/// For example, standard Base64 encodes `b"f"` as `Zg` and accepts both `Zg` and `Zg==`. +/// Partial padding such as `Zg=` is invalid. See [`PaddedOptional`] for padded output. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] -pub struct OptionalPadding; +pub struct UnpaddedOptional; /// Letter case policy that emits lowercase ASCII letters. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] @@ -60,15 +75,23 @@ pub struct Mixed; pub struct Strict; impl sealed::PaddingPolicy for Padded { - const MODE: PaddingMode = PaddingMode::Required; + const EMIT_PADDING: bool = true; + const DECODE_PADDING_OPTIONAL: bool = false; } impl sealed::PaddingPolicy for Unpadded { - const MODE: PaddingMode = PaddingMode::Forbidden; + const EMIT_PADDING: bool = false; + const DECODE_PADDING_OPTIONAL: bool = false; } -impl sealed::PaddingPolicy for OptionalPadding { - const MODE: PaddingMode = PaddingMode::Optional; +impl sealed::PaddingPolicy for PaddedOptional { + const EMIT_PADDING: bool = true; + const DECODE_PADDING_OPTIONAL: bool = true; +} + +impl sealed::PaddingPolicy for UnpaddedOptional { + const EMIT_PADDING: bool = false; + const DECODE_PADDING_OPTIONAL: bool = true; } impl sealed::LetterCase for Lower { @@ -88,28 +111,35 @@ impl sealed::DecodeCasePolicy for Strict { } pub(crate) mod sealed { - #[derive(Clone, Copy)] - pub enum PaddingMode { - Required, - Forbidden, - Optional, - } + pub trait PaddingPolicy: 'static { + const EMIT_PADDING: bool; + const DECODE_PADDING_OPTIONAL: bool; + const ACCEPTS_PADDING: bool = Self::EMIT_PADDING || Self::DECODE_PADDING_OPTIONAL; - impl PaddingMode { #[inline] - pub fn decode_padded(self, input: &[u8]) -> bool { - match self { - Self::Required => true, - Self::Forbidden => false, - Self::Optional => input.last() == Some(&b'='), + fn decode_padded(input: &[u8]) -> bool { + if Self::DECODE_PADDING_OPTIONAL { + input.last() == Some(&b'=') + } else { + Self::EMIT_PADDING } } } - pub trait PaddingPolicy: 'static { - const MODE: PaddingMode; - const EMIT_PADDING: bool = matches!(Self::MODE, PaddingMode::Required); + macro_rules! profile_name { + ($base:literal, $padding:ty) => { + match ( + <$padding>::EMIT_PADDING, + <$padding>::DECODE_PADDING_OPTIONAL, + ) { + (true, false) => $base, + (false, false) => concat!($base, "-unpadded"), + (true, true) => concat!($base, "-padded-optional"), + (false, true) => concat!($base, "-unpadded-optional"), + } + }; } + pub(crate) use profile_name; pub trait LetterCase: 'static { const UPPERCASE: bool; diff --git a/tests-integration/tests/contracts.rs b/tests-integration/tests/contracts.rs index 92ae9ce..7b0813d 100644 --- a/tests-integration/tests/contracts.rs +++ b/tests-integration/tests/contracts.rs @@ -64,48 +64,66 @@ fn payload(len: usize) -> Vec { #[test] fn optional_padding_accepts_only_canonical_tail_lengths() { - fn check(reference: &Encoding) { + fn check_decode(wire: &str, expected: Option<&[u8]>) { + let mut out = vec![0; C::max_decoded_len(wire.len())]; + assert_eq!( + C::decode_into(wire, &mut out).ok().as_deref(), + expected, + "{wire}" + ); + let mut in_place = wire.as_bytes().to_vec(); + assert_eq!( + C::decode_in_place(&mut in_place).ok().as_deref(), + expected, + "{wire}" + ); + for chunk in 1..=wire.len().max(1) { + assert_eq!( + streaming::decode::(wire.as_bytes(), chunk) + .ok() + .as_deref(), + expected, + "{wire}, chunk {chunk}" + ); + } + } + + fn check(reference: &Encoding) { for len in 0..=10 { let raw = payload(len); let padded = reference.encode(&raw); let bare = padded.trim_end_matches('='); - assert_eq!(C::encode(&raw), bare); + assert_eq!(Padded::encode(&raw), padded); + assert_eq!(Unpadded::encode(&raw), bare); + assert_eq!(streaming::encode::(&raw, 1), padded); + assert_eq!(streaming::encode::(&raw, 1), bare); let required = padded.len() - bare.len(); for count in 0..=required + 1 { let wire = format!("{bare}{}", "=".repeat(count)); let expected = (count == 0 || count == required).then_some(raw.as_slice()); - let mut out = vec![0; C::max_decoded_len(wire.len())]; - assert_eq!( - C::decode_into(&wire, &mut out).ok().as_deref(), - expected, - "{wire}" - ); - let mut in_place = wire.as_bytes().to_vec(); - assert_eq!( - C::decode_in_place(&mut in_place).ok().as_deref(), - expected, - "{wire}" - ); - for chunk in 1..=wire.len().max(1) { - assert_eq!( - streaming::decode::(wire.as_bytes(), chunk) - .ok() - .as_deref(), - expected, - "{wire}, chunk {chunk}" - ); - } + check_decode::(&wire, expected); + check_decode::(&wire, expected); } } } - check::>(&data_encoding::BASE64); - check::>(&data_encoding::BASE64URL); - check::>(&data_encoding::BASE32); - check::>( - &data_encoding::BASE32HEX, - ); + check::< + base64::Base64, + base64::Base64, + >(&data_encoding::BASE64); + check::< + base64::Base64, + base64::Base64, + >(&data_encoding::BASE64URL); + check::< + base32::Base32, + base32::Base32, + >(&data_encoding::BASE32); + check::< + base32::Base32, + base32::Base32, + >(&data_encoding::BASE32HEX); } macro_rules! profile { diff --git a/tests-integration/tests/contracts/malformed.rs b/tests-integration/tests/contracts/malformed.rs index 896fed8..a2f7a14 100644 --- a/tests-integration/tests/contracts/malformed.rs +++ b/tests-integration/tests/contracts/malformed.rs @@ -28,8 +28,8 @@ use crate::streaming; #[test] fn optional_padding_preserves_alphabet_and_trailing_bit_errors() { - type Base64 = base64::Base64; - type Base32 = base32::Base32; + type Base64 = base64::Base64; + type Base32 = base32::Base32; for wire in [b"Zm9vZh".as_slice(), b"Zm9vZh=="] { assert_error::(wire, DecodeError::NonCanonical { index: 5 }); diff --git a/tests-integration/tests/contracts/streaming.rs b/tests-integration/tests/contracts/streaming.rs index d69af37..6df1ab5 100644 --- a/tests-integration/tests/contracts/streaming.rs +++ b/tests-integration/tests/contracts/streaming.rs @@ -54,7 +54,7 @@ pub fn check(reference: &Encoding) { retry_invalid_update::(reference); } -fn encode(raw: &[u8], chunk: usize) -> String { +pub fn encode(raw: &[u8], chunk: usize) -> String { let mut encoder = C::encoder(); let mut encoded = String::new(); for part in raw.chunks(chunk) { From a99488765207d88cfb0ed531b1a3d20ab26229ae Mon Sep 17 00:00:00 2001 From: tison Date: Wed, 18 Nov 2026 21:20:06 +0800 Subject: [PATCH 3/3] refactor: model decode padding as a three-state policy Base32 and Base64 each choose an output format and an input padding rule. Make the two choices explicit on each marker with ENCODE_PADDED and DECODE_PADDING. The decoder can then distinguish required, forbidden and optional padding directly. Use the input rule to select the strict validator for one-shot and in-place decoding. Match the same rule in the streaming decoder so it recognizes a padded final quantum even when the encoder omits padding. This removes the derived ACCEPTS_PADDING constant from both the padding policy and the codec profile. --- bases/src/base16.rs | 3 ++- bases/src/base32.rs | 13 ++++----- bases/src/base64.rs | 16 +++++++----- bases/src/codec.rs | 3 ++- bases/src/policy.rs | 64 ++++++++++++++++++++++++++------------------- bases/src/stream.rs | 10 +++---- 6 files changed, 63 insertions(+), 46 deletions(-) diff --git a/bases/src/base16.rs b/bases/src/base16.rs index e718f3f..558a3ed 100644 --- a/bases/src/base16.rs +++ b/bases/src/base16.rs @@ -47,6 +47,7 @@ use crate::io::DecoderReader; use crate::io::EncoderWriter; use crate::policy; use crate::policy::sealed::DecodeCasePolicy; +use crate::policy::sealed::DecodePadding; use crate::policy::sealed::LetterCase; #[cfg(feature = "serde")] use crate::serde; @@ -355,7 +356,7 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 1; const ENCODED_QUANTUM: usize = 2; - const ACCEPTS_PADDING: bool = false; + const DECODE_PADDING: DecodePadding = DecodePadding::Forbidden; #[inline] fn encoded_len_impl(input_len: usize) -> Option { diff --git a/bases/src/base32.rs b/bases/src/base32.rs index 0027206..578fece 100644 --- a/bases/src/base32.rs +++ b/bases/src/base32.rs @@ -47,6 +47,7 @@ use crate::io::DecoderReader; use crate::io::EncoderWriter; use crate::policy; use crate::policy::sealed::DecodeCasePolicy; +use crate::policy::sealed::DecodePadding; use crate::policy::sealed::LetterCase; use crate::policy::sealed::PaddingPolicy; use crate::policy::sealed::profile_name; @@ -167,7 +168,7 @@ where /// that a buffer of that size can be allocated. #[inline] pub const fn encoded_len(input_len: usize) -> Result { - let len = if Padding::EMIT_PADDING { + let len = if Padding::ENCODE_PADDED { backend::base32::encoded_len::(input_len) } else { backend::base32::encoded_len::(input_len) @@ -402,11 +403,11 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 5; const ENCODED_QUANTUM: usize = 8; - const ACCEPTS_PADDING: bool = Padding::ACCEPTS_PADDING; + const DECODE_PADDING: DecodePadding = Padding::DECODE_PADDING; #[inline] fn encoded_len_impl(input_len: usize) -> Option { - if Padding::EMIT_PADDING { + if Padding::ENCODE_PADDED { backend::base32::encoded_len::(input_len) } else { backend::base32::encoded_len::(input_len) @@ -420,7 +421,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::decode_padded(input) { + if Padding::DECODE_PADDING.uses_padded_decoder(input) { backend::base32::decode_plan::(input) } else { backend::base32::decode_plan::(input) @@ -431,7 +432,7 @@ where fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { match ( Alphabet::EXTENDED_HEX, - Padding::EMIT_PADDING, + Padding::ENCODE_PADDED, Case::UPPERCASE, ) { (false, false, false) => backend::base32::encode::(input, output), @@ -526,7 +527,7 @@ where fn decode_in_place_impl(buf: &mut [u8]) -> Result { match ( Alphabet::EXTENDED_HEX, - Padding::decode_padded(buf), + Padding::DECODE_PADDING.uses_padded_decoder(buf), Case::UPPERCASE, DecodeCase::STRICT, ) { diff --git a/bases/src/base64.rs b/bases/src/base64.rs index 104bffb..4cda078 100644 --- a/bases/src/base64.rs +++ b/bases/src/base64.rs @@ -46,6 +46,7 @@ use crate::io::DecoderReader; #[cfg(feature = "std")] use crate::io::EncoderWriter; use crate::policy; +use crate::policy::sealed::DecodePadding; use crate::policy::sealed::PaddingPolicy; use crate::policy::sealed::profile_name; #[cfg(feature = "serde")] @@ -147,7 +148,7 @@ where /// that a buffer of that size can be allocated. #[inline] pub const fn encoded_len(input_len: usize) -> Result { - let len = if Padding::EMIT_PADDING { + let len = if Padding::ENCODE_PADDED { backend::base64::encoded_len::(input_len) } else { backend::base64::encoded_len::(input_len) @@ -380,11 +381,11 @@ where const NAME: &'static str = Self::name(); const INPUT_QUANTUM: usize = 3; const ENCODED_QUANTUM: usize = 4; - const ACCEPTS_PADDING: bool = Padding::ACCEPTS_PADDING; + const DECODE_PADDING: DecodePadding = Padding::DECODE_PADDING; #[inline] fn encoded_len_impl(input_len: usize) -> Option { - if Padding::EMIT_PADDING { + if Padding::ENCODE_PADDED { backend::base64::encoded_len::(input_len) } else { backend::base64::encoded_len::(input_len) @@ -398,7 +399,7 @@ where #[inline] fn decode_plan_impl(input: &[u8]) -> Result { - if Padding::decode_padded(input) { + if Padding::DECODE_PADDING.uses_padded_decoder(input) { backend::base64::decode_plan::(input) } else { backend::base64::decode_plan::(input) @@ -407,7 +408,7 @@ where #[inline] fn encode_impl(input: &[u8], output: &mut [MaybeUninit]) -> usize { - match (Alphabet::URL_SAFE, Padding::EMIT_PADDING) { + match (Alphabet::URL_SAFE, Padding::ENCODE_PADDED) { (false, false) => backend::base64::encode::(input, output), (false, true) => backend::base64::encode::(input, output), (true, false) => backend::base64::encode::(input, output), @@ -451,7 +452,10 @@ where #[inline] fn decode_in_place_impl(buf: &mut [u8]) -> Result { - match (Alphabet::URL_SAFE, Padding::decode_padded(buf)) { + match ( + Alphabet::URL_SAFE, + Padding::DECODE_PADDING.uses_padded_decoder(buf), + ) { (false, false) => backend::base64::decode_in_place::(buf), (false, true) => backend::base64::decode_in_place::(buf), (true, false) => backend::base64::decode_in_place::(buf), diff --git a/bases/src/codec.rs b/bases/src/codec.rs index 2dd7cf3..0c39453 100644 --- a/bases/src/codec.rs +++ b/bases/src/codec.rs @@ -591,6 +591,7 @@ pub(crate) mod sealed { use crate::DecodeError; use crate::backend::DecodePlan; + use crate::policy::sealed::DecodePadding; /// A direct `Codec: Profile` bound would let downstream generic code skip /// padding and output-capacity checks: @@ -619,7 +620,7 @@ pub(crate) mod sealed { const NAME: &'static str; const INPUT_QUANTUM: usize; const ENCODED_QUANTUM: usize; - const ACCEPTS_PADDING: bool; + const DECODE_PADDING: DecodePadding; fn encoded_len_impl(input_len: usize) -> Option; fn max_decoded_len_impl(input_len: usize) -> usize; diff --git a/bases/src/policy.rs b/bases/src/policy.rs index f438877..7c7feca 100644 --- a/bases/src/policy.rs +++ b/bases/src/policy.rs @@ -36,6 +36,8 @@ //! assert!(Unpadded::decode_array::<1>("Zg=").is_err()); //! ``` +use crate::policy::sealed::DecodePadding; + /// Padding policy that requires and emits canonical `=` padding. #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)] pub struct Padded; @@ -75,23 +77,23 @@ pub struct Mixed; pub struct Strict; impl sealed::PaddingPolicy for Padded { - const EMIT_PADDING: bool = true; - const DECODE_PADDING_OPTIONAL: bool = false; + const ENCODE_PADDED: bool = true; + const DECODE_PADDING: DecodePadding = DecodePadding::Required; } impl sealed::PaddingPolicy for Unpadded { - const EMIT_PADDING: bool = false; - const DECODE_PADDING_OPTIONAL: bool = false; + const ENCODE_PADDED: bool = false; + const DECODE_PADDING: DecodePadding = DecodePadding::Forbidden; } impl sealed::PaddingPolicy for PaddedOptional { - const EMIT_PADDING: bool = true; - const DECODE_PADDING_OPTIONAL: bool = true; + const ENCODE_PADDED: bool = true; + const DECODE_PADDING: DecodePadding = DecodePadding::Optional; } impl sealed::PaddingPolicy for UnpaddedOptional { - const EMIT_PADDING: bool = false; - const DECODE_PADDING_OPTIONAL: bool = true; + const ENCODE_PADDED: bool = false; + const DECODE_PADDING: DecodePadding = DecodePadding::Optional; } impl sealed::LetterCase for Lower { @@ -111,33 +113,41 @@ impl sealed::DecodeCasePolicy for Strict { } pub(crate) mod sealed { - pub trait PaddingPolicy: 'static { - const EMIT_PADDING: bool; - const DECODE_PADDING_OPTIONAL: bool; - const ACCEPTS_PADDING: bool = Self::EMIT_PADDING || Self::DECODE_PADDING_OPTIONAL; + #[derive(Clone, Copy)] + pub enum DecodePadding { + Required, + Forbidden, + Optional, + } + impl DecodePadding { #[inline] - fn decode_padded(input: &[u8]) -> bool { - if Self::DECODE_PADDING_OPTIONAL { - input.last() == Some(&b'=') - } else { - Self::EMIT_PADDING + pub fn uses_padded_decoder(self, input: &[u8]) -> bool { + match self { + Self::Required => true, + Self::Forbidden => false, + Self::Optional => input.last() == Some(&b'='), } } } + pub trait PaddingPolicy: 'static { + const ENCODE_PADDED: bool; + const DECODE_PADDING: DecodePadding; + } + macro_rules! profile_name { - ($base:literal, $padding:ty) => { - match ( - <$padding>::EMIT_PADDING, - <$padding>::DECODE_PADDING_OPTIONAL, - ) { - (true, false) => $base, - (false, false) => concat!($base, "-unpadded"), - (true, true) => concat!($base, "-padded-optional"), - (false, true) => concat!($base, "-unpadded-optional"), + ($base:literal, $padding:ty) => {{ + use $crate::policy::sealed::DecodePadding; + match <$padding>::DECODE_PADDING { + DecodePadding::Required => $base, + DecodePadding::Forbidden => concat!($base, "-unpadded"), + DecodePadding::Optional if <$padding>::ENCODE_PADDED => { + concat!($base, "-padded-optional") + } + DecodePadding::Optional => concat!($base, "-unpadded-optional"), } - }; + }}; } pub(crate) use profile_name; diff --git a/bases/src/stream.rs b/bases/src/stream.rs index 6db7695..ae886b2 100644 --- a/bases/src/stream.rs +++ b/bases/src/stream.rs @@ -23,6 +23,7 @@ use crate::FinishError; use crate::backend::DecodePlan; use crate::codec; use crate::codec::sealed::Profile; +use crate::policy::sealed::DecodePadding; const MAX_INPUT_QUANTUM: usize = 5; const MAX_ENCODED_QUANTUM: usize = 8; @@ -349,15 +350,14 @@ impl Decoder { let process_len = combined_len / encoded_quantum * encoded_quantum; let pending_offset = self.pending_offset(); - let (padding, padding_reduction, padding_index) = if C::Profile::ACCEPTS_PADDING { - analyze_padding::( + let (padding, padding_reduction, padding_index) = match C::Profile::DECODE_PADDING { + DecodePadding::Forbidden => (0, 0, None), + DecodePadding::Required | DecodePadding::Optional => analyze_padding::( &self.pending[..self.pending_len], input, process_len, pending_offset, - )? - } else { - (0, 0, None) + )?, }; let input_quantum = C::Profile::INPUT_QUANTUM;