//! Enumeration of the ELF modules loaded into the target process.

use std::{
    ffi::{OsStr, OsString},
    path::{Path, PathBuf},
};

use crate::{
    linux::process_inspection::ProcessInspector,
    maps_reader::{MappingEntry, MappingList},
    module_reader::ModuleReaderError,
};
use error_graph::WriteErrorList;

use super::maps_reader::MappingInfo;

#[derive(thiserror::Error, Debug, serde::Serialize)]
pub enum ModuleListError {
    #[error("error reading soname from file")]
    ReadSoNameFromFileFailed(#[source] ModuleReaderError),
}

/// Errors that only cost us the accuracy of a single entry of the module list.
#[derive(thiserror::Error, Debug, serde::Serialize)]
pub enum ModuleResolveError {
    #[error(
        "user-supplied module `{}` starts at {base_address:#x}, where another \
         one already does, so only one of them can be written",
        name.to_string_lossy()
    )]
    DuplicateUserModule { name: OsString, base_address: usize },
    #[error(
        "module `{}` at {base_address:#x} was clamped at {clamped_to:#x} while \
         its last executable segment ends at {code_end:#x}",
        name.to_string_lossy()
    )]
    ModuleImageClamped {
        name: OsString,
        base_address: usize,
        code_end: usize,
        clamped_to: usize,
    },
}

/// Where a module's information came from.
#[derive(Debug)]
pub enum ModuleSource {
    /// Read out of the process, be it from its memory map or from the dynamic
    /// linker's rendez-vous.
    Process,
    /// Supplied by the user, and taken at face value: they know things about it
    /// that we cannot derive, which is why it was supplied in the first place.
    User { identifier: Vec<u8> },
}

impl ModuleSource {
    fn is_user(&self) -> bool {
        matches!(self, Self::User { .. })
    }
}

/// An entry of the module list written to the `ModuleListStream`.
#[derive(Debug)]
pub struct ModuleInfo {
    /// Where the ELF object was loaded — the minidump's `base_of_image`.
    pub base_address: usize,
    pub size: usize,
    pub name: Option<OsString>,
    /// Offset of the object within its backing file; typically 0, but might
    /// not be, e.g. if loaded from an APK.
    pub file_offset: usize,
    /// Whether the object has an executable segment.
    /// It *is* possible to load data-only ELF objects!
    pub executable: bool,
    pub source: ModuleSource,
}

/// A module we may write, before its extent is final.
#[derive(Debug)]
pub struct ModuleCandidate {
    base_address: usize,
    end_address: usize,
    /// End of the object's last executable segment, or `base_address` if none.
    code_end: usize,
    name: Option<OsString>,
    file_offset: usize,
    source: ModuleSource,
}

impl ModuleCandidate {
    /// Builds a module from user-supplied information.
    fn from_user_entry(entry: &MappingEntry) -> Self {
        Self {
            base_address: entry.mapping.start_address,
            end_address: entry.mapping.start_address + entry.mapping.size,
            // Let's assume it's all executable.
            code_end: entry.mapping.start_address + entry.mapping.size,
            name: entry.mapping.name.clone(),
            file_offset: entry.mapping.offset,
            source: ModuleSource::User {
                identifier: entry.identifier.clone(),
            },
        }
    }

    /// Whether `address` falls within this module's extent.
    fn contains_address(&self, address: usize) -> bool {
        (self.base_address..self.end_address).contains(&address)
    }

    fn into_module(self) -> ModuleInfo {
        ModuleInfo {
            base_address: self.base_address,
            size: self.end_address - self.base_address,
            name: self.name,
            file_offset: self.file_offset,
            executable: self.code_end > self.base_address,
            source: self.source,
        }
    }
}

