feat: Merge hermit-image-reader into this crate

Signed-off-by: Ellen Εμιλία Άννα Zscheile <[email protected]>

Author: fogti

Cargo.toml

@@ -21,14 +21,43 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 align-address = "0.3"
+compression = { version = "0.1", default-features = false, features = ["gzip"], optional = true }
 const_parse = "1"
 goblin = { version = "0.10", default-features = false, features = ["elf64"], optional = true }
 log = { version = "0.4", optional = true }
+num-traits = { version = "0.2", default-features = false }
 plain = { version = "0.2", optional = true }
 time = { version = "0.3", default-features = false }
 uhyve-interface = "0.1"
+yoke = { version = "0.8", default-features = false, features = ["derive"], optional = true }
+
+[dependencies.byte-unit]
+version = "5"
+default-features = false
+features = ["byte", "serde"]
+optional = true
+
+[dependencies.serde]
+version = "1"
+default-features = false
+features = ["alloc", "derive"]
+optional = true
+
+[dependencies.toml]
+version = "0.9"
+default-features = false
+features = ["parse", "serde"]
+optional = true
+
+[dev-dependencies]
+proptest = "1.9"
 
 [features]
 default = []
-loader = ["log", "goblin", "plain"]
+std = ["alloc", "compression/std"]
+alloc = []
+compression = ["alloc", "dep:compression"]
+loader = ["dep:log", "dep:goblin", "dep:plain"]
 kernel = []
+config = ["alloc", "dep:byte-unit", "dep:serde", "dep:toml"]
+thin-tree = ["alloc", "dep:yoke"]

README.md

@@ -22,3 +22,20 @@ at your option.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
+
+## Hermit images
+
+This Rust crate also implements a basic reader for Hermit images.
+Overall, these are just `.tar.gz` (i.e. gzipped tar) files.
+
+They contain at least 2 special entries:
+* The config file (in TOML format), at `hermit.toml` in the image root.
+  The expected entries are described in the crate documentation in `hermit_entry::config::Config` (requires enabling the `config` feature).
+* A Hermit Kernel ELF file, whose path is specified in the config.
+
+For performance reasons, it should be preferred to put the config and kernel
+as the first two entries of the image (tar files don't have any sorting or index,
+except that normally, the latest entry of the file takes precedence).
+
+All subdirectories of the image itself are mapped
+(from the Hermit kernel perspective) into `/`.

src/config.rs

@@ -0,0 +1,65 @@
+//! The image `hermit.toml` config file format.
+//!
+//! All file paths are relative to the image root.
+//!
+//! Note that for technical reasons, files in the top-level of the image
+//! might not be reachable from the kernel, but root subdirectories should be,
+//! unless they are named after reserved names like `proc`.
+
+use alloc::string::String;
+use alloc::vec::Vec;
+
+/// The default configuration file name, relative to the image root.
+pub const DEFAULT_CONFIG_NAME: &str = "hermit.toml";
+
+/// The possible errors which the parser might emit.
+pub type ParserError = toml::de::Error;
+
+/// The configuration toplevl structure.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(tag = "version")]
+pub enum Config {
+    /// The first (and current) version of the config format.
+    #[serde(rename = "1")]
+    V1 {
+        /// Input parameter for the kernel and application
+        input: Input,
+
+        /// Minimal requirements for an image to be able to run as expected
+        #[serde(default)]
+        requirements: Requirements,
+
+        /// Kernel ELF file path
+        kernel: String,
+    },
+}
+
+/// Input parameter for the kernel and application
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct Input {
+    /// Arguments to be passed to the kernel
+    pub kernel_args: Vec<String>,
+
+    /// Arguments to be passed to the application
+    pub app_args: Vec<String>,
+
+    /// Environment variables
+    pub env_vars: Vec<String>,
+}
+
+/// Minimal requirements for an image to be able to run as expected
+#[derive(Clone, Debug, Default, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct Requirements {
+    /// Minimum RAM
+    pub memory: Option<byte_unit::Byte>,
+
+    /// Minimum amount of CPUs
+    #[serde(default)]
+    pub cpus: u32,
+}
+
+/// Parse a config file from a byte slice.
+#[inline]
+pub fn parse(data: &[u8]) -> Result<Config, ParserError> {
+    toml::from_slice(data)
+}

