steroid 0.5.0

//! The process module contains everything needed to manipulate a remote process.
//!
//! [`TargetProcess`] is the type used to represent a remote running process. It can be instanciated
//! in two ways, either by running a new command using the function [`spawn_process`], e.g.:
//!
//! ```no_run
//! # use anyhow::Error;
//! use steroid::process::spawn_process;
//!
//! let target = spawn_process("/bin/ls", &["/etc"])?;
//!
//! # Ok::<(), Error>(())
//! ```
//!
//! or by attaching to an existing process using [`try_from(pid)`], e.g.:
//!
//! ```no_run
//! # use anyhow::Error;
//! use std::convert::TryFrom;
//! use steroid::process::{Pid, TargetProcess};
//!
//! let target = TargetProcess::try_from(Pid::from_raw(1234))?;
//!
//! # Ok::<(), Error>(())
//! ```
//!
//! By itself, [`TargetProcess`] does not do much. It is only used to represent a running process
//! and wait for it to stop, using the method [`wait`]. This method returns a [`RunningState`] that
//! tells whether the process is still alive or not. If the process is alive, the user is provided
//! with a [`TargetController`] which is used to perform different kinds of manipulations on the
//! target process. The [`TargetController`] can resume the process execution with its method
//! [`resume`].  Note that it consumes the controller:
//!
//! ```no_run
//! # use anyhow::Error;
//! use steroid::process::spawn_process;
//! use steroid::run::{Executing, RunningState};
//!
//! let target = spawn_process("/bin/ls", &["-a"])?;
//!
//! match target.wait()? {
//!     RunningState::Alive(controller) => {
//!         // The controller is able to do things...
//!         let target = controller.resume()?;
//!         // The controller is dead and the process is running again.
//!     }
//!     RunningState::Exited { reason, .. } => {
//!         println!("Process exited: {}", reason);
//!     }
//!
//! }
//!
//! # Ok::<(), Error>(())
//! ```
//!
//! The insight is that the [`TargetController`] can only live while a process is stopped, it owns
//! the [`TargetProcess`] and only releases it when [`resume`] is called. If a target process is
//! running, no controller shall live. This ensures that every call to [`ptrace`] is valid since a
//! [`TargetProcess`] does not provide methods for manipulations that require the target process to
//! be stopped and a controller cannot survive the continuation of the process.
//!
//! [`try_from(pid)`]: ./struct.TargetProcess.html#impl-TryFrom%3CPid%3E
//! [`wait`]: ./struct.TargetProcess.html#method.wait
//! [`resume`]: ./struct.TargetController.html#method.resume
//! [`ptrace`]: https://man7.org/linux/man-pages/man2/ptrace.2.html

use std::cell::{Ref, RefCell};
use std::collections::{BTreeMap, HashMap, VecDeque};
use std::convert::{TryFrom, TryInto};
use std::ffi::CString;
use std::fmt::Result as FmtResult;
use std::fmt::{Display, Formatter};
use std::fs::read_to_string;
use std::marker::PhantomData;
use std::path::{Path, PathBuf};
use std::rc::Rc;
use std::string::String;

/// Structure representing the values of registers in the remote process.
pub use nix::libc::user_regs_struct as Registers;

use nix::sys::ptrace::Options as NixPtraceOptions;
use nix::sys::ptrace::{
    self, attach, cont, getregs, setoptions, setregs, step, traceme, AddressType,
};
use nix::sys::signal::Signal as NixSignal;
use nix::sys::wait::waitpid;
use nix::unistd::Pid as NixPid;
use nix::unistd::{execv, fork, getpid, ForkResult};
use nix::Error as NixError;

use crate::breakpoint::{Breakpoint, BreakpointId, Mode, TRAP_OPCODE};
use crate::error::{
    CouldNotAttachToPid, CouldNotCreateBreakpoint, CouldNotExecute, CouldNotRead,
    CouldNotReadRegisters, CouldNotRemoveBreakpoint, CouldNotResume, CouldNotSetOptions,
    CouldNotWait, CouldNotWaitForProcess, CouldNotWrite, CouldNotWriteRegisters, ReadWriteError,
    ThreadNotFound,
};
use crate::run::{
    Executing, PtraceEventStrategy, PtraceOption, PtraceOptionMap, Reason, RunningState,
};
use crate::thread::{determine_state, CurrentState, Thread, ThreadHandle};

/// Strongly typed Pid.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Pid(i32);

impl From<NixPid> for Pid {
    fn from(value: NixPid) -> Self {
        Self(value.as_raw())
    }
}

impl From<Pid> for NixPid {
    fn from(val: Pid) -> Self {
        Self::from_raw(val.0)
    }
}

impl Display for Pid {
    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
        write!(f, "{}", self.0)
    }
}

impl Pid {
    #[must_use]
    pub const fn from_raw(value: i32) -> Self {
        Self(value)
    }

    #[must_use]
    pub const fn as_raw(&self) -> i32 {
        self.0
    }
}

/// A representation of a remote process controlled by steroid.
///
/// This type enables to inspect the target process, its associated binary file and even stop its
/// execution. The point of a `TargetProcess` is to manipulate the execution of process, modify its
/// code, profile the execution...
///
/// More details about the overall approach can be found in the [module documentation](self).
#[allow(clippy::module_name_repetitions)] // The typename would not make sense without Process.
pub struct TargetProcess {
    pid: Pid,
    executable: String,
    arguments: Vec<String>,
    breakpoints: RefCell<BTreeMap<BreakpointId, Breakpoint>>,
    threads: RefCell<Vec<Rc<ThreadHandle>>>,
    _unsend: PhantomData<*mut ()>,
}

/// Iterator over the breakpoints of a [`TargetProcess`].
pub struct BreakpointIter<'a> {
    map: Ref<'a, BTreeMap<BreakpointId, Breakpoint>>,
    keys: VecDeque<BreakpointId>,
}

impl<'a> Iterator for BreakpointIter<'a> {
    type Item = Ref<'a, Breakpoint>;

