arora 13.3.0

//! A module directory: the form a device carries a guest module in — the
//! module's header beside the artifact the header's executor runs.
//!
//! ```text
//! <module directory>/
//! ├── header.json      the module's low-level Header, as JSON
//! ├── <artifact>       the one file with the executor's extension: `.wasm`
//! │                    for `wasm`, the platform's dynamic library (`.so`,
//! │                    `.dylib`, `.dll`) for `native`
//! └── records/         optional: the module's record and the records it
//!                      depends on, in arora-registry's layout
//!                      (`module/<id>@<version>.yaml`, `structure/…`,
//!                      `enumeration/…`, `folder/<id>.yaml`)
//! ```
//!
//! The artifact's name is free — its extension names it — so a published
//! artifact directory (a header beside its `.wasm`, and its records) is a
//! module directory as is. A device runner loads every module directory under
//! its device directory's `modules/` at start ([`in_device_dir`]), then any
//! other its command line names (`--module`), with
//! [`AroraBuilder::with_module_dirs`](crate::AroraBuilder::with_module_dirs).
//! The records of every module directory fill one registry ([`registry`]),
//! which describes each module whose record it holds
//! ([`AroraBuilder::with_registry`](crate::AroraBuilder::with_registry)).
//!
//! A module directory that cannot be read — a missing or malformed header, no
//! artifact or several, an executor this runtime has no artifact convention
//! for — is an error naming the module by its directory's name: a device never
//! starts without a module it was given. An entry whose name starts with `.`
//! is neither a module directory nor an artifact: OS metadata (`.DS_Store`, an
//! AppleDouble `._x.wasm`) lands beside the files it describes, and is ignored
//! both under `modules/` and inside a module directory.

use std::collections::HashMap;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};

use anyhow::{bail, Context, Result};
use arora_registry::local::LocalRegistry;
use arora_registry::local_yaml::{
    load_records as load_records_from_yaml, load_records_from_yaml_dir, records_as_yaml, RecordKind,
};
use arora_types::module::low::Header;

/// The subdirectory of the device directory holding its module directories.
const MODULES_DIR: &str = "modules";
/// The header's file name in a module directory.
const HEADER_FILE: &str = "header.json";
/// The subdirectory of a module directory holding its records.
const RECORDS_DIR: &str = "records";

/// A module directory, read: what
/// [`AroraBuilder::with_module`](crate::AroraBuilder::with_module) loads.
#[derive(Debug)]
pub struct ModuleFiles {
    /// The module directory the files were read from.
    pub dir: PathBuf,
    /// The module's header, from its `header.json`.
    pub header: Header,
    /// The artifact's bytes, in the format the header's executor runs.
    pub executable: Box<[u8]>,
}

impl ModuleFiles {
    /// The module directory's `records/`, when it has one.
    pub fn records_dir(&self) -> Option<PathBuf> {
        Some(self.dir.join(RECORDS_DIR)).filter(|dir| dir.is_dir())
    }
}

/// The registry holding the records every one of `modules` carries in its
/// `records/`, for [`AroraBuilder::with_registry`](crate::AroraBuilder::with_registry).
/// A record two directories carry identically is held once. A directory
/// whose records do not read, or that carries a record another directory
/// carries differently under the same id and version, is an error naming the
/// module.
pub async fn registry(modules: &[ModuleFiles]) -> Result<LocalRegistry> {
    let mut registry = LocalRegistry::new();
    load_records(modules, &mut registry).await?;
    Ok(registry)
}

/// Load into `registry` the records every one of `modules` carries in its
/// `records/`, as [`registry`] does into an empty one: a record `registry`
/// already holds identically is held once, and one it holds differently
/// under the same id and version is an error naming the module.
pub(crate) async fn load_records(
    modules: &[ModuleFiles],
    registry: &mut LocalRegistry,
) -> Result<()> {
    for module in modules {
        let Some(records) = module.records_dir() else {
            continue;
        };
        load_records_from_yaml_dir(&records, registry)
            .await
            .with_context(|| {
                format!(
                    "the records of module '{}' ({})",
                    module.header.name,
                    records.display()
                )
            })?;
        log::info!(
            "module directory {}: records of '{}' loaded",
            module.dir.display(),
            module.header.name
        );
    }
    Ok(())
}

