update readme to reflect updated API (#37)

motivation: keep readme in sync with code

changes:
* update readme to latest API + add nesting section
* update leftover renaming issues

Author: tomerd

CONTRIBUTING.md

@@ -70,4 +70,4 @@ For this reason, whenever you add new tests **you have to run a script** that ge
 
 ## How to contribute your work
 
-Please open a pull request at https://github.com/swift-server/swift-service-launcher. Make sure the CI passes, and then wait for code review.
+Please open a pull request at https://github.com/swift-server/swift-service-bootstrap. Make sure the CI passes, and then wait for code review.

README.md

@@ -6,7 +6,7 @@ It also provides a `Signal`-based shutdown hook, to shutdown on signals like `TE
 SwiftServiceBootstrap was designed with the idea that every application has some startup and shutdown workflow-like-logic which is often sensitive to failure and hard to get right.
 The library codes this common need in a safe and reusable way that is non-framework specific, and designed to be integrated with any server framework or directly in an application.
 
-This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. What SwiftServiceBootstrap provides today is covered in the [API docs](https://swift-server.github.io/swift-service-launcher/), but it will continue to evolve with community input.
+This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. What SwiftServiceBootstrap provides today is covered in the [API docs](https://swift-server.github.io/swift-service-bootstrap/), but it will continue to evolve with community input.
 
 ## Getting started
 
@@ -17,23 +17,23 @@ If you have a server-side Swift application or a cross-platform (e.g. Linux, mac
 To add a dependency on the package, declare it in your `Package.swift`:
 
 ```swift
-.package(url: "https://github.com/swift-server/swift-service-launcher.git", from: "1.0.0"),
+.package(url: "https://github.com/swift-server/swift-service-bootstrap.git", from: "1.0.0-alpha.2"),
 ```
 
 and to your application target, add "SwiftServiceBootstrap" to your dependencies:
 
 ```swift
-.target(name: "BestExampleApp", dependencies: ["SwiftServiceBootstrap"]),
+.target(name: "MyApplication", dependencies: ["Lifecycle"]),
 ```
 
 ###  Defining the lifecycle
 
 ```swift
 // import the package
-import ServiceLauncher
+import Lifecycle
 
 // initialize the lifecycle container
-var lifecycle = Lifecycle()
+let lifecycle = ServiceLifecycle()
 
 // register a resource that should be shut down when the application exits.
 //
@@ -45,14 +45,17 @@ lifecycle.registerShutdown(
     eventLoopGroup.syncShutdownGracefully
 )
 
-// register another resource that should be shut down when the application exits.
+// register another resource that should be started when the application starts
+// and shut down when the application exits.
 //
-// in this case, we are registering an `HTTPClient`
-// and passing its `syncShutdown` function to be called on shutdown
-let httpClient = HTTPClient(eventLoopGroupProvider: .shared(eventLoopGroup))
-lifecycle.registerShutdown(
-    name: "httpClient",
-    httpClient.syncShutdown
+// in this case, we are registering a contrived `DatabaseMigrator`
+// and passing its `migrate` function to be called on startup
+// and `shutdown` function to be called on shutdown
+let migrator = DatabaseMigrator()
+lifecycle.register(
+    name: "migrator",
+    start: .async(migrator.migrate),
+    shutdown: .async(migrator.shutdown)
 )
 
 // start the application
@@ -79,11 +82,18 @@ lifecycle.wait()
 
 ## Detailed design
 
-The main type in the library is `Lifecycle` which manages a state machine representing the application's startup and shutdown logic.
+The main types in the library are `ServiceLifecycle` and `ComponentLifecycle`.
+
+`ServiceLifecycle` is the most commonly used type.
+It is designed to manage the top level Application (Service) lifecycle,
+and in addition to managing the startup and shutdown flows it can also set up `Signal` trap for shutdown and install backtraces.
+
+`ComponentLifecycle` manages a state machine representing the startup and shutdown logic flow.
+In larger Applications (Services) `ComponentLifecycle` can be used to manage the lifecycle of subsystems, such that `ServiceLifecycle` can start and shutdown `ComponentLifecycle`s.
 
 ### Registering items
 
-`Lifecycle` is a container for `LifecycleItem`s which need to be registered via one of the following variants:
+`ServiceLifecycle` and `ComponentLifecycle` are containers for `Lifecycle.Task`s which need to be registered via one of the following variants:
 
 You can register simple blocking throwing handlers using:
 
@@ -133,11 +143,23 @@ func register(_ items: [LifecycleItem])
 internal func register(_ items: LifecycleItem...)
 ```
 
+### Configuration
+
+`ServiceLifecycle` constructor takes optional `Lifecycle.Configuration` to further refine the `ServiceLifecycle` behavior:
+
+* `callbackQueue`: Defines the `DispatchQueue` on which startup and shutdown handlers are executed. By default, `DispatchQueue.global` is used.
+
+* `shutdownSignal`: Defines what, if any, signals to trap for invoking shutdown. By default, `INT` and `TERM` are trapped.
+
+* `installBacktrace`: Defines if to install a crash signal trap that prints backtraces. This is especially useful for application running on Linux since Swift does not provide backtraces on Linux out of the box. This functionality is provided via the [Swift Backtrace](https://github.com/swift-server/swift-backtrace) library.
+
 ### Starting the lifecycle
 
-Use `Lifecycle::start` function to start the application. Start handlers passed using the `register` function will be called in the order the items were registered in.
+Use `start` function to start the application.
+Start handlers passed using the `register` function will be called in the order the items were registered in.
 
-`Lifecycle::start` is an asynchronous operation. If a startup error occurred, it will be logged and the startup sequence will halt on the first error, and bubble it up to the provided completion handler.
+`start` is an asynchronous operation.
+If a startup error occurred, it will be logged and the startup sequence will halt on the first error, and bubble it up to the provided completion handler.
 
 ```swift
 lifecycle.start() { error in
@@ -149,17 +171,9 @@ lifecycle.start() { error in
 }
 ```
 
-`Lifecycle::start` takes optional `Lifecycle.Configuration` to further refine the `Lifecycle` behavior:
-
-* `callbackQueue`: Defines the `DispatchQueue` on which startup and shutdown handlers are executed. By default, `DispatchQueue.global` is used.
-
-* `shutdownSignal`: Defines what, if any, signals to trap for invoking shutdown. By default, `INT` and `TERM` are trapped.
-
-* `installBacktrace`: Defines if to install a crash signal trap that prints backtraces. This is especially useful for application running on Linux since Swift does not provide backtraces on Linux out of the box. This functionality is provided via the [Swift Backtrace](https://github.com/swift-server/swift-backtrace) library.
-
 ### Shutdown
 
-Typical use of the library is to call on `Lifecycle::wait` after calling `Lifecycle::start`.
+Typical use of the library is to call on `wait` after calling `start`.
 
 ```swift
 lifecycle.start() { error in
@@ -174,7 +188,7 @@ If you are not interested in handling start completion, there is also a convenie
 lifecycle.startAndWait() // <-- blocks the thread
 ```
 
-`Lifecycle::wait` and `Lifecycle::startAndWait` are blocking operations that wait for the lifecycle library to finish its shutdown sequence.
+Both `wait` and `startAndWait` are blocking operations that wait for the lifecycle library to finish the shutdown sequence.
 The shutdown sequence is typically triggered by the `shutdownSignal` defined in the configuration. By default, `INT` and `TERM` are trapped.
 
 During shutdown, the shutdown handlers passed using the `register` or `registerShutdown` functions are called in the reverse order of the registration. E.g.
@@ -189,15 +203,53 @@ startup order will be 1, 2, 3 and shutdown order will be 3, 2, 1.
 
 If a shutdown error occurred, it will be logged and the shutdown sequence will *continue* to the next item, and attempt to shut it down until all registered items that have been started are shut down.
 
-In more complex cases, when signal trapping based shutdown is not appropriate, you may pass `nil` as the `shutdownSignal` configuration, and call `Lifecycle::shutdown` manually when appropriate. This is a rarely used pressure valve. `Lifecycle::shutdown` is an asynchronous operation. Errors will be logged and bubble it up to the provided completion handler.
+In more complex cases, when signal trapping based shutdown is not appropriate, you may pass `nil` as the `shutdownSignal` configuration, and call `shutdown` manually when appropriate. This is designed to be a rarely used pressure valve.
+
+`shutdown` is an asynchronous operation. Errors will be logged and bubble it up to the provided completion handler.
+
+### Complex Systems and Nesting of Subsystems
+
+In larger Applications (Services) `ComponentLifecycle` can be used to manage the lifecycle of subsystems, such that `ServiceLifecycle` can start and shutdown `ComponentLifecycle`s.
+
+In fact, since `ComponentLifecycle` conforms to `Lifecycle.Task`,
+it can start and stop other `ComponentLifecycles`, forming a tree. E.g.:
+
+```swift
+struct SubSystem {
+    let lifecycle = ComponentLifecycle(label: "SubSystem")
+    let subsystem: SubSubSystem
+
+    init() {
+        self.subsystem = SubSubSystem()
+        self.lifecycle.register(self.subsystem.lifecycle)
+    }
+
+    struct SubSubSystem {
+        let lifecycle = ComponentLifecycle(label: "SubSubSystem")
+
+        init() {
+            self.lifecycle.register(...)
+        }
+    }
+}
+
+let lifecycle = ServiceLifecycle()
+let subsystem = SubSystem()
+lifecycle.register(subsystem.lifecycle)
+
+lifecycle.start { error in
+    ...
+}
+lifecycle.wait()
+```
 
 ### Compatibility with SwiftNIO Futures
 
 [SwiftNIO](https://github.com/apple/swift-nio) is a popular networking library that among other things provides Future abstraction named `EventLoopFuture`.
 
 SwiftServiceBootstrap comes with a compatibility module designed to make managing SwiftNIO based resources easy.
 
-Once you import `ServiceLauncherNIOCompat` module, `Lifecycle.Handler` gains a static helpers named `eventLoopFuture` designed to help simplify the registration call to:
+Once you import `LifecycleNIOCompat` module, `Lifecycle.Handler` gains a static helpers named `eventLoopFuture` designed to help simplify the registration call to:
 
 ```swift
 let foo = ...
@@ -208,7 +260,16 @@ lifecycle.register(
 )
 ```
 
--------
+or, just shutdown:
 
+```swift
+let foo = ...
+lifecycle.registerShutdown(
+    name: "foo",
+    .eventLoopFuture(foo.shutdown)
+)
+```
+
+-------
 
 Do not hesitate to get in touch as well, over on https://forums.swift.org/c/server.

Tests/LifecycleTests/ServiceLifecycleTests+XCTest.swift

@@ -30,6 +30,7 @@ extension ServiceLifecycleTests {
             ("testStartAndWait", testStartAndWait),
             ("testBadStartAndWait", testBadStartAndWait),
             ("testNesting", testNesting),
+            ("testNesting2", testNesting2),
         ]
     }
 }

Tests/LifecycleTests/ServiceLifecycleTests.swift

@@ -19,7 +19,7 @@ import XCTest
 final class ServiceLifecycleTests: XCTestCase {
     func testStartThenShutdown() {
         let items = (5 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() }
-        let lifecycle = ComponentLifecycle(label: "test")
+        let lifecycle = ServiceLifecycle(configuration: .init(shutdownSignal: nil))
         lifecycle.register(items)
         lifecycle.start { startError in
             XCTAssertNil(startError, "not expecting error")
@@ -138,4 +138,37 @@ final class ServiceLifecycleTests: XCTestCase {
         items2.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
         items3.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
     }
+
+    func testNesting2() {
+        struct SubSystem {
+            let lifecycle = ComponentLifecycle(label: "SubSystem")
+            let subsystem: SubSubSystem
+
+            init() {
+                self.subsystem = SubSubSystem()
+                self.lifecycle.register(self.subsystem.lifecycle)
+            }
+
+            struct SubSubSystem {
+                let lifecycle = ComponentLifecycle(label: "SubSubSystem")
+                let items = (0 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() }
+
+                init() {
+                    self.lifecycle.register(self.items)
+                }
+            }
+        }
+
+        let lifecycle = ServiceLifecycle()
+        let subsystem = SubSystem()
+        lifecycle.register(subsystem.lifecycle)
+
+        lifecycle.start { error in
+            XCTAssertNil(error, "not expecting error")
+            subsystem.subsystem.items.forEach { XCTAssertEqual($0.state, .started, "expected item to be started, but \($0.state)") }
+            lifecycle.shutdown()
+        }
+        lifecycle.wait()
+        subsystem.subsystem.items.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
+    }
 }

docker/docker-compose.1604.51.yaml

@@ -3,17 +3,17 @@ version: "3"
 services:
 
   runtime-setup:
-    image: swift-service-launcher:16.04-5.1
+    image: swift-service-bootstrap:16.04-5.1
     build:
       args:
         ubuntu_version: "xenial"
         swift_version: "5.1"
 
   test:
-    image: swift-service-launcher:16.04-5.1
+    image: swift-service-bootstrap:16.04-5.1
     environment:
       - SANITIZER_ARG=--sanitize=thread
       - SKIP_SIGNAL_TEST=true
 
   shell:
-    image: swift-service-launcher:16.04-5.1
+    image: swift-service-bootstrap:16.04-5.1

docker/docker-compose.1804.50.yaml

@@ -3,14 +3,14 @@ version: "3"
 services:
 
   runtime-setup:
-    image: swift-service-launcher:18.04-5.0
+    image: swift-service-bootstrap:18.04-5.0
     build:
       args:
         ubuntu_version: "bionic"
         swift_version: "5.0"
 
   test:
-    image: swift-service-launcher:18.04-5.0
+    image: swift-service-bootstrap:18.04-5.0
 
   shell:
-    image: swift-service-launcher:18.04-5.0
+    image: swift-service-bootstrap:18.04-5.0

docker/docker-compose.1804.52.yaml

@@ -3,14 +3,14 @@ version: "3"
 services:
 
   runtime-setup:
-    image: swift-service-launcher:18.04-5.2
+    image: swift-service-bootstrap:18.04-5.2
     build:
       args:
         ubuntu_version: "bionic"
         swift_version: "5.2"
 
   test:
-    image: swift-service-launcher:18.04-5.2
+    image: swift-service-bootstrap:18.04-5.2
 
   shell:
-    image: swift-service-launcher:18.04-5.2
+    image: swift-service-bootstrap:18.04-5.2

docker/docker-compose.1804.53.yaml

@@ -3,13 +3,13 @@ version: "3"
 services:
 
   runtime-setup:
-    image: swift-service-launcher:18.04-5.3
+    image: swift-service-bootstrap:18.04-5.3
     build:
       args:
         base_image: "swiftlang/swift:nightly-bionic"
 
   test:
-    image: swift-service-launcher:18.04-5.3
+    image: swift-service-bootstrap:18.04-5.3
 
   shell:
-    image: swift-service-launcher:18.04-5.3
+    image: swift-service-bootstrap:18.04-5.3

docker/docker-compose.yaml

@@ -6,13 +6,13 @@ version: "3"
 services:
 
   runtime-setup:
-    image: swift-service-launcher:default
+    image: swift-service-bootstrap:default
     build:
       context: .
       dockerfile: Dockerfile
 
   common: &common
-    image: swift-service-launcher:default
+    image: swift-service-bootstrap:default
     depends_on: [runtime-setup]
     volumes:
       - ~/.ssh:/root/.ssh