mecha10_node_resolver/

lib.rs

//! Mecha10 Node Resolver
//!
//! Lightweight runtime resolver for downloading and spawning mecha10 framework nodes.
//! This crate is designed to be embedded in robot binaries to enable runtime download
//! of pre-compiled framework nodes, avoiding slow cross-compilation during build.
//!
//! # Architecture
//!
//! ```text
//! Robot Binary (thin)
//!   │
//!   ├── Custom nodes (compiled in)
//!   │
//!   └── NodeResolver
//!         │
//!         ├── resolve("speaker") → downloads if needed
//!         │
//!         └── spawn("speaker", env) → runs as subprocess
//!                 │
//!                 └── ~/.mecha10/bin/speaker-0.1.44-aarch64-linux-musl
//! ```
//!
//! # Usage
//!
//! ```no_run
//! use mecha10_node_resolver::NodeResolver;
//! use std::collections::HashMap;
//!
//! # async fn example() -> anyhow::Result<()> {
//! let resolver = NodeResolver::new()?;
//!
//! // Check if it's a framework node
//! if NodeResolver::is_framework_node("@mecha10/speaker") {
//!     // Resolve (downloads if needed)
//!     let binary_path = resolver.resolve("speaker").await?;
//!
//!     // Spawn as subprocess
//!     let mut env = HashMap::new();
//!     env.insert("REDIS_URL".to_string(), "redis://localhost:6379".to_string());
//!     let child = resolver.spawn("speaker", env).await?;
//! }
//! # Ok(())
//! # }
//! ```

use anyhow::{Context, Result};
use std::collections::HashMap;
use std::path::PathBuf;
use std::process::Stdio;
use tokio::process::{Child, Command};

/// GitHub repository for node binaries
const GITHUB_REPO: &str = "mecha-industries/user-tools";

/// Framework version (embedded at compile time)
const FRAMEWORK_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Supported pre-built targets
/// Note: Linux uses gnu targets for better compatibility with system libraries
/// (audio, USB, etc.) since robots typically run Raspberry Pi OS / Ubuntu (glibc)
const SUPPORTED_TARGETS: &[&str] = &[
    "aarch64-apple-darwin",
    "x86_64-apple-darwin",
    "x86_64-unknown-linux-gnu",
    "aarch64-unknown-linux-gnu",
];

/// Node resolver for downloading and spawning framework nodes
#[derive(Clone)]
pub struct NodeResolver {
    /// Binary cache directory (~/.mecha10/bin)
    cache_dir: PathBuf,
    /// Framework version
    version: String,
    /// Target triple for this platform
    target: String,
}

impl NodeResolver {
    /// Create a new node resolver
    pub fn new() -> Result<Self> {
        let cache_dir = Self::default_cache_dir()?;
        let version = FRAMEWORK_VERSION.to_string();
        let target = Self::detect_target()?;

        Ok(Self {
            cache_dir,
            version,
            target,
        })
    }

    /// Create a resolver with a specific version
    pub fn with_version(version: String) -> Result<Self> {
        let cache_dir = Self::default_cache_dir()?;
        let target = Self::detect_target()?;

        Ok(Self {
            cache_dir,
            version,
            target,
        })
    }

    /// Get the default cache directory
    fn default_cache_dir() -> Result<PathBuf> {
        let home = std::env::var("HOME").context("HOME environment variable not set")?;
        Ok(PathBuf::from(home).join(".mecha10").join("bin"))
    }

    /// Detect the current platform's target triple
    fn detect_target() -> Result<String> {
        let target = match (std::env::consts::OS, std::env::consts::ARCH) {
            ("macos", "aarch64") => "aarch64-apple-darwin",
            ("macos", "x86_64") => "x86_64-apple-darwin",
            // Linux uses gnu for compatibility with system libraries (audio, USB, etc.)
            ("linux", "x86_64") => "x86_64-unknown-linux-gnu",
            ("linux", "aarch64") => "aarch64-unknown-linux-gnu",
            (os, arch) => {
                return Err(anyhow::anyhow!(
                    "Unsupported platform: {}-{}. Pre-built binaries not available.",
                    os,
                    arch
                ))
            }
        };
        Ok(target.to_string())
    }

    /// Check if a node name is a framework node (@mecha10/*)
    pub fn is_framework_node(name: &str) -> bool {
        name.starts_with("@mecha10/")
    }

    /// Extract the short name from a framework node identifier
    ///
    /// "@mecha10/speaker" -> "speaker"
    pub fn short_name(name: &str) -> Option<&str> {
        name.strip_prefix("@mecha10/")
    }

    /// Check if pre-built binaries are available for this platform
    pub fn is_prebuilt_available(&self) -> bool {
        SUPPORTED_TARGETS.contains(&self.target.as_str())
    }

    /// Get the version
    pub fn version(&self) -> &str {
        &self.version
    }

    /// Get the target
    pub fn target(&self) -> &str {
        &self.target
    }