/// `registry` with every record `records` holds added: one it holds
/// identically is held once, and one it holds differently under the same id
/// and version is an error naming the record.
///
/// The folders go in first, together, so each finds its parent; then each
/// other record on its own, so an error names the record.
pub(crate) fn merge_records(
    mut registry: LocalRegistry,
    records: &LocalRegistry,
) -> Result<LocalRegistry> {
    let (folders, others): (Vec<_>, Vec<_>) = records_as_yaml(records)?
        .into_iter()
        .partition(|(kind, _, _)| *kind == RecordKind::Folder);
    // A local registry is in memory and the records are in hand: each future
    // completes without waiting on anything.
    futures::executor::block_on(load_records_from_yaml(
        folders
            .iter()
            .map(|(kind, stem, yaml)| (*kind, stem.as_str(), yaml.clone())),
        &mut registry,
    ))
    .context("the folders of the device's module directories do not join its registry")?;
    for (kind, stem, yaml) in &others {
        futures::executor::block_on(load_records_from_yaml(
            [(*kind, stem.as_str(), yaml.clone())],
            &mut registry,
        ))
        .with_context(|| {
            format!(
                "the device's module directories carry {} record {stem}, which does not join \
                 its registry",
                kind.directory()
            )
        })?;
    }
    Ok(registry)
}

/// Read the module directories a device carries: every one under
/// `<device_dir>/modules` ([`in_device_dir`]), then each of `dirs`, in that
/// order. One module in two of them is an error naming both directories.
pub(crate) fn read_device_modules(device_dir: &Path, dirs: &[PathBuf]) -> Result<Vec<ModuleFiles>> {
    let mut modules = in_device_dir(device_dir)?;
    for dir in dirs {
        modules.push(read(dir)?);
    }
    distinct(&modules)?;
    Ok(modules)
}

/// Read every module directory under `<device_dir>/modules`, in name order. A
/// device directory without a `modules/` carries no module; anything there
/// that is not a directory, or whose name starts with `.`, is not a module
/// directory.
pub fn in_device_dir(device_dir: &Path) -> Result<Vec<ModuleFiles>> {
    let modules = device_dir.join(MODULES_DIR);
    let mut dirs = match list(&modules) {
        Ok(entries) => entries,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(e).with_context(|| format!("could not list {}", modules.display())),
    };
    dirs.retain(|path| path.is_dir());
    let modules: Vec<ModuleFiles> = dirs.iter().map(|dir| read(dir)).collect::<Result<_>>()?;
    distinct(&modules)?;
    Ok(modules)
}

/// Read the module directory `dir`: its `header.json`, and the one file with
/// the extension the header's executor names. The error of a directory that
/// cannot be read names the module by the directory's name.
pub fn read(dir: &Path) -> Result<ModuleFiles> {
    let name = dir
        .file_name()
        .map(|name| name.to_string_lossy().into_owned())
        .unwrap_or_else(|| dir.display().to_string());
    read_files(dir).with_context(|| format!("module '{name}' ({})", dir.display()))
}

/// Checks that no two of `modules` carry one module id: the engine keeps the
/// first it loads and the method index the last, so a module in two
/// directories is a configuration to refuse, not to resolve.
fn distinct(modules: &[ModuleFiles]) -> Result<()> {
    let mut seen: HashMap<uuid::Uuid, &ModuleFiles> = HashMap::new();
    for module in modules {
        if let Some(first) = seen.insert(module.header.id, module) {
            bail!(
                "module directories {} and {} both carry module '{}' ({}): a device loads a \
                 module from one directory",
                first.dir.display(),
                module.dir.display(),
                module.header.name,
                module.header.id
            );
        }
    }
    Ok(())
}

