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.
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
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>
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.
This PR adds a `ClosureService`.
You can use a `ClosureService` to create a lightweight, inline `Service`
without defining and conforming a dedicated type.
## 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.
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
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
* Fix global cancelOnGracefulShutdown return type
* Deprecate cancelOnGracefulShutdown and add cancelWhenGracefulShutdown
* Add doc comment even for the deprecated function
* 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
* 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
* 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
# 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.
# 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.
# 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`.
* 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
# 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`.
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>
* 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
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
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
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
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
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
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
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
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
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)
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
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
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>
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)