    fn next(&mut self) -> Option<Self::Item> {
        let key = self.keys.pop_front()?;
        let clone = Ref::clone(&self.map);

        Some(Ref::map(clone, |breakpoints| {
            breakpoints.get(&key).unwrap()
        }))
    }
}

impl<'a> From<Ref<'a, BTreeMap<BreakpointId, Breakpoint>>> for BreakpointIter<'a> {
    fn from(value: Ref<'a, BTreeMap<BreakpointId, Breakpoint>>) -> Self {
        let keys = value.keys().copied().collect();

        BreakpointIter { map: value, keys }
    }
}

/// Convert a string to a [`CString`]. If the conversion fails, it returns the default [`CString`].
fn string_to_cstring<S>(s: S) -> Result<CString, CouldNotExecute>
where
    S: AsRef<str>,
{
    CString::new(s.as_ref().as_bytes()).map_err(|e| CouldNotExecute::NullInString {
        string: s.as_ref().to_owned(),
        source: e,
    })
}

/// Convert a list of string arguments for the target process to a list of [`CString`].
fn arguments_to_c_strings<I, S>(args: I) -> Result<Vec<CString>, CouldNotExecute>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
{
    args.into_iter().map(string_to_cstring).collect()
}

/// Fork the process and make the child execute the given command. The child process will be traced
/// by [`ptrace`].
///
/// [`ptrace`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
fn execute_program<I, Sexec, Sargs>(exec: Sexec, args: I) -> Result<Pid, CouldNotExecute>
where
    I: IntoIterator<Item = Sargs>,
    Sargs: AsRef<str>,
    Sexec: AsRef<str>,
{
    match unsafe { fork() } {
        Err(errno) => Err(CouldNotExecute::CouldNotFork {
            source: errno.into(),
        }),

        Ok(ForkResult::Child) => {
            match traceme() {
                Ok(()) => {
                    let args_vec = arguments_to_c_strings(args)?;
                    // According to the documentation, execv is supposed infallible so the returned
                    // value can be safely ignored.
                    let _ = execv(
                        string_to_cstring(exec.as_ref())?.as_ref(),
                        args_vec.as_slice(),
                    );

                    let exec_s: &str = exec.as_ref();
                    Err(CouldNotExecute::ExecutableNotFound(PathBuf::from(exec_s)))
                }

                Err(errno) => Err(CouldNotExecute::CouldNotTrace {
                    pid: getpid().into(),
                    source: errno.into(),
                }),
            }
        }

        Ok(ForkResult::Parent { child, .. }) => Ok(child.into()),
    }
}

/// Spawn a process using the given executable file and the associated arguments.
///
/// This function does not use the PATH variable to locate the executable file, the given filepath
/// must be correct. It will however be expanded so relative paths are accepted.
///
/// # Arguments
///
/// * `exec` - any kind of path.
/// * `args` - any kind of collection of strings.
///
/// # Example
///
/// ```no_run
/// use steroid::process::spawn_process;
///
/// match spawn_process("/bin/ls", ["-l", "/tmp"]) {
///     Ok(target) => println!("{}", target.pid()), /* Do things with this process. */
///     Err(error) => println!("{:?}", error), /* Handle the error that occured. */
/// }
/// ```
///
/// # Errors
///
/// This function can fail in many ways:
///
/// - the executable file does not exist
/// - the path given for the executable file is not a valid utf8 path
/// - the arguments are not valid utf8 strings
/// - the steroid client could not fork
/// - the process could not be traced (see [`ptrace(2)`])
///
/// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
#[allow(clippy::module_name_repetitions)] // We don't want confusion with thread spawning.
pub fn spawn_process<I, Sexec, Sargs>(
    exec: Sexec,
    args: I,
) -> Result<TargetProcess, CouldNotExecute>
where
    Sexec: AsRef<Path>,
    Sargs: AsRef<str>,
    I: IntoIterator<Item = Sargs>,
{
    fn path_to_string(path: PathBuf) -> Result<String, CouldNotExecute> {
        let cloned = path.clone();
        let s = cloned
            .to_str()
            .ok_or(CouldNotExecute::InvalidUTF8Path(path))?;
        Ok(s.to_owned())
    }

    // Canonicalize the executable filepath.
    let exec_path = exec.as_ref();
    let exec_absolute = exec_path
        .canonicalize()
        .map_err(|_| CouldNotExecute::ExecutableNotFound(exec_path.to_owned()))
        .and_then(path_to_string)?;

    let mut args_vec: Vec<String> = args.into_iter().map(|s| String::from(s.as_ref())).collect();
    args_vec.insert(0, path_to_string(exec_path.to_owned())?);

    let pid = execute_program(exec_absolute.as_str(), &args_vec)?;
    let main_thread = ThreadHandle::new(pid);

    Ok(TargetProcess {
        pid,
        executable: exec_absolute,
        arguments: args_vec,
        breakpoints: RefCell::default(),
        threads: RefCell::from(vec![Rc::from(main_thread)]),
        _unsend: PhantomData,
    })
}

impl TryFrom<Pid> for TargetProcess {
    type Error = CouldNotAttachToPid;

    fn try_from(pid: Pid) -> Result<Self, Self::Error> {
        let proc_path = PathBuf::from(&format!("/proc/{pid}"));

        if proc_path.exists() {
            let cmdline = proc_path.join("cmdline");
            let exe = proc_path.join("exe");

            // If the process exists, the files `/proc/$PID/exe` and `/proc/$PID/cmdline` should
            // exist as well. The only trouble we may run into is permission denial.
            let exec_path = exe
                .read_link()
                .map_err(|_| CouldNotAttachToPid::ExecutableNotFound(exe))?
                .to_string_lossy()
                .into_owned();

            let cmd = read_to_string(cmdline)
                .map_err(|err| CouldNotAttachToPid::CouldNotReadCmdLineFile { pid, source: err })?;

            // Parse the cmdline file in order to retrieve the arguments sent to the program.
            let arguments = cmd
                .split('\0')
                .filter_map(|s| (!s.is_empty()).then(|| s.to_string()))
                .collect();

            // Attach to the given process.
            let nix_pid = pid.into();

            attach(nix_pid).map_err(|source| Self::Error::CouldNotAttach {
                pid,
                source: source.into(),
            })?;
            waitpid(nix_pid, None).map_err(|source| Self::Error::CouldNotStop {
                pid,
                source: source.into(),
            })?;
            cont(nix_pid, NixSignal::SIGCONT).map_err(|source| Self::Error::CouldNotRestart {
                pid,
                source: source.into(),
            })?;

            let main_thread = ThreadHandle::new(pid);

            Ok(Self {
                pid,
                executable: exec_path,
                arguments,
                breakpoints: RefCell::default(),
                threads: RefCell::from(vec![Rc::from(main_thread)]),
                _unsend: PhantomData,
            })
        } else {
            Err(Self::Error::ProcessNotFound { pid })
        }
    }
}