/// Any detected module that starts within a user-provided module must be dropped, as just keeping
/// the tail would make its addresses unresolvable anyway.
fn filter_out_user_overlap(
    process_candidates: &mut Vec<ModuleCandidate>,
    user_candidates: &[ModuleCandidate],
) {
    process_candidates.retain(|c| {
        !user_candidates
            .iter()
            .any(|uc| uc.contains_address(c.base_address))
    });
}

/// If a module contains the entry-point, and it's not already the first
/// one, then we need to make it be first. This is because the minidump
/// format assumes the first module is the one that corresponds to the main
/// executable (as codified in processor/minidump.cc:MinidumpModuleList::GetMainModule()).
fn ensure_entrypoint_is_first(candidates: &mut [ModuleCandidate], entry_point: Option<usize>) {
    if let Some(entry_point) = entry_point
        && let Some(index) = candidates
            .iter()
            .position(|c| c.contains_address(entry_point))
    {
        candidates.swap(0, index);
    }
}

/// Turns the candidates into the entries written to the `ModuleListStream`.
pub(crate) fn resolve(
    candidates: Vec<ModuleCandidate>,
    entry_point: Option<usize>,
    mut soft_errors: impl WriteErrorList<ModuleResolveError>,
) -> Vec<ModuleInfo> {
    let (user_candidates, mut process_candidates): (Vec<_>, Vec<_>) =
        candidates.into_iter().partition(|c| c.source.is_user());

    // Sanity check on the user-provided modules: if they happen to start at the same place,
    // log the error and keep them both, as we don't have enough data to prioritize one.
    for (index, candidate) in user_candidates.iter().enumerate() {
        if user_candidates[..index]
            .iter()
            .any(|earlier| earlier.base_address == candidate.base_address)
        {
            soft_errors.push(ModuleResolveError::DuplicateUserModule {
                name: candidate.name.clone().unwrap_or_default(),
                base_address: candidate.base_address,
            });
        }
    }

    filter_out_user_overlap(&mut process_candidates, &user_candidates);
    ensure_entrypoint_is_first(&mut process_candidates, entry_point);

    let mut candidates: Vec<ModuleCandidate> = process_candidates
        .into_iter()
        .chain(user_candidates)
        .collect();
    clamp_overlapping_modules(&mut candidates, &mut soft_errors);

    candidates
        .into_iter()
        .map(ModuleCandidate::into_module)
        .collect()
}

/// Shortens any module whose image overlaps another entry of the module list.
fn clamp_overlapping_modules(
    modules: &mut [ModuleCandidate],
    mut soft_errors: impl WriteErrorList<ModuleResolveError>,
) {
    let mut claims: Vec<usize> = modules.iter().map(|module| module.base_address).collect();
    claims.sort_unstable();

    for module in modules {
        let Some(&claim) = claims.iter().find(|&&claim| claim > module.base_address) else {
            continue;
        };
        if claim < module.end_address {
            // Clamping is typically harmless *unless* the stuff that's cut
            // out is executable code.
            if claim < module.code_end {
                soft_errors.push(ModuleResolveError::ModuleImageClamped {
                    name: module.name.clone().unwrap_or_default(),
                    base_address: module.base_address,
                    code_end: module.code_end,
                    clamped_to: claim,
                });
            }
            module.end_address = claim;
        }
    }
}

/// Where the object behind `mapping` was loaded.
///
/// `/proc/<pid>/maps` reports where a mapping *starts*, which for an Android
/// object with packed relocations is `min_vaddr` above where the object was
/// actually loaded. Everywhere else the two are the same address.
#[cfg(target_os = "android")]
fn loaded_at(process_inspector: &dyn ProcessInspector, mapping: &MappingInfo) -> usize {
    // Filter out unlikely candidates for libraries
    if mapping.is_executable() && mapping.name_is_path() {
        super::android::effective_load_base(process_inspector, mapping.start_address)
    } else {
        mapping.start_address
    }
}

#[cfg(not(target_os = "android"))]
fn loaded_at(_process_inspector: &dyn ProcessInspector, mapping: &MappingInfo) -> usize {
    mapping.start_address
}

