Skip to content

armgit / kiri

Public Imported from GitHub
0

A small, fast container runtime for macOS, Windows and Linux

Rust
7.5 KB
Raw Blame
//! Image references like `alpine`, `nginx:1.27`, `ghcr.io/o/r@sha256:…`.

use std::fmt;

/// Docker Hub's name for itself in references, and the host its API lives on.
const DOCKER_HUB: &str = "docker.io";
const DOCKER_HUB_API: &str = "registry-1.docker.io";

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Reference {
    /// Registry as written in the reference (`docker.io`, `ghcr.io`, `localhost:5000`).
    pub registry: String,
    /// Repository path (`library/alpine`, `owner/app`).
    pub repository: String,
    /// Tag or digest (`latest`, `sha256:…`).
    pub reference: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseError(pub String);

impl fmt::Display for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "invalid image reference: {}", self.0)
    }
}

impl std::error::Error for ParseError {}

impl Reference {
    pub fn parse(input: &str) -> Result<Reference, ParseError> {
        let bad = || ParseError(input.to_owned());
        if input.is_empty() || input.chars().any(char::is_whitespace) {
            return Err(bad());
        }
        let (name, reference) = if let Some((name, digest)) = input.split_once('@') {
            if crate::store::digest_hex(digest).is_err() {
                return Err(bad());
            }
            // `name:tag@digest` names the digest; the tag is only a label, as
            // in Docker, but it must still be a valid one.
            let name = match name.rfind(':') {
                Some(i) if !name[i..].contains('/') => {
                    let tag = &name[i + 1..];
                    if tag.is_empty() || !tag.bytes().all(|b| b.is_ascii_alphanumeric() || b"_.-".contains(&b)) {
                        return Err(bad());
                    }
                    &name[..i]
                }
                _ => name,
            };
            (name, digest.to_owned())
        } else {
            // A colon after the last slash is a tag; one before it is a port.
            match input.rfind(':') {
                Some(i) if !input[i..].contains('/') => (&input[..i], input[i + 1..].to_owned()),
                _ => (input, "latest".to_owned()),
            }
        };
        // Repository names are lowercase; tags may use any case.
        if name.is_empty() || reference.is_empty() || name.chars().any(|c| c.is_ascii_uppercase()) {
            return Err(bad());
        }
        // The first component is a registry only if it looks like a host.
        let (registry, repository) = match name.split_once('/') {
            Some((first, rest)) if first.contains('.') || first.contains(':') || first == "localhost" => {
                (first.to_owned(), rest.to_owned())
            }
            _ => (DOCKER_HUB.to_owned(), name.to_owned()),
        };
        let repository = if registry == DOCKER_HUB && !repository.contains('/') {
            format!("library/{repository}")
        } else {
            repository
        };
        if repository.split('/').any(str::is_empty) {
            return Err(bad());
        }
        Ok(Reference { registry, repository, reference })
    }

    /// Host that serves the registry API.
    pub fn api_host(&self) -> &str {
        if self.registry == DOCKER_HUB { DOCKER_HUB_API } else { &self.registry }
    }

    /// `https://host`, or `http://host` for a registry on this machine,
    /// which Docker also treats as insecure by default.
    pub fn api_base(&self) -> String {
        format!("{}://{}", if is_local(self.api_host()) { "http" } else { "https" }, self.api_host())
    }

    pub fn is_digest(&self) -> bool {
        self.reference.starts_with("sha256:")
    }

    /// The short form people type and `docker images` shows: `alpine:latest`,
    /// `owner/app:1`, `ghcr.io/o/r:tag`.
    pub fn short(&self) -> String {
        let repo = if self.registry == DOCKER_HUB {
            self.repository.strip_prefix("library/").unwrap_or(&self.repository).to_owned()
        } else {
            format!("{}/{}", self.registry, self.repository)
        };
        let sep = if self.is_digest() { '@' } else { ':' };
        format!("{repo}{sep}{}", self.reference)
    }
}

