mxsh 0.1.0

//! System abstraction layer for mxsh.
//!
//! The runtime trait abstracts external child-process lifecycle.
//!
//! All I/O is fd-based. The shell state carries three [`FileDescriptor`] values
//! (stdin, stdout, stderr).
//! Builtins read/write through these fds.
//!
//! For testing, [`StringStdioIn`] and [`StringStdioOut`] create OS pipes backed by background
//! threads that pump data, so they produce real fds usable by both builtins and spawned processes.

#[cfg(feature = "unix-runtime")]
mod backend;
mod fd;
#[cfg(feature = "test-support")]
mod test_runtimes;
#[cfg(feature = "test-support")]
mod test_stdio;
#[cfg(feature = "unix-runtime")]
mod unix_exec;
mod wait;

use std::ffi::CString;
use std::io;
#[cfg(any(feature = "unix-runtime", feature = "test-support"))]
use std::os::unix::fs::PermissionsExt;
use std::path::Path;
use std::path::PathBuf;

#[cfg(feature = "unix-runtime")]
use self::backend::{FdAction, exec, pid_from_handle, spawn_command};
pub use self::fd::{FileDescriptor, OsPipe};
#[cfg(feature = "test-support")]
pub use self::test_runtimes::{DeterministicRuntime, InMemoryCommand, InMemoryRuntime};
#[cfg(feature = "test-support")]
pub use self::test_stdio::{StringStdioIn, StringStdioOut};
use self::wait::wait_child_status;
#[cfg(feature = "unix-runtime")]
use self::wait::wait_pid_status;
#[cfg(feature = "unix-runtime")]
use self::wait::wait_process;
pub use self::wait::{ProcessEvent, WaitMode};

////////////////////////////////////////// other syscalls //////////////////////////////////////////

/// Get the parent PID.
pub fn parent_pid() -> u32 {
    unsafe { libc::getppid() as u32 }
}

/// Get the current umask (reads and restores it atomically).
pub fn get_umask() -> u32 {
    let mask = unsafe { libc::umask(0) };
    unsafe { libc::umask(mask) };
    mask as u32
}

/// Set the umask.
pub fn set_umask(mask: u32) {
    unsafe { libc::umask(mask as libc::mode_t) };
}

/// Process times from `times(2)`.
pub struct ProcessTimes {
    /// User time in seconds.
    pub user_secs: f64,
    /// System time in seconds.
    pub sys_secs: f64,
    /// Children user time in seconds.
    pub child_user_secs: f64,
    /// Children system time in seconds.
    pub child_sys_secs: f64,
}

/// Get process times via `times(2)`.
pub fn get_times() -> ProcessTimes {
    let mut tms = libc::tms {
        tms_utime: 0,
        tms_stime: 0,
        tms_cutime: 0,
        tms_cstime: 0,
    };
    unsafe { libc::times(&mut tms) };
    let ticks = unsafe { libc::sysconf(libc::_SC_CLK_TCK) } as f64;
    ProcessTimes {
        user_secs: tms.tms_utime as f64 / ticks,
        sys_secs: tms.tms_stime as f64 / ticks,
        child_user_secs: tms.tms_cutime as f64 / ticks,
        child_sys_secs: tms.tms_cstime as f64 / ticks,
    }
}

/// Expand a glob pattern into matching filenames.
pub fn glob_expand(pattern: &str) -> Vec<String> {
    let c_pattern = match CString::new(pattern) {
        Ok(c) => c,
        Err(_) => return Vec::new(),
    };

    let mut glob_buf: libc::glob_t = unsafe { std::mem::zeroed() };
    let ret = unsafe { libc::glob(c_pattern.as_ptr(), 0, None, &mut glob_buf) };

    let mut results = Vec::new();
    if ret == 0 {
        for i in 0..glob_buf.gl_pathc {
            let path = unsafe { *glob_buf.gl_pathv.add(i) };
            if !path.is_null() {
                let s = unsafe { std::ffi::CStr::from_ptr(path) };
                if let Ok(s) = s.to_str() {
                    results.push(s.to_string());
                }
            }
        }
    }
    unsafe { libc::globfree(&mut glob_buf) };
    results
}