/// Survey the process breakpoint list and check if the process is stopped at one of them. If so,
/// set the controller breakpoint ID to this breakpoint. If the process has already exitted, this
/// function does not do anything.
pub(crate) fn set_controller_breakpoint_id<E>(ctrl: &mut TargetController<E>)
where
    E: Executing,
{
    if let &Reason::Breakpoint(brk_id) = ctrl.reason() {
        ctrl.breakpoint_id = Some(brk_id);
    }
}

struct ThreadState {
    reason: Reason,
    brk: Option<BreakpointId>,
    tid: Pid,
}

impl ThreadState {
    pub fn to_running_state_mut<'process>(
        &mut self,
        process: &'process TargetProcess,
    ) -> RunningState<Thread<'process>> {
        if matches!(self.reason, Reason::Exited { .. } | Reason::Signaled { .. }) {
            RunningState::Exited {
                tid: self.tid,
                reason: self.reason,
            }
        } else {
            let threads = process.threads.borrow();
            let handle = threads.iter().find(|thr| thr.tid == self.tid).unwrap();

            let thread = Thread::encapsulate(handle.clone(), process);
            let ctrl = TargetController::new(thread, self.reason, self.brk);
            RunningState::Alive(ctrl)
        }
    }
}

/// Type used to store a stopped [`TargetProcess`] in a [`TargetController`].
///
/// While this type appears in the public API, the user shall never encounter it directly and must
/// assume that the difference between [`TargetProcess`] and [`StoppedProcess`] is a sad
/// implementation detail.
#[allow(clippy::module_name_repetitions)]
pub struct StoppedProcess {
    process: TargetProcess,
    threads: HashMap<Pid, ThreadState>,
}

impl AsRef<TargetProcess> for StoppedProcess {
    fn as_ref(&self) -> &TargetProcess {
        &self.process
    }
}

impl StoppedProcess {
    pub fn threads(&mut self) -> HashMap<Pid, RunningState<Thread>> {
        let process = &self.process;

        self.threads
            .iter_mut()
            .map(|(k, v)| (*k, v.to_running_state_mut(process)))
            .collect()
    }

    /// Unwrap the inner process, consuming the stopped process.
    ///
    /// This function is useful once the user has splitted a [`TargetController<TargetProcess>`]
    /// using [`TargetController::per_thread`] to manipulate the threads individually. At some
    /// point, once the threads have resumed their execution, the user may want to get back an owned
    /// [`TargetProcess`] to use it and this is the purpose of this function.
    ///
    /// # Safety
    ///
    /// Note that it consumes the [`StoppedProcess`], moving the inner [`TargetProcess`], making all
    /// the [`TargetController<Thread>`] created by `self` invalid. The reason is simple: as long as
    /// the [`StoppedProcess`] exists, the [`TargetProcess`] is only accessible via a constant
    /// reference and a method allowing to get the threads. All methods requiring to have a mutable
    /// process are not available, making the [`TargetController<Thread>`]s valid because the user
    /// cannot call [`TargetProcess::threads`] themself, enabling the creation of multiple valid and
    /// independent references to the same thread:
    ///
    /// ```compile_fail
    /// let stopped_process = ctrl.per_thread();
    /// let thread_states = stopped_process.threads();
    /// let threads = thread_states.into_iter()
    ///     .filter_map(|(_, state)| match state {
    ///         RunningState::Exited(_) => None,
    ///         RunningState::Alive(ctrl) => Some(ctrl),
    ///     })
    ///     .map(|ctrl| ctrl.resume())
    ///     .collect::<Result<Thread<'_>, _>()?;
    ///
    /// let mut process = stopped_process.the_real_process_somehow();
    /// let threads_again = process.threads();
    ///
    /// // threads == threads_again
    /// ```
    #[allow(clippy::missing_const_for_fn)]
    pub fn into_inner(self) -> TargetProcess {
        self.process
    }
}

impl Executing for TargetProcess {
    type StoppedRepresentation = StoppedProcess;
    type WaitError = CouldNotWaitForProcess;

    fn process(&self) -> &TargetProcess {
        self
    }

    fn pid(&self) -> Pid {
        self.pid
    }

