pharos_runtime_static/

artifact_server.rs

#![allow(clippy::result_unit_err)]

use std::fs::{self, File};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::{Component, Path, PathBuf};

const MAX_REQUEST_TARGET_BYTES: usize = 8 * 1024;
const MAX_ROUTE_LINE_BYTES: usize = 16 * 1024;
const MAX_STATIC_FILE_BYTES: u64 = 16 * 1024 * 1024;

#[derive(Debug, Clone, Eq, PartialEq)]
/// A validated file slice that can be copied to a connection with bounded memory.
///
/// # Fields
///
/// - `status_code`: Stored field on `StreamResponse`.
/// - `status_text`: Stored field on `StreamResponse`.
/// - `content_type`: Stored field on `StreamResponse`.
/// - `file_path`: Stored field on `StreamResponse`.
/// - `offset`: Stored field on `StreamResponse`.
/// - `content_length`: Stored field on `StreamResponse`.
/// - `complete_length`: Stored field on `StreamResponse`.
/// - `etag`: Stored field on `StreamResponse`.
/// - `cache_control`: Stored field on `StreamResponse`.
/// - `content_disposition`: Stored field on `StreamResponse`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_static::artifact_server::StreamResponse>();
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for constructors, helpers, and neighboring runtime types.
pub struct StreamResponse {
    /// HTTP status code.
    pub status_code: u16,
    /// HTTP reason phrase.
    pub status_text: &'static str,
    /// MIME type selected from the trusted asset filename.
    pub content_type: &'static str,
    /// Canonical file path within the artifact boundary.
    pub file_path: PathBuf,
    /// First byte included in the response.
    pub offset: u64,
    /// Number of bytes included in the response.
    pub content_length: u64,
    /// Complete file length used by `Content-Range`.
    pub complete_length: u64,
    /// Strong local validator for `If-Range`.
    pub etag: String,
    /// Cache policy selected by the runtime, not the application.
    pub cache_control: &'static str,
    /// Trusted attachment filename for protected downloads.
    pub content_disposition: Option<String>,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// A bounded static error plus optional unsatisfied representation length.
///
/// # Fields
///
/// - `response`: Stored field on `StreamError`.
/// - `unsatisfied_length`: Stored field on `StreamError`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_static::artifact_server::StreamError>();
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for constructors, helpers, and neighboring runtime types.
pub struct StreamError {
    /// Existing bounded error body.
    pub response: StaticResponse,
    /// Complete length emitted as `Content-Range: bytes */N` for status 416.
    pub unsatisfied_length: Option<u64>,
}

/// Wraps one ordinary static error without range metadata.
fn stream_error(response: StaticResponse) -> StreamError {
    StreamError {
        response,
        unsatisfied_length: None,
    }
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// A bounded static response selected from one packaged app artifact.
///
/// # Fields
///
/// - `status_code`: Stored field on `StaticResponse`.
/// - `status_text`: Stored field on `StaticResponse`.
/// - `content_type`: Stored field on `StaticResponse`.
/// - `body`: Stored field on `StaticResponse`.
/// - `content_length`: Stored field on `StaticResponse`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_static::artifact_server::StaticResponse>();
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for constructors, helpers, and neighboring runtime types.
pub struct StaticResponse {
    /// HTTP status code.
    pub status_code: u16,
    /// HTTP reason phrase.
    pub status_text: &'static str,
    /// MIME type for the response body.
    pub content_type: &'static str,
    /// Response bytes. Empty for `HEAD` responses.
    pub body: Vec<u8>,
    /// Original body length, retained for `HEAD` and header generation.
    pub content_length: u64,
}

/// Performs response.
fn response(
    status_code: u16,
    status_text: &'static str,
    content_type: &'static str,
    body: Vec<u8>,
    content_length: u64,
) -> StaticResponse {
    StaticResponse {
        status_code,
        status_text,
        content_type,
        body,
        content_length,
    }
}

/// Performs text error.
fn text_error(
    status_code: u16,
    status_text: &'static str,
    message: &'static str,
) -> StaticResponse {
    let code = pharos_runtime_core::error::ErrorCode::from_http_status(status_code);
    let body = pharos_runtime_core::error::envelope(code, message.trim(), None).to_string();
    response(
        status_code,
        status_text,
        "application/json; charset=utf-8",
        body.as_bytes().to_vec(),
        body.len() as u64,
    )
}

/// Performs percent decode path.
fn percent_decode_path(path: &str) -> Option<String> {
    let bytes = path.as_bytes();
    let mut decoded = Vec::with_capacity(bytes.len());
    let mut index = 0usize;
    while index < bytes.len() {
        if bytes[index] == b'%' {
            if index + 2 >= bytes.len() {
                return None;
            }
            let byte = u8::from_str_radix(&path[index + 1..index + 3], 16).ok()?;
            decoded.push(byte);
            index += 3;
        } else {
            decoded.push(bytes[index]);
            index += 1;
        }
    }
    let decoded = String::from_utf8(decoded).ok()?;
    if decoded
        .bytes()
        .any(|byte| byte == 0 || byte < 0x20 || byte == 0x7f)
    {
        return None;
    }
    Some(decoded)
}

/// Returns whether a request path contains a parent-directory component.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::artifact_server::path_has_parent_reference`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::artifact_server::path_has_parent_reference`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::artifact_server::path_has_parent_reference`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::path_has_parent_reference(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn path_has_parent_reference(path: &str) -> bool {
    path.split(['/', '\\']).any(|segment| segment == "..")
}

/// Performs normalized path.
fn normalized_path(target: &str) -> Option<String> {
    if target.is_empty() || target.len() > MAX_REQUEST_TARGET_BYTES {
        return None;
    }
    let raw_path = target.split(['?', '#']).next().unwrap_or_default();
    if !raw_path.starts_with('/') {
        return None;
    }
    let decoded = percent_decode_path(raw_path)?;
    if decoded.contains('\\') {
        return None;
    }
    let mut normalized = String::from("/");
    let mut first = true;
    for component in Path::new(&decoded).components() {
        match component {
            Component::RootDir | Component::CurDir => {}
            Component::ParentDir => 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;
            }
            Component::Prefix(_) => return None,
        }
    }
    Some(normalized)
}