/////////////////////////////////////////// Runtime ////////////////////////////////////////////////

/// Opaque runtime-owned process identity used by the shell.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct ProcessHandle(u64);

impl ProcessHandle {
    pub const fn new(raw: u64) -> Self {
        Self(raw)
    }

    pub const fn as_u64(self) -> u64 {
        self.0
    }
}

/// Runtime spawn intent for one process.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SpawnMode {
    Foreground,
    BackgroundJob,
}

/// Semantic process-group signals requested by the shell.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RuntimeSignal {
    Continue,
    Stop,
    Interrupt,
    Terminate,
}

/// Runtime spawn result including optional presentation metadata.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SpawnedProcess {
    pub handle: ProcessHandle,
    pub display_pid: Option<u32>,
}

/// An inherited parent fd that should appear as `child_fd` in the spawned process.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PassedFileDescriptor {
    pub parent_fd: FileDescriptor,
    pub child_fd: FileDescriptor,
}

/// Fully resolved external command invocation.
#[derive(Debug, Clone)]
pub struct ExternalCommand {
    /// Program name (may be a bare name for PATH search or a path).
    pub program: String,
    /// Full argv including `argv[0]`.
    pub argv: Vec<String>,
    /// Environment variables for the child.
    pub env: Vec<(String, String)>,
    /// Working directory for the child.
    pub cwd: PathBuf,
    /// Whether the child should start in its own process group.
    pub create_process_group: bool,
    /// Additional inherited fds that should be dup'd into the child before exec.
    pub passed_fds: Vec<PassedFileDescriptor>,
}

#[cfg(feature = "embed")]
pub(crate) fn spawn_error_exit_status(err: &io::Error) -> i32 {
    if err.kind() == io::ErrorKind::NotFound || err.raw_os_error() == Some(libc::ENOENT) {
        127
    } else {
        126
    }
}

/// Provide the full runtime surface needed by mxsh execution.
pub trait Runtime {
    /// Runtime-owned foreground lease used to restore terminal ownership.
    type ForegroundGuard;

    /// Create an isolated runtime instance for subshell-style execution.
    ///
    /// Command substitution, subshell bodies, and shell-only pipeline stages
    /// use this to make runtime forking explicit instead of relying on `Clone`.
    fn fork(&self) -> Result<Self, std::io::Error>
    where
        Self: Sized;

    /// Spawn one external command and return a child handle.
    fn spawn_external_command(
        &mut self,
        command: &ExternalCommand,
        stdio: SpawnStdio,
        close_fds: &[FileDescriptor],
        mode: SpawnMode,
    ) -> Result<SpawnedProcess, std::io::Error>;

    /// Observe the next lifecycle event for a previously spawned process.
    fn wait_process(
        &mut self,
        process: ProcessHandle,
        mode: WaitMode,
    ) -> Result<ProcessEvent, std::io::Error>;

    /// Wait for a process identified only by a display pid when supported.
    ///
    /// `Ok(None)` means the runtime does not support pid-only waits. Unknown
    /// pids should return `io::ErrorKind::NotFound`.
    fn wait_display_pid(&mut self, _display_pid: u32) -> Result<Option<i32>, io::Error> {
        Ok(None)
    }

    /// Wait until `process` reaches a terminal status and return the shell exit code.
    fn wait_child(&mut self, process: ProcessHandle) -> i32 {
        wait_child_status(|| self.wait_process(process, WaitMode::Block))
    }

    /// Deliver a semantic signal to the process group associated with `process`.
    fn signal_process_group(
        &mut self,
        process: ProcessHandle,
        signal: RuntimeSignal,
    ) -> Result<(), std::io::Error>;

    /// Claim the terminal foreground for `process`.
    ///
    /// The returned guard represents runtime-owned state required to restore the
    /// previous foreground owner. Callers must pass that exact guard back to
    /// [`Runtime::release_foreground`] once foreground execution is done,
    /// including when command execution fails after the claim succeeds.
    fn claim_foreground(
        &mut self,
        process: ProcessHandle,
        tty: FileDescriptor,
    ) -> Result<Self::ForegroundGuard, std::io::Error>;

