pharos_native/platform/

mod.rs

#[cfg(feature = "wasi-host-bridge")]
use std::collections::HashSet;
#[cfg(feature = "wasi-host-bridge")]
use std::env;
#[cfg(feature = "wasi-host-bridge")]
use std::io::{self, Read};

use std::path::Path;
#[cfg(feature = "wasi-host-bridge")]
use std::process::{Child, Command, Stdio};
#[cfg(feature = "wasi-host-bridge")]
use std::sync::{
    Arc,
    atomic::{AtomicBool, Ordering},
};
#[cfg(feature = "wasi-host-bridge")]
use std::thread;
#[cfg(feature = "wasi-host-bridge")]
use std::thread::JoinHandle;
#[cfg(feature = "wasi-host-bridge")]
use std::time::{Duration, Instant};

/// Public constant `MODULE_STATUS` exposed by this module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::platform::MODULE_STATUS;
/// ```
///
/// # Related
///
/// - [`crate::platform`] for the surrounding module surface.
pub const MODULE_STATUS: &str = "PENDING";

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// Public enum `HostTarget` used by this module.
///
/// # Variants
///
/// - `MacosDarwinX86_64`: Supported `HostTarget` variant.
/// - `Wasm32Wasip1`: Supported `HostTarget` variant.
/// - `Wasm32UnknownUnknown`: Supported `HostTarget` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::platform::HostTarget::MacosDarwinX86_64;
/// ```
///
/// # Related
///
/// - [`crate::platform`] for constructors, helpers, and neighboring runtime types.
pub enum HostTarget {
    MacosDarwinX86_64,
    Wasm32Wasip1,
    Wasm32UnknownUnknown,
}

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// Public struct `TargetConstraint` used by this module.
///
/// # Fields
///
/// - `product_target`: Stored field on `TargetConstraint`.
/// - `rust_target`: Stored field on `TargetConstraint`.
/// - `constraints`: Stored field on `TargetConstraint`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::platform::TargetConstraint>();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for constructors, helpers, and neighboring runtime types.
pub struct TargetConstraint {
    pub product_target: &'static str,
    pub rust_target: HostTarget,
    pub constraints: &'static [&'static str],
}

const MACOS_CONSTRAINTS: &[&str] = &[
    "authoritative local target for Phase 1 first build, lockfile generation, and SBOM generation",
    "native runtime, PostgreSQL rustls TLS, SMTP rustls TLS, and SQLite feasibility remain enabled",
];

const WASI_P1_CONSTRAINTS: &[&str] = &[
    "uses the wasm32-wasip1 target",
    "must fail closed for raw sockets, process spawning, SMTP, PostgreSQL, and unsupported async filesystem behavior",
];

const WASM_WEB_CONSTRAINTS: &[&str] = &[
    "reserved for the host-mediated wasm entrypoint target",
    "no networking, process, SMTP, or PostgreSQL capability may be compiled into this target",
];

/// Public constant `TARGET_CONSTRAINTS` exposed by this module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::platform::TARGET_CONSTRAINTS;
/// ```
///
/// # Related
///
/// - [`crate::platform`] for the surrounding module surface.
pub const TARGET_CONSTRAINTS: &[TargetConstraint] = &[
    TargetConstraint {
        product_target: "native host runtime",
        rust_target: HostTarget::MacosDarwinX86_64,
        constraints: MACOS_CONSTRAINTS,
    },
    TargetConstraint {
        product_target: "wasi guest",
        rust_target: HostTarget::Wasm32Wasip1,
        constraints: WASI_P1_CONSTRAINTS,
    },
    TargetConstraint {
        product_target: "wasm entrypoint",
        rust_target: HostTarget::Wasm32UnknownUnknown,
        constraints: WASM_WEB_CONSTRAINTS,
    },
];

/// Performs target constraints.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::target_constraints`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::target_constraints();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn target_constraints() -> &'static [TargetConstraint] {
    TARGET_CONSTRAINTS
}