impl ModuleCandidate {
    /// Builds a module from a memory mapping.
    fn from_mapping(process_inspector: &dyn ProcessInspector, mapping: &MappingInfo) -> Self {
        // Adjust the base address if needed.
        let base_address = loaded_at(process_inspector, mapping);

        Self {
            base_address,
            end_address: mapping.start_address + mapping.size,
            code_end: if mapping.is_executable() {
                mapping.start_address + mapping.size
            } else {
                mapping.start_address
            },
            name: mapping.name.clone(),
            file_offset: mapping.offset,
            source: ModuleSource::Process,
        }
    }
}

impl ModuleInfo {
    pub fn effective_path_name_and_version(
        &self,
        process_inspector: &dyn ProcessInspector,
        soname: Option<String>,
        soft_errors: impl WriteErrorList<ModuleListError>,
    ) -> (PathBuf, String, Option<SoVersion>) {
        let mut file_path = PathBuf::from(self.name.clone().unwrap_or_default());

        // Just use the filesystem name if no SONAME is present.
        let Some(file_name) = self.find_soname(soname, process_inspector, soft_errors) else {
            //   file_path := /path/to/libname.so
            //   file_name := libname.so
            let file_name = file_path
                .file_name()
                .map(|s| s.to_string_lossy().into_owned())
                .unwrap_or_default();

            return (file_path, file_name, self.so_version());
        };

        self.fix_filename(&mut file_path, &file_name);
        (file_path, file_name, self.so_version())
    }

    /// Tools such as minidump_stackwalk use the name of the module to look up
    /// symbols produced by dump_syms. dump_syms will prefer to use a module's
    /// DT_SONAME as the module name, if one exists, and will fall back to the
    /// filesystem name of the module. For this reason, we try different approaches
    /// before giving up.
    ///
    /// We prefer the SONAME if it's available rather than parse the path.
    fn find_soname(
        &self,
        provided_soname: Option<String>,
        process_inspector: &dyn ProcessInspector,
        mut soft_errors: impl WriteErrorList<ModuleListError>,
    ) -> Option<String> {
        provided_soname.or_else(|| {
            // User supplied the filename, let's use that directly.
            if self.source.is_user() {
                return None;
            }
            match self.elf_so_name(process_inspector) {
                Ok(soname) => soname,
                Err(e) => {
                    // Log error and move on to fallback path.
                    soft_errors.push(e);
                    None
                }
            }
        })
    }

    /// Look in the module ELF metadata to find its soname if it has any.
    /// Typically, executables don't have one.
    fn elf_so_name(
        &self,
        process_inspector: &dyn ProcessInspector,
    ) -> Result<Option<String>, ModuleListError> {
        let path = Path::new(self.name.as_deref().unwrap_or_default());
        match super::module_reader::read_soname_from_file(process_inspector, path, self.file_offset)
        {
            Ok(soname) => Ok(Some(soname)),
            Err(ModuleReaderError::NoSoName { .. }) => Ok(None),
            Err(e) => Err(ModuleListError::ReadSoNameFromFileFailed(e)),
        }
    }

    #[inline]
    fn so_version(&self) -> Option<SoVersion> {
        SoVersion::parse(self.name.as_deref()?)
    }

    /// Handle edge-cases on filename, e.g. archive files.
    fn fix_filename(&self, path: &mut PathBuf, file_name: &str) {
        if self.executable && self.file_offset != 0 {
            // If an executable is mapped from a non-zero offset, this is likely because
            // the executable was loaded directly from inside an archive file (e.g., an
            // apk on Android).
            // In this case, we append the file_name to the mapped archive path:
            //   file_name := libname.so
            //   file_path := /path/to/ARCHIVE.APK/libname.so
            path.push(file_name);
        } else {
            // Otherwise, replace the basename with the SONAME.
            path.set_file_name(file_name);
        }
    }
}