fn read_files(dir: &Path) -> Result<ModuleFiles> {
    let header_path = dir.join(HEADER_FILE);
    let header_text = fs::read_to_string(&header_path)
        .with_context(|| format!("could not read {}", header_path.display()))?;
    let header: Header = serde_json::from_str(&header_text)
        .with_context(|| format!("{} is not a module header", header_path.display()))?;
    log::info!(
        "module directory {}: '{}' ({}, executor {})",
        dir.display(),
        header.name,
        header.id,
        header.executor.name
    );
    let executor = header.executor.name.as_str();
    let extension = artifact_extension(executor)?;
    let artifact = artifact_in(dir, executor, extension)?;
    let executable =
        fs::read(&artifact).with_context(|| format!("could not read {}", artifact.display()))?;
    Ok(ModuleFiles {
        dir: dir.to_path_buf(),
        header,
        executable: executable.into_boxed_slice(),
    })
}

/// The extension of the artifact `executor` runs: `wasm` for the WebAssembly
/// executor, the platform's dynamic-library extension for the native one.
/// These are the executors the runtime's engine carries; any other has no
/// artifact here to look for.
fn artifact_extension(executor: &str) -> Result<&'static str> {
    match executor {
        "wasm" => Ok("wasm"),
        "native" => Ok(std::env::consts::DLL_EXTENSION),
        other => bail!(
            "the header names executor '{other}', which this device does not run (wasm, native)"
        ),
    }
}

/// The one file in `dir` with `extension`.
fn artifact_in(dir: &Path, executor: &str, extension: &str) -> Result<PathBuf> {
    let mut found = list(dir).with_context(|| format!("could not list {}", dir.display()))?;
    found.retain(|path| path.is_file() && path.extension().is_some_and(|ext| ext == extension));
    match found.as_slice() {
        [artifact] => Ok(artifact.clone()),
        [] => {
            bail!("no .{extension} file beside {HEADER_FILE}: the executor '{executor}' runs one")
        }
        several => {
            let names: Vec<String> = several
                .iter()
                .filter_map(|path| path.file_name())
                .map(|name| name.to_string_lossy().into_owned())
                .collect();
            bail!(
                "several .{extension} files ({}): a module directory holds one artifact",
                names.join(", ")
            )
        }
    }
}

/// The entries of `dir` whose name does not start with `.`, sorted by path.
fn list(dir: &Path) -> io::Result<Vec<PathBuf>> {
    let mut entries: Vec<PathBuf> = fs::read_dir(dir)?
        .map(|entry| entry.map(|entry| entry.path()))
        .collect::<io::Result<_>>()?;
    entries.retain(|path| {
        !path
            .file_name()
            .is_some_and(|name| name.to_string_lossy().starts_with('.'))
    });
    entries.sort();
    Ok(entries)
}

