While updating some old projects to use the v0.2.0 release of this crate, I
encountered a couple confusing situations. I'm not necessarily proposing that
we change these, but maybe they could be addressed in documentation. I'll write
up a patch if I get time.
First, the `ByteString` type was a little confusing because I at first assumed
`macaroon` was pulling it in from the `bytestring` crate (aka,
https://docs.rs/bytestring/latest/bytestring/struct.ByteString.html). But, of
course, it is an internal type. Not sure what we could do from our side about
this.
Second, the automatic conversion of `ByteString` to base64 representation was
confusing both when doing string comparisons and when doing debug prints in my
application code with the `identifier` field on `Macaroon`. This is a binary
field, but at least in my application code, is frequently a UTF-8 encoded
string. Without even thinking about it I had some `m.identifier().to_string()`
comparisons which ended up being base64. Maybe `.to_base64_string()` or
something like that would make more sense? (`.to_string()` is infered from
`fmt()` I believe).
Third, the difference in behavior with `MacaroonKey` when initializing from
`[u8; 32]` (creates a key immediately from the bytes) vs. `&[u8]` (does an HMAC
and uses the result as the key bytes) was confusing.
----
questions:
- should Result be MacaroonResult?
proposals:
- all exported types should be top-level? aka 'MacaroonKey' instead of 'crypto::MacaroonKey'
- ByteString should not be public. just use [u8] in public interfaces