#[allow(non_snake_case)]
/// Performs acrt initialize.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__acrt_initialize`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__acrt_initialize();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __acrt_initialize() -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs acrt uninitialize.
///
/// # Parameters
///
/// - `_terminating`: Input consumed by [`crate::platform::__acrt_uninitialize`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__acrt_uninitialize`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__acrt_uninitialize(todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __acrt_uninitialize(_terminating: bool) -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs acrt uninitialize critical.
///
/// # Parameters
///
/// - `_terminating`: Input consumed by [`crate::platform::__acrt_uninitialize_critical`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__acrt_uninitialize_critical`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__acrt_uninitialize_critical(todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __acrt_uninitialize_critical(_terminating: bool) -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs acrt thread attach.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__acrt_thread_attach`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__acrt_thread_attach();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __acrt_thread_attach() -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs acrt thread detach.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__acrt_thread_detach`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__acrt_thread_detach();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __acrt_thread_detach() -> i32 {
    1
}

/// Performs is c termination complete.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::_is_c_termination_complete`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::_is_c_termination_complete();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn _is_c_termination_complete() -> i32 {
    0
}

#[allow(non_snake_case)]
/// Performs vcrt uninitialize critical.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__vcrt_uninitialize_critical`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__vcrt_uninitialize_critical();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __vcrt_uninitialize_critical() -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs vcrt initialize.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__vcrt_initialize`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__vcrt_initialize();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __vcrt_initialize() -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs vcrt uninitialize.
///
/// # Parameters
///
/// - `_terminating`: Input consumed by [`crate::platform::__vcrt_uninitialize`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__vcrt_uninitialize`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__vcrt_uninitialize(todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __vcrt_uninitialize(_terminating: bool) -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs vcrt thread attach.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__vcrt_thread_attach`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__vcrt_thread_attach();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __vcrt_thread_attach() -> i32 {
    1
}

#[allow(non_snake_case)]
/// Performs vcrt thread detach.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::__vcrt_thread_detach`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::__vcrt_thread_detach();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn __vcrt_thread_detach() -> i32 {
    1
}

#[cfg(feature = "wasi-host-bridge")]
const MAX_CAPTURE_OUTPUT_BYTES: usize = 8 * 1024 * 1024;
#[cfg(feature = "wasi-host-bridge")]
const CAPTURE_READ_CHUNK_BYTES: usize = 4096;
#[cfg(feature = "wasi-host-bridge")]
const MAX_CAPTURE_WALL_CLOCK: Duration = Duration::from_secs(30);
#[cfg(feature = "wasi-host-bridge")]
/// Public constant `CHILD_PROCESS_TIMEOUT_CODE` exposed by this module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::platform::CHILD_PROCESS_TIMEOUT_CODE;
/// ```
///
/// # Related
///
/// - [`crate::platform`] for the surrounding module surface.
pub const CHILD_PROCESS_TIMEOUT_CODE: i32 = 70;
#[cfg(feature = "wasi-host-bridge")]
const CAPTURE_POLL_INTERVAL: Duration = Duration::from_millis(5);
#[cfg(feature = "wasi-host-bridge")]
const MAX_CAPTURE_ARGUMENTS: usize = 1024;
#[cfg(feature = "wasi-host-bridge")]
const MAX_CAPTURE_ARGUMENT_BYTES: usize = 64 * 1024;
#[cfg(feature = "wasi-host-bridge")]
const MAX_ENV_COMPONENT_BYTES: usize = 64 * 1024;

#[cfg(feature = "wasi-host-bridge")]
/// Reads one child-process pipe chunk into a bounded output buffer.
///
/// # Parameters
///
/// - `reader`: Reader supplying child-process output bytes.
/// - `buffer`: Input consumed by [`crate::platform::append_pipe_to_buffer`].
/// - `open`: Input consumed by [`crate::platform::append_pipe_to_buffer`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::append_pipe_to_buffer`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::append_pipe_to_buffer(todo!(), &mut [], todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub(crate) fn append_pipe_to_buffer<R: Read>(
    reader: &mut R,
    buffer: &mut Vec<u8>,
    open: &mut bool,
) -> io::Result<()> {
    if !*open {
        return Ok(());
    }

    let remaining = MAX_CAPTURE_OUTPUT_BYTES.saturating_sub(buffer.len());
    let read_limit = remaining.saturating_add(1).min(CAPTURE_READ_CHUNK_BYTES);
    let mut chunk = [0_u8; CAPTURE_READ_CHUNK_BYTES];
    let bytes_read = reader.read(&mut chunk[..read_limit])?;
    if bytes_read == 0 {
        *open = false;
        return Ok(());
    }
    if bytes_read > remaining {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            "child-process output exceeds the capture limit",
        ));
    }
    buffer.extend_from_slice(&chunk[..bytes_read]);
    Ok(())
}

