# quic-codec

Utilities for decoding and encoding values in a safe and performance-oriented
way.

This is an internal crate used by [s2n-quic](https://github.com/aws/s2n-quic). The API is not currently stable and should not be used directly.

## Decoder

Consider the following code:

```rust
fn decode_u8(buffer: &[u8]) -> (u8, &[u8]) {
    let value = buffer[0];
    (value, buffer[1..])
}

decode_u8(&[1, 2, 3]); // => (1, &[2, 3])
decode_u8(&[4]); // => (4, &[])
```

While this is safe as far as Rust is concerned, this method will panic on
missing input:

```rust
decode_u8(&[]) // thread 'main' panicked at 'index out of bounds: the len is 0 but the index is 0'
```

These kind of issues can be hard to detect and can have a large impact on
environments like servers where untrusted data is being passed. An attacker
could potentially craft a payload that will crash the server.

One possible way to mitigate these issues is to perform a check:

```rust
fn decode_u8(buffer: &[u8]) -> Result<(u8, &[u8]), Error> {
    if buffer.len() < 1 {
        return Err(Error::OutOfBounds);
    }

    let value = buffer[0];
    Ok((value, buffer[1..]))
}

decode_u8(&[1, 2, 3]); // => Ok((1, &[2, 3]))
decode_u8(&[4]); // => Ok((4, &[]))
decode_u8(&[]); // => Err(Error::OutOfBounds)
```

This solution works for this particular case but is error-prone, as it requires
each access to the slice to assert its set of preconditions. Special care
especially needs to be taken when the length of a decoded value depends on a
previously decoded, untrusted input:

```rust
fn decode_slice(buffer: &[u8]) -> Result<(&[u8], &[u8]), Error> {
    if buffer.len() < 1 {
        return Err(Error::OutOfBounds);
    }

    let len = buffer[0] as usize;

    if buffer.len() < len {
        return Err(Error::OutOfBounds);
    }

    let value = buffer[1..len];
    Ok((value, buffer[len..]))
}
```

`quic-codec` instead provides an interface to a slice that is guaranteed not to
panic. It accomplishes this by forcing checks to occur and precondition
violations to be handled.

```rust
fn decode_u8(buffer: DecoderBuffer) -> DecoderResult<u8> {
    let (value, buffer) = buffer.decode::<u8>()?;
    Ok((value, buffer))
}
```

Another major advantage is gained through type-inferred decoding. The
`DecoderBuffer::decode` function can be extended to support any type, given it
implements the `DecoderValue` trait. Consider the following example where the
same `decode` function call is used to parse `u32`, `u8`, and `Date` itself:

```rust
struct Date {
    year: u32,
    month: u8,
    day: u8,
}

impl<'a> DecoderValue<'a> for Date {
    fn decode(buffer: DecoderBuffer<'a>) -> DecoderResult<'a, Self> {
        let (year, buffer) = buffer.decode()?;
        let (month, buffer) = buffer.decode()?;
        let (day, buffer) = buffer.decode()?;
        let date = Self { year, month, day };
        Ok((date, buffer))
    }
}

fn decode_two_dates(buffer: DecoderBuffer) -> DecoderResult<(Date, Date)> {
    let (first, buffer) = buffer.decode()?;
    let (second, buffer) = buffer.decode()?;
    Ok(((first, second), buffer))
}
```

## Encoder

The EncoderBuffer is the counterpart to DecoderBuffer. It writes any value that
implements the `EncoderValue` to a pre-allocated mutable slice. Each type gives
hints for the final the encoding size to ensure a single allocation when
encoding a value.