pharos_runtime_core/

http.rs

/// Maximum accepted size of the full HTTP request head.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::http::PHAROS_HTTP_MAX_HEADER_BYTES;
/// ```
///
/// # Related
///
/// - [`crate::http`] for the surrounding module surface.
pub const PHAROS_HTTP_MAX_HEADER_BYTES: usize = 64 * 1024;
/// Maximum accepted size of the request line.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::http::PHAROS_HTTP_MAX_REQUEST_LINE_BYTES;
/// ```
///
/// # Related
///
/// - [`crate::http`] for the surrounding module surface.
pub const PHAROS_HTTP_MAX_REQUEST_LINE_BYTES: usize = 8 * 1024;
/// Maximum accepted size of any single HTTP header line.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::http::PHAROS_HTTP_MAX_HEADER_LINE_BYTES;
/// ```
///
/// # Related
///
/// - [`crate::http`] for the surrounding module surface.
pub const PHAROS_HTTP_MAX_HEADER_LINE_BYTES: usize = 16 * 1024;
/// Maximum accepted size of a non-multipart request body.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::http::PHAROS_HTTP_MAX_BODY_BYTES;
/// ```
///
/// # Related
///
/// - [`crate::http`] for the surrounding module surface.
pub const PHAROS_HTTP_MAX_BODY_BYTES: usize = 1024 * 1024;
/// Maximum accepted size of a multipart request body.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::http::PHAROS_HTTP_MAX_MULTIPART_BODY_BYTES;
/// ```
///
/// # Related
///
/// - [`crate::http`] for the surrounding module surface.
pub const PHAROS_HTTP_MAX_MULTIPART_BODY_BYTES: usize = 16 * 1024 * 1024;

/// Returns the current wall-clock time in microseconds since the Unix epoch.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::win_gettimeofday`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::win_gettimeofday();
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn win_gettimeofday() -> i64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|value| value.as_micros() as i64)
        .unwrap_or(0)
}

use std::fs::File;
use std::io::Write;
use std::net::IpAddr;
use std::path::Path;
use std::time::{SystemTime, UNIX_EPOCH};

/// Returns whether sensitive header name.
fn is_sensitive_header_name(name: &str) -> bool {
    matches!(
        &name.to_ascii_lowercase()[..],
        "authorization" | "cookie" | "set-cookie" | "x-api-key" | "x-pharos-admin-secret"
    )
}

#[derive(Debug, Clone, Default, Eq, PartialEq)]
/// Owned HTTP request data used by the runtime after parsing and body capture.
///
/// # Fields
///
/// - `method`: Stored field on `HttpRequest`.
/// - `target`: Stored field on `HttpRequest`.
/// - `cookie`: Stored field on `HttpRequest`.
/// - `content_type`: Stored field on `HttpRequest`.
/// - `headers`: Stored field on `HttpRequest`.
/// - `body`: Stored field on `HttpRequest`.
/// - `body_file_path`: Stored field on `HttpRequest`.
/// - `body_len`: Stored field on `HttpRequest`.
/// - `is_multipart`: Stored field on `HttpRequest`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::http::HttpRequest>();
/// ```
///
/// # Related
///
/// - [`crate::http`] for constructors, helpers, and neighboring runtime types.
pub struct HttpRequest {
    pub method: String,
    pub target: String,
    pub cookie: Option<String>,
    pub content_type: Option<String>,
    pub headers: String,
    pub body: Vec<u8>,
    pub body_file_path: Option<String>,
    pub body_len: usize,
    pub is_multipart: bool,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Minimal parsed request head returned by [`parse_http_request`].
///
/// # Fields
///
/// - `method`: Stored field on `ParsedHttpRequest`.
/// - `target`: Stored field on `ParsedHttpRequest`.
/// - `headers`: Stored field on `ParsedHttpRequest`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::http::ParsedHttpRequest>();
/// ```
///
/// # Related
///
/// - [`crate::http`] for constructors, helpers, and neighboring runtime types.
pub struct ParsedHttpRequest {
    pub method: String,
    pub target: String,
    pub headers: Vec<(String, String)>,
}
/// Releases owned request buffers and removes any temporary body file.
///
/// # Parameters
///
/// - `request`: Input consumed by [`crate::http::free_http_request`].
///
/// # Returns
///
/// Returns after [`crate::http::free_http_request`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::free_http_request(todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn free_http_request(request: &mut HttpRequest) {
    if let Some(path) = request.body_file_path.take() {
        let _ = std::fs::remove_file(path);
    }
    *request = HttpRequest::default();
}