src/filename.rs

@@ -0,0 +1,191 @@
+use core::{cmp, fmt};
+
+const SEP: u8 = b'/';
+
+/// Truncate a byte slice to the first NULL byte. if any.
+// taken from `tar-rs`
+pub fn truncate(slice: &[u8]) -> &[u8] {
+    match slice.iter().position(|i| *i == 0) {
+        Some(i) => &slice[..i],
+        None => slice,
+    }
+}
+
+// FIXME: once `slice`.split_once is stable, we can get rid of this.
+fn split_once(this: &[u8], on: u8) -> Option<(&[u8], &[u8])> {
+    let index = this.iter().position(|i| *i == on)?;
+    Some((&this[..index], &this[index + 1..]))
+}
+
+/// Zero-copy file name (usually from an in-memory tar file)
+///
+/// Code might rely on the invariant that it doesn't contain null bytes.
+#[derive(Clone, Copy, Debug, Eq)]
+pub enum Filename<'a> {
+    /// A simple file name
+    One(&'a [u8]),
+    /// A prefix and file name (meaning `{0}/{1}`)
+    Two(&'a [u8], &'a [u8]),
+}
+
+impl Filename<'_> {
+    /// Truncate the filename to the first `n` components
+    #[must_use = "input is not modified"]
+    pub fn as_truncated(self, mut n: usize) -> Self {
+        let handle_parts = |n: &mut usize, x: &mut &[u8]| {
+            if *n > 0 {
+                let mut offset = 0;
+                for i in (*x).split(|i| *i == SEP) {
+                    *n -= 1;
+                    offset += i.len();
+                    if *n == 0 {
+                        // truncate
+                        *x = &x[..offset];
+                        break;
+                    }
+                    // separator
+                    offset += 1;
+                }
+            }
+        };
+
+        match self {
+            Self::One(_) if n == 0 => Self::One(&[]),
+            Self::One(mut x) => {
+                handle_parts(&mut n, &mut x);
+                Self::One(x)
+            }
+            Self::Two(mut x, mut y) => {
+                handle_parts(&mut n, &mut x);
+                if n >= 1 {
+                    handle_parts(&mut n, &mut y);
+                    Self::Two(x, y)
+                } else {
+                    Self::One(x)
+                }
+            }
+        }
+    }
+}
+
+impl fmt::Display for Filename<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::One(x) => write!(f, "{:?}", x),
+            Self::Two(x, y) => write!(f, "{:?}/{:?}", x, y),
+        }
+    }
+}
+
+impl cmp::PartialEq for Filename<'_> {
+    fn eq(&self, oth: &Self) -> bool {
+        let (mut this, mut oth) = (*self, *oth);
+        loop {
+            match (this.next(), oth.next()) {
+                (None, None) => break true,
+                (None, _) | (_, None) => break false,
+                (Some(x), Some(y)) if x != y => break false,
+                _ => {}
+            }
+        }
+    }
+}
+
+impl<'a> From<&'a [u8]> for Filename<'a> {
+    #[inline]
+    fn from(x: &'a [u8]) -> Self {
+        // null bytes are the only illegal bytes in a filename
+        assert!(!x.contains(&0x00));
+        Self::One(x)
+    }
+}
+
+impl<'a> From<&'a str> for Filename<'a> {
+    #[inline]
+    fn from(x: &'a str) -> Self {
+        // null bytes are the only illegal bytes in a str filename
+        assert!(!x.contains('\0'));
+        Self::One(x.as_bytes())
+    }
+}
+
+impl<'a> Iterator for Filename<'a> {
+    type Item = &'a [u8];
+
+    fn next(&mut self) -> Option<&'a [u8]> {
+        match self {
+            Self::One([]) => None,
+            Self::One(x) => Some(match split_once(x, SEP) {
+                None => {
+                    let ret = *x;
+                    *x = &[];
+                    ret
+                }
+                Some((fi, rest)) => {
+                    *x = rest;
+                    fi
+                }
+            }),
+            Self::Two(x, y) => Some(match split_once(x, SEP) {
+                None => {
+                    let ret = *x;
+                    *self = Self::One(y);
+                    ret
+                }
+                Some((fi, rest)) => {
+                    *x = rest;
+                    fi
+                }
+            }),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_iteq<'a, I: Iterator<Item = &'a [u8]>>(mut it: I, eqto: &[&str]) {
+        for i in eqto {
+            assert_eq!(it.next(), Some(i.as_bytes()), "divergence @ {}", i);
+        }
+        assert_eq!(it.next(), None);
+    }
+
+    #[test]
+    fn test_filename_iter_one() {
+        let it = Filename::One(b"aleph/beta/omicron");
+        assert_iteq(it, &["aleph", "beta", "omicron"]);
+    }
+
+    #[test]
+    fn test_filename_as_truncated_one() {
+        let it = Filename::One(b"aleph/beta/omicron").as_truncated(2);
+        assert_iteq(it, &["aleph", "beta"]);
+    }
+
+    #[test]
+    fn test_filename_iter_two() {
+        let it = Filename::Two(b"aleph/beta", b"omicron/depth");
+        assert_iteq(it, &["aleph", "beta", "omicron", "depth"]);
+    }
+
+    #[test]
+    fn test_filename_as_truncated_two() {
+        let mfn = Filename::Two(b"aleph/beta", b"omicron/depth");
+        assert_iteq(mfn.as_truncated(2), &["aleph", "beta"]);
+        assert_iteq(mfn.as_truncated(3), &["aleph", "beta", "omicron"]);
+        assert_iteq(mfn.as_truncated(4), &["aleph", "beta", "omicron", "depth"]);
+        assert_iteq(mfn.as_truncated(5), &["aleph", "beta", "omicron", "depth"]);
+    }
+
+    #[test]
+    fn test_filename_non_ascii() {
+        let mfn = Filename::Two("αleph/βetα".as_bytes(), "ο/δth".as_bytes());
+        assert_iteq(mfn, &["αleph", "βetα", "ο", "δth"]);
+        assert_iteq(mfn.as_truncated(2), &["αleph", "βetα"]);
+        assert_iteq(mfn.as_truncated(3), &["αleph", "βetα", "ο"]);
+        assert_iteq(mfn.as_truncated(4), &["αleph", "βetα", "ο", "δth"]);
+        assert_iteq(mfn.as_truncated(5), &["αleph", "βetα", "ο", "δth"]);
+    }
+}

src/lib.rs

@@ -8,14 +8,28 @@
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 #![warn(missing_docs)]
 
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
 pub mod boot_info;
 
+#[cfg(feature = "config")]
+pub mod config;
+
 #[cfg(feature = "loader")]
 pub mod elf;
 
+mod filename;
+pub use filename::Filename;
+
 #[cfg(feature = "kernel")]
 mod note;
 
+pub mod tar_parser;
+
+#[cfg(feature = "thin-tree")]
+pub mod thin_tree;
+
 use core::error::Error;
 use core::fmt;
 use core::str::FromStr;
@@ -179,6 +193,20 @@ impl fmt::Display for UhyveIfVersion {
     }
 }
 
+#[cfg(feature = "compression")]
+/// We assume that all images are gzip-compressed
+pub fn decompress_image(
+    data: &[u8],
+) -> Result<tar_parser::BytesBuf, compression::prelude::CompressionError> {
+    use compression::prelude::{DecodeExt as _, GZipDecoder};
+
+    data.iter()
+        .copied()
+        .decode(&mut GZipDecoder::new())
+        .collect::<Result<_, _>>()
+        .map(tar_parser::BytesBuf)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;