#[cfg(feature = "wasi-host-bridge")]
/// Builds one validated `KEY=VALUE` environment assignment for a child.
///
/// # Parameters
///
/// - `key`: Environment variable name to validate and encode.
/// - `value`: Input consumed by [`crate::platform::build_child_env_assignment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::platform::build_child_env_assignment`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::build_child_env_assignment(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub(crate) fn build_child_env_assignment(key: Option<&str>, value: Option<&str>) -> Option<String> {
    let key = key.filter(|value| !value.is_empty())?;
    let value = value.filter(|value| !value.is_empty())?;
    if key.len() > MAX_ENV_COMPONENT_BYTES
        || value.len() > MAX_ENV_COMPONENT_BYTES
        || key.contains('=')
        || key.contains('\0')
        || value.contains('\0')
    {
        return None;
    }
    Some(format!("{key}={value}"))
}

#[cfg(feature = "wasi-host-bridge")]
/// Builds the inherited environment with valid requested keys applied once.
///
/// # Parameters
///
/// - `env_keys`: Keys to override or append in the child environment.
/// - `env_values`: Input consumed by [`crate::platform::build_child_env`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::platform::build_child_env`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::platform::build_child_env`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::build_child_env(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub(crate) fn build_child_env<K, V>(env_keys: &[K], env_values: &[V]) -> Vec<(String, String)>
where
    K: AsRef<str>,
    V: AsRef<str>,
{
    let assignments: Vec<(String, String)> = env_keys
        .iter()
        .zip(env_values.iter())
        .filter_map(|(key, value)| {
            let assignment = build_child_env_assignment(Some(key.as_ref()), Some(value.as_ref()))?;
            let (key, value) = assignment.split_once('=')?;
            Some((key.to_owned(), value.to_owned()))
        })
        .collect();
    let overridden: HashSet<&str> = assignments.iter().map(|(key, _)| key.as_str()).collect();
    let mut child_env: Vec<(String, String)> = env::vars()
        .filter(|(key, _)| !overridden.contains(key.as_str()))
        .collect();
    child_env.extend(assignments);
    child_env
}

#[cfg(feature = "wasi-host-bridge")]
/// Releases an owned child environment using Rust's normal drop semantics.
///
/// # Parameters
///
/// - `child_env`: Environment vector being consumed and dropped.
///
/// # Returns
///
/// Returns after [`crate::platform::free_child_env`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::free_child_env(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub(crate) fn free_child_env<K, V>(child_env: &mut Vec<(K, V)>) {
    child_env.clear();
}

/// Returns whether a path currently identifies a directory.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::platform::path_is_directory`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::path_is_directory`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::path_is_directory(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn path_is_directory(path: &Path) -> bool {
    !path.as_os_str().is_empty() && path.is_dir()
}

/// Tests whether one string begins with another string.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::platform::starts_with`].
/// - `prefix`: Input consumed by [`crate::platform::starts_with`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::starts_with`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::starts_with("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn starts_with(value: &str, prefix: &str) -> bool {
    value.starts_with(prefix)
}

#[cfg(feature = "wasi-host-bridge")]
#[derive(Debug)]
struct CapturePipeResult {
    bytes: Result<Vec<u8>, i32>,
}

#[cfg(feature = "wasi-host-bridge")]
/// Captures pipe.
fn capture_pipe<R: Read + Send + 'static>(
    mut reader: R,
    failed: Arc<AtomicBool>,
) -> JoinHandle<CapturePipeResult> {
    thread::spawn(move || {
        let mut buffer = Vec::new();
        let mut open = true;
        while open {
            if append_pipe_to_buffer(&mut reader, &mut buffer, &mut open).is_err() {
                failed.store(true, Ordering::Release);
                return CapturePipeResult { bytes: Err(69) };
            }
        }
        CapturePipeResult { bytes: Ok(buffer) }
    })
}