/// Parses the content length value.
fn content_length_value(value: &str) -> Option<i64> {
    let trimmed = value.trim();
    if trimmed.is_empty() || !trimmed.bytes().all(|byte| byte.is_ascii_digit()) {
        return None;
    }
    trimmed.parse::<u64>().ok()?.try_into().ok()
}
/// Returns whether a `Transfer-Encoding` header includes `chunked`.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::http::contains_chunked_transfer`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::http::contains_chunked_transfer`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::contains_chunked_transfer`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::contains_chunked_transfer("value");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn contains_chunked_transfer(value: &str) -> bool {
    value
        .split(',')
        .any(|token| token.trim().eq_ignore_ascii_case("chunked"))
}

/// Parses a decimal `Content-Length` header using the runtime's non-negative bounds.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::http::parse_content_length_header`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::http::parse_content_length_header`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::http::parse_content_length_header`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::parse_content_length_header`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::parse_content_length_header("value");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn parse_content_length_header(value: &str) -> Result<i64, i32> {
    let trimmed = value.trim();
    if trimmed.is_empty() || !trimmed.bytes().all(|byte| byte.is_ascii_digit()) {
        return Err(400);
    }
    trimmed
        .parse::<u64>()
        .ok()
        .and_then(|value| i64::try_from(value).ok())
        .ok_or(400)
}

/// Writes one bounded body chunk, retrying short writes without invoking external code.
///
/// # Parameters
///
/// - `file`: Input consumed by [`crate::http::write_temp_body_chunk`].
/// - `data`: Input consumed by [`crate::http::write_temp_body_chunk`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::write_temp_body_chunk`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::write_temp_body_chunk(todo!(), b"");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn write_temp_body_chunk(file: &mut File, data: &[u8]) -> i32 {
    let mut written = 0usize;
    while written < data.len() {
        match file.write(&data[written..]) {
            Ok(0) | Err(_) => return 69,
            Ok(count) => written += count,
        }
    }
    0
}

/// Returns the MIME type permitted for a static artifact path.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::http::mime_type_for_path`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::mime_type_for_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::mime_type_for_path(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn mime_type_for_path(path: &Path) -> &'static str {
    match path
        .extension()
        .and_then(|value| value.to_str())
        .map(str::to_ascii_lowercase)
        .as_deref()
    {
        Some("html") | Some("htm") => "text/html; charset=utf-8",
        Some("json") => "application/json",
        Some("css") => "text/css; charset=utf-8",
        Some("js") => "application/javascript; charset=utf-8",
        Some("svg") => "image/svg+xml",
        Some("png") => "image/png",
        Some("jpg") | Some("jpeg") => "image/jpeg",
        _ => "application/octet-stream",
    }
}
/// Returns the canonical status line text used by the runtime for a bounded set of statuses.
///
/// # Parameters
///
/// - `status_code`: Input consumed by [`crate::http::http_status_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::http_status_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::http_status_text(400);
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn http_status_text(status_code: u16) -> &'static str {
    match status_code {
        200 => "200 OK",
        302 => "302 Found",
        400 => "400 Bad Request",
        401 => "401 Unauthorized",
        403 => "403 Forbidden",
        404 => "404 Not Found",
        405 => "405 Method Not Allowed",
        409 => "409 Conflict",
        413 => "413 Payload Too Large",
        424 => "424 Failed Dependency",
        429 => "429 Too Many Requests",
        502 => "502 Bad Gateway",
        500 => "500 Internal Server Error",
        503 => "503 Service Unavailable",
        504 => "504 Gateway Timeout",
        _ => "500 Internal Server Error",
    }
}

