No good alternative to `decode_config()` in 0.20

[djc]

I'm unhappy about the API changes in 0.20. In my code base at work we have 12 use cases of base64 0.13 encoding and decoding, 9 of which pass a config (mostly URL_SAFE_NO_PAD, some URL_SAFE). Unless I misunderstand the new API (I don't see any examples of this use case in the README or the top-level documentation), in order to obtain the same result with 0.20 I would have to instantiate a custom FastPortable (which, despite being the only engine shipped with 0.20, I have to import from base64::engine::fast_portable::FastPortable) and initialize with base64::alphabet::URL_SAFE and base64::engine::fast_portable::NO_PAD.

Instead of offering a simpler way to do this through a top-level function, 6 of the 9 top-level functions now take an Engine; I would argue that, in case you already have an engine, these could have been methods attached to it.

I understand that the Engine abstraction is useful if you want to introduce a SIMD-backed implementation. I even like the introduction of a separate Alphabet type. I think it doesn't really make sense to have a Config type that doesn't include Alphabet, keeping it separate instead -- the whole point of having a Config type is to make it easy to wrap all the contextual/usually stable input for your main API calls into a single type. But to not offer a top-level API that makes it easy to use different alphabets/config seems to me like a lack of empathy for how this crate is used.

(FWIW, I also think jumping from 0.13 to 0.20 doesn't have much merit.)

[marshallpierce]

First off, thanks for filing feedback. I released the 0.20 alpha precisely to gather feedback, but that didn't produce any... oh well. If 0.20's role is to be the lightning rod, that's ok!
It is a bit baffling, though, to read what appears to be complaining about changing 12 callsites in a codebase. That is not a heavy burden. I don't really understand complaints about module paths, either. You can use them with whatever amount of prefix you want, and if your editor doesn't automatically do that for you, get one that does...? I do regret shipping with the FastPortable name, though -- I intended to change that before release but it slipped my mind.

I hadn't moved things to be methods on Engine to avoid perturbing the API too much, but I'm not opposed to it.

I went back and forth during development about if FastPortable's config should include an Alphabet, actually, and I think it's viable either way. However, if the goal is to have one thing that joins a Config with an Alphabet, isn't Engine that thing? You create it ahead of time and re-use it. It encapsulates all the behavior in one type.

My intent with the jump from 0.13 to 0.20 was to signal the user that it's a major change in the API, which it obviously is given you filing this issue. ;)

[djc]

It is a bit baffling, though, to read what appears to be complaining about changing 12 callsites in a codebase. That is not a heavy burden.

Right now in most of my usage sites I don't need to import anything, which is an aspect of the previous API I appreciated. The names FastPortable, Config and Alphabet are opaque enough that I'd probably not want to import them as is, but would rename them (since they're too deeply nested in the crate's public API to use prefixed). Compared to the previous API, you've just added a bunch of boilerplate required to make calls to your API.

You create it ahead of time and re-use it.

My 12 uses are in 7 files across 4 different crates, so reusing it would need a bunch of different infrastructure.

My intent with the jump from 0.13 to 0.20 was to signal the user that it's a major change in the API, which it obviously is given you filing this issue. ;)

A one number minor version bump is used by every other 0.x crate out there, so it's a well-established standard. I don't recall any other crate having done a more-than-one minor bump.

If you want to get early feedback on new API, I'd recommend instead adding it in a compatible release and deprecating the old API.

[marshallpierce]

added a bunch of boilerplate required to make calls to your API

If "not needing to import anything" is how you judge your libraries, I think we are not going to see eye to eye. The language gives you the ability to rename types at use-time, so while I'm open to suggestions for better names, in the meantime I encourage to make use of that ability.

reusing it would need a bunch of different infrastructure.

How is that any different than sharing a custom 0.13 Config across crates?

A one number minor version bump is used by every other 0.x crate out there, so it's a well-established standard. I don't recall any other crate having done a more-than-one minor bump.

Complaining about incrementing a vaguely-meaningful number by 7 instead of 1 is making it hard to take you seriously.

[djc]

How is that any different than sharing a custom 0.13 Config across crates?

With 0.13 I didn't need a custom Config, I just used the pre-defined configs that the API exposed.

[Thomasdezeeuw]

If "not needing to import anything" is how you judge your libraries, I think we are not going to see eye to eye. The language gives you the ability to rename types at use-time, so while I'm open to suggestions for better names, in the meantime I encourage to make use of that ability.

I think what @djc is trying to say is that going from base64::decode_config(input, base64::STANDARD_NO_PAD) to a multi line setup is not an improvement.

reusing it would need a bunch of different infrastructure.

How is that any different than sharing a custom 0.13 Config across crates?

Because the Config came with v0.13

A one number minor version bump is used by every other 0.x crate out there, so it's a well-established standard. I don't recall any other crate having done a more-than-one minor bump.

Complaining about incrementing a vaguely-meaningful number by 7 instead of 1 is making it hard to take you seriously.

The problem isn't really the 7 vs 1 jump, it's the breaking of the semver convention. When I saw the jump I though I missed a large number of releases.

[marshallpierce]

With 0.13 I didn't need a custom Config, I just used the pre-defined configs that the API exposed.

That's not really viable now that there is an additional axis of choice. I want users to understand specifically what their API calls are doing.

[msrd0]

That's not really viable now that there is an additional axis of choice. I want users to understand specifically what their API calls are doing.

I don't necessarily want to understand the inner workings of this crate if all I want is a base64 url-encoded unpadded string.

[marshallpierce]

I think what @djc is trying to say is that going from base64::decode_config(input, base64::STANDARD_NO_PAD) to a multi line setup is not an improvement.

Lines of code is a poor metric for quality. I agree that all other things being equal, shorter is better, but all other things are not equal.

[marshallpierce]

I don't necessarily want to understand the inner workings of this crate if all I want is a base64 url-encoded unpadded string.

Hyperbole much? You're welcome to provide concrete suggestions for different API.

[djc]

That's not really viable now that there is an additional axis of choice. I want users to understand specifically what their API calls are doing.

What specifically do you think is so important that users understand? I would like to do url-safe base64 encoding/decoding without padding. Why do you want me to understand what Engine I am using, when the only option beside the default engine is one that I supply myself? Even if you offer a SIMD-enabled engine in the future, making your users select one or the other (as presumably there will be trade-offs) is mostly an anti-pattern in terms of API design, ideally I'd be able to pick a config (and potentially input) and you decide for me which engine is best.

Hyperbole much? You're welcome to provide concrete suggestions for different API.

Given that FastPortable has a const new() anyway, why not provide some of the popular default options as a const DEFAULT: FastPortable in the root of the crate, similar to what you had in 0.13?

Lines of code is a poor metric for quality. I agree that all other things being equal, shorter is better, but all other things are not equal.

I'm honestly not being adversarial, but I fail to see how things are not equal right now.

[msrd0]

Hyperbole much?

I didn't mean to say this in a way that upsets you, and generally I appreciate you making this crate as versatile as possibly, allowing different engines and whatnot.

However, the way I've been using this crate is as a simple utility to create standard base64 encoded strings and url-safe base64 encoded strings. This was easy as all I had to do was calling encode or calling encode_config with the url-safe config you provided in this crate.

With the new API, this gets a lot more complex. I now need to create my own engine with the alphabet that I want, and a custom config that specifies whether I want padding or not. This makes the API more complex, harder to learn (as I now need to learn about the differences between engines, alphabet and config (and I'm not criticizing their existence)), and more verbose on my side.

You're welcome to provide concrete suggestions for different API.

I'd appreciate an API that lets me choose the alphabet and padding without creating my own engine. For example

fn decode_config(input: &str, alphabet: &Alphabet, padding: &Padding) -> Result<Vec<u8>>;

Alternatively, you could also add more pre-defined engines with popular combinations, like url-safe or unpadded.

Additionally, I suggest adding an example for url-safe base64 en/decoding to the documentation.

[zonyitoo]

I am totally agree with the discussion above. For most users, they don't actually need to choose which Engine the library were using to perform encode/decode, what they just want is an API that could input a string and then output a string, the library should choose the most effective way.

I understand the necessary of the abstraction of Engine, but this is really not most users want. I don't believe there are many users want to customize:

• whether to use SIMD engine or pure Rust engine
• character set

Most users should want to use those standardized formats:

• standard base64
• standard base64 url
• standard base64 url without padding

I prefer having an API that @msrd0 proposed.