feat!: provide generic RestartPolicy enum

I found myself in a situation where I need to use the 'always' and 'on success' restart policies on
Linux Systemd and macOS Launchd. It was not possible to do this while using the generic
`ServiceManager` trait; I would have to use specific service managers, which would necessitate the
introduction of conditional compilation.

Now we introduce a generic `RestartPolicy` enum to work with the generic `ServiceManager` trait.
This should cover the most important cases supported by most service managers: 'never', 'always',
and 'on failure', plus the option for 'on success'. Users can still instantiate a particular service
manager if they want to use specific restart options that are only supported by that manager.

In some cases these variants don't map directly to some service manager options, so an approximation
is used and a warning is emitted; however, it should still be very acceptable to configure the
service in this way since the behaviour should not be too surprising.

See the changelog entry for more details.

BREAKING CHANGE: the `disable_restart_on_failure` field was removed in favour of the restart policy
and the fields on specific service managers were made optional.

Author: jacderida

CHANGELOG.md

@@ -5,7 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.0] - 2025-11-22
+
+### Changed
+
+- **BREAKING CHANGE**: Replaced `disable_restart_on_failure: bool` field with `restart_policy: RestartPolicy` in `ServiceInstallCtx`.
+  - The new `RestartPolicy` enum provides a cross-platform abstraction for service-restart behavior with four variants:
+    - `RestartPolicy::Never` - Service never restarts
+    - `RestartPolicy::Always { delay_secs: Option<u32> }` - Service always restarts regardless of exit status
+    - `RestartPolicy::OnFailure { delay_secs: Option<u32> }` - Service restarts only on non-zero exit (default)
+    - `RestartPolicy::OnSuccess { delay_secs: Option<u32> }` - Service restarts only on successful exit (exit code 0)
+  - Different platforms support different levels of granularity:
+    - **systemd** (Linux): Supports all restart policies natively (including `OnSuccess` via `Restart=on-success`)
+    - **launchd** (macOS): Supports Never, Always, and OnSuccess; OnFailure is approximated using `KeepAlive=true`; OnSuccess uses `KeepAlive` dictionary with `SuccessfulExit=false`
+    - **WinSW** (Windows): Supports Never, Always, and OnFailure with optional delays; OnSuccess falls back to Always with a warning
+    - **OpenRC/rc.d/sc.exe**: Limited or no restart support; logs warnings for unsupported policies
+  - Migration guide for `ServiceInstallCtx`:
+    - `disable_restart_on_failure: false` → `restart_policy: RestartPolicy::OnFailure { delay_secs: None }`
+    - `disable_restart_on_failure: true` → `restart_policy: RestartPolicy::Never`
+
+- **BREAKING CHANGE**: Platform-specific restart configuration fields are now `Option` types,
+  allowing the generic `RestartPolicy` to be used by default while still supporting platform-specific
+  features when needed:
+  - `SystemdInstallConfig.restart`: Changed from `SystemdServiceRestartType` to `Option<SystemdServiceRestartType>`
+    - When `Some`, the systemd-specific restart type takes precedence over the generic `RestartPolicy`
+    - When `None` (default), falls back to the generic `RestartPolicy`
+    - Migration: `restart: SystemdServiceRestartType::OnFailure` → 
+      `restart: Some(SystemdServiceRestartType::OnFailure)` or `restart: None` to use generic policy
+  - `LaunchdInstallConfig.keep_alive`: Changed from `bool` to `Option<bool>`
+    - When `Some`, the launchd-specific keep-alive setting takes precedence
+    - When `None` (default), falls back to the generic `RestartPolicy`
+    - Migration: `keep_alive: true` → `keep_alive: Some(true)` or `keep_alive: None` to use generic policy
+  - `WinSwInstallConfig.failure_action`: Changed from `WinSwOnFailureAction` to `Option<WinSwOnFailureAction>`
+    - When `Some`, the WinSW-specific failure action takes precedence
+    - When `None` (default), falls back to the generic `RestartPolicy`
+    - Migration: `failure_action: WinSwOnFailureAction::Restart(...)` →
+      `failure_action: Some(WinSwOnFailureAction::Restart(...))` or `failure_action: None` to use generic policy
+
+### Added
+
+- Support for the `log` crate to emit warnings when platform-specific restart features are not supported
 
 ## [0.8.0] - 2025-02-21
 

