marshallpierce
The definitions of `prelude` engine constants do not document that the engine will enforce no 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 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.
Sounds like a good idea to me. I'll get to it before the next release, but in the mean time I pinky swear to not ever make decoding less stringent.