    /// Restore a previously claimed foreground lease.
    ///
    /// Implementations should make this operation idempotent and best-effort when
    /// possible so terminal ownership is restored even if earlier execution stages
    /// failed. If restoration cannot be completed, return the restore error after
    /// attempting any remaining cleanup that keeps terminal ownership safe.
    fn release_foreground(&mut self, guard: Self::ForegroundGuard) -> Result<(), std::io::Error>;

    /// Return true when the runtime can execute `program` without PATH-based host lookup.
    ///
    /// Implementations may keep this as a fast-path hint for runtimes with internal
    /// command registries, but callers must not treat it as authoritative lookup.
    /// Runtime-based PATH resolution and error classification belong in
    /// [`Runtime::resolve_command_path`].
    fn has_command(&self, _program: &str) -> bool {
        false
    }

    /// Resolve an external command using PATH-like lookup rules.
    ///
    /// `path_var` is a colon-separated search path used when `program` is not already
    /// absolute or explicitly relative. Successful lookup returns the exact program
    /// path the runtime will execute. Missing commands should return
    /// `io::ErrorKind::NotFound`; commands found but not executable should return
    /// `io::ErrorKind::PermissionDenied`.
    fn resolve_command_path(&self, program: &str, _path_var: &str) -> Result<PathBuf, io::Error> {
        if self.has_command(program) {
            Ok(PathBuf::from(program))
        } else {
            Err(io::Error::new(
                io::ErrorKind::NotFound,
                format!("{program}: command not found"),
            ))
        }
    }

    /// Replace the current process with a new program.
    ///
    /// Non-`exec` runtimes should return `io::ErrorKind::Unsupported` to make
    /// limitations explicit.
    fn exec_replace(
        &self,
        program: &str,
        argv: &[String],
        env: &[(String, String)],
        cwd: &Path,
    ) -> Result<(), std::io::Error>;
}

#[cfg(any(feature = "unix-runtime", feature = "test-support"))]
fn resolve_executable_path(path: &Path) -> Result<PathBuf, io::Error> {
    let meta = match std::fs::metadata(path) {
        Ok(meta) => meta,
        Err(err) => {
            return Err(io::Error::new(io::ErrorKind::NotFound, err.to_string()));
        }
    };
    if !meta.is_file() {
        return Err(io::Error::new(
            io::ErrorKind::PermissionDenied,
            format!("{}: Permission denied", path.display()),
        ));
    }
    if meta.permissions().mode() & 0o111 == 0 {
        return Err(io::Error::new(
            io::ErrorKind::PermissionDenied,
            format!("{}: Permission denied", path.display()),
        ));
    }
    Ok(path.to_path_buf())
}

#[cfg(any(feature = "unix-runtime", feature = "test-support"))]
fn resolve_command_path(program: &str, path_var: &str) -> Result<PathBuf, io::Error> {
    if program.contains('/') {
        return resolve_executable_path(Path::new(program));
    }
    for dir in path_var.split(':') {
        let candidate = Path::new(dir).join(program);
        match resolve_executable_path(&candidate) {
            Err(err) if err.kind() == io::ErrorKind::NotFound => {}
            other => return other,
        }
    }
    Err(io::Error::new(
        io::ErrorKind::NotFound,
        format!("{program}: command not found"),
    ))
}

/////////////////////////////////////////// UnixRuntime ////////////////////////////////////////////

/// Unix implementation of the runtime trait using `posix_spawnp` and OS pipes.
#[cfg(feature = "unix-runtime")]
#[derive(Clone, Debug)]
pub struct UnixRuntime {}

#[cfg(feature = "unix-runtime")]
#[derive(Clone, Copy, Debug)]
pub struct UnixForegroundGuard {
    tty: FileDescriptor,
    previous_pgid: libc::pid_t,
}

#[cfg(feature = "unix-runtime")]
impl UnixRuntime {
    /// Create a new UnixRuntime.
    pub fn new() -> Self {
        Self {}
    }
}

