Crate ur

source ·
Expand description

ur is a crate to interact with “uniform resource” encodings of binary data. The encoding scheme is optimized for transport in URIs and QR codes.

The ur::Encoder allows a byte payload to be transmissioned in multiple stages, respecting maximum size requirements. Under the hood, a fountain encoder is used to create an unbounded stream of URIs, subsets of which can be recombined at the receiving side into the payload:

let data = String::from("Ten chars!").repeat(10);
let max_length = 5;
let mut encoder = ur::Encoder::bytes(data.as_bytes(), max_length).unwrap();
let part = encoder.next_part().unwrap();
assert_eq!(
    part,
    "ur:bytes/1-20/lpadbbcsiecyvdidatkpfeghihjtcxiabdfevlms"
);
let mut decoder = ur::Decoder::default();
while !decoder.complete() {
    let part = encoder.next_part().unwrap();
    // Simulate some communication loss
    if encoder.current_index() & 1 > 0 {
        decoder.receive(&part).unwrap();
    }
}
assert_eq!(decoder.message().unwrap().as_deref(), Some(data.as_bytes()));

The following useful building blocks are also part of the public API:

  • The crate::bytewords module contains functionality to encode byte payloads into a suitable alphabet, achieving hexadecimal byte-per-character efficiency.
  • The crate::fountain module provides an implementation of a fountain encoder, which splits up a byte payload into multiple segments and emits an unbounded stream of parts which can be recombined at the receiving decoder side.

Re-exports

Modules

  • Encode and decode byte payloads according to the bytewords scheme.
  • Split up big payloads into constantly sized chunks which can be recombined by a decoder.
  • Split up big payloads into constantly sized URIs which can be recombined by a decoder.