The problem
Consider a careful implementor of some protocol that requires canonical base64 decoding. They notice that in the current implementation as of 0.22.1, the base64::prelude::* engine constants are implemented by calling some permutation of GeneralPurpose::new(&alphabet::{STANDARD,URL_SAFE}, {PAD,NO_PAD}), and that both PAD and NO_PAD are implemented by calling GeneralPurposeConfig::new() which sets decode_allow_trailing_bits to false. And so the decoder checks canonicity for the trailing bits (and also for padding bytes, as documented).
However, they also notice that the fact that these engine configurations will check canonicity of trailing bits on decoding is not documented on any of the prelude constants. It is documented for GeneralPurposeConfig::new(), but the fact that PAD and NO_PAD call that is an implementation detail. And therefore it could change.
So our careful implementor:
a) spends half an hour investigating, and
b) concludes that, despite the fact that is fairly unlikely that this behaviour will change, they still cannot use an engine constant from base64::prelude::*, and will instead have to copy its implementation in terms of a call to GeneralPurposeConfig::new().
(Actually they instead file this ticket in the hope of saving other careful implementors the trouble.)
How I, the issue filer, am going to help solve it
By suggesting to add an explicit statement in the doc comments of prelude::{PAD,NO_PAD} and (redundantly) prelude::{STANDARD,STANDARD_NO_PAD,URL_SAFE,URL_SAFE_NO_PAD}, saying that they check canonicity of trailing bits on decoding.
The problem
Consider a careful implementor of some protocol that requires canonical base64 decoding. They notice that in the current implementation as of 0.22.1, the
base64::prelude::*engine constants are implemented by calling some permutation ofGeneralPurpose::new(&alphabet::{STANDARD,URL_SAFE}, {PAD,NO_PAD}), and that bothPADandNO_PADare implemented by callingGeneralPurposeConfig::new()which setsdecode_allow_trailing_bitstofalse. And so the decoder checks canonicity for the trailing bits (and also for padding bytes, as documented).However, they also notice that the fact that these engine configurations will check canonicity of trailing bits on decoding is not documented on any of the
preludeconstants. It is documented forGeneralPurposeConfig::new(), but the fact thatPADandNO_PADcall that is an implementation detail. And therefore it could change.So our careful implementor:
a) spends half an hour investigating, and
b) concludes that, despite the fact that is fairly unlikely that this behaviour will change, they still cannot use an engine constant from
base64::prelude::*, and will instead have to copy its implementation in terms of a call toGeneralPurposeConfig::new().(Actually they instead file this ticket in the hope of saving other careful implementors the trouble.)
How I, the issue filer, am going to help solve it
By suggesting to add an explicit statement in the doc comments of
prelude::{PAD,NO_PAD}and (redundantly)prelude::{STANDARD,STANDARD_NO_PAD,URL_SAFE,URL_SAFE_NO_PAD}, saying that they check canonicity of trailing bits on decoding.