cranpose_services/

host.rs

//! Framework-owned application-host state and controls.

use std::{
    path::{Path, PathBuf},
    sync::{
        Arc, Mutex, OnceLock,
        atomic::{AtomicU8, Ordering},
    },
};

use portable_atomic::AtomicU64;

pub use crate::durable_save::{
    DurableSaveEffect, DurableSaveError, DurableSaveOutcome, DurableSaveRegistration,
    register_durable_save, register_preference_save, run_durable_saves,
};

/// Platform directory roots for application-owned files.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PlatformDirectories {
    /// Folder for the persistent data of the app.
    pub data: PathBuf,
    /// Folder for settings files.
    pub config: PathBuf,
    /// Folder for files that the app can recreate. The system may delete them.
    pub cache: PathBuf,
    /// Folder for documents that the person can see. `None` where the platform has no such folder.
    pub documents: Option<PathBuf>,
    /// Folder for short-lived files.
    pub temporary: PathBuf,
    /// Folder that the person and other apps can reach, such as the external files folder on
    /// Android. `None` where the platform has no such folder.
    pub shared: Option<PathBuf>,
}

impl PlatformDirectories {
    fn scoped(&self, application_id: &str) -> Self {
        Self {
            data: self.data.join(application_id),
            config: self.config.join(application_id),
            cache: self.cache.join(application_id),
            documents: self
                .documents
                .as_ref()
                .map(|path| path.join(application_id)),
            temporary: self.temporary.join(application_id),
            shared: self.shared.as_ref().map(|path| path.join(application_id)),
        }
    }
}

/// Why the application directories could not be resolved.
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
pub enum PlatformDirectoryError {
    /// The application id is empty or has more than one path component.
    #[error("application id must be one non-empty path component")]
    InvalidApplicationId,
    /// No host has registered an application id.
    #[error("no application id has been registered")]
    NoApplicationId,
    /// The platform reports no directories.
    #[error("platform directories are unavailable")]
    Unavailable,
}

/// Android-style lifecycle state exposed to composition observers.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum LifecycleState {
    /// The host exists and has not become visible yet.
    Created,
    /// The host is visible.
    Started,
    /// The host is in the foreground and receives input.
    Resumed,
    /// The host lost the foreground and may still be visible.
    Paused,
    /// The host is not visible.
    Stopped,
    /// The host is being torn down.
    Destroyed,
}

/// A lifecycle transition delivered by the platform host.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct LifecycleEvent {
    /// The state before the transition.
    pub from: LifecycleState,
    /// The state after the transition.
    pub to: LifecycleState,
}

/// Host operations supplied by the framework platform backend.
pub trait HostController: Send + Sync {
    /// Keeps the host window awake while enabled.
    fn set_keep_screen_on(&self, enabled: bool);
    /// Returns platform directory roots inside the application's host sandbox.
    fn platform_directories(&self) -> Option<PlatformDirectories>;
    /// Finishes/backgrounds the host.
    fn exit(&self);
    /// Requests that the app move to the background.
    fn background(&self);
    /// Ordered BCP 47 language preferences supplied by an embedded or native host.
    /// An empty list lets the application use the operating system's default query.
    #[cfg(feature = "localization")]
    fn preferred_languages(&self) -> Vec<String> {
        Vec::new()
    }
    /// How long this host will wait for durable saves before it suspends the
    /// app. Android's `onPause` and iOS's background transition each allow a
    /// short, platform-defined budget; work that overruns it keeps running
    /// under a background-work lease.
    fn durable_save_deadline(&self) -> std::time::Duration {
        DEFAULT_DURABLE_SAVE_DEADLINE
    }
}

/// The budget used when a host does not state one of its own.
pub const DEFAULT_DURABLE_SAVE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(2);

/// How long the installed host will wait for durable saves.
pub fn durable_save_deadline() -> std::time::Duration {
    host_controller().map_or(DEFAULT_DURABLE_SAVE_DEADLINE, |host| {
        host.durable_save_deadline()
    })
}

/// Shared handle to a [`HostController`].
pub type HostControllerRef = Arc<dyn HostController>;