/// Reading module directories, loading what they hold through the builder, and
/// dispatching it. `test-rust-wasm` is the guest: its header comes from its
/// Rust declaration, its `.wasm` from the `wasm32-wasip1` cdylib artifact
/// dependency Cargo builds.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::Arora;
    use arora_types::call::Call;
    use arora_types::module::low::Executor;
    use arora_types::value::Value;
    use uuid::Uuid;

    const WASM: &[u8] = include_bytes!(env!("CARGO_CDYLIB_FILE_TEST_RUST_WASM_test_rust_wasm"));

    // `succeed() -> bool`, as the guest's declaration pins it.
    const SUCCEED: &str = "00cd31a8-2cf4-48e6-a957-69a55de90424";

    /// A fresh device directory under the system temp dir, unique to `name`
    /// and this process.
    fn scratch(name: &str) -> PathBuf {
        let dir =
            std::env::temp_dir().join(format!("arora-module-dir-{name}-{}", std::process::id()));
        let _ = fs::remove_dir_all(&dir);
        fs::create_dir_all(&dir).unwrap();
        dir
    }

    fn header(executor: &str) -> Header {
        test_rust_wasm::test_rust_wasm::header(Executor {
            name: executor.to_string(),
            min_version: None,
            max_version: None,
        })
    }

    /// A module directory `<device_dir>/modules/<name>` holding `header` and
    /// each of `files`.
    fn module_dir(device_dir: &Path, name: &str, header: &str, files: &[(&str, &[u8])]) -> PathBuf {
        let dir = device_dir.join(MODULES_DIR).join(name);
        fs::create_dir_all(&dir).unwrap();
        fs::write(dir.join(HEADER_FILE), header).unwrap();
        for (file, bytes) in files {
            fs::write(dir.join(file), bytes).unwrap();
        }
        dir
    }

    fn json(header: &Header) -> String {
        serde_json::to_string_pretty(header).unwrap()
    }

    /// The modules under a device directory load into a device, and their
    /// functions dispatch through [`Arora::call`] like any module's. The
    /// artifact keeps the name it was published under.
    #[test]
    fn the_device_directory_s_modules_load_and_dispatch() {
        let device_dir = scratch("loads");
        let header = header("wasm");
        let module_id = header.id;
        module_dir(
            &device_dir,
            "sinus",
            &json(&header),
            &[("test_rust_wasm.wasm", WASM)],
        );

        let modules = in_device_dir(&device_dir).expect("the module directory reads");
        assert_eq!(modules.len(), 1);
        assert_eq!(modules[0].header.id, module_id);
        assert_eq!(modules[0].dir, device_dir.join("modules").join("sinus"));

        let mut builder = Arora::builder();
        for module in modules {
            builder = builder.with_module(module.header, module.executable);
        }
        let mut arora = builder.build().expect("build a device with the module");
        let result = arora
            .call(Call {
                module_id: Some(module_id),
                id: Uuid::parse_str(SUCCEED).unwrap(),
                args: Vec::new(),
            })
            .expect("call succeed() on the loaded module");
        assert_eq!(result.ret, Value::Boolean(true));
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// A device directory with no `modules/` carries no module; a file among
    /// the module directories is not one, nor is a directory whose name
    /// starts with `.` (OS metadata).
    #[test]
    fn a_device_directory_without_modules_carries_none() {
        let device_dir = scratch("none");
        assert!(in_device_dir(&device_dir).unwrap().is_empty());
        let modules = device_dir.join(MODULES_DIR);
        fs::create_dir_all(modules.join(".git")).unwrap();
        fs::create_dir_all(modules.join(".Trashes")).unwrap();
        fs::write(modules.join(".DS_Store"), b"").unwrap();
        fs::write(modules.join("notes.txt"), b"").unwrap();
        assert!(in_device_dir(&device_dir).unwrap().is_empty());
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// OS metadata beside the artifact — an AppleDouble `._m.wasm`, a
    /// `.DS_Store` — is not an artifact: the one `.wasm` is still found.
    #[test]
    fn metadata_beside_the_artifact_is_not_an_artifact() {
        let device_dir = scratch("apple-double");
        module_dir(
            &device_dir,
            "sinus",
            &json(&header("wasm")),
            &[
                ("m.wasm", WASM),
                ("._m.wasm", b"AppleDouble"),
                (".DS_Store", b""),
            ],
        );
        let modules = in_device_dir(&device_dir).expect("the sidecar is ignored");
        assert_eq!(modules.len(), 1);
        assert_eq!(&*modules[0].executable, WASM);
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// A header that is not one fails the read, naming the module.
    #[test]
    fn a_broken_header_fails_naming_the_module() {
        let device_dir = scratch("broken-header");
        module_dir(&device_dir, "broken", "{ not a header", &[]);
        let error = in_device_dir(&device_dir).expect_err("a broken header is refused");
        let message = format!("{error:#}");
        assert!(message.contains("module 'broken'"), "{message}");
        assert!(message.contains("is not a module header"), "{message}");
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// A module directory without a header fails the read, naming the module.
    #[test]
    fn a_missing_header_fails_naming_the_module() {
        let device_dir = scratch("no-header");
        let dir = device_dir.join(MODULES_DIR).join("headless");
        fs::create_dir_all(&dir).unwrap();
        fs::write(dir.join("module.wasm"), WASM).unwrap();
        let error = in_device_dir(&device_dir).expect_err("a module without a header is refused");
        let message = format!("{error:#}");
        assert!(message.contains("module 'headless'"), "{message}");
        assert!(message.contains("header.json"), "{message}");
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// The artifact is the one file with the executor's extension: none, or
    /// several, fails the read naming the module.
    #[test]
    fn the_artifact_is_the_one_file_with_the_executor_s_extension() {
        let device_dir = scratch("artifacts");
        let header = json(&header("wasm"));
        module_dir(
            &device_dir,
            "bare",
            &header,
            &[("readme.md", b"no wasm here")],
        );
        let error = in_device_dir(&device_dir).expect_err("no artifact is refused");
        let message = format!("{error:#}");
        assert!(message.contains("module 'bare'"), "{message}");
        assert!(message.contains("no .wasm file"), "{message}");

        let _ = fs::remove_dir_all(device_dir.join(MODULES_DIR));
        module_dir(
            &device_dir,
            "twice",
            &header,
            &[("a.wasm", WASM), ("b.wasm", WASM)],
        );
        let error = in_device_dir(&device_dir).expect_err("two artifacts are refused");
        let message = format!("{error:#}");
        assert!(message.contains("module 'twice'"), "{message}");
        assert!(
            message.contains("several .wasm files (a.wasm, b.wasm)"),
            "{message}"
        );
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// A native module's artifact is the platform's dynamic library; the read
    /// does not judge its bytes (the engine does, at load).
    #[test]
    fn a_native_module_s_artifact_is_the_platform_s_dynamic_library() {
        let device_dir = scratch("native");
        let library = format!("libthing.{}", std::env::consts::DLL_EXTENSION);
        module_dir(
            &device_dir,
            "thing",
            &json(&header("native")),
            &[(library.as_str(), b"not a library"), ("thing.wasm", WASM)],
        );
        let modules = in_device_dir(&device_dir).expect("the native module reads");
        assert_eq!(&*modules[0].executable, b"not a library");
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// An executor this device does not run has no artifact to look for.
    #[test]
    fn an_executor_the_device_does_not_run_fails_naming_it() {
        let device_dir = scratch("executor");
        module_dir(&device_dir, "py", &json(&header("python")), &[]);
        let error = in_device_dir(&device_dir).expect_err("an unknown executor is refused");
        let message = format!("{error:#}");
        assert!(message.contains("module 'py'"), "{message}");
        assert!(message.contains("executor 'python'"), "{message}");
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// One module in two directories is refused, naming both directories and
    /// the module.
    #[test]
    fn one_module_in_two_directories_is_refused() {
        let device_dir = scratch("twins");
        let header = json(&header("wasm"));
        let first = module_dir(&device_dir, "first", &header, &[("m.wasm", WASM)]);
        let second = module_dir(&device_dir, "second", &header, &[("m.wasm", WASM)]);
        let error = in_device_dir(&device_dir).expect_err("a module in two directories is refused");
        let message = format!("{error:#}");
        assert!(
            message.contains(&format!(
                "module directories {} and {} both carry module 'test-rust-wasm'",
                first.display(),
                second.display()
            )),
            "{message}"
        );
        fs::remove_dir_all(&device_dir).unwrap();
    }

    /// The modules load in the order of their directories' names, so a device
    /// starts the same way each time.
    #[test]
    fn modules_read_in_name_order() {
        let device_dir = scratch("order");
        let base = header("wasm");
        for (name, id) in [("b", 2u128), ("a", 1), ("c", 3)] {
            let mut header = base.clone();
            header.id = Uuid::from_u128(id);
            module_dir(&device_dir, name, &json(&header), &[("m.wasm", WASM)]);
        }
        let ids: Vec<u128> = in_device_dir(&device_dir)
            .unwrap()
            .iter()
            .map(|module| module.header.id.as_u128())
            .collect();
        assert_eq!(ids, vec![1, 2, 3]);
        fs::remove_dir_all(&device_dir).unwrap();
    }
}