/// Removes query and fragment data from a request target.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::http::request_path_without_query`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::request_path_without_query`] 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::http::request_path_without_query`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::request_path_without_query("/");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn request_path_without_query(target: &str) -> Option<String> {
    let path = target.split('?').next()?.split('#').next()?.trim();
    (!path.is_empty()
        && path.starts_with('/')
        && !path.bytes().any(|byte| byte < 0x20 || byte == 0x7f))
    .then(|| path.to_owned())
}

/// Applies the bounded set of request headers consumed by the runtime.
///
/// # Parameters
///
/// - `request`: Input consumed by [`crate::http::apply_known_header`].
/// - `header_name`: Input consumed by [`crate::http::apply_known_header`].
/// - `header_value`: Input consumed by [`crate::http::apply_known_header`].
/// - `content_length`: Input consumed by [`crate::http::apply_known_header`].
/// - `chunked_transfer`: Input consumed by [`crate::http::apply_known_header`].
///
/// # Returns
///
/// Returns after [`crate::http::apply_known_header`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::apply_known_header(todo!(), "content-type", "application/json", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn apply_known_header(
    request: &mut HttpRequest,
    header_name: &str,
    header_value: &str,
    content_length: &mut i64,
    chunked_transfer: &mut bool,
) {
    match header_name.to_ascii_lowercase().as_str() {
        "content-length" => {
            *content_length = content_length_value(header_value).unwrap_or(-1);
        }
        "content-type" => request.content_type = Some(header_value.trim().to_owned()),
        "cookie" => request.cookie = Some(header_value.trim().to_owned()),
        "transfer-encoding" if contains_chunked_transfer(header_value) => {
            *chunked_transfer = true;
        }
        _ => {}
    }
}

/// Parses a bounded HTTP request head without accepting folded or malformed headers.
///
/// # Parameters
///
/// - `bytes`: Input consumed by [`crate::http::parse_http_request`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::http::parse_http_request`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::http::parse_http_request`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::parse_http_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::parse_http_request(b"");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn parse_http_request(bytes: &[u8]) -> Result<ParsedHttpRequest, &'static str> {
    if bytes.is_empty() || bytes.len() > PHAROS_HTTP_MAX_HEADER_BYTES {
        return Err("HTTP header block exceeds its limit");
    }
    let text = std::str::from_utf8(bytes).map_err(|_| "HTTP header block is not UTF-8")?;
    let mut lines = text.split("\r\n");
    let request_line = lines.next().ok_or("HTTP request line is missing")?;
    let mut fields = request_line.split_whitespace();
    let method = fields.next().ok_or("HTTP method is missing")?;
    let target = fields.next().ok_or("HTTP target is missing")?;
    let version = fields.next().ok_or("HTTP version is missing")?;
    if !matches!(version, "HTTP/1.0" | "HTTP/1.1")
        || fields.next().is_some()
        || !matches!(
            method,
            "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS"
        )
        || method.len() > 16
        || target.len() > PHAROS_HTTP_MAX_REQUEST_LINE_BYTES
        || !target.starts_with('/')
        || target
            .bytes()
            .any(|byte| byte < 0x20 || byte == 0x7f || byte == b'\\')
    {
        return Err("HTTP request line is invalid");
    }
    let mut headers = Vec::new();
    for line in lines {
        if line.is_empty() {
            break;
        }
        if line.len() > PHAROS_HTTP_MAX_HEADER_LINE_BYTES {
            return Err("HTTP header line exceeds its limit");
        }
        let (name, value) = line.split_once(':').ok_or("HTTP header is malformed")?;
        if name.is_empty()
            || name
                .bytes()
                .any(|byte| !byte.is_ascii_alphanumeric() && !matches!(byte, b'-'))
        {
            return Err("HTTP header name is invalid");
        }
        headers.push((name.to_ascii_lowercase(), value.trim().to_owned()));
        if headers.len() > 256 {
            return Err("HTTP header count exceeds its limit");
        }
    }
    Ok(ParsedHttpRequest {
        method: method.to_owned(),
        target: target.to_owned(),
        headers,
    })
}