    /// Wait for an event from the target process, such as an exit, a trap or a stop. The process
    /// being stopped, a [`TargetController`] is returned, allowing to make modification to the
    /// target process. If the process exited, only the [`reason`] why the process exited is
    /// returned. See [`RunningState`].
    ///
    /// # Errors
    ///
    /// This function will fail if the pid given to [`waitpid(2)`] is neither the pid of a living
    /// process nor a process the steroid client is attached to. This should not happen as a
    /// `TargetProcess` cannot be created from an invalid pid and [`TargetProcess::try_from`] will
    /// fail if the client cannot attach to the remote process. Nonetheless, if the situation occurs
    /// due to external causes, an error is returned accordingly.
    ///
    /// # Panics
    ///
    /// Not all the options and quicks of [`waitpid(2)`] are currently supported by steroid. If the
    /// user does not try to thwart steroid's safety model, no panic should occur. Otherwise, a
    /// [`todo!`] panic will remind the developers to handle all the possible outcomes of
    /// [`waitpid(2)`].
    ///
    /// [`reason`]: Reason
    /// [`waitpid(2)`]: https://man7.org/linux/man-pages/man2/waitpid.2.html
    fn wait(mut self) -> Result<RunningState<Self>, CouldNotWaitForProcess> {
        let mut one_thread_alive = false;
        let states = self
            .threads()
            .into_iter()
            .map(determine_state)
            .collect::<Result<Vec<_>, _>>()?
            .into_iter()
            .map(|state| match state {
                CurrentState::Running(thr) => thr.wait(),
                CurrentState::Stopped(ctrl) => Ok(RunningState::Alive(ctrl)),
            })
            .collect::<Result<Vec<_>, _>>()?
            .into_iter()
            .map(|state| match state {
                RunningState::Alive(ctrl) => {
                    let tid = ctrl.context.tid();
                    let state = ThreadState {
                        reason: *ctrl.reason(),
                        brk: ctrl.breakpoint_id,
                        tid,
                    };

                    one_thread_alive = true;
                    (tid, state)
                }
                RunningState::Exited { tid, reason } => {
                    let state = ThreadState {
                        reason,
                        brk: None,
                        tid,
                    };

                    (tid, state)
                }
            })
            .collect::<HashMap<_, _>>();

        let stopped_process = StoppedProcess {
            process: self,
            threads: states,
        };

        // NOTE: When the main thread dies, _exit() is called, which itself calls exit_group().
        // TODO: Detect if exit_group() is called ? (exit status == status & 0xFF)
        // TODO: If the main thread exits, can we detect it right now or at the next wait() ?
        // TODO: Ensure we want this function to reflect what happens in the main thread or not.
        let pgid = stopped_process.process.pid();
        let (main_reason, main_brk) = {
            let main_thread = &stopped_process.threads[&pgid];
            (main_thread.reason, main_thread.brk)
        };

        let ctrl = TargetController::<Self>::new(stopped_process, main_reason, main_brk);

        if one_thread_alive {
            Ok(RunningState::Alive(ctrl))
        } else {
            Ok(RunningState::Exited {
                tid: ctrl.process().pid(),
                reason: ctrl.reason,
            })
        }
    }

    fn resume(ctrl: TargetController<Self>) -> Result<Self, CouldNotResume> {
        let mut process = ctrl.context.process;

        for mut thread in ctrl.context.threads.into_values() {
            let tid = thread.tid;
            let state = thread.to_running_state_mut(&process);

            if let RunningState::Alive(ctrl) = state {
                ctrl.resume()?;
            } else {
                drop(state);
                // NOTE: The removal result can be unwraped as we know the TID is valid.
                process.remove_thread(tid).unwrap();
            }
        }

        Ok(process)
    }

    fn set_ptrace_option(
        ctrl: &mut TargetController<Self>,
        option: PtraceOption,
        strategy: PtraceEventStrategy,
    ) -> Result<PtraceEventStrategy, CouldNotSetOptions> {
        let (process, threads) = (&ctrl.context.process, &mut ctrl.context.threads);
        let mut res = PtraceEventStrategy::Unset;

        for thread in threads.values_mut() {
            let tid = thread.tid;
            let state = thread.to_running_state_mut(process);

            if let RunningState::Alive(mut ctrl) = state {
                let old = Thread::set_ptrace_option(&mut ctrl, option, strategy)?;

                if tid == process.pid() {
                    res = old;
                }
            }
        }

        Ok(res)
    }
}

impl TargetProcess {
    #[must_use]
    pub const fn pid(&self) -> Pid {
        self.pid
    }

    #[must_use]
    pub fn executable(&self) -> &str {
        &self.executable
    }

    #[must_use]
    pub fn arguments(&self) -> Vec<&str> {
        self.arguments.iter().map(String::as_str).collect()
    }

    /// Get an iterator over all breakpoints put in the remote process.
    pub fn breakpoints(&self) -> BreakpointIter {
        BreakpointIter::from(self.breakpoints.borrow())
    }

    /// Get a breakpoint from its ID. Returns None if the breakpoint does not live in the remote
    /// process.
    #[must_use]
    pub fn get_breakpoint(&self, id: BreakpointId) -> Option<Ref<Breakpoint>> {
        Ref::filter_map(self.breakpoints.borrow(), |breakpoints| {
            breakpoints.get(&id)
        })
        .ok()
    }

    /// Get all the threads in the process.
    #[must_use]
    pub fn threads(&mut self) -> Vec<Thread> {
        let handles = self.threads.borrow();
        let mut threads = Vec::with_capacity(handles.len());

        for idx in 0..handles.len() {
            let handle = handles[idx].clone();
            let thread = Thread::encapsulate(handle, self);
            threads.push(thread);
        }

        threads
    }

    pub(crate) fn add_thread(&self, handle: ThreadHandle) {
        let mut threads = self.threads.borrow_mut();
        threads.push(Rc::from(handle));
    }

    pub(crate) fn remove_thread(&mut self, tid: Pid) -> Result<(), ThreadNotFound> {
        let mut threads = self.threads.borrow_mut();
        let pos = threads
            .iter()
            .position(|thr| thr.tid == tid)
            .ok_or_else(|| ThreadNotFound {
                pid: self.pid(),
                tid,
            })?;
        threads.remove(pos);
        Ok(())
    }
}

/// An object allowing to make modification to a [`TargetProcess`] that need it to be stopped. A
/// `TargetController` shall only live while the process is stopped and only the controller can
/// resume its execution. This way, the lifetime of a `TargetController` is the time during which
/// the process is stopped. This design ensures the validity of each ptrace calls.
pub struct TargetController<E>
where
    E: Executing,
{
    /// The executing entity the controller is associated to.
    pub(crate) context: E::StoppedRepresentation,
    /// The reason why the process has been stopped.
    reason: Reason,
    /// ID of the breakpoint that caused the stop of the process, if any.
    breakpoint_id: Option<BreakpointId>,
    _unsend: PhantomData<*mut ()>,
}