/// Parses the content type for path.
fn content_type_for_path(path: &Path) -> &'static str {
    match path.extension().and_then(|extension| extension.to_str()) {
        Some("html") => "text/html; charset=utf-8",
        Some("json") => "application/json",
        Some("css") => "text/css; charset=utf-8",
        Some("js") | Some("mjs") => "application/javascript; charset=utf-8",
        Some("svg") => "image/svg+xml",
        Some("woff2") => "font/woff2",
        Some("woff") => "font/woff",
        Some("ttf") => "font/ttf",
        Some("otf") => "font/otf",
        Some("eot") => "application/vnd.ms-fontobject",
        Some("png") => "image/png",
        Some("jpg") | Some("jpeg") => "image/jpeg",
        Some("gif") => "image/gif",
        Some("webp") => "image/webp",
        Some("ico") => "image/x-icon",
        Some("mp3") => "audio/mpeg",
        Some("wav") => "audio/wav",
        Some("ogg") => "audio/ogg",
        Some("m4a") => "audio/mp4",
        Some("zip") => "application/zip",
        Some("txt") => "text/plain; charset=utf-8",
        _ => "application/octet-stream",
    }
}

/// Parses one RFC 7233 byte range against a known representation length.
fn byte_range(value: &str, length: u64) -> Result<(u64, u64), ()> {
    let value = value.trim();
    let raw = value.strip_prefix("bytes=").ok_or(())?;
    if raw.is_empty() || raw.contains(',') || length == 0 {
        return Err(());
    }
    let (start, end) = raw.split_once('-').ok_or(())?;
    if start.is_empty() {
        let suffix = end.parse::<u64>().map_err(|_| ())?;
        if suffix == 0 {
            return Err(());
        }
        let count = suffix.min(length);
        return Ok((length - count, length - 1));
    }
    let start = start.parse::<u64>().map_err(|_| ())?;
    if start >= length {
        return Err(());
    }
    let end = if end.is_empty() {
        length - 1
    } else {
        end.parse::<u64>().map_err(|_| ())?.min(length - 1)
    };
    (end >= start).then_some((start, end)).ok_or(())
}

/// Creates a deterministic validator without reading the representation body.
fn file_etag(metadata: &fs::Metadata) -> String {
    let modified = metadata
        .modified()
        .ok()
        .and_then(|value| value.duration_since(std::time::UNIX_EPOCH).ok())
        .map(|value| value.as_nanos())
        .unwrap_or_default();
    format!("\"{:x}-{:x}\"", metadata.len(), modified)
}