fn controller() -> &'static Mutex<Option<HostControllerRef>> {
    static SLOT: OnceLock<Mutex<Option<HostControllerRef>>> = OnceLock::new();
    SLOT.get_or_init(|| Mutex::new(None))
}

/// Installs the framework host controller.
pub fn set_host_controller(value: HostControllerRef) {
    if let Ok(mut slot) = controller().lock() {
        *slot = Some(value);
    }
    KEEP_SCREEN_ON.store(0, Ordering::Release);
}
/// Removes the installed host controller.
pub fn clear_host_controller() {
    if let Ok(mut slot) = controller().lock() {
        *slot = None;
    }
    KEEP_SCREEN_ON.store(0, Ordering::Release);
}
/// Returns the installed framework host controller.
pub fn host_controller() -> Option<HostControllerRef> {
    controller().lock().ok().and_then(|slot| slot.clone())
}
/// Enables or disables the host's keep-screen-on flag.
pub fn set_keep_screen_on(enabled: bool) {
    let value = if enabled { 2 } else { 1 };
    if KEEP_SCREEN_ON.swap(value, Ordering::AcqRel) == value {
        return;
    }
    if let Some(host) = host_controller() {
        host.set_keep_screen_on(enabled);
    }
}
fn valid_application_id(application_id: &str) -> bool {
    !application_id.is_empty()
        && Path::new(application_id).components().count() == 1
        && application_id != "."
        && application_id != ".."
}

fn desktop_platform_directories() -> Option<PlatformDirectories> {
    let base = directories::BaseDirs::new()?;
    let documents = directories::UserDirs::new()
        .and_then(|directories| directories.document_dir().map(Path::to_path_buf));
    Some(PlatformDirectories {
        data: base.data_dir().to_path_buf(),
        config: base.config_dir().to_path_buf(),
        cache: base.cache_dir().to_path_buf(),
        documents,
        temporary: std::env::temp_dir(),
        shared: None,
    })
}

fn application_id_slot() -> &'static Mutex<Option<String>> {
    static SLOT: OnceLock<Mutex<Option<String>>> = OnceLock::new();
    SLOT.get_or_init(|| Mutex::new(None))
}

/// Registers the id every framework-owned storage path is scoped by.
///
/// Platform backends call this at startup with what the platform packaged —
/// the Android package name, the iOS bundle identifier, the desktop
/// application name — so applications never assemble a storage path
/// themselves.
pub fn set_application_id(application_id: &str) -> Result<(), PlatformDirectoryError> {
    if !valid_application_id(application_id) {
        return Err(PlatformDirectoryError::InvalidApplicationId);
    }
    if let Ok(mut slot) = application_id_slot().lock() {
        *slot = Some(application_id.to_string());
    }
    Ok(())
}

/// Removes the registered application id (tests and teardown).
pub fn clear_application_id() {
    if let Ok(mut slot) = application_id_slot().lock() {
        *slot = None;
    }
}

/// The registered application id, if a host has published one.
pub fn application_id() -> Option<String> {
    application_id_slot()
        .lock()
        .ok()
        .and_then(|slot| slot.clone())
}

/// Returns typed directories for the registered application.
pub fn application_directories() -> Result<PlatformDirectories, PlatformDirectoryError> {
    let application_id = application_id().ok_or(PlatformDirectoryError::NoApplicationId)?;
    let roots = host_controller()
        .and_then(|host| host.platform_directories())
        .or_else(desktop_platform_directories)
        .ok_or(PlatformDirectoryError::Unavailable)?;
    Ok(roots.scoped(&application_id))
}
/// Requests that the host finish the app.
pub fn exit_app() {
    if let Some(host) = host_controller() {
        host.exit();
    }
}
/// Requests that the host move the app to the background.
pub fn background_app() {
    if let Some(host) = host_controller() {
        host.background();
    }
}

#[cfg(not(target_arch = "wasm32"))]
type Observer = Arc<dyn Fn(LifecycleEvent) + Send + Sync>;