impl<E> TargetController<E>
where
    E: Executing,
{
    pub(crate) const fn new(
        context: E::StoppedRepresentation,
        reason: Reason,
        breakpoint_id: Option<BreakpointId>,
    ) -> Self {
        Self {
            context,
            reason,
            breakpoint_id,
            _unsend: PhantomData,
        }
    }

    #[must_use]
    pub fn process(&self) -> &TargetProcess {
        self.context.as_ref().process()
    }

    #[must_use]
    pub fn context(&self) -> &E {
        self.context.as_ref()
    }

    #[must_use]
    pub const fn reason(&self) -> &Reason {
        &self.reason
    }

    /// Get the breakpoint that stopped the remote process if the process has been stopped by a
    /// breakpoint.
    #[must_use]
    pub fn breakpoint(&self) -> Option<Ref<Breakpoint>> {
        self.breakpoint_id
            .and_then(|id| self.process().get_breakpoint(id))
    }

    /// Gracefully remove the breakpoint from the remote process. This method consumes the
    /// [`Breakpoint`] since it has no existence anymore in the remote process.
    ///
    /// # Errors
    ///
    /// If the user tries to remove a breakpoint from the wrong process or a nonexistant breakpoint,
    /// this function will fail, returning a [`CouldNotRemoveBreakpoint::BreakpointNotFound`]. If
    /// the [`ptrace(2)`] call removing the trap instruction fails, a
    /// [`CouldNotRemoveBreakpoint::WriteError`] is returned.
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    pub fn remove_breakpoint(&mut self, id: BreakpointId) -> Result<(), CouldNotRemoveBreakpoint> {
        let res = self.process().get_breakpoint(id).map_or_else(
            || {
                Err(CouldNotRemoveBreakpoint::BreakpointNotFound {
                    id,
                    pid: self.process().pid(),
                })
            },
            |brk| {
                let address = brk.address();
                let saved_byte = brk.saved_byte();
                Ok((address, saved_byte))
            },
        );

        res.and_then(|(address, saved_byte)| {
            self.write(address, &[saved_byte])?;

            let mut breakpoints = self.process().breakpoints.borrow_mut();
            breakpoints.remove(&id);
            Ok(())
        })
    }

    /// Ensure that the process executes the instruction overwritten by the breakpoint before
    /// resuming its execution.
    pub(crate) fn pass_over_breakpoint(&mut self) -> Result<(), CouldNotResume> {
        if let Some(id) = self.breakpoint_id {
            let data = self.process().get_breakpoint(id).map(|brk| {
                let address = brk.address();
                let saved_byte = brk.saved_byte();
                let mode = brk.mode();

                (address, saved_byte, mode)
            });

            let mut regs = self.get_registers()?;

            if let Some((address, saved_byte, mode)) = data {
                self.write(address, &[saved_byte])?;
                regs.rip = address as u64;
                self.set_registers(regs)?;

                if mode == Mode::Persistent {
                    self.breakpoint_id = None;
                    self.singlestep()?;
                    self.write(address, &[TRAP_OPCODE])?;
                } else {
                    self.remove_breakpoint(id)?;
                }
            } else {
                // The breakpoint has been removed in the meantime, we put RIP back to the
                // instruction where the breakpoint was set.
                regs.rip -= 1;
                self.set_registers(regs)?;
            }
        }

        Ok(())
    }

    /// Resume the executing entity's execution, consuming the [`TargetController`]. This function
    /// consider the breakpoints and do the necessary manipulations to resume the execution
    /// correctly and put back the trap instructions.
    ///
    /// # Errors
    ///
    /// This function may try to pass over a breakpoint, consequently any manipulation of the
    /// breakpoint that may fail can make `resume` fail too. Moreover, restarting the execution
    /// involves a call to [`ptrace(2)`] which can fail itself. In summary, the possible failures
    /// are the following:
    ///
    /// - the registers could not be read or written
    /// - the function could not singlestep over the breakpoint
    /// - the memory at the breakpoint's address could not be overwritten
    /// - the breakpoint could not be removed by steroid (see [`TargetController::remove_breakpoint`])
    /// - the execution could not be restarted because of [`ptrace(2)`]
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    pub fn resume(self) -> Result<E, CouldNotResume> {
        Executing::resume(self)
    }

    /// Perform a single step in the target process' execution and wait for its execution. This
    /// method returns the wait status (and modifies the controller's existence [`reason`]). This
    /// method allows to temporary resume the target process while keeping the current controller
    /// alive. Since the continue and wait procedures are both encapsulated inside this method, the
    /// controller should not end in an invalid state.
    ///
    /// # Errors
    ///
    /// This function may try to pass over a breakpoint and as such, any failure in the manipulation
    /// of said breakpoint may prevent `singlestep` to succeed. See [`TargetController::resume`] for
    /// more information.
    ///
    /// [`reason`]: struct.TargetController.html#method.reason
    pub fn singlestep(&mut self) -> Result<Reason, CouldNotResume> {
        self.pass_over_breakpoint()?;

        self.reason = self.blind_singlestep()?;
        set_controller_breakpoint_id(self);
        Ok(self.reason)
    }

    /// Perform a singlestep without managing breakpoints nor the controller's reason
    /// attribute. This function is used for low-level code execution in the remote process, such as
    /// execute syscalls.
    pub(crate) fn blind_singlestep(&mut self) -> Result<Reason, CouldNotResume> {
        let pid = self.process().pid();

        let status = step(pid.into(), None)
            .and_then(|_| waitpid(Some(pid.into()), None))
            .map_err(|source| {
                CouldNotResume::CouldNotStop(CouldNotWait::ProcessNotFound {
                    pid,
                    source: source.into(),
                })
            })?;

        Ok(Reason::from_wait_status(self, status))
    }

    /// Get the register values of the target process.
    ///
    /// # Errors
    ///
    /// If the [`ptrace(2)`] call fails somehow - typically, if the remote process has been
    /// restarted or killed externally by the user - this function returns a
    /// [`CouldNotReadRegisters`].
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    pub fn get_registers(&self) -> Result<Registers, CouldNotReadRegisters> {
        let pid = self.process().pid();

        match getregs(pid.into()) {
            Ok(regs) => Ok(regs),
            Err(source) => Err(CouldNotReadRegisters {
                pid,
                source: source.into(),
            }),
        }
    }

    /// Set the given register values to the target process.
    ///
    /// # Errors
    ///
    /// If the [`ptrace(2)`] call fails somehow - typically, if the remote process has been
    /// restarted or killed externally by the user - this function returns a
    /// [`CouldNotWriteRegisters`].
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    pub fn set_registers(&mut self, regs: Registers) -> Result<(), CouldNotWriteRegisters> {
        let pid = self.process().pid();

        match setregs(pid.into(), regs) {
            Ok(()) => Ok(()),
            Err(source) => Err(CouldNotWriteRegisters {
                pid,
                source: source.into(),
            }),
        }
    }

    /// Read data at the given address. This method is not optimized, see [`write`].
    ///
    /// # Errors
    ///
    /// Like any IO operation, this function may fail. It may fail while trying to read from a
    /// process that has been killed or is not stopped anymore due to an external cause. In this
    /// case, a [`ReadWriteError::ProcessKilled`] is returned. It is also possible that the user
    /// tries to read from an invalid area of the remote process' memory space. Then, a
    /// [`CouldNotRead`] is returned.
    ///
    /// # Panics
    ///
    /// In theory, no other kind of error should happen during the execution of this
    /// function. However, since steroid uses [`ptrace(2)`] internally, this function may panic on
    /// unexpected errors.
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    /// [`write`]: struct.TargetController.html#method.write
    pub fn read(&mut self, mut addr: usize, mut length: usize) -> Result<Vec<u8>, ReadWriteError> {
        let pid = self.process().pid();
        let mut res = Vec::with_capacity(length);

        while length > 0 {
            let addr_ptr = addr as AddressType;

            let word = ptrace::read(pid.into(), addr_ptr)
                .map(i64::to_ne_bytes)
                .map_err(|err| match err {
                    NixError::EFAULT | NixError::EIO => ReadWriteError::from(CouldNotRead {
                        pid,
                        address: addr,
                        source: err.into(),
                    }),
                    NixError::ESRCH => ReadWriteError::ProcessKilled {
                        pid,
                        source: err.into(),
                    },
                    errno => unreachable!("ptrace should not return {} when reading", errno),
                })?;

            if length >= 8 {
                res.extend(word);
                addr += 8;
                length -= 8;
            } else {
                res.extend(&word[0..length]);
                length = 0;
            }
        }

        Ok(res)
    }

    /// Write data at the given address. This method is not optimized, it is only useful for very
    /// small edits such as setting a trap instruction or call a function.
    ///
    /// # Errors
    ///
    /// Like any IO operation, this function may fail. It may fail while trying to write into a
    /// process that has been killed or is not stopped anymore due to an external cause. In this
    /// case, a [`ReadWriteError::ProcessKilled`] is returned. It is also possible that the user
    /// tries to write into an invalid area of the remote process' memory space. Then, either a
    /// [`CouldNotRead`] or [`CouldNotWrite`] is returned, depending on the step of the writing
    /// process steroid has failed at.
    ///
    /// # Panics
    ///
    /// In theory, no other kind of error should happen during the execution of this
    /// function. However, since steroid uses [`ptrace(2)`] internally, this function may panic on
    /// unexpected errors.
    ///
    /// [`ptrace(2)`]: https://man7.org/linux/man-pages/man2/ptrace.2.html
    pub fn write(&mut self, mut addr: usize, data: &[u8]) -> Result<(), ReadWriteError> {
        let pointer_size = 8;
        let pid = self.process().pid();

        for chunk in data.chunks(pointer_size) {
            let addr_ptr = addr as AddressType;
            let mut vec: Vec<u8>;

            // If the chunk is 8-byte long, it can be used as-is. Otherwise, the word at the given
            // address is read and the first few bytes are overwritten by the chunk, making the
            // resulting slice 8-byte long.
            let slice = if chunk.len() == 8 {
                chunk
            } else {
                let word = ptrace::read(pid.into(), addr_ptr)
                    .map(i64::to_ne_bytes)
                    .map_err(|err| match err {
                        NixError::EFAULT | NixError::EIO => ReadWriteError::from(CouldNotRead {
                            pid,
                            address: addr,
                            source: err.into(),
                        }),
                        NixError::ESRCH => ReadWriteError::ProcessKilled {
                            pid,
                            source: err.into(),
                        },
                        errno => unreachable!("ptrace should not return {} when reading", errno),
                    })?;

                vec = word.to_vec();
                vec.splice(0..chunk.len(), chunk.iter().copied());
                vec.as_slice()
            };

            // The chunk is defined as an 8-byte slice so we can unwrap.
            let chunk_array: [u8; 8] = slice.try_into().unwrap();
            let chunk_ptr = usize::from_ne_bytes(chunk_array) as AddressType;

            unsafe {
                ptrace::write(pid.into(), addr_ptr, chunk_ptr).map_err(|err| match err {
                    NixError::EFAULT | NixError::EIO => ReadWriteError::from(CouldNotWrite {
                        pid,
                        address: addr,
                        source: err.into(),
                    }),
                    NixError::ESRCH => ReadWriteError::ProcessKilled {
                        pid,
                        source: err.into(),
                    },
                    errno => unreachable!("ptrace should not return {} when writing", errno),
                })?;
            };

            addr += pointer_size;
        }

        Ok(())
    }

    pub(crate) fn register_breakpoint(
        &mut self,
        brk: Breakpoint,
    ) -> Result<Ref<Breakpoint>, CouldNotCreateBreakpoint> {
        let pid = self.process().pid();
        let mut breakpoints = self.process().breakpoints.borrow_mut();

        if breakpoints.iter().any(|(_, b)| *b == brk) {
            Err(CouldNotCreateBreakpoint::BreakpointAlreadyExists {
                pid,
                address: brk.address(),
            })
        } else {
            let id = brk.id();
            breakpoints.insert(id, brk);
            drop(breakpoints);

            Ok(
                Ref::filter_map(self.process().breakpoints.borrow(), |breakpoints| {
                    breakpoints.get(&id)
                })
                .unwrap(),
            )
        }
    }

    pub(crate) fn update_reason(&mut self, reason: Reason) {
        self.reason = reason;
    }

    pub(crate) fn write_ptrace_options(
        &mut self,
        options: NixPtraceOptions,
    ) -> Result<(), CouldNotSetOptions> {
        let pid = self.context.as_ref().pid();
        let nix_pid = pid.into();

        setoptions(nix_pid, options).map_err(|source| CouldNotSetOptions {
            pid,
            options: PtraceOptionMap::all_set_options(options),
            source: source.into(),
        })
    }
}