/// Build module information out of kernel mapping data
///
/// Only requires access to /proc/pid/maps, but is ultimately just an approximation based on
/// observed behaviour of linkers.
pub(crate) fn from_mappings(
    process_inspector: &dyn ProcessInspector,
    mappings: &[MappingInfo],
) -> Vec<ModuleCandidate> {
    mappings
        .iter()
        .filter(|mapping| mapping.is_interesting())
        .map(|mapping| ModuleCandidate::from_mapping(process_inspector, mapping))
        .collect()
}

/// Builds the modules the user told us about.
pub(crate) fn from_user_mappings(user_mapping_list: &MappingList) -> Vec<ModuleCandidate> {
    user_mapping_list
        .iter()
        .map(ModuleCandidate::from_user_entry)
        .collect()
}

/// Version metadata retrieved from an .so filename
///
/// There is no standard for .so version numbers so this implementation just
/// does a best effort to pull as much data as it can based on real .so schemes
/// seen
///
/// That being said, the [libtool](https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html)
/// versioning scheme is fairly common
#[cfg_attr(test, derive(Debug))]
pub struct SoVersion {
    /// Might be non-zero if there is at least one non-zero numeric component after .so.
    ///
    /// Equivalent to `current` in libtool versions
    pub major: u32,
    /// The numeric component after the major version, if any
    ///
    /// Equivalent to `revision` in libtool versions
    pub minor: u32,
    /// The numeric component after the minor version, if any
    ///
    /// Equivalent to `age` in libtool versions
    pub patch: u32,
    /// The patch component may contain additional non-numeric metadata similar
    /// to a semver prelease, this is any numeric data that suffixes that prerelease
    /// string
    pub prerelease: u32,
}

impl SoVersion {
    /// Attempts to retrieve the .so version of the elf path via its filename
    fn parse(so_path: &OsStr) -> Option<Self> {
        let filename = std::path::Path::new(so_path).file_name()?;

        // Avoid an allocation unless the string contains non-utf8
        let filename = filename.to_string_lossy();

        let (_, version) = filename.split_once(".so.")?;

        let mut sov = Self {
            major: 0,
            minor: 0,
            patch: 0,
            prerelease: 0,
        };

        let comps = [
            &mut sov.major,
            &mut sov.minor,
            &mut sov.patch,
            &mut sov.prerelease,
        ];

        for (i, comp) in version.split('.').enumerate() {
            if i <= 1 {
                *comps[i] = comp.parse().unwrap_or_default();
            } else if i >= 4 {
                break;
            } else {
                // In some cases the release/patch version is alphanumeric (eg. '2rc5'),
                // so try to parse either a single or two numbers
                if let Some(pend) = comp.find(|c: char| !c.is_ascii_digit()) {
                    if let Ok(patch) = comp[..pend].parse() {
                        *comps[i] = patch;
                    }

                    if i >= comps.len() - 1 {
                        break;
                    }
                    if let Some(pre) = comp.rfind(|c: char| !c.is_ascii_digit())
                        && let Ok(pre) = comp[pre + 1..].parse()
                    {
                        *comps[i + 1] = pre;
                        break;
                    }
                } else {
                    *comps[i] = comp.parse().unwrap_or_default();
                }
            }
        }

        Some(sov)
    }
}

#[cfg(test)]
impl PartialEq<(u32, u32, u32, u32)> for SoVersion {
    fn eq(&self, o: &(u32, u32, u32, u32)) -> bool {
        self.major == o.0 && self.minor == o.1 && self.patch == o.2 && self.prerelease == o.3
    }
}

#[cfg(test)]
#[cfg(target_pointer_width = "64")] // All addresses are 64 bit and I'm currently too lazy to adjust it to work for both
mod tests {
    use super::*;
    use error_graph::ErrorList;
    use std::path::PathBuf;

    use crate::linux::{maps_reader::get_mappings_for, process_inspection};

