diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2cf50b8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.DS_Store +/.build +/Packages +/*.xcodeproj +xcuserdata/ +.swiftpm +Package.resolved + +.swift-version diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..c8ad743 --- /dev/null +++ b/.mailmap @@ -0,0 +1,3 @@ +Tomer Doron +Tomer Doron +Tomer Doron diff --git a/.swiftformat b/.swiftformat new file mode 100644 index 0000000..4212a06 --- /dev/null +++ b/.swiftformat @@ -0,0 +1,13 @@ +# file options + +--exclude .build + +# format options + +--self insert +--patternlet inline +--stripunusedargs unnamed-only +--comments ignore +--ifdef no-indent + +# rules diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..10f7e67 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,55 @@ +# Code of Conduct +To be a truly great community, SwiftServiceLauncher needs to welcome developers from all walks of life, +with different backgrounds, and with a wide range of experience. A diverse and friendly +community will have more great ideas, more unique perspectives, and produce more great +code. We will work diligently to make the SwiftServiceLauncher community welcoming to everyone. + +To give clarity of what is expected of our members, SwiftServiceLauncher has adopted the code of conduct +defined by [contributor-covenant.org](https://www.contributor-covenant.org). This document is used across many open source +communities, and we think it articulates our values well. The full text is copied below: + +### Contributor Code of Conduct v1.3 +As contributors and maintainers of this project, and in the interest of fostering an open and +welcoming community, we pledge to respect all people who contribute through reporting +issues, posting feature requests, updating documentation, submitting pull requests or patches, +and other activities. + +We are committed to making participation in this project a harassment-free experience for +everyone, regardless of level of experience, gender, gender identity and expression, sexual +orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or +nationality. + +Examples of unacceptable behavior by participants include: +- The use of sexualized language or imagery +- Personal attacks +- Trolling or insulting/derogatory comments +- Public or private harassment +- Publishing other’s private information, such as physical or electronic addresses, without explicit permission +- Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of +Conduct, or to ban temporarily or permanently any contributor for other behaviors that they +deem inappropriate, threatening, offensive, or harmful. + +By adopting this Code of Conduct, project maintainers commit themselves to fairly and +consistently applying these principles to every aspect of managing this project. Project +maintainers who do not follow or enforce the Code of Conduct may be permanently removed +from the project team. + +This code of conduct applies both within project spaces and in public spaces when an +individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by +contacting a project maintainer at [swift-server-conduct@group.apple.com](mailto:swift-server-conduct@group.apple.com). All complaints will be reviewed and +investigated and will result in a response that is deemed necessary and appropriate to the +circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter +of an incident. + +*This policy is adapted from the Contributor Code of Conduct [version 1.3.0](https://contributor-covenant.org/version/1/3/0/).* + +### Reporting +A working group of community members is committed to promptly addressing any [reported issues](mailto:swift-server-conduct@group.apple.com). +Working group members are volunteers appointed by the project lead, with a +preference for individuals with varied backgrounds and perspectives. Membership is expected +to change regularly, and may grow or shrink. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5250caa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +## Legal + +By submitting a pull request, you represent that you have the right to license +your contribution to Apple and the community, and agree by submitting the patch +that your contributions are licensed under the Apache 2.0 license (see +`LICENSE.txt`). + + +## How to submit a bug report + +Please ensure to specify the following: + +* SwiftServiceLauncher commit hash +* Contextual information (e.g. what you were trying to achieve with SwiftServiceLauncher) +* Simplest possible steps to reproduce + * More complex the steps are, lower the priority will be. + * A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description. +* Anything that might be relevant in your opinion, such as: + * Swift version or the output of `swift --version` + * OS version and the output of `uname -a` + * Network configuration + + +### Example + +``` +SwiftServiceLauncher commit hash: 22ec043dc9d24bb011b47ece4f9ee97ee5be2757 + +Context: +While load testing my HTTP web server written with SwiftServiceLauncher, I noticed +that one file descriptor is leaked per request. + +Steps to reproduce: +1. ... +2. ... +3. ... +4. ... + +$ swift --version +Swift version 4.0.2 (swift-4.0.2-RELEASE) +Target: x86_64-unknown-linux-gnu + +Operating system: Ubuntu Linux 16.04 64-bit + +$ uname -a +Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux + +My system has IPv6 disabled. +``` + +## Writing a Patch + +A good SwiftServiceLauncher patch is: + +1. Concise, and contains as few changes as needed to achieve the end result. +2. Tested, ensuring that any tests provided failed before the patch and pass after it. +3. Documented, adding API documentation as needed to cover new functions and properties. +4. Accompanied by a great commit message, using our commit message template. + +### Commit Message Template + +We require that your commit messages match our template. The easiest way to do that is to get git to help you by explicitly using the template. To do that, `cd` to the root of our repository and run: + + git config commit.template dev/git.commit.template + +### Make sure Tests work on Linux + +SwiftServiceLauncher uses XCTest to run tests on both macOS and Linux. While the macOS version of XCTest is able to use the Objective-C runtime to discover tests at execution time, the Linux version is not. +For this reason, whenever you add new tests **you have to run a script** that generates the hooks needed to run those tests on Linux, or our CI will complain that the tests are not all present on Linux. To do this, merely execute `ruby ./scripts/generate_linux_tests.rb` at the root of the package and check the changes it made. + +## 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. diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt new file mode 100644 index 0000000..db56b9a --- /dev/null +++ b/CONTRIBUTORS.txt @@ -0,0 +1,18 @@ +For the purpose of tracking copyright, this is the list of individuals and +organizations who have contributed source code to SwiftServiceLauncher. + +For employees of an organization/company where the copyright of work done +by employees of that company is held by the company itself, only the company +needs to be listed here. + +## COPYRIGHT HOLDERS + +- Apple Inc. (all contributors with '@apple.com') + +### Contributors + +- Tomer Doron + +**Updating this list** + +Please do not edit this file manually. It is generated using `./scripts/generate_contributors_list.sh`. If a name is misspelled or appearing multiple times: add an entry in `./.mailmap` diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/Package.swift b/Package.swift new file mode 100644 index 0000000..1425ad7 --- /dev/null +++ b/Package.swift @@ -0,0 +1,20 @@ +// swift-tools-version:5.0 + +import PackageDescription + +let package = Package( + name: "swift-service-lancher", + products: [ + .library(name: "Lifecycle", targets: ["Lifecycle"]), + ], + dependencies: [ + .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"), + .package(url: "https://github.com/apple/swift-metrics.git", "1.0.0" ..< "3.0.0"), + .package(url: "https://github.com/swift-server/swift-backtrace.git", from: "1.1.1"), + .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"), // used in tests + ], + targets: [ + .target(name: "Lifecycle", dependencies: ["Logging", "Metrics", "Backtrace"]), + .testTarget(name: "LifecycleTests", dependencies: ["Lifecycle", "NIO"]), + ] +) diff --git a/README.md b/README.md index c95f401..d1c6d17 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,34 @@ -# Lifecycle +# SwiftServiceLauncher -Lifecycle provides a basic mechanism to cleanly start up and shut down the application, freeing resources in order before exiting. +SwiftServiceLauncher provides a basic mechanism to cleanly start up and shut down the application, freeing resources in order before exiting. It also provides a Signal based shutdown hook, to shutdown on signals like TERM or INT. -Lifecycle is non-framework specific, designed to be integrated with any server framework or application. - + +SwiftServiceLauncher is non-framework specific, designed to be integrated with any server framework or directly in an application. + +## Usage + +```swift +var lifecycle = Lifecycle() + +let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount) +lifecycle.append( + name: "eventLoopGroup", + shutdown: eventLoopGroup.syncShutdownGracefully +) + +let httpClient = HTTPClient(eventLoopGroupProvider: .shared(eventLoopGroup)) +lifecycle.append( + name: "HTTPClient", + shutdown: httpClient.shutdown +) +lifecycle.start() { error in + if let error = error { + logger.error("failed starting \(self) ☠️: \(error)") + } else { + logger.info("\(self) started successfully 🚀") + } +} +lifecycle.wait() +``` diff --git a/Sources/Lifecycle/Lifecycle.swift b/Sources/Lifecycle/Lifecycle.swift new file mode 100644 index 0000000..e85c4cf --- /dev/null +++ b/Sources/Lifecycle/Lifecycle.swift @@ -0,0 +1,551 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +#if os(macOS) || os(iOS) || os(watchOS) || os(tvOS) +import Darwin +#else +import Glibc +#endif +import Backtrace +import Dispatch +import Logging + +/// `Lifecycle` provides a basic mechanism to cleanly startup and shutdown the application, freeing resources in order before exiting. +public class Lifecycle { + private let logger = Logger(label: "\(Lifecycle.self)") + private let shutdownGroup = DispatchGroup() + + private var state = State.idle + private let stateSemaphore = DispatchSemaphore(value: 1) + + private var items = [LifecycleItem]() + private let itemsSemaphore = DispatchSemaphore(value: 1) + + /// Creates a `Lifecycle` instance. + public init() { + self.shutdownGroup.enter() + } + + /// Starts the provided `LifecycleItem` array and waits (blocking) until a shutdown `Signal` is captured or `Lifecycle.shutdown` is called on another thread. + /// Startup is performed in the order of items provided. + /// + /// - parameters: + /// - shutdownSignal: Defines what, if any, signals to trap for invoking shutdown. + /// - installBacktrace: Defines if to install a crash signal trap that prints backtraces. + @available(*, deprecated, message: "use startAndWait(configuration) instead") + public func startAndWait(shutdownSignal: [Signal]? = [.TERM, .INT], installBacktrace: Bool = true) throws { + try self.startAndWait(configuration: .init(shutdownSignal: shutdownSignal, installBacktrace: installBacktrace)) + } + + /// Starts the provided `LifecycleItem` array and waits (blocking) until a shutdown `Signal` is captured or `Lifecycle.shutdown` is called on another thread. + /// Startup is performed in the order of items provided. + /// + /// - parameters: + /// - configuration: Defines lifecycle `Configuration` + public func startAndWait(configuration: Configuration) throws { + let waitSemaphore = DispatchSemaphore(value: 0) + var startError: Error? + let items = self.itemsSemaphore.lock { self.items } + self._start(configuration: configuration, items: items) { error in + startError = error + waitSemaphore.signal() + } + waitSemaphore.wait() + try startError.map { throw $0 } + self.shutdownGroup.wait() + } + + /// Starts the provided `LifecycleItem` array. + /// Startup is performed in the order of items provided. + /// + /// - parameters: + /// - shutdownSignal: Defines what, if any, signals to trap for invoking shutdown. + /// - installBacktrace: Defines if to install a crash signal trap that prints backtraces. + /// - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise. + @available(*, deprecated, message: "use start(configuration) instead") + public func start(shutdownSignal: [Signal]? = [.TERM, .INT], installBacktrace: Bool = true, callback: @escaping (Error?) -> Void) { + self.start(configuration: .init(shutdownSignal: shutdownSignal, installBacktrace: installBacktrace), callback: callback) + } + + /// Starts the provided `LifecycleItem` array. + /// Startup is performed in the order of items provided. + /// + /// - parameters: + /// - configuration: Defines lifecycle `Configuration` + /// - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise. + public func start(configuration: Configuration, callback: @escaping (Error?) -> Void) { + let items = self.itemsSemaphore.lock { self.items } + self._start(configuration: configuration, items: items, callback: callback) + } + + /// Shuts down the `LifecycleItem` array provided in `start` or `startAndWait`. + /// Shutdown is performed in reverse order of items provided. + public func shutdown(on queue: DispatchQueue = DispatchQueue.global()) { + self.stateSemaphore.wait() + switch self.state { + case .idle: + self.stateSemaphore.signal() + self.shutdownGroup.leave() + case .starting: + self.state = .shuttingDown + self.stateSemaphore.signal() + case .shuttingDown, .shutdown: + self.stateSemaphore.signal() + return + case .started(let items): + self.state = .shuttingDown + self.stateSemaphore.signal() + self._shutdown(on: queue, items: items) { + self.shutdownGroup.leave() + } + } + } + + /// Waits (blocking) until shutdown signal is captured or `Lifecycle.shutdown` is invoked on another thread. + public func wait() { + self.shutdownGroup.wait() + } + + // MARK: - private + + private func _start(configuration: Configuration, items: [LifecycleItem], callback: @escaping (Error?) -> Void) { + self.stateSemaphore.lock { + guard case .idle = self.state else { + preconditionFailure("invalid state, \(self.state)") + } + precondition(items.count > 0, "invalid number of items, must be > 0") + self.logger.info("starting lifecycle") + if configuration.installBacktrace { + self.logger.info("installing backtrace") + Backtrace.install() + } + self.state = .starting + } + self._start(on: configuration.callbackQueue, items: items, index: 0) { _, error in + self.stateSemaphore.wait() + if error != nil { + self.state = .shuttingDown + } + switch self.state { + case .shuttingDown: + self.stateSemaphore.signal() + // shutdown was called while starting, or start failed, shutdown what we can + self._shutdown(on: configuration.callbackQueue, items: items) { + callback(error) + self.shutdownGroup.leave() + } + case .starting: + self.state = .started(items) + self.stateSemaphore.signal() + configuration.shutdownSignal?.forEach { signal in + self.logger.info("setting up shutdown hook on \(signal)") + let signalSource = Lifecycle.trap(signal: signal, handler: { signal in + self.logger.info("intercepted signal: \(signal)") + self.shutdown(on: configuration.callbackQueue) + }) + self.shutdownGroup.notify(queue: DispatchQueue.global()) { + signalSource.cancel() + } + } + return callback(nil) + default: + preconditionFailure("invalid state, \(self.state)") + } + } + } + + private func _start(on queue: DispatchQueue, items: [LifecycleItem], index: Int, callback: @escaping (Int, Error?) -> Void) { + // async barrier + let start = { (callback) -> Void in queue.async { items[index].start(callback: callback) } } + let callback = { (index, error) -> Void in queue.async { callback(index, error) } } + + if index >= items.count { + return callback(index, nil) + } + self.logger.info("starting item [\(items[index].name)]") + start { error in + if let error = error { + self.logger.info("failed to start [\(items[index].name)]: \(error)") + return callback(index, error) + } + // shutdown called while starting + self.stateSemaphore.wait() + if case .shuttingDown = self.state { + self.stateSemaphore.signal() + return callback(index, nil) + } + self.stateSemaphore.signal() + self._start(on: queue, items: items, index: index + 1, callback: callback) + } + } + + private func _shutdown(on queue: DispatchQueue, items: [LifecycleItem], callback: @escaping () -> Void) { + self.stateSemaphore.lock { + self.logger.info("shutting down lifecycle") + self.state = .shuttingDown + } + self._shutdown(on: queue, items: items.reversed(), index: 0) { + self.stateSemaphore.lock { + guard case .shuttingDown = self.state else { + preconditionFailure("invalid state, \(self.state)") + } + self.state = .shutdown + } + self.logger.info("bye") + callback() + } + } + + private func _shutdown(on queue: DispatchQueue, items: [LifecycleItem], index: Int, callback: @escaping () -> Void) { + // async barrier + let shutdown = { (callback) -> Void in queue.async { items[index].shutdown(callback: callback) } } + let callback = { () -> Void in queue.async { callback() } } + + if index >= items.count { + return callback() + } + self.logger.info("stopping item [\(items[index].name)]") + shutdown { error in + if let error = error { + self.logger.info("failed to stop [\(items[index].name)]: \(error)") + } + self._shutdown(on: queue, items: items, index: index + 1, callback: callback) + } + } + + private enum State { + case idle + case starting + case started([LifecycleItem]) + case shuttingDown + case shutdown + } +} + +extension Lifecycle { + internal struct Item: LifecycleItem { + public let name: String + private let _start: FunctionWithCallback? + private let _shutdown: FunctionWithCallback + + init(name: String, start: FunctionWithCallback?, shutdown: @escaping FunctionWithCallback) { + self.name = name + self._start = start + self._shutdown = shutdown + } + + init(name: String, start: FunctionWithCallback?, shutdown: @escaping ThrowingFunction) { + self.name = name + self._start = start + self._shutdown = Item.callback(shutdown) + } + + init(name: String, start: FunctionWithCallback?, shutdown: @escaping FutureProvider) { + self.name = name + self._start = start + self._shutdown = Item.callback(shutdown) + } + + init(name: String, start: ThrowingFunction?, shutdown: @escaping FunctionWithCallback) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = shutdown + } + + init(name: String, start: ThrowingFunction?, shutdown: @escaping ThrowingFunction) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = Item.callback(shutdown) + } + + init(name: String, start: ThrowingFunction?, shutdown: @escaping FutureProvider) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = Item.callback(shutdown) + } + + init(name: String, start: FutureProvider?, shutdown: @escaping FunctionWithCallback) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = shutdown + } + + init(name: String, start: FutureProvider?, shutdown: @escaping ThrowingFunction) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = Item.callback(shutdown) + } + + init(name: String, start: FutureProvider?, shutdown: @escaping FutureProvider) { + self.name = name + self._start = start.map(Item.callback) + self._shutdown = Item.callback(shutdown) + } + + func start(callback: @escaping (Error?) -> Void) { + if let body = self._start { + body(callback) + } else { + callback(nil) + } + } + + func shutdown(callback: @escaping (Error?) -> Void) { + self._shutdown(callback) + } + + private static func callback(_ body: @escaping ThrowingFunction) -> FunctionWithCallback { + return { callback in + do { + try body() + callback(nil) + } catch { + callback(error) + } + } + } + + private static func callback(_ future: @escaping FutureProvider) -> FunctionWithCallback { + return { callback in + future().whenComplete { result in + switch result { + case .success: + callback(nil) + case .failure(let error): + callback(error) + } + } + } + } + } +} + +extension Lifecycle { + /// `Lifecycle` configuration options. + public struct Configuration { + /// Defines the `DispatchQueue` on which startup and shutdown handlers are executed. + public let callbackQueue: DispatchQueue + /// Defines if to install a crash signal trap that prints backtraces. + public let shutdownSignal: [Signal]? + /// Defines what, if any, signals to trap for invoking shutdown. + public let installBacktrace: Bool + + public init(callbackQueue: DispatchQueue = DispatchQueue.global(), + shutdownSignal: [Signal]? = [.TERM, .INT], + installBacktrace: Bool = true) { + self.callbackQueue = callbackQueue + self.shutdownSignal = shutdownSignal + self.installBacktrace = installBacktrace + } + } +} + +/// Adding items +public extension Lifecycle { + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - items: one or more `LifecycleItem`. + internal func append(_ items: LifecycleItem...) { + self.stateSemaphore.lock { + guard case .idle = self.state else { + preconditionFailure("invalid state, \(self.state)") + } + } + self.itemsSemaphore.lock { + items.forEach { self.items.append($0) } + } + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - items: one or more `LifecycleItem`. + func append(_ items: [LifecycleItem]) { + items.forEach { self.append($0) } + } + + /// Add a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FunctionWithCallback, shutdown: @escaping FunctionWithCallback) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - shutdown: closure to perform the shutdown. + func append(name: String, shutdown: @escaping FunctionWithCallback) { + self.append(Item(name: name, start: nil as FunctionWithCallback?, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FunctionWithCallback, shutdown: @escaping ThrowingFunction) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - shutdown: closure to perform the shutdown. + func append(name: String, shutdown: @escaping ThrowingFunction) { + self.append(Item(name: name, start: nil as ThrowingFunction?, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FunctionWithCallback, shutdown: @escaping FutureProvider) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - shutdown: closure to perform the shutdown. + func append(name: String, shutdown: @escaping FutureProvider) { + self.append(Item(name: name, start: nil as FutureProvider?, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping ThrowingFunction, shutdown: @escaping FunctionWithCallback) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping ThrowingFunction, shutdown: @escaping ThrowingFunction) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping ThrowingFunction, shutdown: @escaping FutureProvider) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FutureProvider, shutdown: @escaping FunctionWithCallback) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Add a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FutureProvider, shutdown: @escaping ThrowingFunction) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } + + /// Adds a `LifecycleItem` to a `LifecycleItems` collection. + /// + /// - parameters: + /// - name: name of the item, useful for debugging. + /// - start: closure to perform the startup. + /// - shutdown: closure to perform the shutdown. + func append(name: String, start: @escaping FutureProvider, shutdown: @escaping FutureProvider) { + self.append(Item(name: name, start: start, shutdown: shutdown)) + } +} + +/// Supported startup and shutdown method styles + +public extension Lifecycle { + typealias FunctionWithCallback = (@escaping (Error?) -> Void) -> Void + typealias ThrowingFunction = () throws -> Void + typealias FutureProvider = () -> Future where Future.Value == Value +} + +public protocol LifecycleFuture { + associatedtype Value + + func whenComplete(_ callback: @escaping (Result) -> Void) +} + +/// Represents an item that can be started and shut down +public protocol LifecycleItem { + var name: String { get } + func start(callback: @escaping (Error?) -> Void) + func shutdown(callback: @escaping (Error?) -> Void) +} + +extension Lifecycle { + /// Setup a signal trap. + /// + /// - parameters: + /// - signal: The signal to trap. + /// - handler: closure to invoke when the signal is captured. + /// - returns: a `DispatchSourceSignal` for the given trap. The source must be cancled by the caller. + public static func trap(signal sig: Signal, handler: @escaping (Signal) -> Void, queue: DispatchQueue = DispatchQueue.global()) -> DispatchSourceSignal { + let signalSource = DispatchSource.makeSignalSource(signal: sig.rawValue, queue: queue) + signal(sig.rawValue, SIG_IGN) + signalSource.setEventHandler(handler: { + signalSource.cancel() + handler(sig) + }) + signalSource.resume() + return signalSource + } + + /// A system signal + public struct Signal { + internal var rawValue: CInt + + public static let TERM: Signal = Signal(rawValue: SIGTERM) + public static let INT: Signal = Signal(rawValue: SIGINT) + // for testing + internal static let ALRM: Signal = Signal(rawValue: SIGALRM) + } +} + +private extension DispatchSemaphore { + func lock(_ body: () -> T) -> T { + self.wait() + defer { self.signal() } + return body() + } +} diff --git a/Tests/LifecycleTests/LifecycleTests+XCTest.swift b/Tests/LifecycleTests/LifecycleTests+XCTest.swift new file mode 100644 index 0000000..66d1e35 --- /dev/null +++ b/Tests/LifecycleTests/LifecycleTests+XCTest.swift @@ -0,0 +1,41 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// +// +// LifecycleTests+XCTest.swift +// +import XCTest + +/// +/// NOTE: This file was generated by generate_linux_tests.rb +/// +/// Do NOT edit this file directly as it will be regenerated automatically when needed. +/// + +extension Tests { + static var allTests: [(String, (Tests) -> () throws -> Void)] { + return [ + ("testStartThenShutdown", testStartThenShutdown), + ("testImmediateShutdown", testImmediateShutdown), + ("testBadStartup", testBadStartup), + ("testBadShutdown", testBadShutdown), + ("testStartAndWait", testStartAndWait), + ("testBadStartAndWait", testBadStartAndWait), + ("testShutdownInOrder", testShutdownInOrder), + ("testSync", testSync), + ("testNIO", testNIO), + ("testAyncBarrier", testAyncBarrier), + ("testConcurrncy", testConcurrncy), + ] + } +} diff --git a/Tests/LifecycleTests/LifecycleTests.swift b/Tests/LifecycleTests/LifecycleTests.swift new file mode 100644 index 0000000..ed85a93 --- /dev/null +++ b/Tests/LifecycleTests/LifecycleTests.swift @@ -0,0 +1,387 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +@testable import Lifecycle +import NIO +import NIOConcurrencyHelpers +import XCTest + +final class Tests: XCTestCase { + func testStartThenShutdown() { + let items = (0 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() } + let lifecycle = Lifecycle() + lifecycle.append(items) + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + // FIXME: this test does not work in rio + func _testShutdownWithSignal() { + let signal = Lifecycle.Signal.ALRM + let items = (0 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() } + let lifecycle = Lifecycle() + lifecycle.append(items) + let configuration = Lifecycle.Configuration(shutdownSignal: [signal]) + lifecycle.start(configuration: configuration) { error in + XCTAssertNil(error, "not expecting error") + kill(getpid(), signal.rawValue) + } + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testImmediateShutdown() { + let items = (0 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() } + let lifecycle = Lifecycle() + lifecycle.append(items) + lifecycle.start(configuration: .init(shutdownSignal: nil)) { _ in } + lifecycle.shutdown() + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testBadStartup() { + class BadItem: LifecycleItem { + var name: String { + return "\(self)" + } + + func start(callback: (Error?) -> Void) { + callback(TestError()) + } + + func shutdown(callback: (Error?) -> Void) { + callback(nil) + } + } + + let items: [LifecycleItem] = [GoodItem(), BadItem(), GoodItem()] + let lifecycle = Lifecycle() + lifecycle.append(items) + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssert(error is TestError, "expected error to match") + } + lifecycle.wait() + let goodItems = items.compactMap { $0 as? GoodItem } + goodItems.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testBadShutdown() { + class BadItem: LifecycleItem { + var name: String { + return "\(self)" + } + + func start(callback: (Error?) -> Void) { + callback(nil) + } + + func shutdown(callback: (Error?) -> Void) { + callback(TestError()) + } + } + + let items: [LifecycleItem] = [GoodItem(), BadItem(), GoodItem()] + let lifecycle = Lifecycle() + lifecycle.append(items) + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + items.compactMap { $0 as? GoodItem }.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testStartAndWait() { + class Item: LifecycleItem { + private let semaphore: DispatchSemaphore + var state = State.idle + + init(_ semaphore: DispatchSemaphore) { + self.semaphore = semaphore + } + + var name: String { + return "\(self)" + } + + func start(callback: (Error?) -> Void) { + self.state = .started + self.semaphore.signal() + callback(nil) + } + + func shutdown(callback: (Error?) -> Void) { + self.state = .shutdown + callback(nil) + } + + enum State { + case idle + case started + case shutdown + } + } + + let lifecycle = Lifecycle() + let semaphore = DispatchSemaphore(value: 0) + DispatchQueue(label: "test").asyncAfter(deadline: .now() + 0.1) { + semaphore.wait() + lifecycle.shutdown() + } + let item = Item(semaphore) + lifecycle.append(item) + XCTAssertNoThrow(try lifecycle.startAndWait(configuration: .init(shutdownSignal: nil))) + XCTAssertEqual(item.state, .shutdown, "expected item to be shutdown") + } + + func testBadStartAndWait() { + class BadItem: LifecycleItem { + var name: String { + return "\(self)" + } + + func start(callback: (Error?) -> Void) { + callback(TestError()) + } + + func shutdown(callback: (Error?) -> Void) { + callback(nil) + } + } + + let lifecycle = Lifecycle() + lifecycle.append(GoodItem(), BadItem()) + XCTAssertThrowsError(try lifecycle.startAndWait(configuration: .init(shutdownSignal: nil))) { error in + XCTAssert(error is TestError, "expected error to match") + } + } + + func testShutdownInOrder() { + class Item: LifecycleItem { + let id: String + var result: [String] + + init(_ result: inout [String]) { + self.id = UUID().uuidString + self.result = result + } + + var name: String { + return "\(self.id)" + } + + func start(callback: (Error?) -> Void) { + self.result.append(self.id) + callback(nil) + } + + func shutdown(callback: (Error?) -> Void) { + if self.result.last == self.id { + _ = self.result.removeLast() + } + callback(nil) + } + } + + var result = [String]() + let items = [Item(&result), Item(&result), Item(&result), Item(&result)] + let lifecycle = Lifecycle() + lifecycle.append(items) + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + XCTAssert(result.isEmpty, "expected item to be shutdown in order") + } + + func testSync() { + class Sync { + let id: String + var state = State.idle + + init() { + self.id = UUID().uuidString + } + + func start() { + self.state = .started + } + + func shutdown() { + self.state = .shutdown + } + + enum State { + case idle + case started + case shutdown + } + } + + let lifecycle = Lifecycle() + let items = (0 ... Int.random(in: 10 ... 20)).map { _ in Sync() } + items.forEach { item in + lifecycle.append(name: item.id, start: item.start, shutdown: item.shutdown) + } + + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testNIO() { + let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount) + let lifecycle = Lifecycle() + + let items = (0 ... Int.random(in: 10 ... 20)).map { _ in NIOItem(eventLoopGroup: eventLoopGroup) } + items.forEach { item in + lifecycle.append(name: item.id, start: item.start, shutdown: item.shutdown) + } + + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testAyncBarrier() { + let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount) + let lifecycle = Lifecycle() + + let item1 = NIOItem(eventLoopGroup: eventLoopGroup) + lifecycle.append(name: "item1", start: item1.start, shutdown: item1.shutdown) + + lifecycle.append(name: "blocker", + start: { () -> Void in try! eventLoopGroup.next().makeSucceededFuture(()).wait() }, + shutdown: { () -> Void in try! eventLoopGroup.next().makeSucceededFuture(()).wait() }) + + let item2 = NIOItem(eventLoopGroup: eventLoopGroup) + lifecycle.append(name: "item2", start: item2.start, shutdown: item2.shutdown) + + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + [item1, item2].forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } + + func testConcurrncy() { + let lifecycle = Lifecycle() + let items = (0 ... 50000).map { _ in GoodItem(startDelay: 0, shutdownDelay: 0) } + let group = DispatchGroup() + items.forEach { item in + group.enter() + DispatchQueue(label: "test", attributes: .concurrent).async { + defer { group.leave() } + lifecycle.append(item) + } + } + group.wait() + lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in + XCTAssertNil(error, "not expecting error") + lifecycle.shutdown() + } + lifecycle.wait() + items.forEach { XCTAssert($0.state == .shutdown, "expected item to be shutdown, but \($0.state)") } + } +} + +private class GoodItem: LifecycleItem { + let queue = DispatchQueue(label: "GoodItem", attributes: .concurrent) + let startDelay: Double + let shutdownDelay: Double + + var state = State.idle + let stateLock = Lock() + + init(startDelay: Double = Double.random(in: 0.01 ... 0.1), shutdownDelay: Double = Double.random(in: 0.01 ... 0.1)) { + self.startDelay = startDelay + self.shutdownDelay = shutdownDelay + } + + var name: String { + return "\(GoodItem.self)" + } + + func start(callback: @escaping (Error?) -> Void) { + self.queue.asyncAfter(deadline: .now() + self.startDelay) { + self.stateLock.withLock { self.state = .started } + callback(nil) + } + } + + func shutdown(callback: @escaping (Error?) -> Void) { + self.queue.asyncAfter(deadline: .now() + self.shutdownDelay) { + self.stateLock.withLock { self.state = .shutdown } + callback(nil) + } + } + + enum State { + case idle + case started + case shutdown + } +} + +private class NIOItem { + let id: String + let eventLoopGroup: EventLoopGroup + let startDelay: Int64 + let shutdownDelay: Int64 + + var state = State.idle + let stateLock = Lock() + + init(eventLoopGroup: EventLoopGroup, startDelay: Int64 = Int64.random(in: 10 ... 20), shutdownDelay: Int64 = Int64.random(in: 10 ... 20)) { + self.id = UUID().uuidString + self.eventLoopGroup = eventLoopGroup + self.startDelay = startDelay + self.shutdownDelay = shutdownDelay + } + + func start() -> EventLoopFuture { + return self.eventLoopGroup.next().scheduleTask(in: .milliseconds(self.startDelay)) { + self.stateLock.withLock { self.state = .started } + }.futureResult + } + + func shutdown() -> EventLoopFuture { + return self.eventLoopGroup.next().scheduleTask(in: .milliseconds(self.shutdownDelay)) { + self.stateLock.withLock { self.state = .shutdown } + }.futureResult + } + + enum State { + case idle + case started + case shutdown + } +} + +private struct TestError: Error {} + +extension EventLoopFuture: LifecycleFuture {} diff --git a/Tests/LinuxMain.swift b/Tests/LinuxMain.swift new file mode 100644 index 0000000..1543be9 --- /dev/null +++ b/Tests/LinuxMain.swift @@ -0,0 +1,31 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// +// +// LinuxMain.swift +// +import XCTest + +/// +/// NOTE: This file was generated by generate_linux_tests.rb +/// +/// Do NOT edit this file directly as it will be regenerated automatically when needed. +/// + +#if os(Linux) || os(FreeBSD) +@testable import LifecycleTests + +XCTMain([ + testCase(Tests.allTests), +]) +#endif diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..818eae2 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,36 @@ +ARG swift_version=5.0 +ARG ubuntu_version=bionic +ARG base_image=swift:$swift_version-$ubuntu_version +FROM $base_image +# needed to do again after FROM due to docker limitation +ARG swift_version +ARG ubuntu_version + +# set as UTF-8 +RUN apt-get update && apt-get install -y locales locales-all +ENV LC_ALL en_US.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +# dependencies +RUN apt-get update && apt-get install -y wget +RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools curl jq # used by integration tests + +# ruby and jazzy for docs generation +RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev +RUN gem install jazzy --no-ri --no-rdoc + +# tools +RUN mkdir -p $HOME/.tools +RUN echo 'export PATH="$HOME/.tools:$PATH"' >> $HOME/.profile + +# script to allow mapping framepointers on linux (until part of the toolchain) +RUN wget -q https://raw.githubusercontent.com/apple/swift/master/utils/symbolicate-linux-fatal -O $HOME/.tools/symbolicate-linux-fatal +RUN chmod 755 $HOME/.tools/symbolicate-linux-fatal + +# swiftformat (until part of the toolchain) + +ARG swiftformat_version=0.40.12 +RUN git clone --branch $swiftformat_version --depth 1 https://github.com/nicklockwood/SwiftFormat $HOME/.tools/swift-format +RUN cd $HOME/.tools/swift-format && swift build -c release +RUN ln -s $HOME/.tools/swift-format/.build/release/swiftformat $HOME/.tools/swiftformat diff --git a/docker/docker-compose.1604.51.yaml b/docker/docker-compose.1604.51.yaml new file mode 100644 index 0000000..f164e69 --- /dev/null +++ b/docker/docker-compose.1604.51.yaml @@ -0,0 +1,18 @@ +version: "3" + +services: + + runtime-setup: + image: swift-service-launcher:16.04-5.1 + build: + args: + ubuntu_version: "xenial" + swift_version: "5.1" + + test: + image: swift-service-launcher:16.04-5.1 + environment: + - SANITIZER_ARG=--sanitize=thread + + shell: + image: swift-service-launcher:16.04-5.1 diff --git a/docker/docker-compose.1804.50.yaml b/docker/docker-compose.1804.50.yaml new file mode 100644 index 0000000..9b42c1b --- /dev/null +++ b/docker/docker-compose.1804.50.yaml @@ -0,0 +1,16 @@ +version: "3" + +services: + + runtime-setup: + image: swift-service-launcher:18.04-5.0 + build: + args: + ubuntu_version: "bionic" + swift_version: "5.0" + + test: + image: swift-service-launcher:18.04-5.0 + + shell: + image: swift-service-launcher:18.04-5.0 diff --git a/docker/docker-compose.1804.52.yaml b/docker/docker-compose.1804.52.yaml new file mode 100644 index 0000000..2f55d57 --- /dev/null +++ b/docker/docker-compose.1804.52.yaml @@ -0,0 +1,15 @@ +version: "3" + +services: + + runtime-setup: + image: swift-service-launcher:18.04-5.2 + build: + args: + base_image: "swiftlang/swift:nightly-5.2-bionic" + + test: + image: swift-service-launcher:18.04-5.2 + + shell: + image: swift-service-launcher:18.04-5.2 diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml new file mode 100644 index 0000000..24111d6 --- /dev/null +++ b/docker/docker-compose.yaml @@ -0,0 +1,37 @@ +# this file is not designed to be run directly +# instead, use the docker-compose.. files +# eg docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.1804.50.yaml run test +version: "3" + +services: + + runtime-setup: + image: swift-service-launcher:default + build: + context: . + dockerfile: Dockerfile + + common: &common + image: swift-service-launcher:default + depends_on: [runtime-setup] + volumes: + - ~/.ssh:/root/.ssh + - ..:/code:z + working_dir: /code + cap_drop: + - CAP_NET_RAW + - CAP_NET_BIND_SERVICE + + sanity: + <<: *common + command: /bin/bash -cl "./scripts/sanity.sh" + + test: + <<: *common + command: /bin/bash -cl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}" + + # util + + shell: + <<: *common + entrypoint: /bin/bash diff --git a/scripts/generate_contributors_list.sh b/scripts/generate_contributors_list.sh new file mode 100755 index 0000000..db34deb --- /dev/null +++ b/scripts/generate_contributors_list.sh @@ -0,0 +1,39 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftServiceLauncher open source project +## +## Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu +here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +contributors=$( cd "$here"/.. && git shortlog -es | cut -f2 | sed 's/^/- /' ) + +cat > "$here/../CONTRIBUTORS.txt" <<- EOF + For the purpose of tracking copyright, this is the list of individuals and + organizations who have contributed source code to SwiftServiceLauncher. + + For employees of an organization/company where the copyright of work done + by employees of that company is held by the company itself, only the company + needs to be listed here. + + ## COPYRIGHT HOLDERS + + - Apple Inc. (all contributors with '@apple.com') + + ### Contributors + + $contributors + + **Updating this list** + + Please do not edit this file manually. It is generated using \`./scripts/generate_contributors_list.sh\`. If a name is misspelled or appearing multiple times: add an entry in \`./.mailmap\` +EOF diff --git a/scripts/generate_linux_tests.rb b/scripts/generate_linux_tests.rb new file mode 100755 index 0000000..5e333c0 --- /dev/null +++ b/scripts/generate_linux_tests.rb @@ -0,0 +1,231 @@ +#!/usr/bin/env ruby + +# +# process_test_files.rb +# +# Copyright 2016 Tony Stone +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# Created by Tony Stone on 5/4/16. +# +require 'getoptlong' +require 'fileutils' +require 'pathname' + +include FileUtils + +# +# This ruby script will auto generate LinuxMain.swift and the +XCTest.swift extension files for Swift Package Manager on Linux platforms. +# +# See https://github.com/apple/swift-corelibs-xctest/blob/master/Documentation/Linux.md +# +def header(fileName) + string = <<-eos +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// +// +// +// +import XCTest + +/// +/// NOTE: This file was generated by generate_linux_tests.rb +/// +/// Do NOT edit this file directly as it will be regenerated automatically when needed. +/// + eos + + string + .sub('', File.basename(fileName)) + .sub('', Time.now.to_s) +end + +def createExtensionFile(fileName, classes) + extensionFile = fileName.sub! '.swift', '+XCTest.swift' + print 'Creating file: ' + extensionFile + "\n" + + File.open(extensionFile, 'w') do |file| + file.write header(extensionFile) + file.write "\n" + + for classArray in classes + file.write 'extension ' + classArray[0] + " {\n" + file.write ' static var allTests: [(String, (' + classArray[0] + ") -> () throws -> Void)] {\n" + file.write " return [\n" + + for funcName in classArray[1] + file.write ' ("' + funcName + '", ' + funcName + "),\n" + end + + file.write " ]\n" + file.write " }\n" + file.write "}\n" + end + end +end + +def createLinuxMain(testsDirectory, allTestSubDirectories, files) + fileName = testsDirectory + '/LinuxMain.swift' + print 'Creating file: ' + fileName + "\n" + + File.open(fileName, 'w') do |file| + file.write header(fileName) + file.write "\n" + + file.write "#if os(Linux) || os(FreeBSD)\n" + for testSubDirectory in allTestSubDirectories.sort { |x, y| x <=> y } + file.write '@testable import ' + testSubDirectory + "\n" + end + file.write "\n" + file.write "XCTMain([\n" + + testCases = [] + for classes in files + for classArray in classes + testCases << classArray[0] + end + end + + for testCase in testCases.sort { |x, y| x <=> y } + file.write ' testCase(' + testCase + ".allTests),\n" + end + file.write "])\n" + file.write "#endif\n" + end +end + +def parseSourceFile(fileName) + puts 'Parsing file: ' + fileName + "\n" + + classes = [] + currentClass = nil + inIfLinux = false + inElse = false + ignore = false + + # + # Read the file line by line + # and parse to find the class + # names and func names + # + File.readlines(fileName).each do |line| + if inIfLinux + if /\#else/.match(line) + inElse = true + ignore = true + else + if /\#end/.match(line) + inElse = false + inIfLinux = false + ignore = false + end + end + else + if /\#if[ \t]+os\(Linux\)/.match(line) + inIfLinux = true + ignore = false + end + end + + next if ignore + # Match class or func + match = line[/class[ \t]+[a-zA-Z0-9_]*(?=[ \t]*:[ \t]*XCTestCase)|func[ \t]+test[a-zA-Z0-9_]*(?=[ \t]*\(\))/, 0] + if match + + if match[/class/, 0] == 'class' + className = match.sub(/^class[ \t]+/, '') + # + # Create a new class / func structure + # and add it to the classes array. + # + currentClass = [className, []] + classes << currentClass + else # Must be a func + funcName = match.sub(/^func[ \t]+/, '') + # + # Add each func name the the class / func + # structure created above. + # + currentClass[1] << funcName + end + end + end + classes +end + +# +# Main routine +# +# + +testsDirectory = 'Tests' + +options = GetoptLong.new(['--tests-dir', GetoptLong::OPTIONAL_ARGUMENT]) +options.quiet = true + +begin + options.each do |option, value| + case option + when '--tests-dir' + testsDirectory = value + end + end +rescue GetoptLong::InvalidOption +end + +allTestSubDirectories = [] +allFiles = [] + +Dir[testsDirectory + '/*'].each do |subDirectory| + next unless File.directory?(subDirectory) + directoryHasClasses = false + Dir[subDirectory + '/*Test{s,}.swift'].each do |fileName| + next unless File.file? fileName + fileClasses = parseSourceFile(fileName) + + # + # If there are classes in the + # test source file, create an extension + # file for it. + # + next unless fileClasses.count > 0 + createExtensionFile(fileName, fileClasses) + directoryHasClasses = true + allFiles << fileClasses + end + + if directoryHasClasses + allTestSubDirectories << Pathname.new(subDirectory).split.last.to_s + end +end + +# +# Last step is the create a LinuxMain.swift file that +# references all the classes and funcs in the source files. +# +if allFiles.count > 0 + createLinuxMain(testsDirectory, allTestSubDirectories, allFiles) +end +# eof diff --git a/scripts/sanity.sh b/scripts/sanity.sh new file mode 100755 index 0000000..96e6a09 --- /dev/null +++ b/scripts/sanity.sh @@ -0,0 +1,140 @@ +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftServiceLauncher open source project +## +## Copyright (c) 2017-2018 Apple Inc. and the SwiftServiceLauncher project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## + +set -eu + +here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +function replace_acceptable_years() { + # this needs to replace all acceptable forms with 'YEARS' + sed -e 's/2017-2018/YEARS/' -e 's/2019-2020/YEARS/' -e 's/2019/YEARS/' -e 's/2020/YEARS/' +} + +printf "=> Checking linux tests... " +FIRST_OUT="$(git status --porcelain)" +ruby "$here/../scripts/generate_linux_tests.rb" > /dev/null +SECOND_OUT="$(git status --porcelain)" +if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then + printf "\033[0;31mmissing changes!\033[0m\n" + git --no-pager diff + exit 1 +else + printf "\033[0;32mokay.\033[0m\n" +fi + +printf "=> Checking format... " +FIRST_OUT="$(git status --porcelain)" +swiftformat . > /dev/null 2>&1 +SECOND_OUT="$(git status --porcelain)" +if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then + printf "\033[0;31mformatting issues!\033[0m\n" + git --no-pager diff + exit 1 +else + printf "\033[0;32mokay.\033[0m\n" +fi + +printf "=> Checking license headers\n" +tmp=$(mktemp /tmp/.swift-aws-lambda-sanity_XXXXXX) + +for language in swift-or-c bash dtrace; do + printf " * $language... " + declare -a matching_files + declare -a exceptions + expections=( ) + matching_files=( -name '*' ) + case "$language" in + swift-or-c) + exceptions=( -name Package.swift ) + matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' ) + cat > "$tmp" <<"EOF" +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftServiceLauncher open source project +// +// Copyright (c) YEARS Apple Inc. and the SwiftServiceLauncher project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// +EOF + ;; + bash) + matching_files=( -name '*.sh' ) + cat > "$tmp" <<"EOF" +#!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the SwiftServiceLauncher open source project +## +## Copyright (c) YEARS Apple Inc. and the SwiftServiceLauncher project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## +EOF + ;; + dtrace) + matching_files=( -name '*.d' ) + cat > "$tmp" <<"EOF" +#!/usr/sbin/dtrace -q -s +/*===----------------------------------------------------------------------===* + * + * This source file is part of the SwiftServiceLauncher open source project + * + * Copyright (c) YEARS Apple Inc. and the SwiftServiceLauncher project authors + * Licensed under Apache License v2.0 + * + * See LICENSE.txt for license information + * See CONTRIBUTORS.txt for the list of SwiftServiceLauncher project authors + * + * SPDX-License-Identifier: Apache-2.0 + * + *===----------------------------------------------------------------------===*/ +EOF + ;; + *) + echo >&2 "ERROR: unknown language '$language'" + ;; + esac + + expected_lines=$(cat "$tmp" | wc -l) + expected_sha=$(cat "$tmp" | shasum) + + ( + cd "$here/.." + find . \ + \( \! -path './.build/*' -a \ + \( "${matching_files[@]}" \) -a \ + \( \! \( "${exceptions[@]}" \) \) \) | while read line; do + if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then + printf "\033[0;31mmissing headers in file '$line'!\033[0m\n" + diff -u <(cat "$line" | replace_acceptable_years | head -n $expected_lines) "$tmp" + exit 1 + fi + done + printf "\033[0;32mokay.\033[0m\n" + ) +done + +rm "$tmp"