impl TargetController<TargetProcess> {
    /// Consume the controller in order to enable the manipulation of each thread independently.
    ///
    /// This function provides the user with the controller's internal [`StoppedProcess`] which in
    /// turn provides a [`threads`] method that allows to manipulate each thread independently.
    ///
    /// # Examples
    ///
    /// ```
    /// # use std::path::PathBuf;
    /// # use anyhow::Error;
    /// # use steroid::process::spawn_process;
    /// # use steroid::run::Executing;
    /// # let mut path_buf = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    /// # path_buf.push("resources/test/create_thread_join_and_die");
    /// # let process = spawn_process::<_, _, &str>(path_buf, vec![])?;
    /// let ctrl = process.wait()?.assume_alive()?;
    /// let mut stopped_process = ctrl.per_thread();
    /// let main_pid = stopped_process.as_ref().pid();
    ///
    /// let mut threads = stopped_process.threads();
    /// let main_thread_ctrl = threads.remove(&main_pid).unwrap().assume_alive()?;
    /// # let state = main_thread_ctrl.resume()?.wait()?;
    /// # assert!(state.has_exited());
    /// # Ok::<(), Error>(())
    /// ```
    ///
    /// [`threads`]: crate::process::StoppedProcess::threads
    #[allow(clippy::missing_const_for_fn)]
    pub fn per_thread(self) -> StoppedProcess {
        self.context
    }
}