/// Extracts a response status code from an HTTP status line.
///
/// # Parameters
///
/// - `response`: Input consumed by [`crate::http::http_status_code_from_response`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::http_status_code_from_response`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::http_status_code_from_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::http_status_code_from_response(todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn http_status_code_from_response(response: &str) -> u16 {
    response
        .lines()
        .next()
        .and_then(|line| line.split_whitespace().nth(1))
        .and_then(|value| value.parse::<u16>().ok())
        .unwrap_or(0)
}

/// Returns the complete first status line from an HTTP response.
///
/// # Parameters
///
/// - `response`: Input consumed by [`crate::http::http_status_line_from_response`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::http_status_line_from_response`] 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::http::http_status_line_from_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::http_status_line_from_response(todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn http_status_line_from_response(response: &str) -> Option<String> {
    let line = response.lines().next()?.trim();
    (line.starts_with("HTTP/") && http_status_code_from_response(response) != 0)
        .then(|| line.to_owned())
}

/// Performs sensitive headers mask.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::http::sensitive_headers_mask`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::sensitive_headers_mask`] 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::http::sensitive_headers_mask`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::sensitive_headers_mask("host: example");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn sensitive_headers_mask(headers: &str) -> Option<String> {
    if headers.is_empty() {
        return Some(String::new());
    }
    let mut out = String::new();
    for raw_line in headers.lines() {
        let line = raw_line.trim();
        if let Some((name_raw, value_raw)) = line.split_once(':') {
            let name = name_raw.trim();
            let value = value_raw.trim();
            if is_sensitive_header_name(name) {
                let prefix_len = value.len().min(4);
                out.push_str(name);
                out.push_str(": [REDACTED: ");
                out.push_str(&value[..prefix_len]);
                out.push_str("]\n");
            } else {
                out.push_str(name_raw);
                out.push(':');
                out.push_str(value_raw);
                out.push('\n');
            }
        } else {
            out.push_str(line);
            out.push('\n');
        }
    }
    Some(out)
}

/// Compares two configured log levels without accepting empty values.
///
/// # Parameters
///
/// - `level`: Input consumed by [`crate::http::log_level_matches`].
/// - `target`: Input consumed by [`crate::http::log_level_matches`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::http::log_level_matches`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::log_level_matches("info", "/");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn log_level_matches(level: &str, target: &str) -> bool {
    !level.is_empty() && !target.is_empty() && level.eq_ignore_ascii_case(target)
}

/// Compacts one log line while preserving bounded UTF-8 text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::http::compact_log_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::compact_log_text`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::compact_log_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::compact_log_text("{}");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn compact_log_text(text: &str) -> String {
    text.lines()
        .map(str::trim)
        .filter(|line| !line.is_empty())
        .collect::<Vec<_>>()
        .join(" ")
        .chars()
        .take(16 * 1024)
        .collect()
}

/// Returns a stable UTC-like access timestamp in seconds.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::access_timestamp`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::access_timestamp();
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn access_timestamp() -> String {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|value| value.as_secs().to_string())
        .unwrap_or_else(|_| "0".to_owned())
}

/// Closes an optional log file explicitly.
///
/// # Parameters
///
/// - `file`: Input consumed by [`crate::http::close_logged_file`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::http::close_logged_file`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::close_logged_file(todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn close_logged_file(file: Option<File>) -> bool {
    drop(file);
    true
}

