#docker #validation #parser

no-std docker-image

A simple, no_std-compatible Docker image reference parser with strict adherence to Docker's naming rules

3 unstable releases

0.2.1 Feb 22, 2025
0.2.0 Feb 22, 2025
0.1.0 Nov 17, 2024

#421 in Algorithms

Download history 1/week @ 2025-01-29 13/week @ 2025-02-05 15/week @ 2025-02-12 270/week @ 2025-02-19 130/week @ 2025-02-26 830/week @ 2025-03-05 1206/week @ 2025-03-12 933/week @ 2025-03-19 196/week @ 2025-03-26 409/week @ 2025-04-02 303/week @ 2025-04-09 133/week @ 2025-04-16 161/week @ 2025-04-23 134/week @ 2025-04-30 1612/week @ 2025-05-07 1140/week @ 2025-05-14

3,059 downloads per month

EUPL-1.2

24KB
428 lines

πŸ‹ docker-image

A utility crate for parsing Docker image references.

Crates.io Docs Build Status Safety Dance codecov MSRV EUPL 1.2 licensed

Features

  • Parse Docker image references into structured components:
    • Registry (e.g., docker.io, ghcr.io)
    • Name (e.g., nginx, library/nginx)
    • Tag (e.g., latest, v1.0.0)
    • Digest (e.g., sha256:<64-character-digest>)
  • Validate Docker image references against Docker's official naming rules.
  • Designed for safety:
    • #![no_std] compatible for embedded and minimal environments (however alloc remains a requirement).
    • #![forbid(unsafe_code)] ensures memory safety.
  • Minimum Supported Rust Version (MSRV): Rust 1.81.0
    • This is the earliest version of Rust required to use this library.
    • Note: The MSRV may increase in future releases due to updates in dependencies or library features.

Supported Formats:

  • nginx
  • nginx:latest
  • docker.io/library/nginx
  • docker.io/library/nginx:latest
  • docker.io/library/nginx@sha256:<digest>
  • docker.io/library/nginx:latest@sha256:<digest>

Not Supported:

  • Unicode characters in names, tags, or digests.
  • Uppercase letters in names (Docker requires lowercase).
  • Invalid or malformed registries, tags, or digests.

Usage Examples

Parsing a Docker Image Reference

use docker_image::DockerImage;

fn it_works() {
    let image = DockerImage::parse("docker.io/library/nginx:latest").unwrap();
    assert_eq!(image.registry, Some("docker.io".to_string()));
    assert_eq!(image.name, "library/nginx".to_string());
    assert_eq!(image.tag, Some("latest".to_string()));
    assert_eq!(image.digest, None);
}

Invalid Docker Image Reference

use docker_image::DockerImage;

fn it_works() {
    let result = DockerImage::parse("nginxπŸš€");
    assert_eq!(result, Err(DockerImageError::InvalidFormat));
}

Display Implementation

use docker_image::DockerImage;

fn it_works() {
    let image = DockerImage {
        registry: Some("docker.io".to_string()),
        name: "library/nginx".to_string(),
        tag: Some("latest".to_string()),
        digest: None,
    };

    assert_eq!(format!("{}", image), "docker.io/library/nginx:latest");
}

Dependencies

~2.1–3.5MB
~57K SLoC