/// Selects immutable caching only for filenames that visibly carry a content hash.
fn cache_control_for_path(path: &Path) -> &'static str {
    let stem = path
        .file_stem()
        .and_then(|value| value.to_str())
        .unwrap_or("");
    let hashed = stem
        .split(['-', '.'])
        .any(|part| part.len() >= 8 && part.bytes().all(|byte| byte.is_ascii_hexdigit()));
    if hashed {
        "public, max-age=31536000, immutable"
    } else {
        "public, no-cache"
    }
}

/// Resolves a public static/media request into a bounded streaming plan.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::serve_streamable_asset`].
/// - `method`: Input consumed by [`crate::artifact_server::serve_streamable_asset`].
/// - `target`: Input consumed by [`crate::artifact_server::serve_streamable_asset`].
/// - `range`: Input consumed by [`crate::artifact_server::serve_streamable_asset`].
/// - `if_range`: Input consumed by [`crate::artifact_server::serve_streamable_asset`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::artifact_server::serve_streamable_asset`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::artifact_server::serve_streamable_asset`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::serve_streamable_asset(std::path::Path::new("."), todo!(), "/", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn serve_streamable_asset(
    root: &Path,
    method: &str,
    target: &str,
    range: Option<&str>,
    if_range: Option<&str>,
) -> Result<Option<StreamResponse>, StreamError> {
    if !matches!(method, "GET" | "HEAD") {
        return Err(stream_error(text_error(
            405,
            "Method Not Allowed",
            "method not allowed\n",
        )));
    }
    if root.as_os_str().is_empty() || !root.is_dir() {
        return Err(stream_error(text_error(
            500,
            "Internal Server Error",
            "artifact root unavailable\n",
        )));
    }
    let normalized = normalized_path(target)
        .ok_or_else(|| stream_error(text_error(400, "Bad Request", "invalid request path\n")))?;
    let Some((file_path, content_type)) = resolve_direct_asset(root, &normalized)
        .map_err(|_| stream_error(text_error(400, "Bad Request", "invalid request path\n")))?
    else {
        return Ok(None);
    };
    let metadata = fs::metadata(&file_path)
        .map_err(|_| stream_error(text_error(404, "Not Found", "not found\n")))?;
    let complete_length = metadata.len();
    let etag = file_etag(&metadata);
    let selected_range = range.filter(|_| if_range.is_none_or(|value| value.trim() == etag));
    let (status_code, status_text, offset, content_length) = match selected_range {
        Some(value) => match byte_range(value, complete_length) {
            Ok((start, end)) => (206, "Partial Content", start, end - start + 1),
            Err(()) => {
                return Err(StreamError {
                    response: text_error(416, "Range Not Satisfiable", "invalid byte range\n"),
                    unsatisfied_length: Some(complete_length),
                });
            }
        },
        None => (200, "OK", 0, complete_length),
    };
    Ok(Some(StreamResponse {
        status_code,
        status_text,
        content_type,
        file_path: file_path.clone(),
        offset,
        content_length,
        complete_length,
        etag,
        cache_control: cache_control_for_path(&file_path),
        content_disposition: None,
    }))
}

