pharos_native/runtime/

runtime_reports.rs

//! Bounded JSON report builders for runtime and app operations.

use std::path::Path;

use serde_json::{Map, Value};

use crate::config::AppRuntime;

use super::RuntimeStack;

/// Performs app summary.
fn app_summary(app: &AppRuntime) -> Value {
    let backend = app
        .app_root
        .as_deref()
        .filter(|value| !value.is_empty())
        .and_then(|app_root| {
            super::database::dynamic_relational_backend(
                Path::new(app_root),
                app.runtime_conf_path.as_deref().map(Path::new),
            )
        })
        .unwrap_or_else(|| "sqlite".to_owned());
    let db_ready = super::database::runtime_database_ready(app).unwrap_or(false);
    serde_json::json!({
        "app_id": app.app_id.as_deref().unwrap_or_default(),
        "mount_path": app.base_path.as_deref().unwrap_or_default(),
        "app_root": app.app_root.as_deref().unwrap_or_default(),
        "build_dir": app.build_dir.as_deref().unwrap_or_default(),
        "state_path": app.state_path.as_deref().unwrap_or_default(),
        "log_path": app.log_path.as_deref().unwrap_or_default(),
        "log_format": app.log_format.as_deref().unwrap_or("service"),
        "error_report_path": app.error_report_path.as_deref().unwrap_or_default(),
        "log_level": app.log_level.as_deref().unwrap_or("WARN"),
        "host_profile": app.host_profile.as_deref().unwrap_or_default(),
        "runtime_conf_path": app.runtime_conf_path.as_deref().unwrap_or_default(),
        "backend": {
            "db_backend": backend,
            "db_ready": db_ready,
        },
    })
}

/// Builds the native runtime build report.
///
/// # Parameters
///
/// - `target_id`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_build_report_json`].
/// - `conf_path`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_build_report_json`].
/// - `apps_dir`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_build_report_json`].
/// - `app_count`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_build_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_runtime_build_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_runtime_build_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_runtime_build_report_json("dev_docs", std::path::Path::new("app.conf"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_runtime_build_report_json(
    target_id: &str,
    conf_path: Option<&str>,
    apps_dir: &str,
    app_count: usize,
) -> Result<String, &'static str> {
    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-runtime-build-v1",
        "target_kind": "runtime",
        "target_id": target_id,
        "status": "built",
        "app_count": app_count,
        "config_path": conf_path.unwrap_or_default(),
        "apps_dir": apps_dir,
    }))
    .map_err(|_| "runtime report encoding failed")
}

/// Builds the native app runtime report.
///
/// # Parameters
///
/// - `report_id`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
/// - `verb`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
/// - `host_target`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
/// - `host_mode`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
/// - `artifact_dir`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
/// - `app`: Input consumed by [`crate::runtime::runtime_reports::build_app_runtime_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_app_runtime_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_app_runtime_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_app_runtime_report_json(todo!(), todo!(), todo!(), todo!(), std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_app_runtime_report_json(
    report_id: Option<&str>,
    verb: Option<&str>,
    host_target: Option<&str>,
    host_mode: Option<&str>,
    artifact_dir: Option<&str>,
    app: &AppRuntime,
) -> Result<String, &'static str> {
    let mut report = Map::new();
    report.insert(
        "report_id".to_owned(),
        Value::String(
            report_id
                .unwrap_or("pharos-local-app-runtime-v1")
                .to_owned(),
        ),
    );
    report.insert(
        "verb".to_owned(),
        Value::String(verb.unwrap_or("status").to_owned()),
    );
    report.insert("target_kind".to_owned(), Value::String("app".to_owned()));
    report.insert(
        "target_id".to_owned(),
        Value::String(app.app_id.as_deref().unwrap_or_default().to_owned()),
    );
    report.insert("status".to_owned(), Value::String("ok".to_owned()));
    report.insert(
        "artifact_dir".to_owned(),
        Value::String(artifact_dir.unwrap_or_default().to_owned()),
    );
    report.insert(
        "runtime_launcher".to_owned(),
        Value::Bool(matches!(verb, Some("run" | "probe" | "smoke"))),
    );
    report.insert(
        "host_target".to_owned(),
        Value::String(host_target.unwrap_or("native-host").to_owned()),
    );
    report.insert(
        "host_mode".to_owned(),
        Value::String(host_mode.unwrap_or("native-host-target").to_owned()),
    );
    report.insert(
        "generated_by".to_owned(),
        Value::String("pharos-native-runtime".to_owned()),
    );
    report.insert("runtime_summary".to_owned(), app_summary(app));
    serde_json::to_string(&Value::Object(report)).map_err(|_| "app report encoding failed")
}