/// Resolves the configured error report path, restricting relative paths to the app root.
///
/// # Parameters
///
/// - `app_id`: Input consumed by [`crate::http::resolved_error_report_path`].
/// - `configured_path`: Input consumed by [`crate::http::resolved_error_report_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::resolved_error_report_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::http::resolved_error_report_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::resolved_error_report_path(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn resolved_error_report_path(
    app_id: Option<&str>,
    configured_path: Option<&Path>,
) -> Option<String> {
    let app_id = app_id.filter(|value| !value.is_empty()).unwrap_or("app");
    if app_id
        .bytes()
        .any(|byte| !byte.is_ascii_alphanumeric() && byte != b'_' && byte != b'-')
    {
        return None;
    }
    let path = configured_path
        .filter(|path| !path.as_os_str().is_empty())
        .map(Path::to_path_buf)
        .unwrap_or_else(|| Path::new("/tmp/pharos").join(format!("{app_id}.error.jsonl")));
    if path.as_os_str().to_string_lossy().contains("..") {
        return None;
    }
    Some(path.to_string_lossy().into_owned())
}

/// Writes one structured error report as an append-only JSONL record.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::http::write_error_report`].
/// - `report`: Input consumed by [`crate::http::write_error_report`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::write_error_report`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::write_error_report(std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn write_error_report(path: &Path, report: &serde_json::Value) -> i32 {
    let Some(parent) = path.parent() else {
        return 69;
    };
    if std::fs::create_dir_all(parent).is_err() {
        return 69;
    }
    let Ok(text) = serde_json::to_string(report) else {
        return 75;
    };
    let record = format!("{text}\n");
    crate::fs::append_file_within(
        parent,
        path,
        record.as_bytes(),
        crate::fs::PRIVATE_FILE_MODE,
    )
    .map(|_| 0)
    .unwrap_or(69)
}

/// Returns the first forwarded client address when it is a valid IP literal.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::http::extract_forwarded_ip`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::extract_forwarded_ip`] 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::http::extract_forwarded_ip`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::extract_forwarded_ip("value");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn extract_forwarded_ip(value: &str) -> Option<String> {
    value.split(',').map(str::trim).find_map(|candidate| {
        candidate
            .parse::<IpAddr>()
            .ok()
            .map(|_| candidate.to_owned())
    })
}

/// Extracts an address from peer information without trusting arbitrary text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::http::extract_ip_from_peer_info`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::extract_ip_from_peer_info`] 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::http::extract_ip_from_peer_info`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::extract_ip_from_peer_info("value");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn extract_ip_from_peer_info(value: &str) -> Option<String> {
    value.split([' ', '\t', '\n', ':']).find_map(|candidate| {
        candidate
            .parse::<IpAddr>()
            .ok()
            .map(|_| candidate.to_owned())
    })
}

/// Selects the real client IP from trusted forwarded headers or peer data.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::http::extract_real_ip_from_headers`].
/// - `peer_info`: Input consumed by [`crate::http::extract_real_ip_from_headers`].
/// - `trusted_proxy`: Input consumed by [`crate::http::extract_real_ip_from_headers`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::extract_real_ip_from_headers`] 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::http::extract_real_ip_from_headers`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::extract_real_ip_from_headers("host: example", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn extract_real_ip_from_headers(
    headers: &str,
    peer_info: Option<&str>,
    trusted_proxy: bool,
) -> Option<String> {
    if trusted_proxy
        && let Some(value) = headers
            .lines()
            .find_map(|line| {
                let (name, value) = line.split_once(':')?;
                name.trim()
                    .eq_ignore_ascii_case("x-forwarded-for")
                    .then_some(value.trim())
            })
            .and_then(extract_forwarded_ip)
    {
        return Some(value);
    }
    peer_info.and_then(extract_ip_from_peer_info)
}