/// Resolves one already-authorized private asset key into a streaming plan.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::serve_private_asset`].
/// - `private_root`: Input consumed by [`crate::artifact_server::serve_private_asset`].
/// - `asset_key`: Input consumed by [`crate::artifact_server::serve_private_asset`].
/// - `method`: Input consumed by [`crate::artifact_server::serve_private_asset`].
/// - `range`: Input consumed by [`crate::artifact_server::serve_private_asset`].
/// - `if_range`: Input consumed by [`crate::artifact_server::serve_private_asset`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::artifact_server::serve_private_asset`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::artifact_server::serve_private_asset`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::artifact_server::serve_private_asset`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::serve_private_asset(std::path::Path::new("."), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn serve_private_asset(
    root: &Path,
    private_root: &str,
    asset_key: &str,
    method: &str,
    range: Option<&str>,
    if_range: Option<&str>,
) -> Result<StreamResponse, StreamError> {
    if !matches!(method, "GET" | "HEAD") {
        return Err(stream_error(text_error(
            405,
            "Method Not Allowed",
            "method not allowed\n",
        )));
    }
    let private_root_path = safe_artifact_path(root, private_root)
        .ok_or_else(|| stream_error(text_error(404, "Not Found", "not found\n")))?;
    let file_path = pharos_runtime_core::safe_existing_artifact_path(&private_root_path, asset_key)
        .filter(|path| path.is_file())
        .ok_or_else(|| stream_error(text_error(404, "Not Found", "not found\n")))?;
    let metadata = fs::metadata(&file_path)
        .map_err(|_| stream_error(text_error(404, "Not Found", "not found\n")))?;
    let complete_length = metadata.len();
    let etag = file_etag(&metadata);
    let selected_range = range.filter(|_| if_range.is_none_or(|value| value.trim() == etag));
    let (status_code, status_text, offset, content_length) = match selected_range {
        Some(value) => match byte_range(value, complete_length) {
            Ok((start, end)) => (206, "Partial Content", start, end - start + 1),
            Err(()) => {
                return Err(StreamError {
                    response: text_error(416, "Range Not Satisfiable", "invalid byte range\n"),
                    unsatisfied_length: Some(complete_length),
                });
            }
        },
        None => (200, "OK", 0, complete_length),
    };
    let filename = file_path
        .file_name()
        .and_then(|value| value.to_str())
        .filter(|value| {
            !value.is_empty()
                && value
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'))
        })
        .map(ToOwned::to_owned)
        .ok_or_else(|| stream_error(text_error(404, "Not Found", "not found\n")))?;
    Ok(StreamResponse {
        status_code,
        status_text,
        content_type: content_type_for_path(&file_path),
        file_path,
        offset,
        content_length,
        complete_length,
        etag,
        cache_control: "private, no-store",
        content_disposition: Some(format!("attachment; filename=\"{filename}\"")),
    })
}

/// Builds a safe artifact path.
fn safe_artifact_path(root: &Path, relative: &str) -> Option<PathBuf> {
    pharos_runtime_core::safe_existing_artifact_path(root, relative)
}

/// Resolves a direct `/static/` or `/media/` request under an artifact root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::resolve_direct_asset`].
/// - `path`: Input consumed by [`crate::artifact_server::resolve_direct_asset`].
/// - `) -> Result<Option<(PathBuf, 'static str)>, (`: Input consumed by [`crate::artifact_server::resolve_direct_asset`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::artifact_server::resolve_direct_asset`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::artifact_server::resolve_direct_asset`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::resolve_direct_asset(std::path::Path::new("."), std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn resolve_direct_asset(
    root: &Path,
    path: &str,
) -> Result<Option<(PathBuf, &'static str)>, ()> {
    let normalized = normalized_path(path).ok_or(())?;
    let relative = normalized.strip_prefix('/').ok_or(())?;
    if !(relative.starts_with("static/") || relative.starts_with("media/")) {
        return Ok(None);
    }
    // Builder context attachments are private intake, never public media assets.
    if relative.starts_with("media/attachments/") {
        return Err(());
    }
    if let Some(media_path) = relative.strip_prefix("media/") {
        let media_root = pharos_runtime_core::config::app_media_root(root).ok_or(())?;
        if let Some(file) =
            safe_artifact_path(&media_root, media_path).filter(|file| file.is_file())
        {
            let content_type = content_type_for_path(&file);
            return Ok(Some((file, content_type)));
        }
    }
    let file = safe_artifact_path(root, relative).ok_or(())?;
    if !file.is_file() {
        return Ok(None);
    }
    let content_type = content_type_for_path(&file);
    Ok(Some((file, content_type)))
}