/// Take a controller and use it to update certain registers within the target process. The
/// following example gives an insight of the syntax used in this macro.
///
/// ```
/// #[macro_use(update_registers)]
/// extern crate steroid;
///
/// use anyhow::Error;
/// use steroid::process::spawn_process;
/// use steroid::run::Executing;
///
/// fn main() -> Result<(), Error> {
///     let mut target = spawn_process("/bin/ls", &["-a"])?;
///     let mut ctrl = target.wait()?.assume_alive()?;
///
///     update_registers![
///         &mut ctrl => {
///             rdi: 0xdeadbeef,
///             rsi: 35
///         }
///     ]?;
///
///     Ok(())
/// }
/// ```
#[macro_export]
macro_rules! update_registers {
    (
        $ctrl:expr => {
            $($reg:ident: $exp:expr),*
        }
    ) => {{
        #[allow(unused_mut)]
        let mut ctrl = $ctrl;
        ctrl.get_registers()
	    .map_err( |e| $crate::error::CouldNotReadWriteRegister::from(e) )
            .map( |mut regs| { $( regs.$reg = $exp; )* regs })
            .and_then( |regs| {
		ctrl.set_registers(regs)
		    .map_err( |e| $crate::error::CouldNotReadWriteRegister::from(e))
	    })
    }}
}

/// Take a controller and some register assignments and then apply the given function using these
/// registers. The idea is to be able to execute code in the target process using the given
/// registers and then write back the registers as they were before the manipulation. Note that the
/// instruction pointer is saved as well as the other registers.
///
/// The expected function must have the following type:
///
/// ```
/// use steroid::error::CouldNotReadWriteRegister;
/// use steroid::process::{Registers, TargetController};
/// use steroid::run::Executing;
///
/// type FunctionType<T, E, Ctx>
/// where
///   E: From<CouldNotReadWriteRegister>,
///   Ctx: Executing,
/// = fn(&mut TargetController<Ctx>, Registers) -> Result<T, E>;
/// ```
///
/// Here is an example of how to use this macro:
///
/// ```
/// #[macro_use(with_registers)]
/// extern crate steroid;
///
/// use anyhow::Error;
///
/// use steroid::error::CouldNotResume;
/// use steroid::process::{Registers, spawn_process};
/// use steroid::run::Executing;
///
/// fn main() -> Result<(), Error> {
///     let mut target = spawn_process("/bin/ls", &["-a"])?;
///     let mut ctrl = target.wait()?.assume_alive()?;
///
///     let result = with_registers!(&mut ctrl, rdi: 0xdeadbeef, rsi: 12;
///         |ref mut _ctrl, regs| {
///             // One can return the remote procedure's return, for instance.
///             Ok::<_, CouldNotResume>(regs.rax)
///         })?;
///
///     Ok(())
/// }
/// ```
#[macro_export]
macro_rules! with_registers {
    (
        $ctrl:expr,
        $($reg:ident: $exp:expr),*;
        $func:expr
    ) => {{
        const fn type_hint<F, T, E, ExeCtx>(func: F) -> F
        where
	    F: Fn(&mut $crate::process::TargetController<ExeCtx>,
		  $crate::process::Registers) -> Result<T, E>,
	    E: std::error::Error + From<$crate::error::CouldNotReadWriteRegister>,
	    ExeCtx: $crate::run::Executing,
	{
            func
        }

	fn to_err_type<F, T, E, ExeCtx>(_func: &F, e: $crate::error::CouldNotReadWriteRegister) -> E
	where
	    F: Fn(&mut $crate::process::TargetController<ExeCtx>,
		  $crate::process::Registers) -> Result<T, E>,
	    E: std::error::Error + From<$crate::error::CouldNotReadWriteRegister>,
	    ExeCtx: $crate::run::Executing,
	{
	    E::from(e)
	}

        #[allow(unused_mut)]
        let mut ctrl = $ctrl;
	let func = type_hint($func);
        ctrl.get_registers()
            .map( |mut regs| {
                let save = regs.clone();
                $( regs.$reg = $exp; )*
                (save, regs)
            })
	    .map_err( |e| $crate::error::CouldNotReadWriteRegister::from(e) )
	    .map_err( |e| to_err_type(&func, e) )
            .and_then( |(save, regs)| {
                ctrl.set_registers(regs)?;
                let res = func(&mut ctrl, regs)?;
                ctrl.set_registers(save)?;
                Ok((res))
            })
    }}
}