/// Checks whether a direct peer address belongs to one of the configured CIDRs.
///
/// # Parameters
///
/// - `peer_ip`: Input consumed by [`crate::http::is_trusted_proxy`].
/// - `trusted_proxy_cidrs`: Input consumed by [`crate::http::is_trusted_proxy`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::http::is_trusted_proxy`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::http::is_trusted_proxy`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::is_trusted_proxy("127.0.0.1", "127.0.0.1/32");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn is_trusted_proxy(peer_ip: &str, trusted_proxy_cidrs: &str) -> bool {
    let Ok(peer) = peer_ip.parse::<IpAddr>() else {
        return false;
    };
    trusted_proxy_cidrs
        .split(',')
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .any(|cidr| {
            let Some((network, bits)) = cidr.split_once('/') else {
                return false;
            };
            let Ok(network) = network.parse::<IpAddr>() else {
                return false;
            };
            let Ok(bits) = bits.parse::<u8>() else {
                return false;
            };
            match (peer, network) {
                (IpAddr::V4(peer), IpAddr::V4(network)) if bits <= 32 => {
                    let mask = if bits == 0 {
                        0
                    } else {
                        u32::MAX << (32 - bits)
                    };
                    u32::from(peer) & mask == u32::from(network) & mask
                }
                (IpAddr::V6(peer), IpAddr::V6(network)) if bits <= 128 => {
                    let peer = u128::from_be_bytes(peer.octets());
                    let network = u128::from_be_bytes(network.octets());
                    let mask = if bits == 0 {
                        0
                    } else {
                        u128::MAX << (128 - bits)
                    };
                    peer & mask == network & mask
                }
                _ => false,
            }
        })
}

/// Returns a client address selected from the request's trusted proxy context.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::http::request_real_ip`].
/// - `peer_info`: Input consumed by [`crate::http::request_real_ip`].
/// - `trusted_proxy_cidrs`: Input consumed by [`crate::http::request_real_ip`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::request_real_ip`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::request_real_ip("host: example", todo!(), "127.0.0.1/32");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn request_real_ip(
    headers: &str,
    peer_info: Option<&str>,
    trusted_proxy_cidrs: Option<&str>,
) -> Option<String> {
    let peer = peer_info.and_then(extract_ip_from_peer_info)?;
    let trusted = trusted_proxy_cidrs.is_some_and(|cidrs| is_trusted_proxy(&peer, cidrs));
    extract_real_ip_from_headers(headers, Some(&peer), trusted)
}

/// Redacts sensitive request headers before they enter an access log.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::http::sensitive_headers_redact`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::sensitive_headers_redact`] 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::http::sensitive_headers_redact`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::sensitive_headers_redact("host: example");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn sensitive_headers_redact(headers: &str) -> Option<String> {
    let mut result = String::new();
    for line in headers.lines() {
        let Some((name, value)) = line.split_once(':') else {
            result.push_str(line);
            result.push('\n');
            continue;
        };
        result.push_str(name.trim());
        result.push_str(": ");
        if is_sensitive_header_name(name.trim()) {
            result.push_str("[REDACTED]");
        } else {
            result.push_str(value.trim());
        }
        result.push('\n');
    }
    Some(result)
}

/// Returns request headers with a validated client-address line appended.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::http::request_headers_with_client_ip`].
/// - `client_ip`: Input consumed by [`crate::http::request_headers_with_client_ip`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::request_headers_with_client_ip`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::request_headers_with_client_ip("host: example", todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn request_headers_with_client_ip(headers: &str, client_ip: Option<&str>) -> String {
    let mut output = headers.to_owned();
    if let Some(client_ip) = client_ip.filter(|value| value.parse::<IpAddr>().is_ok()) {
        if !output.is_empty() && !output.ends_with('\n') {
            output.push('\n');
        }
        output.push_str("X-Client-IP: ");
        output.push_str(client_ip);
        output.push('\n');
    }
    output
}

