service_manager/

lib.rs

#![doc = include_str!("../README.md")]

#[doc = include_str!("../README.md")]
#[cfg(doctest)]
pub struct ReadmeDoctests;

use std::{
    ffi::{OsStr, OsString},
    fmt, io,
    path::PathBuf,
    str::FromStr,
};

mod kind;
mod launchd;
mod openrc;
mod rcd;
mod sc;
mod systemd;
mod typed;
mod utils;
mod winsw;

pub use kind::*;
pub use launchd::*;
pub use openrc::*;
pub use rcd::*;
pub use sc::*;
pub use systemd::*;
pub use typed::*;
pub use winsw::*;

/// Interface for a service manager
pub trait ServiceManager {
    /// Determines if the service manager exists (e.g. is `launchd` available on the system?) and
    /// can be used
    fn available(&self) -> io::Result<bool>;

    /// Installs a new service using the manager
    fn install(&self, ctx: ServiceInstallCtx) -> io::Result<()>;

    /// Uninstalls an existing service using the manager
    fn uninstall(&self, ctx: ServiceUninstallCtx) -> io::Result<()>;

    /// Starts a service using the manager
    fn start(&self, ctx: ServiceStartCtx) -> io::Result<()>;

    /// Stops a running service using the manager
    fn stop(&self, ctx: ServiceStopCtx) -> io::Result<()>;

    /// Returns the current target level for the manager
    fn level(&self) -> ServiceLevel;

    /// Sets the target level for the manager
    fn set_level(&mut self, level: ServiceLevel) -> io::Result<()>;

    /// Return the service status info
    fn status(&self, ctx: ServiceStatusCtx) -> io::Result<ServiceStatus>;
}

impl dyn ServiceManager {
    /// Creates a new service using the specified type, falling back to selecting
    /// based on native service manager for the current operating system if no type provided
    pub fn target_or_native(
        kind: impl Into<Option<ServiceManagerKind>>,
    ) -> io::Result<Box<dyn ServiceManager>> {
        Ok(TypedServiceManager::target_or_native(kind)?.into_box())
    }

    /// Creates a new service manager targeting the specific service manager kind using the
    /// default service manager instance
    pub fn target(kind: ServiceManagerKind) -> Box<dyn ServiceManager> {
        TypedServiceManager::target(kind).into_box()
    }

    /// Attempts to select a native service manager for the current operating system
    ///
    /// * For MacOS, this will use [`LaunchdServiceManager`]
    /// * For Windows, this will use [`ScServiceManager`]
    /// * For BSD variants, this will use [`RcdServiceManager`]
    /// * For Linux variants, this will use either [`SystemdServiceManager`] or [`OpenRcServiceManager`]
    pub fn native() -> io::Result<Box<dyn ServiceManager>> {
        native_service_manager()
    }
}

/// Attempts to select a native service manager for the current operating system1
///
/// * For MacOS, this will use [`LaunchdServiceManager`]
/// * For Windows, this will use [`ScServiceManager`]
/// * For BSD variants, this will use [`RcdServiceManager`]
/// * For Linux variants, this will use either [`SystemdServiceManager`] or [`OpenRcServiceManager`]
#[inline]
pub fn native_service_manager() -> io::Result<Box<dyn ServiceManager>> {
    Ok(TypedServiceManager::native()?.into_box())
}

impl<'a, S> From<S> for Box<dyn ServiceManager + 'a>
where
    S: ServiceManager + 'a,
{
    fn from(service_manager: S) -> Self {
        Box::new(service_manager)
    }
}

/// Represents whether a service is system-wide or user-level
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum ServiceLevel {
    System,
    User,
}