/// Looks up one GET route in the artifact route map.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::lookup_route_map`].
/// - `path`: Input consumed by [`crate::artifact_server::lookup_route_map`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::artifact_server::lookup_route_map`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::artifact_server::lookup_route_map`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::artifact_server::lookup_route_map`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::lookup_route_map(std::path::Path::new("."), std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn lookup_route_map(root: &Path, path: &str) -> Result<Option<(PathBuf, &'static str)>, ()> {
    let normalized = normalized_path(path).ok_or(())?;
    let map_path = safe_artifact_path(root, "runtime-route-map.tsv").ok_or(())?;
    if !map_path.is_file() {
        return Ok(None);
    }
    let text = fs::read_to_string(map_path).map_err(|_| ())?;
    for line in text.lines() {
        if line.len() > MAX_ROUTE_LINE_BYTES {
            continue;
        }
        let mut fields = line.split('\t');
        let method = fields.next().unwrap_or_default();
        let route_path = fields.next().unwrap_or_default();
        let artifact = fields.next().unwrap_or_default();
        let content_type = fields.next().unwrap_or_default();
        let _status = fields.next().unwrap_or_default();
        if method != "GET"
            || normalized_path(route_path).as_deref() != Some(normalized.as_str())
            || artifact.is_empty()
        {
            continue;
        }
        let file = safe_artifact_path(root, artifact).ok_or(())?;
        if !file.is_file() {
            return Ok(None);
        }
        let content_type = match content_type {
            "text/html; charset=utf-8" => "text/html; charset=utf-8",
            "application/json" => "application/json",
            "text/css; charset=utf-8" => "text/css; charset=utf-8",
            "application/javascript; charset=utf-8" => "application/javascript; charset=utf-8",
            "image/svg+xml" => "image/svg+xml",
            _ => content_type_for_path(&file),
        };
        return Ok(Some((file, content_type)));
    }
    Ok(None)
}

/// Reads file.
fn read_file(path: &Path) -> Result<(Vec<u8>, u64), ()> {
    let mut file = File::open(path).map_err(|_| ())?;
    let length = file.metadata().map_err(|_| ())?.len();
    if length > MAX_STATIC_FILE_BYTES {
        return Err(());
    }
    file.seek(SeekFrom::Start(0)).map_err(|_| ())?;
    let mut body = Vec::with_capacity(length as usize);
    file.take(MAX_STATIC_FILE_BYTES + 1)
        .read_to_end(&mut body)
        .map_err(|_| ())?;
    if body.len() as u64 != length || body.len() as u64 > MAX_STATIC_FILE_BYTES {
        return Err(());
    }
    Ok((body, length))
}

/// Serves one request from one app artifact root without invoking a shell or C runtime.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::serve_artifact_request`].
/// - `method`: Input consumed by [`crate::artifact_server::serve_artifact_request`].
/// - `target`: Input consumed by [`crate::artifact_server::serve_artifact_request`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::artifact_server::serve_artifact_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::serve_artifact_request(std::path::Path::new("."), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn serve_artifact_request(root: &Path, method: &str, target: &str) -> StaticResponse {
    if !matches!(method, "GET" | "HEAD") {
        return text_error(405, "Method Not Allowed", "method not allowed\n");
    }
    if root.as_os_str().is_empty() || !root.is_dir() {
        return text_error(500, "Internal Server Error", "artifact root unavailable\n");
    }
    let normalized = match normalized_path(target) {
        Some(path) => path,
        None => return text_error(400, "Bad Request", "invalid request path\n"),
    };
    let asset = resolve_direct_asset(root, &normalized).ok().flatten();
    let route = if asset.is_none() {
        lookup_route_map(root, &normalized).ok().flatten()
    } else {
        None
    };
    let Some((file, content_type)) = asset.or(route) else {
        return text_error(404, "Not Found", "not found\n");
    };
    let (body, content_length) = match read_file(&file) {
        Ok(value) => value,
        Err(_) => return text_error(404, "Not Found", "not found\n"),
    };
    let body = if method == "HEAD" { Vec::new() } else { body };
    response(200, "OK", content_type, body, content_length)
}

/// Performs response bytes.
fn response_bytes(response: StaticResponse, method: &str) -> Vec<u8> {
    let mut headers = format!(
        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
        response.status_code, response.status_text, response.content_type, response.content_length,
    )
    .into_bytes();
    if method != "HEAD" {
        headers.extend_from_slice(&response.body);
    }
    headers
}