/// Parses an IPv4 address into its network-order integer representation.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::http::parse_ip_to_uint32`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::http::parse_ip_to_uint32`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::parse_ip_to_uint32("value");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn parse_ip_to_uint32(value: &str) -> Option<u32> {
    match value.parse::<std::net::Ipv4Addr>() {
        Ok(value) => Some(u32::from(value)),
        Err(_) => None,
    }
}

/// Builds a text response wire representation with a bounded body.
///
/// # Parameters
///
/// - `status`: Input consumed by [`crate::http::send_text_response`].
/// - `status_text`: Input consumed by [`crate::http::send_text_response`].
/// - `body`: Input consumed by [`crate::http::send_text_response`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::http::send_text_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::send_text_response(400, "400 Bad Request", b"");
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn send_text_response(status: u16, status_text: &str, body: &str) -> String {
    let body = body
        .as_bytes()
        .get(..body.len().min(PHAROS_HTTP_MAX_BODY_BYTES))
        .and_then(|bytes| std::str::from_utf8(bytes).ok())
        .unwrap_or("");
    format!(
        "HTTP/1.1 {status} {}\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
        if status_text.is_empty() {
            http_status_text(status)
        } else {
            status_text
        },
        body.len()
    )
}

/// Appends a formatted text fragment to a bounded connection response buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::http::connection_printf`].
/// - `fragment`: Input consumed by [`crate::http::connection_printf`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::http::connection_printf`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::http::connection_printf(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::http`] for adjacent helpers that share the same runtime surface.
pub fn connection_printf(output: &mut String, fragment: &str) -> bool {
    if output.len().saturating_add(fragment.len()) > 16 * 1024 * 1024 {
        return false;
    }
    output.push_str(fragment);
    true
}

#[cfg(test)]
mod parser_tests {
    use super::parse_http_request;

    /// Exercises a deterministic malformed corpus against the only active request-head parser.
    #[test]
    fn hostile_request_corpus_fails_closed() {
        let malformed = [
            b"".as_slice(),
            b"TRACE / HTTP/1.1\r\n\r\n".as_slice(),
            b"GET relative HTTP/1.1\r\n\r\n".as_slice(),
            b"GET /\\escape HTTP/1.1\r\n\r\n".as_slice(),
            b"GET / HTTP/9.9\r\n\r\n".as_slice(),
            b"GET / HTTP/1.1 extra\r\n\r\n".as_slice(),
            b"GET / HTTP/1.1\r\n folded: value\r\n\r\n".as_slice(),
            b"GET / HTTP/1.1\r\nBad Header: value\r\n\r\n".as_slice(),
            b"GET / HTTP/1.1\r\nMissing-Colon\r\n\r\n".as_slice(),
        ];
        for request in malformed {
            assert!(parse_http_request(request).is_err(), "accepted {request:?}");
        }
        assert!(
            parse_http_request(b"GET /ready?probe=1 HTTP/1.1\r\nHost: localhost\r\n\r\n").is_ok()
        );
    }

    /// Allows browser return requests with larger cookie headers while retaining bounded parsing.
    #[test]
    fn browser_return_request_accepts_large_cookie_header() {
        let cookie_value = "s".repeat(12 * 1024);
        let request = format!(
            "GET /ucal/appointments/?session_id=cs_test_return HTTP/1.1\r\nHost: 127.0.0.1:8084\r\nCookie: pharos_session={cookie_value}\r\n\r\n"
        );
        let parsed = parse_http_request(request.as_bytes()).expect("large browser return header");
        assert_eq!(parsed.method, "GET");
        assert_eq!(
            parsed.target,
            "/ucal/appointments/?session_id=cs_test_return"
        );
        assert!(
            parsed
                .headers
                .iter()
                .any(|(name, value)| name == "cookie" && value.len() > 12_000)
        );
    }
}