Struct ImageName

Source

pub struct ImageName {
    pub hostname: String,
    pub port: Option<u16>,
    pub name: Name,
    pub reference: Reference,
}

Expand description

Image name

The input must be valid both as “org.opencontainers.image.ref.name” defined in pre-defined annotation keys in OCI image spec:

ref       ::= component ("/" component)*
component ::= alphanum (separator alphanum)*
alphanum  ::= [A-Za-z0-9]+
separator ::= [-._:@+] | "--"

and as an argument for docker tag.

§Terminology

We call each components of image name to match OCI distribution spec:

ghcr.io/termoshtt/ocipkg/testing:latest
^^^^^^^---------------------------------- hostname
        ^^^^^^^^^^^^^^^^^^^^^^^^--------- name
                                 ^^^^^^-- reference

use ocipkg::{ImageName, distribution::{Name, Reference}};
let name = ImageName::parse("ghcr.io/termoshtt/ocipkg/testing:latest")?;
assert_eq!(
    name,
    ImageName {
        hostname: "ghcr.io".to_string(),
        port: None,
        name: Name::new("termoshtt/ocipkg/testing")?,
        reference: Reference::new("latest")?,
    }
);

If a port number is included:

localhost:5000/test_repo:tag1
^^^^^^^^^---------------------- hostname
          ^^^^----------------- port
               ^^^^^^^^^------- name
                         ^^^^-- reference

use ocipkg::{ImageName, distribution::{Name, Reference}};
let name = ImageName::parse("localhost:5000/test_repo:latest")?;
assert_eq!(
    name,
    ImageName {
        hostname: "localhost".to_string(),
        port: Some(5000),
        name: Name::new("test_repo")?,
        reference: Reference::new("latest")?,
    }
);

Reference can be a digest:

quay.io/jitesoft/alpine:sha256:6755355f801f8e3694bffb1a925786813462cea16f1ce2b0290b6a48acf2500c
^^^^^^^-------------------- hostname
        ^^^^^^^^^^^^^^^---- name
           reference ---^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

use ocipkg::{ImageName, distribution::{Name, Reference}};
let name = ImageName::parse("quay.io/jitesoft/alpine:sha256:6755355f801f8e3694bffb1a925786813462cea16f1ce2b0290b6a48acf2500c")?;
assert_eq!(
    name,
    ImageName {
        hostname: "quay.io".to_string(),
        port: None,
        name: Name::new("jitesoft/alpine")?,
        reference: Reference::new("sha256:6755355f801f8e3694bffb1a925786813462cea16f1ce2b0290b6a48acf2500c")?,
    }
);

§Default values

If hostname is absent, use registry-1.docker.io for docker compatibility:

use ocipkg::{ImageName, distribution::{Name, Reference}};
let name = ImageName::parse("ubuntu:20.04")?;
assert_eq!(
    name,
    ImageName {
        hostname: "registry-1.docker.io".to_string(),
        port: None,
        name: Name::new("ubuntu")?,
        reference: Reference::new("20.04")?,
    }
);

If reference is absent, use latest:

use ocipkg::{ImageName, distribution::{Name, Reference}};
let name = ImageName::parse("alpine").unwrap();
assert_eq!(
    name,
    ImageName {
        hostname: "registry-1.docker.io".to_string(),
        port: None,
        name: Name::new("alpine")?,
        reference: Reference::new("latest")?,
    }
);