/// Handles request head.
fn request_head(
    stream: &mut std::net::TcpStream,
) -> Result<(String, String, Option<String>, Option<String>), ()> {
    let mut bytes = Vec::with_capacity(1024);
    let mut chunk = [0u8; 1024];
    loop {
        let read = stream.read(&mut chunk).map_err(|_| ())?;
        if read == 0 {
            return Err(());
        }
        bytes.extend_from_slice(&chunk[..read]);
        if bytes.windows(4).any(|window| window == b"\r\n\r\n")
            || bytes.windows(2).any(|window| window == b"\n\n")
        {
            let text = std::str::from_utf8(&bytes).map_err(|_| ())?;
            let mut lines = text.lines();
            let mut fields = lines.next().ok_or(())?.split_whitespace();
            let method = fields.next().ok_or(())?.to_owned();
            let target = fields.next().ok_or(())?.to_owned();
            if !matches!(fields.next(), Some(version) if version.starts_with("HTTP/")) {
                return Err(());
            }
            let mut range = None;
            let mut if_range = None;
            for line in lines.take(256) {
                let Some((name, value)) = line.split_once(':') else {
                    continue;
                };
                match name.trim().to_ascii_lowercase().as_str() {
                    "range" if range.is_none() => range = Some(value.trim().to_owned()),
                    "if-range" if if_range.is_none() => if_range = Some(value.trim().to_owned()),
                    _ => {}
                }
            }
            return Ok((method, target, range, if_range));
        }
        if bytes.len() > 16 * 1024 {
            return Err(());
        }
    }
}

/// Sends all.
fn send_all(stream: &mut std::net::TcpStream, bytes: &[u8]) -> Result<(), ()> {
    stream.write_all(bytes).map_err(|_| ())
}

/// Streams one selected response body to the standalone static server client.
fn send_stream(
    stream: &mut std::net::TcpStream,
    response: &StreamResponse,
    method: &str,
) -> Result<(), ()> {
    let content_range = if response.status_code == 206 {
        format!(
            "Content-Range: bytes {}-{}/{}\r\n",
            response.offset,
            response.offset + response.content_length.saturating_sub(1),
            response.complete_length
        )
    } else {
        String::new()
    };
    let headers = format!(
        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nAccept-Ranges: bytes\r\nETag: {}\r\nCache-Control: {}\r\nX-Content-Type-Options: nosniff\r\n{}{}Connection: close\r\n\r\n",
        response.status_code,
        response.status_text,
        response.content_type,
        response.content_length,
        response.etag,
        response.cache_control,
        content_range,
        response
            .content_disposition
            .as_ref()
            .map(|value| format!("Content-Disposition: {value}\r\n"))
            .unwrap_or_default(),
    );
    send_all(stream, headers.as_bytes())?;
    if method == "HEAD" {
        return Ok(());
    }
    let mut file = File::open(&response.file_path).map_err(|_| ())?;
    file.seek(SeekFrom::Start(response.offset))
        .map_err(|_| ())?;
    let mut remaining = response.content_length;
    let mut buffer = [0u8; 64 * 1024];
    while remaining > 0 {
        let count = usize::try_from(remaining.min(buffer.len() as u64)).map_err(|_| ())?;
        let read = file.read(&mut buffer[..count]).map_err(|_| ())?;
        if read == 0 {
            return Err(());
        }
        send_all(stream, &buffer[..read])?;
        remaining = remaining.saturating_sub(read as u64);
    }
    Ok(())
}

/// Handles client.
fn handle_client(stream: &mut std::net::TcpStream, root: &Path) -> Result<(), ()> {
    let (method, target, range, if_range) = match request_head(stream) {
        Ok(request) => request,
        Err(_) => {
            let bytes = response_bytes(text_error(400, "Bad Request", "bad request\n"), "GET");
            return send_all(stream, &bytes);
        }
    };
    match serve_streamable_asset(
        root,
        &method,
        &target,
        range.as_deref(),
        if_range.as_deref(),
    ) {
        Ok(Some(response)) => return send_stream(stream, &response, &method),
        Err(error) => {
            let mut bytes = response_bytes(error.response, &method);
            if let Some(length) = error.unsatisfied_length
                && let Some(separator) = bytes.windows(2).position(|window| window == b"\r\n")
            {
                let header = format!("Content-Range: bytes */{length}\r\nAccept-Ranges: bytes\r\n");
                bytes.splice(separator + 2..separator + 2, header.bytes());
            }
            return send_all(stream, &bytes);
        }
        Ok(None) => {}
    }
    let response = serve_artifact_request(root, &method, &target);
    let bytes = response_bytes(response, &method);
    send_all(stream, &bytes)
}

