66 Commits
Author SHA1 Message Date
Kohei Ota (inductor) c55297914e Fix flaky testRun_whenServiceThrows_andShutdownGracefully (#260)
## Motivation


[`testRun_whenServiceThrows_andShutdownGracefully`](https://github.com/swift-server/swift-service-lifecycle/blob/5e3b0e9/Tests/ServiceLifecycleTests/ServiceGroupTests.swift#L433-L441)
is flaky. It failed on the Swift 6.3 Linux job:
https://github.com/swift-server/swift-service-lifecycle/actions/runs/35197849503/job/105125249343

After service3 exits, the test pings service1 and expects `.runPing`
before `.shutdownGracefully`. But the service group sends the graceful
shutdown to service1 as soon as service3 exits, so the two events can
arrive in either order.

## Modifications

Wait for `.shutdownGracefully` on service1 before pinging it, like
`testRun_whenServiceThrows_andShutdownGracefully_andOtherServiceThrows`
already does.

## Result

The test no longer depends on the order of the two events.

`ServiceGroupTests` pass locally with Swift 6.3, and `swift format lint
--strict` passes.
2026-10-01 10:39:56 +00:00
Muhammadjon Marufov 5e3b0e9a1e Fix dispatch source leaks in UnixSignalsSequence (#258)
Fixes #256.

## Motivation

`UnixSignalsSequence` keeps dispatch signal sources alive after the
sequence and its iterator are released. The event handler captures the
whole `Source` value, which holds the `DispatchSource`, creating a
retain cycle.

## Modifications

- Keep the sources on `Storage` and cancel them in `deinit`.
- Resume sources skipped when initialization is cancelled so libdispatch
can run cancellation cleanup and release their handlers.
- Add regression tests for normal teardown and cancelled initialization.
The teardown test waits for cancellation because the registration
callback can briefly retain `Storage` after initialization returns.

## Result

Sources are cleaned up after the last sequence or iterator releases the
storage, including when initialization is cancelled.

In the macOS reproducer, 2,000 create/drop iterations went from 2,005
live dispatch sources before the fix to 5 afterward, matching the
zero-iteration control. These measurements were made on macOS only.

All 10 UnixSignals tests pass locally in release mode on macOS with
Swift 6.3.3 and the CI warning, explicit-import, and Sendable flags.
Strict formatting and `git diff --check` also pass. The weak-reference
test has not been run locally on Linux; its first Linux validation will
be in CI.
2026-09-14 12:59:27 +00:00
Aryan Singh K. 7f9326b032 Remember graceful shutdown requested before run (#250)
Closes #248

## Summary
- remember a graceful-shutdown request made while the service group is
still initial
- start configured services when run() is eventually called, then
deliver the pending request through the existing graceful-shutdown path
- ignore services added after a pre-start shutdown request
- add a regression test covering service startup, graceful shutdown, and
normal completion

## Validation
- swift test
- 70 tests passed
- git diff --check
2026-08-09 17:16:59 +02:00
卓林and赖卓林 0c3343fa54 Default ServiceGroup logger to Logger.current (#252)
Fixes #251

## Summary
- Raise the minimum swift-log dependency to 1.14.0, which provides the
task-local Logger.current API.
- Default ServiceGroup's logger parameter to Logger.current so callers
can inherit the current task-local logger.
- Add a regression test that constructs and runs ServiceGroup without an
explicit logger.

## Design
The change is limited to the current ServiceGroup convenience
initializer. Existing explicit logger calls and
ServiceGroupConfiguration initializers remain unchanged.

## Validation
- Focused test passed: swift test --disable-sandbox --filter
ServiceGroupTests/testRun_withDefaultLogger
- Full test suite passed: swift test --disable-sandbox
- Result: 62 ServiceLifecycle/XCTest tests and all Swift Testing suites
passed.
- git diff --check passed.

Tests used the Xcode 27 beta developer toolchain because the active
Command Line Tools installation does not provide XCTest.

Co-authored-by: 赖卓林 <zhuolin@laizhuolindeMac-mini.local>
2026-08-09 17:14:46 +02:00
Vladimir Kukushkin db7637f5cd Support custom service names (#233)
Add an extra `serviceName` field to the `ServiceConfiguration` to
customize SSL logs metadata.

Motivation:

This would allow giving meaningful name to services and service groups.
Closes #220.

Modifications:

- Added `.serviceName` to the `ServiceConfiguration`.
- Added a new initializer for `ServiceConfiguration` with `serviceName`
param.
- Logs now use `.serviceName` instead of `.service` for `sl-service`
metadata value.

Result:

Different `ServiceGroup`s can be distinguished in the logs.
2026-03-30 21:37:52 +01:00
Gus Cairo 89888196dd Add missing availability (#228)
https://github.com/swift-server/swift-service-lifecycle/pull/227 added a
`ClosureService`, but we forgot to add availability guards to make sure
Swift Concurrency is available.
2026-02-20 17:06:14 +01:00
Gus Cairo 9db4c30383 Add a ClosureService (#227)
This PR adds a `ClosureService`.

You can use a `ClosureService` to create a lightweight, inline `Service`
without defining and conforming a dedicated type.
2026-02-20 14:49:38 +01:00
Franz Busch 250ca9c389 Fix weak var warning on 6.2 and above (#223) 2026-02-06 14:53:40 +01:00
Franz BuschandJoannis Orlandos 1de37290c0 Enable 6.2 CI and enable Windows CI (#215)
Co-authored-by: Joannis Orlandos <joannis@orlandos.nl>
2025-11-03 19:57:02 +01:00
Franz Busch 0fcc4c9c2d Include the service name in the serviceFinishedUnexpectedly error (#217)
## Motivation

To aid debugging and troubleshooting, it is helpful to understand which
Service led to the error.

## Modifications

Add the service name to the `serviceFinishedUnexpectedly` error.

## Result

Easier to debug failing services.
2025-10-08 09:40:06 +02:00
George Barnett e718730918 Remove platforms from manifest (#203)
Motivation:

Adding or raising the deployment platforms in the package manifest is a
SemVer major breaking change as consumers must also add or raise their
deployment platforms. This is a known limitation of SwiftPM.

Unforunately this means that it's very difficult for non-leaf packages
to adopt packages which declare their platforms in the manifest. Doing
so puts the brakes on adoption and ecosystem growth. For 'core' packages
like this one availability constraints should be expressed on
declarations rather than in the manifest.

Modifications:

- Remove platforms from the package manifest
- Add availability annotations to types which require it

Result:

This package can be more widely adopted
2025-04-23 08:59:36 +00:00
Simon Leeb 7ee57f99fb Support adding services while ServiceGroup is running (#199)
somewhat straight-forward implementation draft of 
https://github.com/swift-server/swift-service-lifecycle/issues/185

choices were made, what do we think?
2025-03-08 11:16:14 +00:00
Joannis Orlandos e2b442cc73 Import the Android module if available, since glibc and musl are unavailable on Android (#198)
I don't expect us to run CI against this until that's more formally
supported, but this would greatly help adoption of server-focused
packages on Android
2025-02-17 07:52:11 +00:00
Franz Busch f70b838872 [CI] Adopt GitHub actions (#187)
# Motivation

We want to switch our CI to GitHub actions.

# Modification

This PR sets up the reusable workflows from NIO.

# Result

More modern CI.
2024-10-31 12:17:45 +01:00
Si Beaumont 12a031bcc1 Support compiling against Musl (#182) 2024-05-08 09:08:21 -07:00
Iceman 877d7494e2 Global cancelOnGracefulShutdown returns non nil value (#181)
* Fix global cancelOnGracefulShutdown return type

* Deprecate cancelOnGracefulShutdown and add cancelWhenGracefulShutdown

* Add doc comment even for the deprecated function
2024-04-26 14:12:25 +01:00
Fabian Fett d7fe0e7314 cancelOnGracefulShutdown hangs, if cancellation is not immediately (#177)
* Add test case

* Fix tests

* Make code simpler

* Fix Sendable

* swift-format
2024-02-22 11:43:51 +00:00
Adam Fowler 3a186eae18 Add withTaskCancellationOrGracefulShutdownHandler (#176)
* Add withTaskCancellationOrGracefulShutdownHandler

* Test withTaskCancellationOrGracefulShutdownHandler
2024-02-19 08:15:38 +00:00
Franz Busch 55f45e39dd Conform ServiceGroup to Service (#172) 2024-02-10 17:02:43 +00:00
Franz Busch cdd6040d0d Fix logic issues during graceful shutdown (#171)
* Fix logic issues during graceful shutdown

# Motivation

This should fix the remaining issues raised in https://github.com/swift-server/swift-service-lifecycle/pull/166. The problem here was that if a service finished/threw out of order then we were wrongly treating this as if the service that we are currently shutting down finished.

# Modification
This PR ensures that we use the same `services` array during the graceful shutdown to nil out services that have finished. This way we correctly keep track of any service that finished. Additionally, there was a separate bug where we started to shutdown the next service to early if another service threw and had the termination behaviour of `shutdownGracefully`.

# Result
No more incorrect shutdown orderings.

* Fix one more race condition
2024-01-26 12:05:08 +00:00
Franz Busch 0907d4aa34 Make sure we return after gracefully shutdown (#170)
* Make sure we return after gracefully shutdown

# Motivation

After calling `shutdownGracefully` in our `ServiceGroup` we know that one of two things happened:
1. We got an error so something went wrong
2. We got no error so all services finished

In the 2. case, there might still be a few child tasks in the task group e.g. the graceful shutdown timeout task. We are currently still iterating the remaining child task results which might lead into unexpected fatal errors.

# Modification
This PR makes sure that after we have successfully shutdown we are stopping iterating the child task results.

# Result
No more unexpected fatal errors.

* Fix flaky test
2024-01-25 06:15:50 -08:00
Franz Busch 026ed0d5b1 Adopt AsyncAlgorithms (#167)
# Motivation

Now that `swift-async-algorithms` has a `1.0.0` tag we can depend on it instead of shipping our own version of `merge`.
2023-12-05 09:39:21 +00:00
Franz Busch d673fdc912 Add a configurable escalation behaviour (#162)
* Add a configurable escalation behaviour

# Motivation
The service group is often running multiple services and orchestrates shutdown for them. We have seen that sometimes some services never shutdown nor do they respond to task cancellation properly. This can become quite problematic when the whole application is waiting for a service to cancel and otherwise appears to be healthy but in reality can't serve any traffic.

# Modification
This PR adds a new configuration to escalate both graceful shutdown and cancellation. The escalation order is graceful shutdown -> task cancellation -> `fatalError`. The `fatalError` acts a last resort to make sure applications are never stuck.

* George review

* Fix some smaller issues
2023-10-13 06:02:25 -07:00
Franz Busch b71a961c12 Add support for SIGWINCH (#161)
# Motivation
`SIGWINCH` is sent to applications when the window resizes. This is useful to observe for terminal applications to reformat the logging one resize.

# Modification
This PR adds support for `SIGWINCH` in `UnixSignal`s.
2023-10-10 19:31:12 +01:00
Gustavo Cairo 45a31b6f1c Add async gracefulShutdown (#158) 2023-09-13 14:37:09 +01:00
Franz Busch 5b1c2defff Vendor swift-async-algorithms (#157)
# Motivation
We are about to tag a `2.0.0` and cannot depend on any non major package.

# Modification
This vendors in `swift-async-algorithms` so that we can use the `AsyncMergeSequence`. In the future, once `swift-async-algorithms` is `1.0.0` itself we can swap back.

# Result
No more non-major dependency.
2023-08-24 02:14:41 -07:00
Franz Busch 06ec110192 Propagate service error during graceful shutdown (#153)
# Motivation

When a service threw during graceful shutdown but had its behaviour set to `gracefulShutdown` itself then we were not rethrowing the error.

# Modification
This PR makes sure that the first service that throws an error which doesn't have its `failureTerminationBehavior` to `.ignore` gets rethrown by the `ServiceGroup`.
2023-08-23 11:19:20 +01:00
Franz Busch 98a9396dcb Propagate service error when gracefully shutting down (#152)
# Motivation

Propagate the service error when we shutdown the group after the service threw.
2023-08-22 20:54:36 +01:00
Franz Busch f58dbbfaa9 Add support for return/ThrowBehavior of services (#148)
* Add support for `return/ThrowBehavior` of services

# Motivation

Currently the `ServiceGroup` cancels the whole group when a service returns or throws. This is fine for most server applications but it doesn't work for CLI tools since they mostly want to use the group to orchestrate the services as long as the user command is handled and then return cleanly from the group. Furthermore, even on server setups one might want to customize the behavior of what happens when a service returns/throws e.g. one might want to shutdown the group after their HTTP server throws so that a telemetry service flushes out all the remaining data.

# Modification

This PR does a few things:
1. It creates a new `ServiceConfiguration` and `TerminationBehavior` in the `ServiceGroupConfiguration`. Those can be used to declare the services that are run and what happens when the service returns or throws
2. Adds a new `cancellationSignals` to to the `ServiceGroupConfiguration` which allows cancellation to trigger based on a signal
3. Makes sure that any given service is only retained as long as necessary i.e. when a service returns the group is not retaining it anymore. This allows freeing of resources as early as possible
4. Breaking: Removes the `Hashable` conformance on the configuration structs. This was wrong in the first place and something we should just avoid doing in general.

# Result
We now give the user even more control about the group's behaviors.

* Review

* Review

* Fix CI
2023-08-16 13:22:22 +01:00
Franz Busch 36f71f61d7 Add support for SIGQUIT (#146)
# Motivation
Some applications want to react to `SIGQUIT` which is similar to `SIGINT` but normally maps to a different key `C-\`.

# Modification
This PR adds support for `SIGQUIT` in the `UnixSignal`s module.

# Result
Support for `SIGQUIT`.
2023-08-14 11:18:31 +01:00
Franz Busch 4eaaf079a8 Rename shutdownGracefully to triggerGracefulShutdown on the ServiceGroup (#142) 2023-06-01 09:03:11 +02:00
Simon LeebandSimon Leeb 5074896b5a Fixes cancelOnGracefulShutdown issue (#135) (#136)
Motivation:
+ cancelOnGracefulShutdown was getting stuck on macOS

Modifications:
+ added explicit group.cancelAll() to all execution paths

Co-authored-by: Simon Leeb <simon.leeb@sinformatics.at>
2023-05-11 11:04:39 +01:00
Franz Busch fafab8f7ad Overhaul service lifecycle for Structured Concurrency (#130)
* Overhaul service lifecycle for Structured Concurrency

# Motivation
Since the release of Swift Concurrency the server ecosystem has adopted `async`/`await` in a lot of APIs making the user experience amazing. Another thing that Swift Concurrency introduced is Structured Concurrency which allows to create a task tree that with parent to child relations. Structured Concurrency has many benefits such as automatic cancellation and task local propagation.
The current state of this library predates the introduction of Swift Concurrency and is not inline anymore with how applications are structured that want to leverage Concurrency.

# Modification
This PR overhauls the implementation of service lifecycle completely. The reason for this is that the current implementation is very focused on how NIO based applications work before the introduction of Concurrency. Furthermore, Structured Concurrency is actually replacing part of the current functionality by providing new scoping mechanisms.
The overhauled implementation provides two primitive types. Anew `Service` protocol and a `ServiceRunner`. The former is providing a clear API which services have to conform to so that they can be run by the `ServiceRunner`.

An example usage of the types looks like this

```swift
actor FooService: Service {
    func run() async throws {}

    func shutdownGracefully() async throws {}
}
actor BarService: Service {
    func run() async throws {}

    func shutdownGracefully() async throws {}
}

let fooService = FooService()
let barService = BarService()

let runner = ServiceRunner(
    services: [fooService, barService],
   configuration: .init(),
   logger: logger
)

try await runner.run()
```

# Result
We now have a service lifecycle library that integrates nicely with Structured Concurrency. Its value add is that it solves to complex setup of the task group with the signal handling. Furthermore, it provides a currency type `Service` that can be passed to inject services.

* Remove `shutdownGracefully` method and switch to a handler based approach.

* Code review from George

* Add extensions to `TaskGroup` and `ThrowingTaskGroup`

* Remove long running property

* Documentation

* Fix tests

* Ensure ordering of shutdown

* Test

# Motivation

# Modification

# Result

* Introduce ServiceLifecycleTestKit

* Add AsyncCancelOngracefulShutdownSequence

* Tests and docs for graceful shutdown

# Motivation

# Modification

# Result

* Remove unsafe flags

* Add article for application authors

* Add correct licence and notice information for the things we copied from swift-nio

* Code review

* Remove @_unsafeInheritExectuor

* Code review

* Change log levels, rename to withGracefulShutdownHandler and support nested service runner graceful shutdown

* Add public `shutdownGracefully` method to the service runner

* Code review and expose new cancelOnGracefulShutdown method

* Extend graceful shutdown APIs and tolerate running outside of a `ServiceRunner`

* Rename to `ServiceGroup`

* Enable Swift 5.6 support

* Update soundess dockerfile

* Update Readme

* Make 5.6 build work
2023-04-27 11:56:08 +01:00
tomer doron b7628eb6b3 add docker compose setup for swift 5.8 (#129)
motivation: prepare for swift 5.8

changes:
* update use of Locks to address NIO warnings
* update docker compose setup to use release version of 5.7
* add docker compose setup for 5.8
2023-04-04 19:54:32 -07:00
tomer doron 22363fed31 add the ability to de-register a task (#121)
motivation: sometimes a task needs to be de-registered since the task was manually shutdown outside the lifecycle scope

changes:
* registration APIs now return a registration key which can be used as a cancellation token
* add API to de-register a task
* refactor state to use a registery instead of array of tasks
* add tests
2022-06-13 10:28:56 -07:00
tomer doron 2133bfa9c5 shutdown() should cancel the signal handlers installed by start() (#120) 2022-05-20 18:18:29 -07:00
Josh Wright cea89ce043 Switch up compiler directives for concurrency (#111)
* Switch up compiler directives for concurrency
2021-09-22 11:46:51 -07:00
tomer doron 2744df51f9 unless shutdownIfNotStarted is set to true, dont shutdown items that failed to start (#107)
motivation: improve confusing behavior

changes:
* change startTask to return an array of started tasks instead of an index
* only shutdown successfully started tasks or ones that have explicitly set shutdownIfNotStarted to true
* add and adjust tests
2021-09-03 23:17:55 -07:00
tomer doron c825a58490 shutdown any task that have shutdownIfNotStarted set to true when shutting down a never-started-lifecycle (#109)
motivation: more reliable shutdown in edge cases where lifecycle never gets started

changes: when shutting down an idle lifecycle, try to shutdown any tasks that have shutdownIfNotStarted set to true
2021-09-02 08:48:04 -07:00
tomer doron 66fb9c089b fix repeated shutdown issue on linux (#104)
motivation: repeatedly calling shutdown in linux was broken due to multiple calls to singal() which work on darwin but not linux

changes:
* conditionalize the call to signal to once per process
* add test
2021-08-19 17:23:03 -07:00
tomer doron 7f70674c22 add handlers that support async functions (#99)
motivation: async/await is coming in 5.5, take first steps to support it

changes:
* introduce handler initializers that takes async functions (@escaping () async throws -> Void, @escaping () async throws -> State)
* add tests
2021-05-12 21:41:15 -07:00
tomer doron 4714c3cdfa add lifecycle metrics (#93)
motivation: startup/shutdown metrics are important for real-life services, for example spike in start metrics indicates a crash-loop

changes:
* add start and shutdown counters to ComponentLifecycle
* add start and shutdown timers to report duration of startup and shutdown operations
2021-03-18 11:39:26 -07:00
tomer doron e6b78a807b add support for stateful handler (#84)
motivation: allow lifecycle handlers to have the library manage the state for them so they do not need to do that manually

changes:
* introduce LifecycleStartHandler and LifecycleShutdownHandler which can handle state on behalf of the lifecycle item
* add registerStateful function to regsiter stateful handlers
* add tests
2021-03-13 11:29:28 -08:00
tomer doron faa9f17905 expose the underlying lifecycle for composition reasons (#70)
motivation: application frameworks thae use ServiceLifecycle may need to expose their underlying  lifecycle so they can be also composed into larger systems

changes:
* expose ServiceLifecycle::underlying
* make sure backtrace installer is only called once per process
* add swift-atomics dependency (>=5.2 and above)
* add atomic helper (<5.2)
2021-03-13 11:20:42 -08:00
tomer doron a7356e142b add semantics for stopping tasks that have no start handler (#77)
motivation: address shutdown for tasks which allocate resources on construction. before this change, only tasks that have been started are shutdown, this creates an issue when the resources are allocated on construction since the item may not get started at all (for example due to error in earlier task) and thus will never be shutdown and the resources will leak.

changes: add sematics to request shutdown even if not started, and assume this sematics when registering with start: .none or with registerShutdown
2020-10-26 16:12:50 -07:00
tomer doron 3a02d48c95 abstract registration functions into a protocol (#75)
motivation: allow frameworks that want to expose the lifecycle so that their downstream dependencies could register additional items

changes: abstract registration functions into a protocol and conform ComponentLifecycle and ServiceLifecycle to it
2020-09-26 16:42:20 -07:00
adfec6ae94 API docs cleanup and other minor fixes (#73)
motivation: better API docs and usability

changes:
* allow customization of ServiceLifecycle label
* adjust APi docs
* fix tests on macOS (availability)

Co-authored-by: Yim Lee <yim_lee@apple.com>
Co-authored-by: Konrad `ktoso` Malawski <konrad.malawski@project13.pl>
2020-09-01 14:43:57 -07:00
tomer doron c8e99520d7 setup shutdown hooks on ServiceLifecycle::startAndWait (#69)
motivation: fix startAndWait to work as advertised

changes:
* extract shutdown setup to a func and call it from both start and startAndWait
* add test
* fix api doc
* fixi jazzy xenial issue (fixes ci)
2020-08-08 20:27:20 -07:00
YR Chen 5ad999203c Allow zero-task startup (#55)
* Allow zero-task startup

* Add test for zero-task

* Fix Linux build and improve consistency

* Fix sanity
2020-07-17 12:28:22 +09:00
tomer doron daef88b82a prepare to open source (#47)
motivation: cleanup naming and collatoral in preperation to open sourcing the library

changes:
* rename "bootstrap" to "lifecycle"
* contributors list
2020-07-15 14:57:44 -07:00