#[cfg(feature = "wasi-host-bridge")]
/// Captures argv.
fn capture_argv<A: AsRef<str>>(argv: &[A]) -> Result<Vec<String>, i32> {
    if argv.is_empty() || argv.len() > MAX_CAPTURE_ARGUMENTS {
        return Err(69);
    }
    argv.iter()
        .map(|argument| {
            let argument = argument.as_ref();
            if argument.is_empty()
                || argument.len() > MAX_CAPTURE_ARGUMENT_BYTES
                || argument.contains('\0')
            {
                Err(69)
            } else {
                Ok(argument.to_owned())
            }
        })
        .collect()
}

#[cfg(feature = "wasi-host-bridge")]
/// Terminates a supervised child and its process group where supported, then reaps it.
///
/// # Parameters
///
/// - `child`: Input consumed by [`crate::platform::terminate_child_process_tree`].
///
/// # Returns
///
/// Returns after [`crate::platform::terminate_child_process_tree`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::terminate_child_process_tree(todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn terminate_child_process_tree(child: &mut Child) {
    #[cfg(unix)]
    {
        let group = format!("-{}", child.id());
        let _ = Command::new("/bin/kill")
            .args(["-TERM", "--", group.as_str()])
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .status();
        thread::sleep(Duration::from_millis(20));
        let _ = Command::new("/bin/kill")
            .args(["-KILL", "--", group.as_str()])
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .status();
    }
    #[cfg(windows)]
    {
        let pid = child.id().to_string();
        let taskkill = env::var_os("SystemRoot")
            .map(|root| Path::new(&root).join("System32").join("taskkill.exe"))
            .unwrap_or_else(|| Path::new("taskkill.exe").to_path_buf());
        let _ = Command::new(taskkill)
            .args(["/PID", pid.as_str(), "/T", "/F"])
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .status();
    }
    let _ = child.kill();
    let _ = child.wait();
}

/// Executes an argv vector directly with bounded output and wall-clock lifetime.
///
/// No shell is involved. Each stream is drained concurrently and is capped at
/// `MAX_CAPTURE_OUTPUT_BYTES`. A timeout terminates the child process tree where
/// supported and always reaps the direct child before returning.
#[cfg(feature = "wasi-host-bridge")]
fn capture_execv_output_split_env_with_timeout<A, K, V>(
    argv: &[A],
    env_keys: &[K],
    env_values: &[V],
    timeout: Duration,
) -> Result<(i32, Vec<u8>, Vec<u8>), i32>
where
    A: AsRef<str>,
    K: AsRef<str>,
    V: AsRef<str>,
{
    let argv = capture_argv(argv)?;
    let mut child_env = build_child_env(env_keys, env_values);
    let mut command = Command::new(&argv[0]);
    command
        .args(&argv[1..])
        .env_clear()
        .stdout(Stdio::piped())
        .stderr(Stdio::piped());
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        command.process_group(0);
    }
    for (key, value) in &child_env {
        command.env(key, value);
    }
    free_child_env(&mut child_env);

    let mut child = command.spawn().map_err(|_| 69)?;
    let stdout = child.stdout.take().ok_or(69)?;
    let stderr = child.stderr.take().ok_or(69)?;
    let failed = Arc::new(AtomicBool::new(false));
    let stdout_thread = capture_pipe(stdout, Arc::clone(&failed));
    let stderr_thread = capture_pipe(stderr, Arc::clone(&failed));
    let deadline = Instant::now().checked_add(timeout);

    let status = loop {
        if failed.load(Ordering::Acquire) {
            terminate_child_process_tree(&mut child);
            break child.try_wait().map_err(|_| 69)?.ok_or(69)?;
        }
        if deadline.is_some_and(|value| Instant::now() >= value) {
            terminate_child_process_tree(&mut child);
            let _ = stdout_thread.join();
            let _ = stderr_thread.join();
            return Err(CHILD_PROCESS_TIMEOUT_CODE);
        }
        match child.try_wait() {
            Ok(Some(status)) => break status,
            Ok(None) => thread::sleep(CAPTURE_POLL_INTERVAL),
            Err(_) => {
                terminate_child_process_tree(&mut child);
                return Err(69);
            }
        }
    };

    let stdout = stdout_thread.join().map_err(|_| 69)?.bytes?;
    let stderr = stderr_thread.join().map_err(|_| 69)?.bytes?;
    Ok((status.code().unwrap_or(69), stdout, stderr))
}