#[cfg(feature = "unix-runtime")]
impl Default for UnixRuntime {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(feature = "unix-runtime")]
impl Runtime for UnixRuntime {
    type ForegroundGuard = UnixForegroundGuard;

    fn fork(&self) -> Result<Self, std::io::Error> {
        Ok(Self::new())
    }

    fn spawn_external_command(
        &mut self,
        command: &ExternalCommand,
        stdio: SpawnStdio,
        close_fds: &[FileDescriptor],
        mode: SpawnMode,
    ) -> Result<SpawnedProcess, std::io::Error> {
        let fd_actions: Vec<FdAction> = close_fds.iter().copied().map(FdAction::Close).collect();
        let create_process_group =
            command.create_process_group || matches!(mode, SpawnMode::BackgroundJob);
        let pid = spawn_command(command, create_process_group, stdio, &fd_actions)?;
        Ok(SpawnedProcess {
            handle: ProcessHandle::new(pid as u64),
            display_pid: Some(pid as u32),
        })
    }

    fn wait_process(
        &mut self,
        process: ProcessHandle,
        mode: WaitMode,
    ) -> Result<ProcessEvent, std::io::Error> {
        wait_process(pid_from_handle(process)?, mode)
    }

    fn wait_display_pid(&mut self, display_pid: u32) -> Result<Option<i32>, io::Error> {
        wait_pid_status(display_pid as libc::pid_t).map(Some)
    }

    fn signal_process_group(
        &mut self,
        process: ProcessHandle,
        signal: RuntimeSignal,
    ) -> Result<(), std::io::Error> {
        let pid = pid_from_handle(process)?;
        let signal = match signal {
            RuntimeSignal::Continue => libc::SIGCONT,
            RuntimeSignal::Stop => libc::SIGSTOP,
            RuntimeSignal::Interrupt => libc::SIGINT,
            RuntimeSignal::Terminate => libc::SIGTERM,
        };
        if unsafe { libc::kill(-pid, signal) } == 0 {
            Ok(())
        } else {
            Err(std::io::Error::last_os_error())
        }
    }

    fn claim_foreground(
        &mut self,
        process: ProcessHandle,
        tty: FileDescriptor,
    ) -> Result<Self::ForegroundGuard, std::io::Error> {
        let pid = pid_from_handle(process)?;
        let previous_pgid = unsafe { libc::getpgrp() };
        if unsafe { libc::tcsetpgrp(tty.into_raw_fd(), pid) } == 0 {
            Ok(UnixForegroundGuard { tty, previous_pgid })
        } else {
            Err(std::io::Error::last_os_error())
        }
    }

    fn release_foreground(&mut self, guard: Self::ForegroundGuard) -> Result<(), std::io::Error> {
        if unsafe { libc::tcsetpgrp(guard.tty.into_raw_fd(), guard.previous_pgid) } == 0 {
            Ok(())
        } else {
            Err(std::io::Error::last_os_error())
        }
    }

    fn has_command(&self, _program: &str) -> bool {
        false
    }

    fn resolve_command_path(&self, program: &str, path_var: &str) -> Result<PathBuf, io::Error> {
        resolve_command_path(program, path_var)
    }

    fn exec_replace(
        &self,
        program: &str,
        argv: &[String],
        env: &[(String, String)],
        cwd: &Path,
    ) -> Result<(), std::io::Error> {
        exec(program, argv, env, cwd)
    }
}

///////////////////////////////////////////// SpawnStdio ///////////////////////////////////////////

/// Parent-provided stdio fds for child processes.
#[derive(Clone, Copy, Debug)]
pub struct SpawnStdio {
    /// Stdin fd for the child.
    pub stdin_fd: FileDescriptor,
    /// Stdout fd for the child.
    pub stdout_fd: FileDescriptor,
    /// Stderr fd for the child.
    pub stderr_fd: FileDescriptor,
}

impl Default for SpawnStdio {
    fn default() -> Self {
        Self {
            stdin_fd: FileDescriptor::STDIN,
            stdout_fd: FileDescriptor::STDOUT,
            stderr_fd: FileDescriptor::STDERR,
        }
    }
}

#[cfg(all(test, feature = "test-support", feature = "unix-runtime"))]
mod tests;