/// Represents the restart policy for a service.
///
/// This enum provides a cross-platform abstraction for service restart behavior with a set of
/// simple options that cover most service managers.
///
/// For most service cases you likely want a restart-on-failure policy, so this is the default.
///
/// Each service manager supports different levels of granularity:
///
/// - **Systemd** (Linux): supports all variants natively
/// - **Launchd** (macOS): supports Never, Always, OnFailure (approximated), and OnSuccess via KeepAlive dictionary
/// - **WinSW** (Windows): supports Never, Always, and OnFailure; OnSuccess falls back to Always with a warning
/// - **OpenRC/rc.d/sc.exe**: limited or no restart support as of yet
///
/// When a platform doesn't support a specific policy, the implementation will fall back
/// to the closest approximation and log a warning.
///
/// In the case where you need a restart policy that is very specific to a particular service
/// manager, you should instantiate that service manager directly, rather than using the generic
/// `ServiceManager` trait.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum RestartPolicy {
    /// Never restart the service
    Never,

    /// Always restart the service regardless of exit status.
    ///
    /// The optional delay specifies seconds to wait before restarting.
    Always {
        /// Delay in seconds before restarting
        delay_secs: Option<u32>,
    },

    /// Restart the service only when it exits with a non-zero status.
    ///
    /// The optional delay specifies seconds to wait before restarting.
    OnFailure {
        /// Delay in seconds before restarting
        delay_secs: Option<u32>,

        /// Maximum number of restart attempts before giving up.
        ///
        /// If `None`, the service will restart indefinitely (platform default behavior).
        /// If `Some(n)`, the service will be restarted at most `n` times before stopping.
        ///
        /// Platform mapping:
        /// - **WinSW**: Generates `n` `<onfailure action="restart"/>` elements followed by
        ///   `<onfailure action="none"/>`.
        /// - **Systemd**: TODO — map to `StartLimitBurst`.
        /// - **Launchd**: TODO — no direct equivalent.
        max_retries: Option<u32>,

        /// Duration in seconds after which the failure counter resets.
        ///
        /// If the service runs successfully for this many seconds, any previous failures
        /// are forgotten and the retry counter starts fresh.
        ///
        /// If `None`, the platform default is used (e.g., WinSW defaults to 1 day).
        ///
        /// Platform mapping:
        /// - **WinSW**: Maps to `<resetfailure>`.
        /// - **Systemd**: TODO — map to `StartLimitIntervalSec`.
        /// - **Launchd**: TODO — no direct equivalent.
        reset_after_secs: Option<u32>,
    },

    /// Restart the service only when it exits with a zero status (success).
    ///
    /// The optional delay specifies seconds to wait before restarting.
    OnSuccess {
        /// Delay in seconds before restarting
        delay_secs: Option<u32>,
    },
}

impl Default for RestartPolicy {
    fn default() -> Self {
        RestartPolicy::OnFailure {
            delay_secs: None,
            max_retries: None,
            reset_after_secs: None,
        }
    }
}

/// Represents the status of a service
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum ServiceStatus {
    NotInstalled,
    Running,
    Stopped(Option<String>), // Provide a reason if possible
}

/// Label describing the service (e.g. `org.example.my_application`
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ServiceLabel {
    /// Qualifier used for services tied to management systems like `launchd`
    ///
    /// E.g. `org` or `com`
    pub qualifier: Option<String>,

    /// Organization associated with the service
    ///
    /// E.g. `example`
    pub organization: Option<String>,

    /// Application name associated with the service
    ///
    /// E.g. `my_application`
    pub application: String,
}

impl ServiceLabel {
    /// Produces a fully-qualified name in the form of `{qualifier}.{organization}.{application}`
    pub fn to_qualified_name(&self) -> String {
        let mut qualified_name = String::new();
        if let Some(qualifier) = self.qualifier.as_ref() {
            qualified_name.push_str(qualifier.as_str());
            qualified_name.push('.');
        }
        if let Some(organization) = self.organization.as_ref() {
            qualified_name.push_str(organization.as_str());
            qualified_name.push('.');
        }
        qualified_name.push_str(self.application.as_str());
        qualified_name
    }

    /// Produces a script name using the organization and application
    /// in the form of `{organization}-{application}`
    pub fn to_script_name(&self) -> String {
        let mut script_name = String::new();
        if let Some(organization) = self.organization.as_ref() {
            script_name.push_str(organization.as_str());
            script_name.push('-');
        }
        script_name.push_str(self.application.as_str());
        script_name
    }
}

impl fmt::Display for ServiceLabel {
    /// Produces a fully-qualified name
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.to_qualified_name().as_str())
    }
}

impl FromStr for ServiceLabel {
    type Err = io::Error;

    /// Parses a fully-qualified name in the form of `{qualifier}.{organization}.{application}`
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let tokens = s.split('.').collect::<Vec<&str>>();

