# How Services Are Exposed in vorssaint-utils: Singleton Patterns and XPC Architecture

> Discover how vorssaint-utils exposes services via static singletons and XPC architecture. Learn about protocol-based access and dependency injection for robust system operations.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-10

---

**Services in vorssaint-utils are exposed globally through static `shared` singleton properties, with privileged system operations delegated to XPC helper processes via `@objc` protocols, while internal implementations remain abstracted behind dependency-injection-friendly interfaces.**

The `vorssaint-utils` repository organizes its system-level functionality into modular service layers located under `Sources/Vorssaint/Services`. Understanding how services are exposed in vorssaint-utils reveals a consistent architectural pattern that balances global accessibility with testability and security. The codebase relies on **Swift singletons** for efficient instance management while leveraging **macOS XPC** mechanisms for operations requiring elevated privileges.

## Service Location and Core Architecture

All functional logic resides in discrete service modules within `Sources/Vorssaint/Services`. Each service is implemented as a Swift **class or struct** that encapsulates a specific piece of system-level functionality, such as fan control, mouse-button shortcuts, clipboard history, or window layout management. This modular organization ensures that system interactions remain isolated from UI code, promoting maintainability and clear separation of concerns.

## Global Access Through the Singleton Pattern

The primary exposure mechanism uses a **static singleton accessor** pattern. Each service exposes a globally reachable instance through a `public static let shared` property, eliminating the need for complex dependency injection containers in production code while ensuring only one instance manages a particular system resource.

In [`Sources/Vorssaint/Services/FanControl/FanControlService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/FanControl/FanControlService.swift), the pattern appears as:

```swift
public final class FanControlService {
    public static let shared = FanControlService()
    
    private var connection: NSXPCConnection?
    
    public func setFanSpeed(_ speed: Int, for identifier: FanID) {
        // Implementation logic
    }
}

```

The **lazy instantiation** occurs when `shared` is first accessed, ensuring services consume resources only when actively used. The application's entry point in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) and various UI controllers reference these singletons directly to coordinate system behavior with user interface elements.

## Privileged Operations via XPC Communication

For operations requiring elevated privileges—such as hardware fan control—services cannot execute directly within the main application sandbox. Instead, `vorssaint-utils` employs **XPC (inter-process communication)** through `NSXPCConnection` to communicate with separate helper binaries running with higher privileges.

The `FanControlService` creates and manages an XPC connection defined by an `@objc` protocol in [`Sources/Vorssaint/Services/FanControl/FanControlXPC.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/FanControl/FanControlXPC.swift). The protocol specifies type-safe message shapes for cross-process communication:

```swift
@objc protocol FanControlXPCProtocol {
    func setFanSpeed(_ speed: Int, for identifier: FanID, withReply reply: @escaping (Data?) -> Void)
    func getCurrentSpeed(withReply reply: @escaping (Data) -> Void)
}

```

The service forwards privileged calls to the helper process while maintaining a clean public API for consumers, effectively isolating security-sensitive operations from the main application code.

## Protocol-Based Abstraction and Testing

Beyond singleton concrete implementations, each service typically defines a corresponding **support protocol** in a `*Support.swift` file. For example, [`Sources/Vorssaint/Services/FanControl/FanControlSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/FanControl/FanControlSupport.swift) defines the `FanControlSupport` protocol, which abstracts the concrete service implementation.

This approach enables **dependency injection** during testing or when alternative implementations are required. Callers depend on the protocol rather than concrete classes, allowing mock objects to substitute for actual system services during unit tests. The pattern appears consistently across the codebase, from [`MouseButtonShortcutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MouseButtonShortcutSupport.swift) to [`WindowLayoutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutSupport.swift).

## Anatomy of a Service Implementation

A complete service implementation combines these architectural elements into a standardized structure:

```swift
// Sources/Vorssaint/Services/FanControl/FanControlService.swift
public final class FanControlService: FanControlSupport {
    public static let shared = FanControlService()
    
    private var connection: NSXPCConnection?
    
    // Public API exposed to consumers
    public func setFanSpeed(_ speed: Int, for identifier: FanID) {
        guard let proxy = proxy(errorHandler: { _ in }) else { return }
        proxy.setFanSpeed(speed, for: identifier) { _ in }
    }
    
    // Private XPC helper access
    private func proxy(errorHandler: @escaping (Error) -> Void) -> FanControlXPCProtocol? {
        // Connection management logic
        return connection?.remoteObjectProxyWithErrorHandler(errorHandler) as? FanControlXPCProtocol
    }
}

```

The [`Sources/Vorssaint/Services/QuickTools/ScreenshotService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/QuickTools/ScreenshotService.swift) and [`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift) follow identical structural patterns, demonstrating architectural consistency across functional domains.

## Practical Integration Examples

### Controlling Hardware Components

Access the fan control service directly through its singleton to adjust system hardware:

```swift
import Vorssaint

// Set CPU fan to 50% maximum speed
FanControlService.shared.setFanSpeed(50, for: .cpu)

```

### Registering Global Shortcuts

The mouse button shortcut service exposes similar singleton-based access for registering system-wide hotkeys:

```swift
import Vorssaint

MouseButtonShortcutService.shared.registerHotkey(
    key: .f13,
    modifiers: [.control, .option],
    action: { print("Custom shortcut triggered") }
)

```

### Advanced XPC Interaction

For advanced use cases requiring raw XPC communication, access the underlying proxy directly:

```swift
if let proxy = FanControlService.shared.proxy(errorHandler: { _ in }) {
    proxy.getCurrentSpeed { data in
        let speed = data.withUnsafeBytes { $0.load(as: Int.self) }
        print("Current fan speed: \(speed)")
    }
}

```

## Summary

- Services reside under `Sources/Vorssaint/Services` as Swift classes or structs encapsulating specific system functionality.
- **Static `shared` properties** provide global, lazy-initialized access to service instances from any application context.
- **XPC connections** in `*XPC.swift` files handle privileged operations via separate helper binaries, defined by `@objc` protocols like `FanControlXPCProtocol`.
- **Support protocols** in `*Support.swift` files enable dependency injection and testability by abstracting concrete implementations.
- The architecture maintains a consistent pattern across all modules, from [`FanControlService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlService.swift) to [`ClipboardHistorySupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistorySupport.swift), balancing convenience with security and testability.

## Frequently Asked Questions

### What pattern does vorssaint-utils use to expose services globally?

The repository uses a **singleton pattern** where each service defines a `public static let shared` property. This approach, visible in files like [`FanControlService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlService.swift), provides global access while maintaining single-instance semantics for resource management.

### How does vorssaint-utils handle privileged system operations?

Privileged operations utilize **XPC (Inter-Process Communication)**. Services like `FanControlService` create `NSXPCConnection` instances to communicate with privileged helper binaries. The communication protocol defines methods in files like [`FanControlXPC.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlXPC.swift), ensuring type-safe message passing between the main app and elevated helpers.

### What is the purpose of the Support.swift files in the Services directory?

The `*Support.swift` files define **protocols** that abstract the concrete service implementations. This enables protocol-based dependency injection for testing and allows different implementations to satisfy the same interface. For example, [`FanControlSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlSupport.swift) defines the contract that `FanControlService` fulfills.

### How are services initialized in the application lifecycle?

Services employ **lazy initialization** through their `shared` properties. No explicit startup registration is required; the first access to `ServiceName.shared` triggers instantiation. This pattern appears throughout [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) and UI controllers, where services are referenced only when specific functionality is needed.