#[cfg(feature = "wasi-host-bridge")]
/// Executes an argv vector directly and captures stdout and stderr separately.
///
/// # Parameters
///
/// - `argv`: Input consumed by [`crate::platform::capture_execv_output_split_env`].
/// - `env_keys`: Input consumed by [`crate::platform::capture_execv_output_split_env`].
/// - `env_values`: Input consumed by [`crate::platform::capture_execv_output_split_env`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::platform::capture_execv_output_split_env`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::platform::capture_execv_output_split_env`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::capture_execv_output_split_env(todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn capture_execv_output_split_env<A, K, V>(
    argv: &[A],
    env_keys: &[K],
    env_values: &[V],
) -> Result<(i32, Vec<u8>, Vec<u8>), i32>
where
    A: AsRef<str>,
    K: AsRef<str>,
    V: AsRef<str>,
{
    capture_execv_output_split_env_with_timeout(argv, env_keys, env_values, MAX_CAPTURE_WALL_CLOCK)
}

#[cfg(feature = "wasi-host-bridge")]
/// Executes argv with validated environment overrides and merges both streams.
///
/// # Parameters
///
/// - `argv`: Input consumed by [`crate::platform::capture_execv_output_env`].
/// - `env_keys`: Input consumed by [`crate::platform::capture_execv_output_env`].
/// - `env_values`: Input consumed by [`crate::platform::capture_execv_output_env`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::platform::capture_execv_output_env`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::platform::capture_execv_output_env`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::capture_execv_output_env(todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn capture_execv_output_env<A, K, V>(
    argv: &[A],
    env_keys: &[K],
    env_values: &[V],
) -> Result<(i32, Vec<u8>), i32>
where
    A: AsRef<str>,
    K: AsRef<str>,
    V: AsRef<str>,
{
    let (status, stdout, stderr) = capture_execv_output_split_env(argv, env_keys, env_values)?;
    if stdout
        .len()
        .checked_add(stderr.len())
        .is_none_or(|length| length > MAX_CAPTURE_OUTPUT_BYTES)
    {
        return Err(69);
    }
    let mut output = Vec::with_capacity(stdout.len() + stderr.len());
    output.extend_from_slice(&stdout);
    output.extend_from_slice(&stderr);
    Ok((status, output))
}

#[cfg(feature = "wasi-host-bridge")]
/// Executes argv directly and captures bounded merged output.
///
/// # Parameters
///
/// - `argv`: Input consumed by [`crate::platform::capture_execv_output`].
/// - `Vec<u8>`: Input consumed by [`crate::platform::capture_execv_output`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::platform::capture_execv_output`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::platform::capture_execv_output`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::capture_execv_output(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn capture_execv_output<A: AsRef<str>>(argv: &[A]) -> Result<(i32, Vec<u8>), i32> {
    let empty: [&str; 0] = [];
    capture_execv_output_env(argv, &empty, &empty)
}

/// Checks writability without creating files or invoking external commands.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::platform::path_is_writable`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::path_is_writable`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::path_is_writable(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn path_is_writable(path: &Path) -> bool {
    if path.as_os_str().is_empty() {
        return false;
    }
    let directory = if path.is_dir() {
        path.to_path_buf()
    } else {
        path.parent()
            .unwrap_or_else(|| Path::new("."))
            .to_path_buf()
    };
    if !directory.is_dir() {
        return false;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        directory
            .metadata()
            .map(|metadata| metadata.permissions().mode() & 0o222 != 0)
            .unwrap_or(false)
    }
    #[cfg(not(unix))]
    {
        true
    }
}

const PLATFORM_BUFFER_LIMIT: usize = 16 * 1024 * 1024;

#[derive(Debug, Clone, Default, Eq, PartialEq)]
/// Public struct `PlatformBuffer` used by this module.
///
/// # Fields
///
/// - `bytes`: Stored field on `PlatformBuffer`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::platform::PlatformBuffer>();
/// ```
///
/// # Related
///
/// - [`crate::platform`] for constructors, helpers, and neighboring runtime types.
pub struct PlatformBuffer {
    pub bytes: Vec<u8>,
}

/// Initializes a bounded platform buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::platform::buffer_init`].
///
/// # Returns
///
/// Returns after [`crate::platform::buffer_init`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::buffer_init(&mut []);
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn buffer_init(buffer: &mut PlatformBuffer) {
    buffer.bytes.clear();
}

