skenion-runtime 0.43.0

Skenion native runtime
Documentation
use serde::{Deserialize, Serialize};
use skenion_contracts::{
    RuntimeConnectionProfile, RuntimeConnectionProfileMode, RuntimeEndpointMetadata,
    RuntimeEndpointProtocol, RuntimeOwnershipMode, RuntimeProcessMetadata,
};

use crate::{DiagnosticSeverity, RUNTIME_API_VERSION, RuntimeDiagnostic};

#[derive(Debug, Clone)]
pub struct RuntimeEndpointConfig {
    pub host: String,
    pub port: u16,
    pub url: String,
}

impl RuntimeEndpointConfig {
    pub fn new(host: String, port: u16) -> Self {
        let url = format!("http://{host}:{port}");
        Self { host, port, url }
    }
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarStartupResponse {
    pub schema: &'static str,
    pub schema_version: &'static str,
    pub ok: bool,
    pub runtime: RuntimeSidecarRuntimeInfo,
    pub endpoint: RuntimeEndpointMetadata,
    pub profile: RuntimeConnectionProfile,
    pub default_session_id: String,
    pub default_session_url: String,
    pub health: RuntimeSidecarHealthInfo,
    pub token: RuntimeSidecarTokenInfo,
    pub shutdown: RuntimeSidecarShutdownInfo,
    pub diagnostics: Vec<RuntimeDiagnostic>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarRuntimeInfo {
    pub name: &'static str,
    pub version: &'static str,
    pub api_version: &'static str,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarHealthInfo {
    pub ok: bool,
    pub url: String,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarHealthResponse {
    pub schema: &'static str,
    pub schema_version: &'static str,
    pub ok: bool,
    pub readiness: &'static str,
    pub runtime: RuntimeSidecarRuntimeInfo,
    pub endpoint: RuntimeEndpointMetadata,
    pub profile: RuntimeConnectionProfile,
    pub diagnostics: Vec<RuntimeDiagnostic>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarTokenInfo {
    pub required: bool,
    pub header: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarShutdownInfo {
    pub supported: bool,
    pub method: &'static str,
    pub url: String,
    pub scope: &'static str,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarShutdownRequest {
    #[serde(default)]
    pub reason: Option<String>,
    #[serde(default)]
    pub owner_window_id: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RuntimeSidecarShutdownResponse {
    pub schema: &'static str,
    pub schema_version: &'static str,
    pub ok: bool,
    pub accepted: bool,
    pub action: &'static str,
    pub scope: &'static str,
    pub diagnostics: Vec<RuntimeDiagnostic>,
}

pub(crate) fn sidecar_startup_response(
    endpoint_config: &RuntimeEndpointConfig,
    default_session_id: &str,
    started_at_wall_clock: &str,
) -> RuntimeSidecarStartupResponse {
    let endpoint = runtime_endpoint_metadata(endpoint_config);
    RuntimeSidecarStartupResponse {
        schema: "skenion.runtime.sidecar.startup",
        schema_version: "0.1.0",
        ok: true,
        runtime: RuntimeSidecarRuntimeInfo {
            name: "skenion-runtime",
            version: env!("CARGO_PKG_VERSION"),
            api_version: RUNTIME_API_VERSION,
        },
        endpoint: endpoint.clone(),
        profile: runtime_connection_profile(endpoint_config, started_at_wall_clock),
        default_session_id: default_session_id.to_owned(),
        default_session_url: format!("{}/v0/sessions/{default_session_id}", endpoint.url),
        health: RuntimeSidecarHealthInfo {
            ok: true,
            url: format!("{}/v0/sidecar/health", endpoint.url),
        },
        token: runtime_sidecar_token(),
        shutdown: RuntimeSidecarShutdownInfo {
            supported: true,
            method: "POST",
            url: format!("{}/v0/sidecar/shutdown", endpoint.url),
            scope: "owned-child-only",
        },
        diagnostics: Vec::new(),
    }
}

pub(crate) fn sidecar_health_response(
    endpoint_config: &RuntimeEndpointConfig,
    started_at_wall_clock: &str,
) -> RuntimeSidecarHealthResponse {
    RuntimeSidecarHealthResponse {
        schema: "skenion.runtime.sidecar.health",
        schema_version: "0.1.0",
        ok: true,
        readiness: "ready",
        runtime: RuntimeSidecarRuntimeInfo {
            name: "skenion-runtime",
            version: env!("CARGO_PKG_VERSION"),
            api_version: RUNTIME_API_VERSION,
        },
        endpoint: runtime_endpoint_metadata(endpoint_config),
        profile: runtime_connection_profile(endpoint_config, started_at_wall_clock),
        diagnostics: Vec::new(),
    }
}

pub(crate) fn runtime_connection_profile(
    endpoint_config: &RuntimeEndpointConfig,
    started_at_wall_clock: &str,
) -> RuntimeConnectionProfile {
    RuntimeConnectionProfile {
        mode: RuntimeConnectionProfileMode::LocalManaged,
        ownership: RuntimeOwnershipMode::OwnedChild,
        display_name: Some("Skenion Runtime local-managed sidecar".to_owned()),
        endpoint: runtime_endpoint_metadata(endpoint_config),
        process: Some(RuntimeProcessMetadata {
            owned_by_host: true,
            pid: Some(std::process::id()),
            executable_path: std::env::current_exe()
                .ok()
                .map(|path| path.display().to_string()),
            working_directory: std::env::current_dir()
                .ok()
                .map(|path| path.display().to_string()),
            started_at: Some(started_at_wall_clock.to_owned()),
            owner_window_id: None,
            platform: Some(std::env::consts::OS.to_owned()),
            arch: Some(std::env::consts::ARCH.to_owned()),
        }),
    }
}

fn runtime_endpoint_metadata(endpoint_config: &RuntimeEndpointConfig) -> RuntimeEndpointMetadata {
    RuntimeEndpointMetadata {
        url: endpoint_config.url.clone(),
        canonical_url: Some(endpoint_config.url.clone()),
        protocol: RuntimeEndpointProtocol::Http,
        host: Some(endpoint_config.host.clone()),
        port: Some(endpoint_config.port),
        tls: Some(false),
    }
}

fn runtime_sidecar_token() -> RuntimeSidecarTokenInfo {
    runtime_sidecar_token_from_value(std::env::var("SKENION_RUNTIME_TOKEN").ok())
}

fn runtime_sidecar_token_from_value(token: Option<String>) -> RuntimeSidecarTokenInfo {
    let token = match token {
        Some(token) if !token.is_empty() => Some(token),
        _ => None,
    };
    RuntimeSidecarTokenInfo {
        required: token.is_some(),
        header: "Authorization",
        token,
    }
}

pub(crate) fn sidecar_shutdown_response(body: &[u8]) -> RuntimeSidecarShutdownResponse {
    let diagnostics = match sidecar_shutdown_request(body) {
        Ok(request) => shutdown_request_diagnostics(request),
        Err(error) => vec![RuntimeDiagnostic::error(format!(
            "invalid sidecar shutdown request: {error}"
        ))],
    };
    RuntimeSidecarShutdownResponse {
        schema: "skenion.runtime.sidecar.shutdown",
        schema_version: "0.1.0",
        ok: diagnostics
            .iter()
            .all(|diagnostic| diagnostic.severity != DiagnosticSeverity::Error),
        accepted: false,
        action: "host-owned-process-stop-required",
        scope: "owned-child-only",
        diagnostics,
    }
}

fn sidecar_shutdown_request(
    body: &[u8],
) -> Result<RuntimeSidecarShutdownRequest, serde_json::Error> {
    if body.is_empty() {
        return Ok(RuntimeSidecarShutdownRequest {
            reason: None,
            owner_window_id: None,
        });
    }
    serde_json::from_slice(body)
}

fn shutdown_request_diagnostics(request: RuntimeSidecarShutdownRequest) -> Vec<RuntimeDiagnostic> {
    let mut diagnostics = vec![RuntimeDiagnostic::warning(
        "runtime shutdown is a structured primitive; the host must stop only its owned child process",
    )];
    if let Some(reason) = request.reason.filter(|reason| !reason.is_empty()) {
        diagnostics.push(RuntimeDiagnostic {
            severity: DiagnosticSeverity::Info,
            message: format!("shutdown requested: {reason}"),
            code: Some("sidecar.shutdown.reason".to_owned()),
            details: request
                .owner_window_id
                .map(|owner_window_id| serde_json::json!({ "ownerWindowId": owner_window_id })),
        });
    }
    diagnostics
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn startup_response_is_machine_readable() {
        let endpoint = RuntimeEndpointConfig::new("127.0.0.1".to_owned(), 3761);
        let response = sidecar_startup_response(&endpoint, "default", "unix-ms:1");

        assert!(response.ok);
        assert_eq!(response.endpoint.url, "http://127.0.0.1:3761");
        assert_eq!(response.default_session_id, "default");
        assert_eq!(
            response.profile.mode,
            RuntimeConnectionProfileMode::LocalManaged
        );
        assert_eq!(response.token.header, "Authorization");
        assert_eq!(response.shutdown.scope, "owned-child-only");
    }

    #[test]
    fn health_response_is_not_startup_handshake() {
        let endpoint = RuntimeEndpointConfig::new("127.0.0.1".to_owned(), 3761);
        let response = sidecar_health_response(&endpoint, "unix-ms:1");
        let value = serde_json::to_value(&response).expect("health response should serialize");

        assert!(response.ok);
        assert_eq!(response.schema, "skenion.runtime.sidecar.health");
        assert_eq!(response.readiness, "ready");
        assert_eq!(response.runtime.version, env!("CARGO_PKG_VERSION"));
        assert_eq!(response.endpoint.url, "http://127.0.0.1:3761");
        assert!(value.get("token").is_none());
        assert!(value.get("shutdown").is_none());
        assert!(value.get("defaultSessionUrl").is_none());
    }

    #[test]
    fn token_info_reports_present_token_without_environment_mutation() {
        let present = runtime_sidecar_token_from_value(Some("test-token".to_owned()));
        let empty = runtime_sidecar_token_from_value(Some(String::new()));

        assert!(present.required);
        assert_eq!(present.token.as_deref(), Some("test-token"));
        assert!(!empty.required);
        assert!(empty.token.is_none());
    }

    #[test]
    fn shutdown_response_is_structured_without_killing_processes() {
        let empty = sidecar_shutdown_response(&[]);
        let reason = sidecar_shutdown_response(
            br#"{ "reason": "window-close", "ownerWindowId": "window-1" }"#,
        );
        let invalid = sidecar_shutdown_response(b"{");

        assert!(empty.ok);
        assert!(!empty.accepted);
        assert!(reason.ok);
        assert_eq!(reason.diagnostics.len(), 2);
        assert!(!invalid.ok);
    }
}