/// `localhost:5000`, `127.0.0.1:5000`, `[::1]:5000`, `registry.localhost`.
pub fn is_local(host: &str) -> bool {
    let name = if host.starts_with('[') { host.split(']').next().unwrap_or(host).trim_start_matches('[') } else { host.split(':').next().unwrap_or(host) };
    name == "localhost" || name.ends_with(".localhost") || name.parse::<std::net::IpAddr>().is_ok_and(|ip| ip.is_loopback())
}

impl fmt::Display for Reference {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.short())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn r(s: &str) -> (String, String, String) {
        let r = Reference::parse(s).unwrap();
        (r.registry, r.repository, r.reference)
    }

    #[test]
    fn parses_common_forms() {
        let s = |a: &str, b: &str, c: &str| (a.to_owned(), b.to_owned(), c.to_owned());
        assert_eq!(r("alpine"), s("docker.io", "library/alpine", "latest"));
        assert_eq!(r("nginx:1.27-alpine"), s("docker.io", "library/nginx", "1.27-alpine"));
        assert_eq!(r("bitnami/redis:7"), s("docker.io", "bitnami/redis", "7"));
        assert_eq!(r("ghcr.io/o/r:v1"), s("ghcr.io", "o/r", "v1"));
        assert_eq!(r("localhost:5000/app"), s("localhost:5000", "app", "latest"));
        let d = format!("sha256:{}", "a".repeat(64));
        assert_eq!(r(&format!("alpine@{d}")), s("docker.io", "library/alpine", &d));
    }

    #[test]
    fn a_digest_wins_over_a_tag() {
        let d = format!("sha256:{}", "a".repeat(64));
        for s in [format!("kindest/node:v1.37.0@{d}"), format!("kindest/node@{d}"), format!("docker.io/kindest/node:v1@{d}")] {
            let r = Reference::parse(&s).unwrap();
            assert_eq!((r.registry.as_str(), r.repository.as_str(), r.reference.as_str()), ("docker.io", "kindest/node", d.as_str()), "{s}");
            assert_eq!(r.short(), format!("kindest/node@{d}"));
        }
        let r = Reference::parse(&format!("localhost:5000/app:1@{d}")).unwrap();
        assert_eq!((r.registry.as_str(), r.repository.as_str()), ("localhost:5000", "app"));
        let r = Reference::parse(&format!("localhost:5000/app@{d}")).unwrap();
        assert_eq!((r.registry.as_str(), r.repository.as_str()), ("localhost:5000", "app"));
        for s in [format!("alpine:@{d}"), format!("alpine:b@d@{d}")] {
            assert!(Reference::parse(&s).is_err(), "{s}");
        }
    }

    #[test]
    fn short_form_round_trips() {
        for s in ["alpine:latest", "bitnami/redis:7", "ghcr.io/o/r:v1"] {
            assert_eq!(Reference::parse(s).unwrap().short(), s);
        }
    }

    #[test]
    fn rejects_garbage() {
        let non_hex = format!("alpine@sha256:{}", "g".repeat(64));
        let traversal = format!("alpine@sha256:{}", "../".repeat(21) + "ab");
        for s in ["", "a b", "alpine:", "alpine@sha256:short", "/x", "Alpine", &non_hex, &traversal] {
            assert!(Reference::parse(s).is_err(), "{s}");
        }
    }

    #[test]
    fn only_real_loopback_registries_are_local() {
        for host in ["localhost", "localhost:5000", "registry.localhost", "127.0.0.1", "127.1.2.3:5000", "[::1]:5000"] {
            assert!(is_local(host), "{host}");
        }
        for host in ["127.evil.com", "127.0.0.1.evil.com", "example.com", "[::2]:5000"] {
            assert!(!is_local(host), "{host}");
        }
        assert_eq!(Reference::parse("127.evil.com/owner/image").unwrap().api_base(), "https://127.evil.com");
    }
}