#[cfg(not(target_arch = "wasm32"))]
fn observers() -> &'static Mutex<Vec<(u64, Observer)>> {
    static SLOT: OnceLock<Mutex<Vec<(u64, Observer)>>> = OnceLock::new();
    SLOT.get_or_init(|| Mutex::new(Vec::new()))
}
static NEXT_ID: AtomicU64 = AtomicU64::new(1);
static LIFECYCLE_STATE: AtomicU8 = AtomicU8::new(LifecycleState::Created as u8);
static KEEP_SCREEN_ON: AtomicU8 = AtomicU8::new(0);

/// RAII lifecycle observer registration.
pub struct LifecycleObserver {
    id: u64,
}
impl Drop for LifecycleObserver {
    fn drop(&mut self) {
        #[cfg(not(target_arch = "wasm32"))]
        if let Ok(mut list) = observers().lock() {
            list.retain(|(id, _)| *id != self.id);
        }
        #[cfg(target_arch = "wasm32")]
        crate::thread_state::with(|state| state.lifecycle_observers.remove(self.id));
    }
}
/// Observes host lifecycle transitions until the returned handle is dropped.
#[cfg(not(target_arch = "wasm32"))]
pub fn observe_lifecycle(
    observer: impl Fn(LifecycleEvent) + Send + Sync + 'static,
) -> LifecycleObserver {
    let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
    if let Ok(mut list) = observers().lock() {
        list.push((id, Arc::new(observer)));
    }
    LifecycleObserver { id }
}
/// Observes host lifecycle transitions until the returned handle is dropped.
#[cfg(target_arch = "wasm32")]
pub fn observe_lifecycle(observer: impl Fn(LifecycleEvent) + 'static) -> LifecycleObserver {
    let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
    crate::thread_state::with(|state| {
        state
            .lifecycle_observers
            .add(id, std::rc::Rc::new(observer));
    });
    LifecycleObserver { id }
}
/// Publishes a lifecycle transition from the platform host.
pub fn dispatch_lifecycle(event: LifecycleEvent) {
    LIFECYCLE_STATE.store(event.to as u8, Ordering::Release);
    crate::media::on_lifecycle(event);
    #[cfg(not(target_arch = "wasm32"))]
    let callbacks = observers()
        .lock()
        .map(|list| {
            list.iter()
                .map(|(_, cb)| Arc::clone(cb))
                .collect::<Vec<_>>()
        })
        .unwrap_or_default();
    #[cfg(target_arch = "wasm32")]
    let callbacks = crate::thread_state::with(|state| state.lifecycle_observers.all());
    for callback in callbacks {
        callback(event);
    }
}

/// Returns the latest lifecycle state published by the platform host.
pub fn current_lifecycle_state() -> LifecycleState {
    match LIFECYCLE_STATE.load(Ordering::Acquire) {
        0 => LifecycleState::Created,
        1 => LifecycleState::Started,
        2 => LifecycleState::Resumed,
        3 => LifecycleState::Paused,
        4 => LifecycleState::Stopped,
        _ => LifecycleState::Destroyed,
    }
}

/// Publishes a platform lifecycle state and derives the transition source from
/// the framework's previous state.
///
/// Leaving the foreground runs every registered durable save first, inside the
/// budget the host allows, so an application never has to hook the transition
/// itself to persist its data.
pub fn dispatch_lifecycle_state(to: LifecycleState) {
    let from = current_lifecycle_state();
    if from == to {
        return;
    }
    if matches!(to, LifecycleState::Paused) {
        let outcome = run_durable_saves(durable_save_deadline());
        if matches!(
            outcome,
            DurableSaveOutcome::TimedOut | DurableSaveOutcome::Failed
        ) {
            log::warn!("cranpose: durable saves did not complete successfully: {outcome:?}");
        }
    }
    dispatch_lifecycle(LifecycleEvent { from, to });
}

/// The lifecycle state of a window or browser page that is `visible` and
/// has keyboard `focused`, mapped the way Compose Multiplatform maps desktop
/// windows: resumed while focused, paused while only visible, and stopped
/// while minimized, hidden or in a background tab.
pub fn window_lifecycle_state(visible: bool, focused: bool) -> LifecycleState {
    match (visible, focused) {
        (false, _) => LifecycleState::Stopped,
        (true, true) => LifecycleState::Resumed,
        (true, false) => LifecycleState::Paused,
    }
}

