container_image_dist_ref 0.1.0

A library for parsing and validating container image references.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# container_image_dist_ref

A docker/OCI image reference parser.

This library is extensively tested against the authoritative image reference implementation, https://github.com/distribution/reference.

## Motivation

<!-- TODO: rewrite -->

I wanted to use `distribution/reference` in a rust project, but didn't want to deal with FFI into `go`.

## Goals

1. fidelity to the `distribution/reference`'s parser
1. fun optimizations!
<!-- 1. The eventual ability to re-use the parser in other languages -->

More about these goals and design choices in [`./ARCHITECTURE.md`](./ARCHITECTURE.md).

## Benchmarks

Based on some naive benchmarking, this library achieves at least a 10x speedup compared to distribution/reference.

<details open><summary>Running the benchmarks</summary>

```sh
#!/bin/bash
cargo bench # rust
( # go
  cd internal/reference_oracle &&
  go test -bench=.
)
```

</details>

<details><summary>Benchmarks on my machine</summary>

distribution/reference:

```
goos: linux
goarch: amd64
pkg: github.com/skalt/container_image_dist_ref/internal/reference_oracle
cpu: Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz
BenchmarkOracleEntireTestSuite-8            9218            148438 ns/op
```

This crate:

```
entire_test_suite       time:   [5.0737 µs 5.1349 µs 5.2047 µs]
```

```
speedup = (148438 ns) / ((5.1349 µs) * (1000 ns / µs)) = 28.908
```

</details>