sal/service_manager
Mahmoud-Emad 131d978450 feat: Add service manager support
- Add a new service manager crate for dynamic service management
- Integrate service manager with Rhai for scripting
- Provide examples for circle worker management and basic usage
- Add comprehensive tests for service lifecycle and error handling
- Implement cross-platform support for macOS and Linux (zinit/systemd)
2025-07-01 18:00:21 +03:00
..
src feat: Add service manager support 2025-07-01 18:00:21 +03:00
tests feat: Add service manager support 2025-07-01 18:00:21 +03:00
Cargo.toml feat: Add service manager support 2025-07-01 18:00:21 +03:00
plan_to_fix.md feat: Add service manager support 2025-07-01 18:00:21 +03:00
README.md feat: Add service manager support 2025-07-01 18:00:21 +03:00

SAL Service Manager

Crates.io Documentation

A cross-platform service management library for the System Abstraction Layer (SAL). This crate provides a unified interface for managing system services across different platforms, enabling dynamic deployment of workers and services.

Features

  • Cross-platform service management - Unified API across macOS and Linux
  • Dynamic worker deployment - Perfect for circle workers and on-demand services
  • Platform-specific implementations:
    • macOS: Uses launchctl with plist management
    • Linux: Uses zinit for lightweight service management (systemd also available)
  • Complete lifecycle management - Start, stop, restart, status monitoring, and log retrieval
  • Service configuration - Environment variables, working directories, auto-restart
  • Production-ready - Comprehensive error handling and resource management

Usage

Add this to your Cargo.toml:

[dependencies]
sal-service-manager = "0.1.0"

Or use it as part of the SAL ecosystem:

[dependencies]
sal = { version = "0.1.0", features = ["service_manager"] }

Primary Use Case: Dynamic Circle Worker Management

This service manager was designed specifically for dynamic deployment of circle workers in freezone environments. When a new resident registers, you can instantly launch a dedicated circle worker:

use sal_service_manager::{create_service_manager, ServiceConfig};
use std::collections::HashMap;

// New resident registration triggers worker creation
fn deploy_circle_worker(resident_id: &str) -> Result<(), Box<dyn std::error::Error>> {
    let manager = create_service_manager();

    let mut env = HashMap::new();
    env.insert("RESIDENT_ID".to_string(), resident_id.to_string());
    env.insert("WORKER_TYPE".to_string(), "circle".to_string());

    let config = ServiceConfig {
        name: format!("circle-worker-{}", resident_id),
        binary_path: "/usr/bin/circle-worker".to_string(),
        args: vec!["--resident".to_string(), resident_id.to_string()],
        working_directory: Some("/var/lib/circle-workers".to_string()),
        environment: env,
        auto_restart: true,
    };

    // Deploy the worker
    manager.start(&config)?;
    println!("✅ Circle worker deployed for resident: {}", resident_id);

    Ok(())
}

Basic Usage Example

Here is an example of the core service management API:

use sal_service_manager::{create_service_manager, ServiceConfig};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service_manager = create_service_manager();

    let config = ServiceConfig {
        name: "my-service".to_string(),
        binary_path: "/usr/local/bin/my-service-executable".to_string(),
        args: vec!["--config".to_string(), "/etc/my-service.conf".to_string()],
        working_directory: Some("/var/tmp".to_string()),
        environment: HashMap::new(),
        auto_restart: true,
    };

    // Start a new service
    service_manager.start(&config)?;

    // Get the status of the service
    let status = service_manager.status("my-service")?;
    println!("Service status: {:?}", status);

    // Stop the service
    service_manager.stop("my-service")?;

    Ok(())
}

Examples

Comprehensive examples are available in the SAL examples directory:

Circle Worker Manager Example

The primary use case - dynamically launching circle workers for new freezone residents:

# Run the circle worker management example
herodo examples/service_manager/circle_worker_manager.rhai

This example demonstrates:

  • Creating service configurations for circle workers
  • Complete service lifecycle management
  • Error handling and status monitoring
  • Service cleanup and removal

Basic Usage Example

A simpler example showing the core API:

# Run the basic usage example
herodo examples/service_manager/basic_usage.rhai

See examples/service_manager/README.md for detailed documentation.

Prerequisites

Linux (zinit)

Make sure zinit is installed and running:

# Start zinit with default socket
zinit -s /tmp/zinit.sock init

macOS (launchctl)

No additional setup required - uses the built-in launchctl system.

Platform Support

  • macOS: Full support using launchctl for service management
  • Linux: Full support using zinit for service management (systemd also available as alternative)
  • Windows: Not currently supported