Swift Service Lifecycle

Swift Service Lifecycle uses two primary abstractions to manage application startup and shutdown:

1. Service protocol: You model long-running work by implementing this protocol. It requires a single method: func run() async throws. A service can be a struct, class, or actor.

2. ServiceGroup actor: This orchestrates multiple services. When you call run() on a ServiceGroup, it spawns a child task for each provided service and executes their run() methods. The group also manages signal listeners (like SIGTERM) to trigger a graceful shutdown across all services when a signal is received.

This design integrates natively with Swift's Structured Concurrency.

import ServiceLifecycle
import Logging

// 1. Implement the Service protocol
struct FooService: Service {
    func run() async throws {
        print("FooService starting")
        try await Task.sleep(for: .seconds(10))
        print("FooService done")
    }
}

@main
struct Application {
    static let logger = Logger(label: "Application")
    
    static func main() async throws {
        let service1 = FooService()
        let service2 = FooService()
        
        // 2. Orchestrate services with ServiceGroup
        let serviceGroup = ServiceGroup(
            services: [service1, service2],
            gracefulShutdownSignals: [.sigterm],
            logger: logger
        )
        
        try await serviceGroup.run()
    }
}

Graceful shutdown is an opt-in mechanism that allows your service to perform cleanup (like closing sockets or finishing active requests) before being forcefully terminated. This is distinct from task cancellation.

Using withGracefulShutdownHandler

Use the withGracefulShutdownHandler(operation:onGracefulShutdown:) function to define what happens when a shutdown signal is received. The operation block contains your main logic, and the onGracefulShutdown block contains your cleanup logic.

Using cancelOnGracefulShutdown()

For services that rely on AsyncSequence (like timers or connection streams), ServiceLifecycle provides a convenience method .cancelOnGracefulShutdown() to automatically trigger cancellation of the sequence when a graceful shutdown occurs.

// Example: Server with graceful shutdown
public actor TCPEchoServer: Service {
  public init() { }
  public func run() async throws {
    await withGracefulShutdownHandler {
        for connection in self.listeningSocket.connections {
          // Handle incoming connections
        }
    } onGracefulShutdown: {
        self.listeningSocket.close()
    }
  }
}

// Example: Client using cancelOnGracefulShutdown()
public actor TCPEchoClient: Service {
  public init() { }
  public func run() async throws {
    for await _ in AsyncTimerSequence(interval: .seconds(1), clock: .continuous).cancelOnGracefulShutdown() {
      self.sendKeepAlivePings()
    }
  }
  private func sendKeepAlivePings() async { ... }
}

The ServiceGroup actor is used to orchestrate multiple Service instances in an application. It runs each service in a separate child task and manages their lifecycle.

Dependency Management: ServiceGroup infers dependencies based on the order of the services array passed to the initializer. Services with a higher index can depend on services with a lower index. To ensure a dependency is available, place the dependency service earlier in the array.

To use it, initialize ServiceGroup with your services and a Logger, then call run() within an asynchronous context (like @main).

import ServiceLifecycle
import Logging

@main
struct Application {
  static let logger = Logger(label: "Application")

  static func main() async throws {
    let fooService = FooService()
    let barService = BarService(fooService: fooService)

    let serviceGroup = ServiceGroup(
      // We encode the dependency hierarchy by putting fooService first
      services: [fooService, barService],
      logger: logger
    )

    try await serviceGroup.run()
  }
}

Graceful shutdown is a non-forceful alternative to task cancellation. It allows services to clean up resources or finish ongoing work before exiting.

To enable graceful shutdown at the application level, configure ServiceGroup with gracefulShutdownSignals (e.g., [.sigterm]).

To make your service logic responsive to a graceful shutdown, use the cancelOnGracefulShutdown() method on any AsyncSequence. This ensures that loops iterating over streams or requests terminate when the shutdown signal is received.

Note: ServiceGroup shuts down services in reverse startup order, waiting for each service's run() method to return before proceeding to the next.

import ServiceLifecycle
import Logging

struct StreamingService: Service {
  // ... implementation ...

  func run() async throws {
    await withDiscardingTaskGroup { group in
      // Use cancelOnGracefulShutdown() to stop iteration during shutdown
      for stream in makeStreams().cancelOnGracefulShutdown() {
        group.addTask {
          await streamHandler(stream.requestStream, stream.responseWriter)
        }
      }
    }
  }
}

@main
struct Application {
  static let logger = Logger(label: "Application")

  static func main() async throws {
    let streamingService = StreamingService(streamHandler: { requestStream, responseWriter in
      // Use cancelOnGracefulShutdown() inside handlers as well
      for await request in requestStream.cancelOnGracefulShutdown() {
        responseWriter.write("response")
      }
    })

    let serviceGroup = ServiceGroup(
      services: [streamingService],
      gracefulShutdownSignals: [.sigterm],
      logger: logger
    )

    try await serviceGroup.run()
  }
}

To allow your library's components to be coordinated by a ServiceGroup, conform your types to the Service protocol. The protocol requires a single run() method that contains the service's long-running work.

Best Practices

1. Use Structured Concurrency: Instead of spawning unstructured Task { ... } blocks in an init(), implement the work inside run(). This ensures that when the service is cancelled, the work is automatically cancelled via Swift's structured concurrency propagation.
2. Handle Termination: Returning from run() or throwing an error is interpreted as a failure. By default, this causes a ServiceGroup to cancel all other services in the group.
3. Implement Cancellation: Ensure your run() method reacts to cancellation. If you consume an AsyncSequence or call other cancellation-aware async methods, this is often handled automatically.

public actor TCPEchoClient: Service {
  public init() { }

  public func run() async throws {
    for await _ in AsyncTimerSequence(interval: .seconds(1), clock: .continuous) {
      self.sendKeepAlivePings()
    }
  }

  private func sendKeepAlivePings() async { ... }
}