pharos_runtime_core/

lib.rs

#![forbid(unsafe_code)]

/// Provides the `application_ir` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::application_ir;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod application_ir;
/// Provides framework builtin response helpers.
pub mod builtin;
/// Provides the `config` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::config;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod config;
/// Provides the `connection` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::connection;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod connection;
/// Provides the `error` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::error;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod error;
/// Provides the `fs` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::fs;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod fs;
/// Provides the `http` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::http;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod http;
/// Provides the `listener` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::listener;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod listener;
/// Provides runtime readiness helpers.
pub mod readiness;
/// Provides app-neutral render request data helpers.
pub mod render;
/// Provides runtime request dispatch helpers.
pub mod request;
/// Provides runtime route lookup helpers.
pub mod route;
/// Provides runtime stack records.
pub mod stack;

/// Provides the `support` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::support;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod support;
/// Provides runtime timestamp formatting helpers.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::time;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod time;
/// Provides the `worker_pool` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::worker_pool;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod worker_pool;
/// Provides the `yaml` module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_runtime_core::yaml;
/// ```
///
/// # Related
///
/// - [`crate`] for sibling modules in the same crate.
pub mod yaml;

use std::path::{Component, Path, PathBuf};

/// Returns the longest matching mount index for an absolute request path.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::best_mount_index`].
/// - `mounts`: Input consumed by [`crate::best_mount_index`].
/// - `'a str`: Input consumed by [`crate::best_mount_index`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::best_mount_index`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::best_mount_index`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::best_mount_index(std::path::Path::new("fixture.json"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate`] for adjacent helpers that share the same runtime surface.
pub fn best_mount_index<'a, I>(path: &str, mounts: I) -> Option<usize>
where
    I: IntoIterator<Item = (usize, &'a str)>,
{
    let mut best = None;
    let mut best_len = 0usize;
    for (index, mount) in mounts {
        let mount_len = mount.len();
        if mount_len == 0 {
            if best.is_none() {
                best = Some(index);
            }
            continue;
        }
        let matches_mount = path == mount
            || (path.starts_with(mount)
                && matches!(
                    path.as_bytes().get(mount_len),
                    Some(b'/') | Some(b'?') | None
                ));
        if matches_mount && mount_len > best_len {
            best = Some(index);
            best_len = mount_len;
        }
    }
    best
}

/// Removes one app mount prefix while preserving the query string.
///
/// # Parameters
///
/// - `mount`: Input consumed by [`crate::relative_target`].
/// - `target`: Input consumed by [`crate::relative_target`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::relative_target`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::relative_target(None, "/");
/// ```
///
/// # Related
///
/// - [`crate`] for adjacent helpers that share the same runtime surface.
pub fn relative_target(mount: Option<&str>, target: &str) -> String {
    let mount = mount
        .filter(|value| !value.is_empty() && *value != "/")
        .map(|value| value.trim_end_matches('/'));
    let Some(mount) = mount else {
        return target.to_owned();
    };
    let (path, query) = target.split_once('?').unwrap_or((target, ""));
    let relative_path = if path == mount {
        "/".to_owned()
    } else if let Some(suffix) = path.strip_prefix(mount) {
        if suffix.starts_with('/') {
            suffix.to_owned()
        } else {
            path.to_owned()
        }
    } else {
        path.to_owned()
    };
    if query.is_empty() {
        relative_path
    } else {
        format!("{relative_path}?{query}")
    }
}

/// Normalizes an absolute request path without permitting parent traversal.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::normalize_request_path`].
/// - `max_bytes`: Input consumed by [`crate::normalize_request_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::normalize_request_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::normalize_request_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::normalize_request_path("/", 1024);
/// ```
///
/// # Related
///
/// - [`crate`] for adjacent helpers that share the same runtime surface.
pub fn normalize_request_path(target: &str, max_bytes: usize) -> Option<String> {
    if target.is_empty() || target.len() > max_bytes {
        return None;
    }
    let raw_path = target.split(['?', '#']).next().unwrap_or_default();
    if !raw_path.starts_with('/') || raw_path.contains('\\') {
        return None;
    }
    let mut normalized = String::from("/");
    let mut first = true;
    for component in Path::new(raw_path).components() {
        match component {
            Component::RootDir | Component::CurDir => {}
            Component::ParentDir | Component::Prefix(_) => return None,
            Component::Normal(segment) => {
                let segment = segment.to_str()?;
                if segment.is_empty() {
                    continue;
                }
                if !first {
                    normalized.push('/');
                }
                normalized.push_str(segment);
                first = false;
            }
        }
    }
    Some(normalized)
}

/// Resolves a relative artifact path and proves it remains under the artifact root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::safe_existing_artifact_path`].
/// - `relative`: Input consumed by [`crate::safe_existing_artifact_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::safe_existing_artifact_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::safe_existing_artifact_path(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate`] for adjacent helpers that share the same runtime surface.
pub fn safe_existing_artifact_path(root: &Path, relative: &str) -> Option<PathBuf> {
    if relative.is_empty() || Path::new(relative).is_absolute() || relative.contains('\\') {
        return None;
    }
    let canonical_root = std::fs::canonicalize(root).ok()?;
    let canonical_candidate = std::fs::canonicalize(root.join(relative)).ok()?;
    canonical_candidate
        .starts_with(canonical_root)
        .then_some(canonical_candidate)
}

#[cfg(test)]
mod tests {
    use super::{best_mount_index, normalize_request_path, relative_target};

    #[test]
    /// Performs prefers longest matching mount.
    fn prefers_longest_matching_mount() {
        let mounts = [(0, ""), (1, "/docs"), (2, "/docs/reference")];
        assert_eq!(best_mount_index("/docs/reference/page", mounts), Some(2));
    }

    #[test]
    /// Performs preserves query when trimming mount.
    fn preserves_query_when_trimming_mount() {
        assert_eq!(
            relative_target(Some("/ucal"), "/ucal/accounts/login/?next=/"),
            "/accounts/login/?next=/"
        );
    }

    #[test]
    /// Performs rejects parent path components.
    fn rejects_parent_path_components() {
        assert_eq!(normalize_request_path("/static/../secret", 8192), None);
    }
}