/// Builds the native runtime status report.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_status_report_json`].
/// - `apps_dir`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_status_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_runtime_status_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_runtime_status_report_json`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::runtime_reports::build_runtime_status_report_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_runtime_status_report_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_runtime_status_report_json(
    stack: &RuntimeStack,
    apps_dir: &str,
) -> Result<String, &'static str> {
    let apps: Vec<Value> = stack.apps.iter().map(app_summary).collect();
    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-runtime-status-v1",
        "status": "ok",
        "host": stack.host.as_deref().unwrap_or("127.0.0.1"),
        "port": stack.port.as_deref().unwrap_or("7323"),
        "socket_path": stack.socket_path.as_deref().unwrap_or_default(),
        "redis_status": crate::runtime::cache::redis_status(),
        "apps_dir": apps_dir,
        "app_count": apps.len(),
        "apps": apps,
    }))
    .map_err(|_| "status report encoding failed")
}

/// Builds a migration operation report with an explicit result status.
///
/// # Parameters
///
/// - `target_id`: Input consumed by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`].
/// - `backend`: Input consumed by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`].
/// - `operation`: Input consumed by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`].
/// - `status`: Input consumed by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`].
/// - `error`: Input consumed by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_migrate_operation_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_migrate_operation_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_migrate_operation_report_json("dev_docs", todo!(), todo!(), 400, todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_migrate_operation_report_json(
    target_id: &str,
    backend: &str,
    operation: &str,
    status: &str,
    error: Option<&str>,
) -> Result<String, &'static str> {
    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-migrate-v1",
        "target_kind": "app",
        "target_id": target_id,
        "backend": backend,
        "operation": operation,
        "status": status,
        "error": error,
    }))
    .map_err(|_| "migration report encoding failed")
}

/// Builds a bounded website status report from a discovered artifact root.
///
/// # Parameters
///
/// - `website`: Input consumed by [`crate::runtime::runtime_reports::build_website_status_report_json`].
/// - `artifact_root`: Input consumed by [`crate::runtime::runtime_reports::build_website_status_report_json`].
/// - `status`: Input consumed by [`crate::runtime::runtime_reports::build_website_status_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_website_status_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_website_status_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_website_status_report_json(todo!(), todo!(), 400);
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_website_status_report_json(
    website: &str,
    artifact_root: &std::path::Path,
    status: &str,
) -> Result<String, &'static str> {
    if website.is_empty() || artifact_root.as_os_str().is_empty() || status.is_empty() {
        return Err("website status inputs are incomplete");
    }
    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-website-status-v1",
        "website": website,
        "artifact_root": artifact_root,
        "status": status,
    }))
    .map_err(|_| "website status report encoding failed")
}

/// Resolves one website artifact directory below a trusted root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::runtime_reports::website_artifact_dir`].
/// - `website`: Input consumed by [`crate::runtime::runtime_reports::website_artifact_dir`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::runtime_reports::website_artifact_dir`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::website_artifact_dir(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn website_artifact_dir(root: &std::path::Path, website: &str) -> Option<String> {
    if root.as_os_str().is_empty() || website.is_empty() || website.contains(['/', '\\']) {
        return None;
    }
    let path = root.join("apps").join(website);
    path.is_dir().then(|| path.to_string_lossy().into_owned())
}

/// Builds a compact runtime summary from one loaded app.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::runtime_reports::build_runtime_summary_json_from_app`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::build_runtime_summary_json_from_app`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::build_runtime_summary_json_from_app`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::build_runtime_summary_json_from_app(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn build_runtime_summary_json_from_app(app: &AppRuntime) -> Result<String, &'static str> {
    serde_json::to_string(&app_summary(app)).map_err(|_| "runtime summary encoding failed")
}

/// Captures a bounded migration verification report without shell execution.
///
/// # Parameters
///
/// - `target_id`: Input consumed by [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`].
/// - `backend`: Input consumed by [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`].
/// - `status`: Input consumed by [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`].
/// - `error`: Input consumed by [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_reports::capture_migrate_verify_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_reports::capture_migrate_verify_report_json("dev_docs", todo!(), 400, todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::runtime_reports`] for adjacent helpers that share the same runtime surface.
pub fn capture_migrate_verify_report_json(
    target_id: &str,
    backend: &str,
    status: &str,
    error: Option<&str>,
) -> Result<String, &'static str> {
    build_migrate_operation_report_json(target_id, backend, "verify", status, error)
}