impl LifecycleState {
    /// Whether this state is at least as active as `other`, counting paused
    /// as started and stopped as created — Android's `isAtLeast`.
    pub fn is_at_least(self, other: LifecycleState) -> bool {
        lifecycle_level(self) >= lifecycle_level(other)
    }
}

fn lifecycle_level(state: LifecycleState) -> u8 {
    match state {
        LifecycleState::Destroyed => 0,
        LifecycleState::Created | LifecycleState::Stopped => 1,
        LifecycleState::Started | LifecycleState::Paused => 2,
        LifecycleState::Resumed => 3,
    }
}

fn next_lifecycle_step(from: LifecycleState, to: LifecycleState) -> Option<LifecycleState> {
    let rising = match lifecycle_level(from).cmp(&lifecycle_level(to)) {
        std::cmp::Ordering::Equal => return None,
        std::cmp::Ordering::Less => true,
        std::cmp::Ordering::Greater => false,
    };
    match (from, rising) {
        (LifecycleState::Destroyed, _) => None,
        (LifecycleState::Created | LifecycleState::Stopped, true) => Some(LifecycleState::Started),
        (LifecycleState::Started | LifecycleState::Paused, true) => Some(LifecycleState::Resumed),
        (LifecycleState::Resumed, _) => Some(LifecycleState::Paused),
        (LifecycleState::Started | LifecycleState::Paused, false) => Some(LifecycleState::Stopped),
        (LifecycleState::Created | LifecycleState::Stopped, false) => {
            Some(LifecycleState::Destroyed)
        }
    }
}

/// Moves the host lifecycle to `target` through every state in between, in
/// Android's order: a stopped app starts before it resumes, and a resumed one
/// pauses before it stops, so leaving the foreground always runs the durable
/// saves. Paused and started count as the same place, as do created and
/// stopped. Hosts whose platform reports only visibility and focus use this
/// instead of dispatching each transition themselves.
pub fn advance_lifecycle(target: LifecycleState) {
    while let Some(next) = next_lifecycle_step(current_lifecycle_state(), target) {
        dispatch_lifecycle_state(next);
    }
}

/// The `CompositionLocal` carrying the host's current lifecycle state.
///
/// [`ProvideLifecycle`] installs it; descendants read it and recompose on every
/// transition, so a screen can pause its own work without registering an
/// observer of its own.
pub fn local_lifecycle_state() -> cranpose_core::CompositionLocal<LifecycleState> {
    crate::composition_locals::cached_local(
        |locals| &locals.lifecycle,
        || cranpose_core::compositionLocalOf(current_lifecycle_state),
    )
}

/// The host's lifecycle state as observable state.
#[expect(non_snake_case)]
#[track_caller]
pub fn rememberLifecycleState() -> cranpose_core::State<LifecycleState> {
    let transitions = rememberLifecycleEvents();
    let state = cranpose_core::collectAsState(
        transitions,
        (),
        LifecycleEvent {
            from: current_lifecycle_state(),
            to: current_lifecycle_state(),
        },
    );
    cranpose_core::derivedStateOf(move || state.get().to)
}

/// Host lifecycle transitions as a composition-scoped stream.
#[expect(non_snake_case)]
#[track_caller]
pub fn rememberLifecycleEvents() -> cranpose_core::EventStream<LifecycleEvent> {
    cranpose_core::rememberEventStream((), |sender| {
        observe_lifecycle(move |event| sender.send(event))
    })
}

/// Provides the host's lifecycle state to descendant composables.
///
/// The application shell wraps its content in this once; screens then read
/// [`local_lifecycle_state`].
#[cranpose_macros::composable]
pub fn ProvideLifecycle(content: impl FnOnce()) {
    let state = rememberLifecycleState();
    let local = local_lifecycle_state();
    cranpose_core::CompositionLocalProvider([local.provides(state.get())], move || {
        content();
    });
}

#[cfg(test)]
#[path = "tests/host_tests.rs"]
mod tests;