/// Runs the bounded loopback static-server binary for one packaged artifact.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::artifact_server::run`].
/// - `port`: Input consumed by [`crate::artifact_server::run`].
/// - `max_requests`: Input consumed by [`crate::artifact_server::run`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::artifact_server::run`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::artifact_server::run`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_static::artifact_server::run(std::path::Path::new("."), "8080", todo!());
/// ```
///
/// # Related
///
/// - [`crate::artifact_server`] for adjacent helpers that share the same runtime surface.
pub fn run(root: &Path, port: u16, max_requests: usize) -> i32 {
    if root.as_os_str().is_empty() || !root.is_dir() || port == 0 || max_requests == 0 {
        return 64;
    }
    let listener = match std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, port)) {
        Ok(listener) => listener,
        Err(_) => return 70,
    };
    for _ in 0..max_requests {
        let (mut stream, _) = match listener.accept() {
            Ok(connection) => connection,
            Err(_) => return 71,
        };
        if handle_client(&mut stream, root).is_err() {
            return 72;
        }
    }
    0
}

#[cfg(test)]
mod tests {
    use super::{lookup_route_map, serve_private_asset, serve_streamable_asset};

    /// Serves configured external media while retaining bundled assets and rejecting symlink escapes.
    #[test]
    fn configured_media_root_separates_media_from_models() {
        let root = root("configured-media");
        let app = root.join("app");
        let media = root.join("uploads");
        let models = root.join("models");
        std::fs::create_dir_all(app.join("media")).unwrap();
        std::fs::create_dir_all(&media).unwrap();
        std::fs::create_dir_all(&models).unwrap();
        std::fs::write(
            app.join("app.conf"),
            format!("MEDIA_ROOT={}\n", media.display()),
        )
        .unwrap();
        std::fs::write(media.join("uploaded.png"), b"upload").unwrap();
        std::fs::write(app.join("media/bundled.png"), b"bundled").unwrap();
        std::fs::write(models.join("private.bin"), b"model").unwrap();
        assert_eq!(
            super::resolve_direct_asset(&app, "/media/uploaded.png")
                .unwrap()
                .unwrap()
                .0,
            media.join("uploaded.png").canonicalize().unwrap()
        );
        assert!(
            super::resolve_direct_asset(&app, "/media/bundled.png")
                .unwrap()
                .is_some()
        );
        assert!(
            super::resolve_direct_asset(&app, "/media/private.bin")
                .ok()
                .flatten()
                .is_none()
        );
        assert!(super::resolve_direct_asset(&app, "/media/../models/private.bin").is_err());
        #[cfg(unix)]
        {
            std::os::unix::fs::symlink(models.join("private.bin"), media.join("escape.bin"))
                .unwrap();
            assert!(
                super::resolve_direct_asset(&app, "/media/escape.bin")
                    .ok()
                    .flatten()
                    .is_none()
            );
        }
        std::fs::create_dir_all(media.join("attachments")).unwrap();
        std::fs::write(media.join("attachments/private.bin"), b"private context").unwrap();
        assert!(super::resolve_direct_asset(&app, "/media/attachments/private.bin").is_err());
        std::fs::remove_dir_all(root).unwrap();
    }

    /// Creates one unique temporary artifact root.
    fn root(label: &str) -> std::path::PathBuf {
        let nonce = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        std::env::temp_dir().join(format!(
            "pharos-static-{label}-{}-{nonce}",
            std::process::id()
        ))
    }

