Support ECMA262's `proposal-arraybuffer-base64`

[jedel1043]

Hello! At Boa (Javascript engine) we were trying to find a good and performant base64 encoding and decoding library to implement the arraybuffer-base64 proposal. We stumbled upon this library which looked really nice, but we encountered some limitations on its available encoding options. I'll let @magic-akari's comment speak for itself:

The main missing feature is LastChunkHandlingOptions. Currently, data-encoding only offers two padding modes: None and Some, both of which enforce strict padding validation.
However, the ECMA-262 spec requires three distinct modes: strict("="), loose("="), and StopBeforePartial.
Our current implementation works around this limitation by checking for the presence of = in the input beforehand to toggle between Some("=") and None. Having native loose("=") support in data-encoding would eliminate this hack.
There's another subtle issue: ECMA-262 disallows concatenated padded inputs, but data-encoding with padding enabled accepts them. A proper loose mode shouldn't just be a binary switch—it needs to reject concatenated padded inputs to match the spec.

We're open to help implement those missing features, but we wanted to ask first if those didn't conflict with any plans for the development of this library. Thank you!

[ia0]

Thanks for the issue! This is interesting and definitely something worth looking into for v3 (#106). Note that the PadConcat versus PadFinal distinction is already planned. I've added this new notion of PadLoose.

A temporary workaround would be to implement this feature on your side like so:

/// Decodes `input` in `output` with custom last chunk handling
///
/// The `nopad` and `padded` parameters must be either:
/// - `BASE64_NOPAD` and `BASE64`, or
/// - `BASE64URL_NOPAD` and `BASE64URL`.
///
/// The `strict` parameter specifies the last chunk handling:
/// - `Some(true)` means "strict"
/// - `Some(false)` means "loose"
/// - `None` means "stop-before-partial"
///
/// The `output` parameter must be:
/// - exactly `nopad.decode_len(input.len())` long in "loose" mode
/// - exactly `padded.decode_len(input.len())` long in "strict" mode
/// - exactly `input.len() / 4 * 3` long in "stop-before-partial" mode
///
/// Note that in "stop-before-partial" mode, the input may be partially read. The number of bytes
/// actually decoded is `input.len() / 4 * 4`.
fn decode_mut(
    nopad: &Encoding, padded: &Encoding, input: &[u8], output: &mut [u8], strict: Option<bool>,
) -> Result<usize, DecodeError> {
    // Explicitly handle empty input (we rely on it being non-empty below).
    if input.is_empty() {
        return Ok(0);
    }
    // Select the longest prefix of complete blocks except for the last block.
    let ilen = (input.len() - 1) / 4 * 4;
    let olen = ilen / 4 * 3;
    // Decode that prefix without padding to reject concatenated padded inputs.
    match nopad.decode_mut(&input[.. ilen], &mut output[.. olen]) {
        Ok(x) => debug_assert_eq!(x, olen),
        Err(e) => return Err(e.error),
    }
    // Use the appropriate encoding for the last block based on the mode and whether it is partial.
    let partial = input.len() < ilen + 4;
    let base = match (strict, partial) {
        // A complete block is always decoded with padding regardless of the mode.
        (_, false) => padded,
        // A partial block in "strict" mode is a length error, but we let it trigger later.
        (Some(true), true) => padded,
        // A partial block in "loose" mode is decoded without padding.
        (Some(false), true) => nopad,
        // A partial block in "stop-before-partial" mode is not decoded.
        (None, true) => return Ok(olen),
    };
    match base.decode_mut(&input[ilen ..], &mut output[olen ..]) {
        Ok(x) => Ok(olen + x),
        Err(x) => Err(DecodeError { position: ilen + x.error.position, ..x.error }),
    }
}

fn decode(
    nopad: &Encoding, padded: &Encoding, input: &[u8], strict: Option<bool>,
) -> Result<Vec<u8>, DecodeError> {
    let olen = match strict {
        Some(true) => padded.decode_len(input.len())?,
        Some(false) => nopad.decode_len(input.len())?,
        None => input.len() / 4 * 3,
    };
    let mut output = vec![0; olen];
    let olen = decode_mut(nopad, padded, input, &mut output, strict)?;
    output.truncate(olen);
    Ok(output)
}

I don't think this should be added to v2 in that shape (because it takes 2 encodings that must be related and also does not support ignored characters, which ECMA-262 doesn't need), but maybe I find a way to make this more general to be compatible with all existing features of an encoding without being too complicated. So I hope it's fine if you have that code in your code-base (possibly with a small wrapper crate).

Also, if the above code doesn't do exactly what you need, please tell me, I might have misunderstood the ECMA262 logic.