#[cfg(test)]
mod tests {
    use std::fs::File;
    use std::io::{Read, Seek, SeekFrom};
    use std::process::{Command, Stdio};

    use anyhow::Error as AnyError;

    use pretty_assertions::assert_eq;

    use crate::error::CouldNotReadWriteRegister;
    use crate::run::Signal;

    use super::*;

    #[test]
    fn process_spawned() {
        match spawn_process("/bin/ls", ["-l", "/tmp"]) {
            Err(err) => panic!("Failed to spawn process with error: {:?}", err),
            Ok(target) => {
                assert_eq!(target.executable(), "/usr/bin/ls");
                assert_eq!(target.arguments(), vec!["/bin/ls", "-l", "/tmp"]);
            }
        }
    }

    #[test]
    fn controller_created() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-l"])?;
        let ctrl = target.wait()?.assume_alive()?;

        assert_eq!(ctrl.reason, Reason::Trapped);
        Ok(())
    }

    #[test]
    fn controller_died() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-l"])?;
        let ctrl = target.wait()?.assume_alive()?;

        assert_eq!(ctrl.reason, Reason::Trapped);

        let target = ctrl.resume()?;

        let state = target.wait()?;
        assert!(state.has_exited(), "{}", state.reason());

        Ok(())
    }

    #[test]
    #[ignore]
    #[allow(clippy::cast_possible_wrap)]
    fn process_from_pid() -> Result<(), AnyError> {
        match Command::new("cat").stdin(Stdio::piped()).spawn() {
            Ok(mut child) => {
                let pid = Pid(child.id() as i32);

                let process = TargetProcess::try_from(pid)?;
                let ctrl = process.wait()?.assume_alive()?;
                let process = ctrl.resume()?;
                drop(child.stdin.take().unwrap());
                let state = process.wait()?;
                assert!(state.has_exited(), "{}", state.reason());

                Ok(())
            }

            Err(err) => panic!("Could not spawn process with error: {}", err),
        }
    }

    #[test]
    #[ignore]
    #[allow(clippy::cast_possible_wrap)]
    fn stop_after_attach() -> Result<(), AnyError> {
        match Command::new("cat").stdin(Stdio::piped()).spawn() {
            Ok(mut child) => {
                let pid = Pid(child.id() as i32);

                let target = TargetProcess::try_from(pid)?;
                let ctrl = target.wait()?.assume_alive()?;

                assert_eq!(
                    ctrl.reason,
                    Reason::Stopped {
                        signal: Signal::SIGSTOP
                    }
                );

                let target = ctrl.resume()?;
                let stdin = child.stdin.take().unwrap();
                drop(stdin);

                let state = target.wait()?;
                assert!(state.has_exited(), "{}", state.reason());

                Ok(())
            }

            Err(err) => panic!("Could not spawn process with error: {}", err),
        }
    }

    #[test]
    fn get_and_set_registers() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-a"])?;
        let mut ctrl = target.wait()?.assume_alive()?;

        let regs = ctrl.get_registers()?;
        ctrl.set_registers(regs)?;

        let target = ctrl.resume()?;

        let state = target.wait()?;
        assert!(state.has_exited(), "{}", state.reason());

        Ok(())
    }

    #[test]
    fn update_registers() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-a"])?;
        let mut ctrl = target.wait()?.assume_alive()?;

        update_registers![
            &mut ctrl => {
                rax: 0xbeef,
                rbx: 0xdead,
                rcx: 0x0cd
            }
        ]?;

        let regs = ctrl.get_registers()?;

        assert_eq!(0xbeef, regs.rax);
        assert_eq!(0xdead, regs.rbx);
        assert_eq!(0x0cd, regs.rcx);
        Ok(())
    }

    #[test]
    fn with_register() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-a"])?;
        let mut ctrl = target.wait()?.assume_alive()?;

        let (rax, rcx, rdx, rdi) = with_registers!(&mut ctrl, rax: 1, rcx: 2, rdx: 3;
        |_, regs| {
            Ok::<_, CouldNotReadWriteRegister>((regs.rax, regs.rcx, regs.rdx, regs.rdi))
        })?;

        let expected_rdi = ctrl.get_registers()?.rdi;

        assert_eq!(1, rax);
        assert_eq!(2, rcx);
        assert_eq!(3, rdx);
        assert_eq!(expected_rdi, rdi);
        Ok(())
    }

    #[test]
    fn write_to_memory() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-a"])?;
        let mut ctrl = target.wait()?.assume_alive()?;

        let datas = [
            vec![0xef, 0xbe, 0xad, 0xde, 0xfe, 0xca, 0x0b, 0xb0],
            vec![0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09],
        ];

        for data in datas {
            let regs = ctrl.get_registers()?;
            ctrl.write(regs.rip as usize, &data)?;

            let filename = format!("/proc/{}/mem", ctrl.process().pid());
            let mut file = File::open(filename).expect("Could not open file");
            file.seek(SeekFrom::Start(regs.rip))
                .expect("Could not seek RIP");

            let mut buf: Vec<u8> = vec![0; data.len()];
            file.read_exact(&mut buf).expect("buffer overflow");

            assert_eq!(&data, buf.as_slice());
        }

        Ok(())
    }

    #[test]
    fn read_from_memory() -> Result<(), AnyError> {
        let target = spawn_process("/bin/ls", ["-a"])?;
        let mut ctrl = target.wait()?.assume_alive()?;

        let sizes = [1, 4, 8, 12, 30];

        for size in sizes {
            let regs = ctrl.get_registers()?;
            let data = ctrl.read(regs.rip as usize, size)?;

            let filename = format!("/proc/{}/mem", ctrl.process().pid());
            let mut file = File::open(filename).expect("Could not open file");
            file.seek(SeekFrom::Start(regs.rip))
                .expect("Could not seek RIP");

            let mut buf: Vec<u8> = vec![0; size];
            file.read_exact(&mut buf).expect("buffer overflow");

            assert_eq!(data.len(), buf.len());
            assert_eq!(&data, buf.as_slice());
        }

        Ok(())
    }
}