    #[test]
    /// Performs audio ranges select exact file slices.
    fn audio_ranges_select_exact_file_slices() {
        let root = root("range");
        let media = root.join("media");
        std::fs::create_dir_all(&media).expect("media");
        std::fs::write(media.join("preview-a1b2c3d4.mp3"), b"0123456789").expect("asset");
        let partial = serve_streamable_asset(
            &root,
            "GET",
            "/media/preview-a1b2c3d4.mp3",
            Some("bytes=2-5"),
            None,
        )
        .expect("selection")
        .expect("asset");
        assert_eq!(partial.status_code, 206);
        assert_eq!(partial.offset, 2);
        assert_eq!(partial.content_length, 4);
        assert_eq!(partial.complete_length, 10);
        assert_eq!(partial.content_type, "audio/mpeg");
        assert!(partial.cache_control.contains("immutable"));

        let suffix = serve_streamable_asset(
            &root,
            "GET",
            "/media/preview-a1b2c3d4.mp3",
            Some("bytes=-3"),
            None,
        )
        .expect("selection")
        .expect("asset");
        assert_eq!((suffix.offset, suffix.content_length), (7, 3));
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs invalid ranges fail and if range mismatch returns complete body.
    fn invalid_ranges_fail_and_if_range_mismatch_returns_complete_body() {
        let root = root("if-range");
        let media = root.join("media");
        std::fs::create_dir_all(&media).expect("media");
        std::fs::write(media.join("preview.ogg"), b"0123456789").expect("asset");
        let error = serve_streamable_asset(
            &root,
            "GET",
            "/media/preview.ogg",
            Some("bytes=40-50"),
            None,
        )
        .expect_err("unsatisfied");
        assert_eq!(error.response.status_code, 416);
        assert_eq!(error.unsatisfied_length, Some(10));

        let complete = serve_streamable_asset(
            &root,
            "GET",
            "/media/preview.ogg",
            Some("bytes=2-5"),
            Some("\"stale-validator\""),
        )
        .expect("selection")
        .expect("asset");
        assert_eq!(complete.status_code, 200);
        assert_eq!((complete.offset, complete.content_length), (0, 10));
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs private assets are no store attachments and cannot escape.
    fn private_assets_are_no_store_attachments_and_cannot_escape() {
        let root = root("private");
        let private = root.join("private/downloads");
        std::fs::create_dir_all(&private).expect("private");
        std::fs::write(private.join("pack.zip"), b"zip-body").expect("asset");
        let response = serve_private_asset(
            &root,
            "private/downloads",
            "pack.zip",
            "GET",
            Some("bytes=0-2"),
            None,
        )
        .expect("private selection");
        assert_eq!(response.status_code, 206);
        assert_eq!(response.content_type, "application/zip");
        assert_eq!(response.cache_control, "private, no-store");
        assert_eq!(
            response.content_disposition.as_deref(),
            Some("attachment; filename=\"pack.zip\"")
        );
        assert!(
            serve_private_asset(&root, "private/downloads", "../pack.zip", "GET", None, None,)
                .is_err()
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Matches declared directory routes using the same normalization as requests.
    fn route_map_lookup_normalizes_declared_directory_paths() {
        let root = root("directory-route-map");
        std::fs::create_dir_all(&root).expect("artifact root");
        std::fs::write(root.join("about.html"), "about").expect("artifact");
        std::fs::write(
            root.join("runtime-route-map.tsv"),
            "GET\t/about/\tabout.html\ttext/html; charset=utf-8\t200\n",
        )
        .expect("route map");
        for path in ["/about/", "/about", "/about/?review=1"] {
            assert!(lookup_route_map(&root, path).expect("lookup").is_some());
        }
        assert!(lookup_route_map(&root, "/../about/").is_err());
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Resolves route-map entries even when the matching path appears after many earlier rows.
    fn route_map_lookup_scans_beyond_four_thousand_entries() {
        let root = root("route-map");
        let pages = root.join("reference");
        std::fs::create_dir_all(&pages).expect("reference dir");
        std::fs::write(
            pages.join("library-reference.html"),
            "<html><body>library</body></html>",
        )
        .expect("artifact");
        let mut route_map = String::new();
        for index in 0..5000 {
            route_map.push_str(&format!(
                "GET\t/filler/{index}.html\tfiller/{index}.html\ttext/html; charset=utf-8\t200\n"
            ));
        }
        route_map.push_str(
            "GET\t/reference/library-reference.html\treference/library-reference.html\ttext/html; charset=utf-8\t200\n",
        );
        std::fs::write(root.join("runtime-route-map.tsv"), route_map).expect("route map");
        let resolved = lookup_route_map(&root, "/reference/library-reference.html")
            .expect("lookup")
            .expect("resolved");
        assert_eq!(resolved.1, "text/html; charset=utf-8");
        assert_eq!(
            resolved.0.file_name().and_then(|name| name.to_str()),
            Some("library-reference.html")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }
    /// Keeps direct preview font responses consistent with packaged route-map font declarations.
    #[test]
    fn direct_font_assets_use_font_media_types() {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../..")
            .join("tmp/0.8.4-testing")
            .join(format!("pharos-font-assets-{}", std::process::id()));
        std::fs::create_dir_all(root.join("static/fonts")).unwrap();
        let bytes = b"wOF2 local font test input";
        std::fs::write(root.join("static/fonts/icons.woff2"), bytes).unwrap();
        let response = super::serve_artifact_request(&root, "GET", "/static/fonts/icons.woff2");
        assert_eq!(response.status_code, 200);
        assert_eq!(response.content_type, "font/woff2");
        assert_eq!(response.body, bytes);
        std::fs::remove_dir_all(root).unwrap();
    }
}