/// Releases a platform buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::platform::buffer_free`].
///
/// # Returns
///
/// Returns after [`crate::platform::buffer_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::buffer_free(&mut []);
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn buffer_free(buffer: &mut PlatformBuffer) {
    buffer.bytes.clear();
    buffer.bytes.shrink_to_fit();
}

/// Reserves bounded capacity for a platform buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::platform::buffer_reserve`].
/// - `needed`: Input consumed by [`crate::platform::buffer_reserve`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::buffer_reserve`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::buffer_reserve(&mut [], todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn buffer_reserve(buffer: &mut PlatformBuffer, needed: usize) -> bool {
    needed <= PLATFORM_BUFFER_LIMIT
        && buffer
            .bytes
            .try_reserve(needed.saturating_sub(buffer.bytes.len()))
            .is_ok()
}

/// Appends bytes to a platform buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::platform::buffer_append`].
/// - `data`: Input consumed by [`crate::platform::buffer_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::buffer_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::buffer_append(&mut [], b"");
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn buffer_append(buffer: &mut PlatformBuffer, data: &[u8]) -> bool {
    if !buffer_reserve(buffer, buffer.bytes.len().saturating_add(data.len())) {
        return false;
    }
    buffer.bytes.extend_from_slice(data);
    true
}

/// Duplicates a bounded byte range as UTF-8 text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::platform::dup_range`].
/// - `length`: Input consumed by [`crate::platform::dup_range`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::platform::dup_range`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::dup_range("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn dup_range(text: &str, length: usize) -> Option<String> {
    text.get(..length.min(text.len())).map(ToOwned::to_owned)
}

/// Trims ASCII whitespace in place.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::platform::trim_in_place`].
///
/// # Returns
///
/// Returns after [`crate::platform::trim_in_place`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::trim_in_place("{}");
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn trim_in_place(text: &mut String) {
    *text = text.trim().to_owned();
}

/// Joins two paths without allowing an absolute right-hand replacement.
///
/// # Parameters
///
/// - `left`: Input consumed by [`crate::platform::path_join`].
/// - `right`: Input consumed by [`crate::platform::path_join`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::platform::path_join`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::path_join(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn path_join(left: &str, right: &str) -> Option<String> {
    if left.is_empty() || right.is_empty() || Path::new(right).is_absolute() || right.contains('\0')
    {
        return None;
    }
    Some(Path::new(left).join(right).to_string_lossy().into_owned())
}

/// Returns a path's parent component as owned text.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::platform::path_dirname`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::platform::path_dirname`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::path_dirname(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn path_dirname(path: &str) -> Option<String> {
    Path::new(path)
        .parent()
        .map(|value| value.to_string_lossy().into_owned())
}

/// Checks whether a path exists without following user-controlled commands.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::platform::path_exists`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::platform::path_exists`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::path_exists(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn path_exists(path: &str) -> bool {
    !path.is_empty() && Path::new(path).exists()
}

/// Reads a bounded UTF-8 file.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::platform::read_file_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::platform::read_file_text`] 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::platform::read_file_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::platform::read_file_text(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::platform`] for adjacent helpers that share the same runtime surface.
pub fn read_file_text(path: &Path) -> Option<String> {
    let metadata = std::fs::metadata(path).ok()?;
    (metadata.len() <= PLATFORM_BUFFER_LIMIT as u64)
        .then(|| std::fs::read_to_string(path).ok())
        .flatten()
}

#[cfg(all(test, feature = "wasi-host-bridge"))]
mod tests {
    use super::{CHILD_PROCESS_TIMEOUT_CODE, capture_execv_output_split_env_with_timeout};
    use std::time::{Duration, Instant};

    #[cfg(unix)]
    #[test]
    /// Captures timeout terminates a child process group.
    fn capture_timeout_terminates_a_child_process_group() {
        let started = Instant::now();
        let result = capture_execv_output_split_env_with_timeout(
            &["/bin/sh", "-c", "sleep 5 & wait"],
            &[] as &[&str],
            &[] as &[&str],
            Duration::from_millis(100),
        );
        assert_eq!(result, Err(CHILD_PROCESS_TIMEOUT_CODE));
        assert!(started.elapsed() < Duration::from_secs(2));
    }
}