    /// Resolve a framework node binary, downloading if needed
    ///
    /// # Arguments
    ///
    /// * `node_name` - Short name of the node (e.g., "speaker", not "@mecha10/speaker")
    ///
    /// # Returns
    ///
    /// Path to the executable binary
    pub async fn resolve(&self, node_name: &str) -> Result<PathBuf> {
        // Check cache first
        if let Some(cached) = self.find_cached(node_name) {
            tracing::debug!("Using cached binary: {}", cached.display());
            return Ok(cached);
        }

        // Try to download
        if self.is_prebuilt_available() {
            match self.download(node_name).await {
                Ok(path) => {
                    tracing::info!("Downloaded binary for {}: {}", node_name, path.display());
                    return Ok(path);
                }
                Err(e) => {
                    tracing::warn!("Failed to download binary for {}: {}", node_name, e);
                }
            }
        } else {
            tracing::warn!(
                "Pre-built binary not available for {} on {}",
                node_name,
                self.target
            );
        }

        Err(anyhow::anyhow!(
            "Could not resolve binary for node '{}'. \
             Pre-built binary not available for target '{}'.",
            node_name,
            self.target
        ))
    }

    /// Spawn a framework node as a subprocess
    ///
    /// # Arguments
    ///
    /// * `node_name` - Short name of the node (e.g., "speaker")
    /// * `env` - Environment variables to pass to the node
    ///
    /// # Returns
    ///
    /// The spawned child process
    pub async fn spawn(&self, node_name: &str, env: HashMap<String, String>) -> Result<Child> {
        let binary_path = self.resolve(node_name).await?;

        tracing::info!("Spawning node {} from {}", node_name, binary_path.display());

        let child = Command::new(&binary_path)
            .envs(env)
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()
            .with_context(|| format!("Failed to spawn node {}", node_name))?;

        Ok(child)
    }

    /// Spawn a framework node and wait for it to complete
    pub async fn spawn_and_wait(&self, node_name: &str, env: HashMap<String, String>) -> Result<()> {
        let binary_path = self.resolve(node_name).await?;

        tracing::info!("Running node {} from {}", node_name, binary_path.display());

        let status = Command::new(&binary_path)
            .envs(env)
            .status()
            .await
            .with_context(|| format!("Failed to run node {}", node_name))?;

        if !status.success() {
            return Err(anyhow::anyhow!(
                "Node {} exited with status: {}",
                node_name,
                status
            ));
        }

        Ok(())
    }

    /// Check for cached binary
    fn find_cached(&self, node_name: &str) -> Option<PathBuf> {
        let binary_name = self.binary_name(node_name);
        let path = self.cache_dir.join(&binary_name);

        if path.exists() && path.is_file() {
            #[cfg(unix)]
            {
                use std::os::unix::fs::PermissionsExt;
                if let Ok(metadata) = path.metadata() {
                    if metadata.permissions().mode() & 0o111 != 0 {
                        return Some(path);
                    }
                }
            }

            #[cfg(not(unix))]
            {
                return Some(path);
            }
        }

        // Also check symlink without version
        let symlink_path = self.cache_dir.join(node_name);
        if symlink_path.exists() {
            if let Ok(resolved) = std::fs::canonicalize(&symlink_path) {
                if resolved.exists() {
                    return Some(resolved);
                }
            }
        }

        None
    }

    /// Build the binary name for a node
    fn binary_name(&self, node_name: &str) -> String {
        format!("{}-{}-{}", node_name, self.version, self.target)
    }

    /// Build the tarball name for a node
    fn tarball_name(&self, node_name: &str) -> String {
        format!("{}-{}-{}.tar.gz", node_name, self.version, self.target)
    }

