Crate base64urlsafedata

Wrappers for Vec<u8> to make Serde serialise and deserialise as URL-safe, non-padded Base64 (per RFC 4648 §5).

Serialisation behaviour

• Base64UrlSafeData always serialises to URL-safe, non-padded Base64.

• HumanBinaryData only serialises to URL-safe, non-padded Base64 when using a human-readable format.

  Otherwise, it serialises as a “bytes”-like type (like serde_bytes).

  This feature is new in base64urlsafe v0.1.4.

By comparison, Serde’s default behaviour is to serialise Vec<u8> as a sequence of integers. This is a problem for many formats:

• serde_cbor encodes as an array, rather than a bytes. This uses zig-zag encoded integers for values > 0x1F, which averages about 1.88 bytes per byte assuming an equal distribution of values.

• serde_json encodes as an Array<Number>, which averages 3.55 bytes per byte without whitespace.

Using Base64 encoding averages 1.33 bytes per byte, and most formats pass strings nearly-verbatim.

Deserialisation behaviour

Both types will deserialise multiple formats, provided the format is self-describing (ie: implements deserialize_any):

• Bytes types are passed as-is (new in v0.1.4).

  HumanBinaryData produces this for non-human-readable formats.

• Sequences of integers are passed as-is.

  Serde’s default Vec<u8> serialiser produces this for many formats.

• Strings are decoded Base64 per RFC 4648 §5 (URL-safe) or §4 (standard), with optional padding.

  Base64UrlSafeData produces this for all formats, and HumanBinaryData produces this for human-readable formats. This should also be compatible with many other serialisers.

Migrating from Base64UrlSafeData to HumanBinaryData

Base64UrlSafeData always uses Base64 encoding, which isn’t optimal for many binary formats. For that reason, it’s a good idea to migrate to HumanBinaryData if you’re using a binary format.

However, you’ll need to make sure all readers using Base64UrlSafeData are on base64urlsafedata v0.1.4 or later before switching anything to HumanBinaryData. Otherwise, they’ll not be able to read any data in the new format!

Once they’re all migrated across, you can start issuing writes in the new format. It’s a good idea to slowly roll out the change, in case you discover something has been left behind.

Alternatives

• serde_bytes, which implements efficient coding of Vec<u8> for non-human-readable formats only.

Structs

• Base64UrlSafeData
  Serde wrapper for Vec<u8> which always emits URL-safe, non-padded Base64, and accepts Base64 and binary formats.
• HumanBinaryData
  Serde wrapper for Vec<u8> which emits URL-safe, non-padded Base64 for only human-readable formats, and accepts Base64 and binary formats.