https://github.com/skalt/container_image_dist_ref
A library for parsing OCI container image references
https://github.com/skalt/container_image_dist_ref
docker oci-distribution oci-image parser
Last synced: 4 months ago
JSON representation
A library for parsing OCI container image references
- Host: GitHub
- URL: https://github.com/skalt/container_image_dist_ref
- Owner: SKalt
- License: apache-2.0
- Created: 2024-01-03T15:40:37.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-28T13:21:35.000Z (over 1 year ago)
- Last Synced: 2025-10-24T03:40:01.474Z (8 months ago)
- Topics: docker, oci-distribution, oci-image, parser
- Language: Rust
- Homepage:
- Size: 286 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project
README
# container_image_dist_ref
A docker/OCI image reference parser.
[](https://crates.io/crates/container_image_dist_ref)
[](https://docs.rs/container_image_dist_ref/latest/container_image_dist_ref/)
This library is extensively tested against the authoritative image reference implementation, https://github.com/distribution/reference.
Image references follow this [EBNF](https://www.w3.org/TR/xml11/#sec-notation) grammar:
```ebnf
reference ::= name (":" tag )? ("@" digest )?
name ::= (domain "/")? path
domain ::= host (":" port-number)?
host ::= domain-name | IPv4address | "[" IPv6address "]" /* see https://www.rfc-editor.org/rfc/rfc3986#appendix-A */
domain-name ::= domain-component ("." domain-component)*
domain-component ::= ([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])
port-number ::= [0-9]+
path-component ::= [a-z0-9]+ (separator [a-z0-9]+)*
path ::= path-component ("/" path-component)*
separator ::= [_.] | "__" | "-"+
tag ::= [\w][\w.-]{0,127}
digest ::= algorithm ":" encoded
algorithm ::= algorithm-component (algorithm-separator algorithm-component)*
algorithm-separator ::= [+._-]
algorithm-component ::= [A-Za-z][A-Za-z0-9]*
encoded ::= [a-fA-F0-9]{32,} /* At least 128 bit digest value */
identifier ::= [a-f0-9]{64}
```
(This is translated from [https://github.com/distribution/reference/blob/main/reference.go](https://github.com/distribution/reference/blob/main/reference.go#L4-L26))
To avoid worst-case performance, image references are restricted further:
| part | maximum length |
| ----------- | -------------: |
| `name` | 255 |
| `tag` | 127 |
| `digest` | 1024 |
| `algorithm` | 255 |
## Motivation
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!
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.
Running the benchmarks
```sh
#!/bin/bash
cargo bench # rust
( # go
cd internal/reference_oracle &&
go test -bench=.
)
```
Benchmarks on my machine
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
```