    /// Download binary from GitHub releases
    async fn download(&self, node_name: &str) -> Result<PathBuf> {
        let client = reqwest::Client::builder()
            .user_agent("mecha10-node-resolver")
            .build()
            .context("Failed to build HTTP client")?;

        let tarball_name = self.tarball_name(node_name);
        let release_tag = format!("v{}", self.version);

        // Try to get release info
        let release_url = format!(
            "https://api.github.com/repos/{}/releases/tags/{}",
            GITHUB_REPO, release_tag
        );

        tracing::info!("Downloading {} (v{})...", node_name, self.version);

        let response = client
            .get(&release_url)
            .send()
            .await
            .context("Failed to fetch release info from GitHub")?;

        if !response.status().is_success() {
            let status = response.status();
            if status.as_u16() == 404 {
                return Err(anyhow::anyhow!(
                    "Release v{} not found. Node binaries may not be published yet.",
                    self.version
                ));
            }
            return Err(anyhow::anyhow!("Failed to get release info: HTTP {}", status));
        }

        let release: serde_json::Value = response.json().await?;

        // Find the asset
        let assets = release["assets"]
            .as_array()
            .ok_or_else(|| anyhow::anyhow!("No assets in release"))?;

        let asset = assets
            .iter()
            .find(|a| a["name"].as_str().map(|n| n == tarball_name).unwrap_or(false))
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "Binary '{}' not found in release v{}.",
                    tarball_name,
                    self.version
                )
            })?;

        let download_url = asset["browser_download_url"]
            .as_str()
            .ok_or_else(|| anyhow::anyhow!("No download URL for asset"))?;

        // Download
        let response = client
            .get(download_url)
            .send()
            .await
            .context("Failed to download binary")?;

        if !response.status().is_success() {
            return Err(anyhow::anyhow!("Download failed: HTTP {}", response.status()));
        }

        // Download to temp file
        let temp_dir = tempdir()?;
        let temp_file = temp_dir.path().join("binary.tar.gz");

        let bytes = response.bytes().await?;
        tokio::fs::write(&temp_file, &bytes).await?;

        // Create cache directory
        tokio::fs::create_dir_all(&self.cache_dir).await?;

        // Extract tarball
        let tar_gz = std::fs::File::open(&temp_file)?;
        let tar = flate2::read::GzDecoder::new(tar_gz);
        let mut archive = tar::Archive::new(tar);

        let extract_dir = temp_dir.path().join("extract");
        std::fs::create_dir_all(&extract_dir)?;
        archive.unpack(&extract_dir)?;

        // Find the binary
        let extracted_binary = extract_dir.join(node_name);
        if !extracted_binary.exists() {
            return Err(anyhow::anyhow!("Binary '{}' not found in tarball", node_name));
        }

        // Move to cache
        let binary_name = self.binary_name(node_name);
        let dest_path = self.cache_dir.join(&binary_name);

        tokio::fs::copy(&extracted_binary, &dest_path).await?;

        // Make executable
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mut perms = tokio::fs::metadata(&dest_path).await?.permissions();
            perms.set_mode(0o755);
            tokio::fs::set_permissions(&dest_path, perms).await?;
        }

        // Create symlink
        let symlink_path = self.cache_dir.join(node_name);
        if symlink_path.exists() || symlink_path.is_symlink() {
            tokio::fs::remove_file(&symlink_path).await.ok();
        }

        #[cfg(unix)]
        {
            std::os::unix::fs::symlink(&binary_name, &symlink_path)?;
        }

        tracing::info!("Installed {} to {}", node_name, dest_path.display());

        Ok(dest_path)
    }

    /// Resolve all framework nodes from a list, downloading in parallel
    pub async fn resolve_all(&self, nodes: &[String]) -> Result<HashMap<String, PathBuf>> {
        use futures_util::future::join_all;

        let framework_nodes: Vec<_> = nodes
            .iter()
            .filter(|n| Self::is_framework_node(n))
            .filter_map(|n| Self::short_name(n).map(|s| s.to_string()))
            .collect();

        if framework_nodes.is_empty() {
            return Ok(HashMap::new());
        }

        tracing::info!("Resolving {} framework nodes...", framework_nodes.len());

        let futures = framework_nodes.iter().map(|name| {
            let resolver = self.clone();
            let name = name.clone();
            async move {
                let result = resolver.resolve(&name).await;
                (name, result)
            }
        });

        let results = join_all(futures).await;

        let mut resolved = HashMap::new();
        for (name, result) in results {
            match result {
                Ok(path) => {
                    resolved.insert(name, path);
                }
                Err(e) => {
                    return Err(anyhow::anyhow!("Failed to resolve node '{}': {}", name, e));
                }
            }
        }

        tracing::info!("All {} framework nodes ready", resolved.len());
        Ok(resolved)
    }
}

impl Default for NodeResolver {
    fn default() -> Self {
        Self::new().expect("Failed to create NodeResolver")
    }
}

// Inline tempdir implementation to avoid external dependency
struct TempDir {
    path: PathBuf,
}

impl TempDir {
    fn path(&self) -> &std::path::Path {
        &self.path
    }
}

impl Drop for TempDir {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.path);
    }
}

fn tempdir() -> std::io::Result<TempDir> {
    let mut path = std::env::temp_dir();
    path.push(format!("mecha10-node-resolver-{}-{}", std::process::id(), rand_u64()));
    std::fs::create_dir_all(&path)?;
    Ok(TempDir { path })
}

fn rand_u64() -> u64 {
    use std::time::{SystemTime, UNIX_EPOCH};
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos() as u64)
        .unwrap_or(0)
}

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

    #[test]
    fn test_is_framework_node() {
        assert!(NodeResolver::is_framework_node("@mecha10/speaker"));
        assert!(NodeResolver::is_framework_node("@mecha10/motor"));
        assert!(!NodeResolver::is_framework_node("my-custom-node"));
        assert!(!NodeResolver::is_framework_node("speaker"));
    }

    #[test]
    fn test_short_name() {
        assert_eq!(NodeResolver::short_name("@mecha10/speaker"), Some("speaker"));
        assert_eq!(NodeResolver::short_name("@mecha10/motor"), Some("motor"));
        assert_eq!(NodeResolver::short_name("my-custom-node"), None);
    }

    #[test]
    fn test_binary_name() {
        let resolver = NodeResolver {
            cache_dir: PathBuf::from("/tmp"),
            version: "0.1.44".to_string(),
            target: "aarch64-unknown-linux-gnu".to_string(),
        };

        assert_eq!(
            resolver.binary_name("speaker"),
            "speaker-0.1.44-aarch64-unknown-linux-gnu"
        );
    }
}