        let label = match tokens.len() {
            1 => Self {
                qualifier: None,
                organization: None,
                application: tokens[0].to_string(),
            },
            2 => Self {
                qualifier: None,
                organization: Some(tokens[0].to_string()),
                application: tokens[1].to_string(),
            },
            3 => Self {
                qualifier: Some(tokens[0].to_string()),
                organization: Some(tokens[1].to_string()),
                application: tokens[2].to_string(),
            },
            _ => Self {
                qualifier: Some(tokens[0].to_string()),
                organization: Some(tokens[1].to_string()),
                application: tokens[2..].join("."),
            },
        };

        Ok(label)
    }
}

/// Context provided to the install function of [`ServiceManager`]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceInstallCtx {
    /// Label associated with the service
    ///
    /// E.g. `org.example.my_application`
    pub label: ServiceLabel,

    /// Path to the program to run
    ///
    /// E.g. `/usr/local/bin/my-program`
    pub program: PathBuf,

    /// Arguments to use for the program
    ///
    /// E.g. `--arg`, `value`, `--another-arg`
    pub args: Vec<OsString>,

    /// Optional contents of the service file for a given ServiceManager
    /// to use instead of the default template.
    pub contents: Option<String>,

    /// Optionally supply the user the service will run as
    ///
    /// If not specified, the service will run as the root or Administrator user.
    pub username: Option<String>,

    /// Optionally specify a working directory for the process launched by the service
    pub working_directory: Option<PathBuf>,

    /// Optionally specify a list of environment variables to be passed to the process launched by
    /// the service
    pub environment: Option<Vec<(String, String)>>,

    /// Specify whether the service should automatically start on reboot
    pub autostart: bool,

    /// Specify the restart policy for the service
    ///
    /// This controls when and how the service should be restarted if it exits.
    /// Different platforms support different levels of granularity - see [`RestartPolicy`]
    /// documentation for details.
    ///
    /// Defaults to [`RestartPolicy::OnFailure`] if not specified.
    pub restart_policy: RestartPolicy,
}

impl ServiceInstallCtx {
    /// Iterator over the program and its arguments
    pub fn cmd_iter(&self) -> impl Iterator<Item = &OsStr> {
        std::iter::once(self.program.as_os_str()).chain(self.args_iter())
    }

    /// Iterator over the program arguments
    pub fn args_iter(&self) -> impl Iterator<Item = &OsStr> {
        self.args.iter().map(OsString::as_os_str)
    }
}

/// Context provided to the uninstall function of [`ServiceManager`]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceUninstallCtx {
    /// Label associated with the service
    ///
    /// E.g. `rocks.distant.manager`
    pub label: ServiceLabel,
}

/// Context provided to the start function of [`ServiceManager`]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceStartCtx {
    /// Label associated with the service
    ///
    /// E.g. `rocks.distant.manager`
    pub label: ServiceLabel,
}

/// Context provided to the stop function of [`ServiceManager`]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceStopCtx {
    /// Label associated with the service
    ///
    /// E.g. `rocks.distant.manager`
    pub label: ServiceLabel,
}

/// Context provided to the status function of [`ServiceManager`]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServiceStatusCtx {
    /// Label associated with the service
    ///
    /// E.g. `rocks.distant.manager`
    pub label: ServiceLabel,
}

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

    #[test]
    fn test_service_label_parssing_1() {
        let label = ServiceLabel::from_str("com.example.app123").unwrap();

        assert_eq!(label.qualifier, Some("com".to_string()));
        assert_eq!(label.organization, Some("example".to_string()));
        assert_eq!(label.application, "app123".to_string());

        assert_eq!(label.to_qualified_name(), "com.example.app123");
        assert_eq!(label.to_script_name(), "example-app123");
    }

    #[test]
    fn test_service_label_parssing_2() {
        let label = ServiceLabel::from_str("example.app123").unwrap();

        assert_eq!(label.qualifier, None);
        assert_eq!(label.organization, Some("example".to_string()));
        assert_eq!(label.application, "app123".to_string());

        assert_eq!(label.to_qualified_name(), "example.app123");
        assert_eq!(label.to_script_name(), "example-app123");
    }

    #[test]
    fn test_service_label_parssing_3() {
        let label = ServiceLabel::from_str("app123").unwrap();

        assert_eq!(label.qualifier, None);
        assert_eq!(label.organization, None);
        assert_eq!(label.application, "app123".to_string());

        assert_eq!(label.to_qualified_name(), "app123");
        assert_eq!(label.to_script_name(), "app123");
    }
}