API rework

[marshallpierce]

• Incorporate feedback from No good alternative to decode_config() in 0.20 #205
  • Rename FastPortable
  • Move encode and decode to methods
  • Consts for common engine arrangements
  • Better samples in top level docs
• Doc improvements from Upgrade guide of 0.20 for users used to use config base64::URL_SAFE_NO_PAD #206
  • More details on padding changes (implicit indifferent)
• Error instead of panicking from base64::decode_config_slice should not panic #192

[djmitche]

Thanks for the updated release notes!

[Gelbpunkt]

Hello @marshallpierce,

thanks for this update. I like the concise new API, but there seems to be somewhat of a regression (?) regarding the calculation of output in decode_config_slice.

I've put together an example in this gist. The quick rundown is that I have a websocket implementation that base64-encodes a slice of 20 bytes, which will then be 28 bytes large.

base64 0.13 was able to decode this into a slice with the length 20 just fine, even though it claims to panic if the slice is too small. base64 0.21-beta.2 will error because the length estimate for an input of length 28 returns 21 and it fails early.

I am guessing that this is due to the estimates being conservative, however there is no way for me to decode into a slice of length 20 now, even though it will work! Would it be possible to make the checking of the output length lazy (as I assume that must be how 0.13 did it, I haven't read the source), or adding a method that skips this check and panics instead?

[marshallpierce]

• The *_slice decode/encode functions now return an error instead of panicking when the output slice is too small
  - As part of this, there isn't now a public way to decode into a slice exactly the size needed for inputs that
  aren't multiples of 4 tokens. If adding up to 2 bytes to always be a multiple of 3 bytes for the decode buffer is
  a problem, file an issue.

@Gelbpunkt I see this part has come true. :) I was persuaded in #192 that decode_slice should not panic so that there was a safe way available. However, I don't mind adding back the old behavior, perhaps as decode_slice_unchecked. Would that work for you? It would be more work to make a more precise and/or lazy check, so I can explore that later, but for now I think just adding back the old logic is fine.

[Gelbpunkt]

• The *_slice decode/encode functions now return an error instead of panicking when the output slice is too small
  • As part of this, there isn't now a public way to decode into a slice exactly the size needed for inputs that
    aren't multiples of 4 tokens. If adding up to 2 bytes to always be a multiple of 3 bytes for the decode buffer is
    a problem, file an issue.

@Gelbpunkt I see this part has come true. :) I was persuaded in #192 that decode_slice should not panic so that there was a safe way available. However, I don't mind adding back the old behavior, perhaps as decode_slice_unchecked. Would that work for you? It would be more work to make a more precise and/or lazy check, so I can explore that later, but for now I think just adding back the old logic is fine.

I agree that not panicking is the better implementation, even for my usecase. It allows for handling malicious user input (or in this case HTTP requests with a header value that'll exceed the buffer). That's why I would prefer lazy checking in the long run, but for now adding back the old behaviour as an unchecked variant would be good enough already. Thank you for the quick response!

[marshallpierce]

I've captured that in #210. In the meantime, I'll release rc1 with decode_slice_unchecked.

[aolbrech]

Hi,

Just a question on release expectations for "stable" 0.21.0. We ran into problems after upgrading to version 0.20.0, and I have been trying to fix them the last couple of days. Since I noticed work is being done on a version 0.21.0 I used the rc.1 release today and noticed that this again causes some significant API changes.

In case the 0.21.0 release is to be expected in the very near future, it would make more sense to just wait for this release to be made available and change all our code at that point. Just a rough estimate would be helpful.

Thanks!

[marshallpierce]

If people don't use the release candidates, there's no point to publishing them -- they're there to gather feedback. :)

Since there's been no feedback thus far on rc.1, I'll probably release it as 0.21.0 in the next few days.