Struct ImageReference 

pub struct ImageReference {
    pub transport: Transport,
    pub name: String,
}

Combination of a transport and image name.

For example, docker://quay.io/exampleos/blah:latest would be parsed as:

• transport: Registry
• name: quay.io/exampleos/blah:latest

Name formats by transport

The name field format varies by transport:

Transport	Name format	Example
Registry	[domain/]name[:tag][@digest]	quay.io/example/image:latest
OciDir	path[:reference]	/path/to/oci-layout:mytag
OciArchive	path[:reference]	/path/to/image.tar:v1.0
DockerArchive	path[:docker-reference]	/path/to/image.tar:myimage:tag
ContainerStorage	[[storage-spec]]{image-id|docker-ref}	localhost/myimage:latest
Dir	path	/path/to/directory
DockerDaemon	docker-reference or algo:digest	myimage:latest

Fields

transport: Transport

The storage and transport for the image

name: String

The image name - format depends on transport (see struct docs)

Implementations

impl ImageReference

pub fn new(transport: Transport, name: impl Into<String>) -> Self

Create a new image reference from a transport and name.

Examples

use containers_image_proxy::{ImageReference, Transport};

let imgref = ImageReference::new(Transport::Registry, "quay.io/example/image:tag");
assert_eq!(imgref.to_string(), "docker://quay.io/example/image:tag");

pub fn new_registry(reference: Reference) -> Self

Create a new registry image reference from a parsed OCI Reference.

Examples

use containers_image_proxy::ImageReference;
use oci_spec::distribution::Reference;

let oci_ref: Reference = "quay.io/example/image:latest".parse().unwrap();
let imgref = ImageReference::new_registry(oci_ref);
assert_eq!(imgref.to_string(), "docker://quay.io/example/image:latest");

pub fn try_new_registry(name: &str) -> Result<Self, ParseError>

Try to create a new registry image reference by parsing the name.

Returns an error if the name is not a valid OCI distribution reference.

Examples

use containers_image_proxy::ImageReference;

let imgref = ImageReference::try_new_registry("quay.io/example/image:latest").unwrap();
assert_eq!(imgref.to_string(), "docker://quay.io/example/image:latest");

// Invalid references return an error
assert!(ImageReference::try_new_registry("not a valid reference!").is_err());

pub fn as_registry(&self) -> Option<Result<Reference, ParseError>>

For Registry transport, parse the name as an OCI distribution Reference.

Returns None for non-Registry transports. For Registry transport, returns Some(Result) with the parsed reference or a parse error.

This is useful when you need structured access to the registry, repository, tag, and digest components of a registry image reference.

Examples

use containers_image_proxy::{ImageReference, Transport};

let imgref: ImageReference = "docker://quay.io/example/image:latest".try_into().unwrap();
let oci_ref = imgref.as_registry().unwrap().unwrap();
assert_eq!(oci_ref.registry(), "quay.io");
assert_eq!(oci_ref.repository(), "example/image");
assert_eq!(oci_ref.tag(), Some("latest"));

// Non-registry transports return None
let imgref: ImageReference = "oci:/path/to/image".try_into().unwrap();
assert!(imgref.as_registry().is_none());

pub fn as_containers_storage(&self) -> Option<ContainersStorageRef<'_>>

For ContainerStorage transport, parse into structured components.

Returns None for non-ContainerStorage transports.

Examples

use containers_image_proxy::{ImageReference, Transport};

// Simple image reference
let imgref: ImageReference = "containers-storage:localhost/myimage:tag".try_into().unwrap();
let csref = imgref.as_containers_storage().unwrap();
assert_eq!(csref.store_spec(), None);
assert_eq!(csref.image(), "localhost/myimage:tag");

// With store specifier
let imgref: ImageReference = "containers-storage:[overlay@/var/lib/containers]busybox".try_into().unwrap();
let csref = imgref.as_containers_storage().unwrap();
assert_eq!(csref.store_spec(), Some("overlay@/var/lib/containers"));
assert_eq!(csref.image(), "busybox");

// Normalizing sha256: prefix (workaround for skopeo#2750)
let imgref: ImageReference = "containers-storage:sha256:abc123".try_into().unwrap();
let csref = imgref.as_containers_storage().unwrap();
assert_eq!(csref.image_for_skopeo(), "abc123");

Trait Implementations

impl Clone for ImageReference

fn clone(&self) -> ImageReference

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImageReference

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ImageReference

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for ImageReference

type Err = ImageReferenceError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for ImageReference

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ImageReference

fn eq(&self, other: &ImageReference) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<&str> for ImageReference

fn try_from(value: &str) -> Result<Self, ImageReferenceError>

Parse an image reference string into transport and name components.

Examples

use containers_image_proxy::transport::{ImageReference, Transport};

let imgref: ImageReference = "docker://quay.io/example/image:tag".try_into().unwrap();
assert_eq!(imgref.transport, Transport::Registry);
assert_eq!(imgref.name, "quay.io/example/image:tag");

let imgref: ImageReference = "containers-storage:localhost/myimage".try_into().unwrap();
assert_eq!(imgref.transport, Transport::ContainerStorage);
assert_eq!(imgref.name, "localhost/myimage");

type Error = ImageReferenceError

The type returned in the event of a conversion error.

impl Eq for ImageReference

impl StructuralPartialEq for ImageReference