    // All addresses below are 64 bit, and `MappingInfo::aggregate` drops any
    // mapping it can't fit into a `usize`.
    #[cfg(target_pointer_width = "64")]
    #[test]
    fn test_get_module_effective_name() {
        let mappings = get_mappings_for(
            "\
7f0b97b6f000-7f0b97b70000 r--p 00000000 00:3e 27136458                   /home/martin/Documents/mozilla/devel/mozilla-central/obj/widget/gtk/mozgtk/gtk3/libmozgtk.so
7f0b97b70000-7f0b97b71000 r-xp 00000000 00:3e 27136458                   /home/martin/Documents/mozilla/devel/mozilla-central/obj/widget/gtk/mozgtk/gtk3/libmozgtk.so
7f0b97b71000-7f0b97b73000 r--p 00000000 00:3e 27136458                   /home/martin/Documents/mozilla/devel/mozilla-central/obj/widget/gtk/mozgtk/gtk3/libmozgtk.so
7f0b97b73000-7f0b97b74000 rw-p 00001000 00:3e 27136458                   /home/martin/Documents/mozilla/devel/mozilla-central/obj/widget/gtk/mozgtk/gtk3/libmozgtk.so",
            0x7ffe091bf000,
        );
        assert_eq!(mappings.len(), 1);
        let process_inspector = process_inspection::local(0);
        let modules = resolve(
            from_mappings(process_inspector.as_ref(), &mappings),
            None,
            &mut ErrorList::default(),
        );

        // The path doesn't exist, so the SONAME read fails and we fall back to
        // the filesystem name -- which is the behaviour under test.
        let mut soft_errors = ErrorList::default();
        let (file_path, file_name, _version) = modules[0].effective_path_name_and_version(
            process_inspector.as_ref(),
            None,
            &mut soft_errors,
        );
        assert!(!soft_errors.is_empty());
        assert_eq!(file_name, "libmozgtk.so");
        assert_eq!(
            file_path,
            PathBuf::from(
                "/home/martin/Documents/mozilla/devel/mozilla-central/obj/widget/gtk/mozgtk/gtk3/libmozgtk.so"
            )
        );
    }

    #[test]
    fn test_elf_file_so_version() {
        #[rustfmt::skip]
        let test_cases = [
            ("/usr/lib/x86_64-linux-gnu/libstdc++.so.6.0.32", (6, 0, 32, 0)),
            ("/usr/lib/x86_64-linux-gnu/libcairo-gobject.so.2.11800.0", (2, 11800, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libm.so.6", (6, 0, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libpthread.so.0", (0, 0, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libgmodule-2.0.so.0.7800.0", (0, 7800, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libabsl_time_zone.so.20220623.0.0", (20220623, 0, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libdbus-1.so.3.34.2rc5", (3, 34, 2, 5)),
            ("/usr/lib/x86_64-linux-gnu/libdbus-1.so.3.34.2rc", (3, 34, 2, 0)),
            ("/usr/lib/x86_64-linux-gnu/libdbus-1.so.3.34.rc5", (3, 34, 0, 5)),
            ("/usr/lib/x86_64-linux-gnu/libtoto.so.AAA", (0, 0, 0, 0)),
            ("/usr/lib/x86_64-linux-gnu/libsemver-1.so.1.2.alpha.1", (1, 2, 0, 1)),
            ("/usr/lib/x86_64-linux-gnu/libboop.so.1.2.3.4.5", (1, 2, 3, 4)),
            ("/usr/lib/x86_64-linux-gnu/libboop.so.1.2.3pre4.5", (1, 2, 3, 4)),
        ];

        assert!(SoVersion::parse(OsStr::new("/home/alex/bin/firefox/libmozsandbox.so")).is_none());

        for (path, expected) in test_cases {
            let actual = SoVersion::parse(OsStr::new(path)).unwrap();
            assert_eq!(actual, expected);
        }
    }
}