Cargo.toml

@@ -25,6 +25,7 @@ members = ["system-tests"]
 cfg-if = "1.0"
 clap = { version = "4", features = ["derive"], optional = true }
 dirs = "4.0"
+log = "0.4"
 plist = "1.1"
 serde = { version = "1", features = ["derive"], optional = true }
 which = "4.0"

README.md

@@ -69,7 +69,7 @@ manager.install(ServiceInstallCtx {
     working_directory: None, // Optional String for the working directory for the service process.
     environment: None, // Optional list of environment variables to supply the service process.
     autostart: true, // Specify whether the service should automatically start upon OS reboot.
-    disable_restart_on_failure: false, // Services restart on crash by default.
+    restart_policy: RestartPolicy::default(), // Restart on failure by default.
 }).expect("Failed to install");
 
 // Start our service using the underlying service management platform
@@ -133,7 +133,7 @@ let mut manager = LaunchdServiceManager::system();
 
 // Update an install configuration property where installing a service
 // will NOT add the KeepAlive flag
-manager.config.install.keep_alive = false;
+manager.config.install.keep_alive = Some(false);
 
 // Install our service using the explicit service manager
 manager.install(ServiceInstallCtx {
@@ -145,10 +145,75 @@ manager.install(ServiceInstallCtx {
     working_directory: None, // Optional String for the working directory for the service process.
     environment: None, // Optional list of environment variables to supply the service process.
     autostart: true, // Specify whether the service should automatically start upon OS reboot.
-    disable_restart_on_failure: false, // Services restart on crash by default.
+    restart_policy: RestartPolicy::default(), // Restart on failure by default.
 }).expect("Failed to install");
 ```
 
+### Configuring restart policies
+
+The crate provides a cross-platform `RestartPolicy` enum that allows you to control
+when and how services should be restarted. Different platforms support different levels
+of granularity, and the implementation will use the closest approximation when an exact
+match isn't available.
+
+If you need options specific to any given service manager, you should use that specific
+service manager rather than the generic `ServiceManager` crate.
+
+```rust,no_run
+use service_manager::*;
+use std::ffi::OsString;
+use std::path::PathBuf;
+
+let label: ServiceLabel = "com.example.my-service".parse().unwrap();
+let manager = <dyn ServiceManager>::native()
+    .expect("Failed to detect management platform");
+
+// Example 1: Never restart the service
+manager.install(ServiceInstallCtx {
+    label: label.clone(),
+    program: PathBuf::from("path/to/my-service-executable"),
+    args: vec![OsString::from("--some-arg")],
+    contents: None,
+    username: None,
+    working_directory: None,
+    environment: None,
+    autostart: true,
+    restart_policy: RestartPolicy::Never,
+}).expect("Failed to install");
+
+// Example 2: Always restart regardless of exit status
+manager.install(ServiceInstallCtx {
+    label: label.clone(),
+    program: PathBuf::from("path/to/my-service-executable"),
+    args: vec![OsString::from("--some-arg")],
+    contents: None,
+    username: None,
+    working_directory: None,
+    environment: None,
+    autostart: true,
+    restart_policy: RestartPolicy::Always { delay_secs: Some(10) },
+}).expect("Failed to install");
+
+// Example 3: Restart only on failure (non-zero exit)
+manager.install(ServiceInstallCtx {
+    label: label.clone(),
+    program: PathBuf::from("path/to/my-service-executable"),
+    args: vec![OsString::from("--some-arg")],
+    contents: None,
+    username: None,
+    working_directory: None,
+    environment: None,
+    autostart: true,
+    restart_policy: RestartPolicy::OnFailure { delay_secs: Some(5) },
+}).expect("Failed to install");
+```
+
+**Platform support:**
+- **systemd (Linux)**: Supports all restart policies natively
+- **launchd (macOS)**: Only supports Never vs Always/OnFailure (uses KeepAlive boolean)
+- **WinSW (Windows)**: Supports all restart policies
+- **OpenRC/rc.d/sc.exe**: Limited or no restart support; warnings logged for unsupported policies
+
 ### Running tests
 
 For testing purposes, we use a separate crate called `system-tests` and

src/launchd.rs

@@ -1,8 +1,8 @@
 use crate::utils::wrap_output;
 
 use super::{
-    utils, ServiceInstallCtx, ServiceLevel, ServiceManager, ServiceStartCtx, ServiceStopCtx,
-    ServiceUninstallCtx,
+    utils, RestartPolicy, ServiceInstallCtx, ServiceLevel, ServiceManager, ServiceStartCtx,
+    ServiceStopCtx, ServiceUninstallCtx,
 };
 use plist::{Dictionary, Value};
 use std::{
@@ -25,13 +25,14 @@ pub struct LaunchdConfig {
 /// Configuration settings tied to launchd services during installation
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct LaunchdInstallConfig {
-    /// If true, will include `KeepAlive` flag set to true
-    pub keep_alive: bool,
+    /// Launchd-specific keep-alive setting. If `Some`, this takes precedence over the generic
+    /// `RestartPolicy` in `ServiceInstallCtx`. If `None`, the generic policy is used.
+    pub keep_alive: Option<bool>,
 }
 
 impl Default for LaunchdInstallConfig {
     fn default() -> Self {
-        Self { keep_alive: true }
+        Self { keep_alive: None }
     }
 }
 
@@ -121,7 +122,7 @@ impl ServiceManager for LaunchdServiceManager {
                 ctx.working_directory.clone(),
                 ctx.environment.clone(),
                 ctx.autostart,
-                ctx.disable_restart_on_failure
+                ctx.restart_policy,
             ),
         };
 
@@ -276,7 +277,7 @@ fn make_plist<'a>(
     working_directory: Option<PathBuf>,
     environment: Option<Vec<(String, String)>>,
     autostart: bool,
-    disable_restart_on_failure: bool,
+    restart_policy: RestartPolicy,
 ) -> String {
     let mut dict = Dictionary::new();
 
@@ -290,8 +291,63 @@ fn make_plist<'a>(
         Value::Array(program_arguments),
     );
 
-    if !disable_restart_on_failure {
-        dict.insert("KeepAlive".to_string(), Value::Boolean(config.keep_alive));
+    // Handle restart configuration
+    // Priority: launchd-specific config > generic RestartPolicy
+    if let Some(keep_alive) = config.keep_alive {
+        // Use launchd-specific keep_alive configuration
+        if keep_alive {
+            dict.insert("KeepAlive".to_string(), Value::Boolean(true));
+        }
+    } else {
+        // Fall back to generic RestartPolicy
+        // Convert generic `RestartPolicy` to Launchd `KeepAlive`.
+        //
+        // Right now we are only supporting binary restart for Launchd, with `KeepAlive` either set or
+        // not.
+        //
+        // However, Launchd does support further options when `KeepAlive` is set, e.g.,
+        // `SuccessfulExit`. These could be extensions for the future.
+        match restart_policy {
+            RestartPolicy::Never => {
+                // Don't set KeepAlive
+            }
+            RestartPolicy::Always { delay_secs } => {
+                dict.insert("KeepAlive".to_string(), Value::Boolean(true));
+                if delay_secs.is_some() {
+                    log::warn!(
+                        "Launchd does not support restart delays; delay_secs will be ignored for service '{}'",
+                        label
+                    );
+                }
+            }
+            RestartPolicy::OnFailure { delay_secs } => {
+                dict.insert("KeepAlive".to_string(), Value::Boolean(true));
+                log::warn!(
+                    "Right now we don't have more granular restart support for Launchd so the service will always restart; using KeepAlive=true for service '{}'",
+                    label
+                );
+                if delay_secs.is_some() {
+                    log::warn!(
+                        "Launchd does not support restart delays; delay_secs will be ignored for service '{}'",
+                        label
+                    );
+                }
+            }
+            RestartPolicy::OnSuccess { delay_secs } => {
+                // Create KeepAlive dictionary with SuccessfulExit=false
+                // This means: restart when exit is successful (exit code 0)
+                let mut keep_alive_dict = Dictionary::new();
+                keep_alive_dict.insert("SuccessfulExit".to_string(), Value::Boolean(false));
+                dict.insert("KeepAlive".to_string(), Value::Dictionary(keep_alive_dict));
+
+                if delay_secs.is_some() {
+                    log::warn!(
+                        "Launchd does not support restart delays; delay_secs will be ignored for service '{}'",
+                        label
+                    );
+                }
+            }
+        }
     }
 
     if let Some(username) = username {

src/lib.rs

@@ -111,6 +111,62 @@ pub enum ServiceLevel {
     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>,
+    },
+
+    /// 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 }
+    }
+}
+
 /// Represents the status of a service
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub enum ServiceStatus {
@@ -245,10 +301,14 @@ pub struct ServiceInstallCtx {
     /// Specify whether the service should automatically start on reboot
     pub autostart: bool,
 
-    /// Optionally disable a service from restarting when it exits with a failure
+    /// 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.
     ///
-    /// This could overwrite the platform specific service manager config.
-    pub disable_restart_on_failure: bool,
+    /// Defaults to [`RestartPolicy::OnFailure`] if not specified.
+    pub restart_policy: RestartPolicy,
 }
 
 impl ServiceInstallCtx {

src/openrc.rs

@@ -1,8 +1,8 @@
 use crate::utils::wrap_output;
 
 use super::{
-    utils, ServiceInstallCtx, ServiceLevel, ServiceManager, ServiceStartCtx, ServiceStopCtx,
-    ServiceUninstallCtx,
+    utils, RestartPolicy, ServiceInstallCtx, ServiceLevel, ServiceManager, ServiceStartCtx,
+    ServiceStopCtx, ServiceUninstallCtx,
 };
 use std::{
     ffi::{OsStr, OsString},
@@ -50,6 +50,20 @@ impl ServiceManager for OpenRcServiceManager {
     }
 
     fn install(&self, ctx: ServiceInstallCtx) -> io::Result<()> {
+        // OpenRC doesn't support restart policies in the basic implementation.
+        // Log a warning if user requested anything other than `Never`.
+        match ctx.restart_policy {
+            RestartPolicy::Never => {
+                // This is fine, OpenRC services don't restart by default
+            }
+            RestartPolicy::Always { .. } | RestartPolicy::OnFailure { .. } | RestartPolicy::OnSuccess { .. } => {
+                log::warn!(
+                    "OpenRC does not support automatic restart policies; service '{}' will not restart automatically",
+                    ctx.label.to_script_name()
+                );
+            }
+        }
+
         let dir_path = service_dir_path();
         std::fs::create_dir_all(&dir_path)?;
 
@@ -84,11 +98,7 @@ impl ServiceManager for OpenRcServiceManager {
 
     fn uninstall(&self, ctx: ServiceUninstallCtx) -> io::Result<()> {
         // If the script is configured to run at boot, remove it
-        let _ = rc_update(
-            "del",
-            &ctx.label.to_script_name(),
-            [OsStr::new("default")],
-        );
+        let _ = rc_update("del", &ctx.label.to_script_name(), [OsStr::new("default")]);
 
         // Uninstall service by removing the script
         std::fs::remove_file(service_dir_path().join(&ctx.label.to_script_name()))