mirror
/
swift-nio-transport-services
mirror of https://github.com/apple/swift-nio-transport-services.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Use Docc for documentation (#154) 

Motivation

Documentation is nice, and we can help support users by providing useful
clear docs.

Modifications

Add Docc to 5.6 and later builds
Make sure symbol references work
Add overview docs

Result

Nice rendering docs
This commit is contained in:
Cory Benfield 2022-07-29 15:02:01 +01:00 committed by GitHub
parent 94645c8fcd
commit 4e02d9cf35
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 326 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Package.swift
View File

@ -1,4 +1,4 @@
// swift-tools-version:5.4
// swift-tools-version:5.6
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
@ -23,6 +23,7 @@ let package = Package(
dependencies: [
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
],
targets: [
.target(

60
Package@swift-5.4.swift Normal file
View File

@ -0,0 +1,60 @@
// swift-tools-version:5.4
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-nio-transport-services",
products: [
.library(name: "NIOTransportServices", targets: ["NIOTransportServices"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
],
targets: [
.target(
name: "NIOTransportServices",
dependencies: [
.product(name: "NIO", package: "swift-nio"),
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOFoundationCompat", package: "swift-nio"),
.product(name: "NIOTLS", package: "swift-nio"),
.product(name: "Atomics", package: "swift-atomics"),
]),
.executableTarget(
name: "NIOTSHTTPClient",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOHTTP1", package: "swift-nio"),
]),
.executableTarget(
name: "NIOTSHTTPServer",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOHTTP1", package: "swift-nio"),
]),
.testTarget(
name: "NIOTransportServicesTests",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOEmbedded", package: "swift-nio"),
.product(name: "Atomics", package: "swift-atomics"),
]),
]
)

60
Package@swift-5.5.swift Normal file
View File

@ -0,0 +1,60 @@
// swift-tools-version:5.5
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-nio-transport-services",
products: [
.library(name: "NIOTransportServices", targets: ["NIOTransportServices"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
],
targets: [
.target(
name: "NIOTransportServices",
dependencies: [
.product(name: "NIO", package: "swift-nio"),
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOFoundationCompat", package: "swift-nio"),
.product(name: "NIOTLS", package: "swift-nio"),
.product(name: "Atomics", package: "swift-atomics"),
]),
.executableTarget(
name: "NIOTSHTTPClient",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOHTTP1", package: "swift-nio"),
]),
.executableTarget(
name: "NIOTSHTTPServer",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOHTTP1", package: "swift-nio"),
]),
.testTarget(
name: "NIOTransportServicesTests",
dependencies: [
"NIOTransportServices",
.product(name: "NIOCore", package: "swift-nio"),
.product(name: "NIOEmbedded", package: "swift-nio"),
.product(name: "Atomics", package: "swift-atomics"),
]),
]
)

2
README.md
View File

@ -20,7 +20,7 @@ NIO Transport Services primarily uses SwiftPM as its build tool, so we recommend
```
dependencies: [
.package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.1.1")
.package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.13.0")
]
```

97
Sources/NIOTransportServices/Docs.docc/index.md Normal file
View File

@ -0,0 +1,97 @@
# ``NIOTransportServices``
Extensions for SwiftNIO to support Apple platforms as first-class citizens.
## About NIO Transport Services
NIO Transport Services is an extension to SwiftNIO that provides first-class support for Apple platforms by using [Network.framework](https://developer.apple.com/documentation/network) to provide network connectivity, and [Dispatch](https://developer.apple.com/documentation/dispatch) to provide concurrency. NIOTS provides an alternative [EventLoop](https://apple.github.io/swift-nio/docs/current/NIO/Protocols/EventLoop.html), [EventLoopGroup](https://apple.github.io/swift-nio/docs/current/NIO/Protocols/EventLoopGroup.html), and several alternative [Channels](https://apple.github.io/swift-nio/docs/current/NIO/Protocols/Channel.html) and Bootstraps.
In addition to providing first-class support for Apple platforms, NIO Transport Services takes advantage of the richer API of Network.framework to provide more insight into the behaviour of the network than is normally available to NIO applications. This includes the ability to wait for connectivity until a network route is available, as well as all of the extra proxy and VPN support that is built directly into Network.framework.
All regular NIO applications should work just fine with NIO Transport Services, simply by changing the event loops and bootstraps in use.
## Why Transport Services?
Network.framework is Apple's reference implementation of the [proposed post-sockets API](https://datatracker.ietf.org/wg/taps/charter/) that is currently being worked on by the Transport Services Working Group (taps) of the IETF. To indicate the proposed long-term future of interfaces like Network.framework, we decided to call this module NIOTransportServices. Also, NIONetworkFramework didn't appeal to us much as a name.
## How to Use NIO Transport Services
NIO Transport Services primarily uses SwiftPM as its build tool, so we recommend using that as well. If you want to depend on NIO Transport Services in your own project, it's as simple as adding a dependencies clause to your Package.swift:
```
dependencies: [
.package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.13.0")
]
```
and then adding the `NIOTransportServices` module to your target dependencies.
If your project is set up as an Xcode project and you're using Xcode 11+, you can add NIO Transport Services as a dependency to your Xcode project by clicking File -> Swift Packages -> Add Package Dependency. In the upcoming dialog, please enter `https://github.com/apple/swift-nio-transport-services.git` and click Next twice. Finally, make sure `NIOTransportServices` is selected and click finish. Now will be able to `import NIOTransportServices` in your project.
### Supported Platforms
NIOTransportServices is supported where Network.framework is supported: macOS
10.14+, iOS 12+, tvOS 12+, and watchOS 6+.
In order to allow dependencies to use NIOTransportServices when it's available
and fallback to NIO when it isn't, all code is behind import guards checking
the availability of Network.framework. As such NIOTransportServices may be
built on platforms where Network.framework is *not* available.
NIOTransportServices can be built on macOS 10.12+, iOS 10+, tvOS 10+, watchOS
6+ and Linux but is only functionally useful on macOS 10.14+, iOS 12+, tvOS 12+
and watchOS 6+.
## Versioning
Just like the rest of the SwiftNIO family, `swift-nio-transport-services` follows [SemVer 2.0.0](https://semver.org/#semantic-versioning-200) with a separate document
declaring [SwiftNIO's Public API](https://github.com/apple/swift-nio/blob/main/docs/public-api.md).
### NIO Transport Services 1.x
`swift-nio-transport-services` versions 1.x is part of the SwiftNIO 2 family of repositories and does not have any dependencies besides [`swift-nio`](https://github.com/apple/swift-nio), Swift 5.4, and an Apple OS supporting `Network.framework`. As the latest version, it lives on the [`main`](https://github.com/apple/swift-nio-transport-services) branch.
To depend on `swift-nio-transport-services `, put the following in the `dependencies` of your `Package.swift`:
.package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.0.0"),
`swift-nio-transport-services` version 1.11.x and earlier support Swift 5.2 and 5.3. Earlier 1.x versions also support Swift 5.0 and 5.1.
### NIO Transport Services 0.x
The legacy `swift-nio-transport-services` 0.x is part of the SwiftNIO 1 family of repositories and works with Swift 4.1 and newer. The source code can be found on the [`swift-nio-transport-services-swift-4-maintenance`](https://github.com/apple/swift-nio-transport-services/tree/swift-nio-transport-services-swift-4-maintenance) branch.
## Topics
### Event Loops and Groups
- ``NIOTSEventLoopGroup``
- ``QoSEventLoop``
### Client Connections
- ``NIOTSConnectionBootstrap``
- ``NIOTSClientTLSProvider``
### Server Connections
- ``NIOTSListenerBootstrap``
### Configuring Channels
- ``NIOTSChannelOptions``
- ``NIOTSEnablePeerToPeerOption``
- ``NIOTSWaitForActivityOption``
### Managing Channels
- ``NIOTSNetworkEvents``
- ``NIOTSNetworkEvent``
### Errors
- ``NIOTSErrors``
- ``NIOTSError``
### Channel Handlers
- ``NIOFilterEmptyWritesHandler``

40
Sources/NIOTransportServices/NIOTSChannelOptions.swift
View File

@ -18,23 +18,28 @@ import Network
/// Options that can be set explicitly and only on bootstraps provided by `NIOTransportServices`.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public struct NIOTSChannelOptions {
/// - seealso: `NIOTSWaitForActivityOption`.
/// See: ``Types/NIOTSWaitForActivityOption``.
public static let waitForActivity = NIOTSChannelOptions.Types.NIOTSWaitForActivityOption()
/// See: ``Types/NIOTSEnablePeerToPeerOption``.
public static let enablePeerToPeer = NIOTSChannelOptions.Types.NIOTSEnablePeerToPeerOption()
/// - See: NIOTSChannelOptions.Types.NIOTSAllowLocalEndpointReuse
/// See: ``Types/NIOTSAllowLocalEndpointReuse``.
public static let allowLocalEndpointReuse = NIOTSChannelOptions.Types.NIOTSAllowLocalEndpointReuse()
/// See: ``Types/NIOTSCurrentPathOption``.
public static let currentPath = NIOTSChannelOptions.Types.NIOTSCurrentPathOption()
/// See: ``Types/NIOTSMetadataOption``
public static let metadata = { (definition: NWProtocolDefinition) -> NIOTSChannelOptions.Types.NIOTSMetadataOption in
.init(definition: definition)
}
/// See: ``Types/NIOTSEstablishmentReportOption``.
@available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public static let establishmentReport = NIOTSChannelOptions.Types.NIOTSEstablishmentReportOption()
/// See: ``Types/NIOTSDataTransferReportOption``.
@available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public static let dataTransferReport = NIOTSChannelOptions.Types.NIOTSDataTransferReportOption()
}
@ -42,15 +47,16 @@ public struct NIOTSChannelOptions {
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
extension NIOTSChannelOptions {
/// A namespace for ``NIOTSChannelOptions`` datastructures.
public enum Types {
/// `NIOTSWaitForActivityOption` controls whether the `Channel` should wait for connection changes
/// ``NIOTSWaitForActivityOption`` controls whether the `Channel` should wait for connection changes
/// during the connection process if the connection attempt fails. If Network.framework believes that
/// a connection may succeed in future, it may transition into the `.waiting` state. By default, this option
/// is set to `true` and NIO allows this state transition, though it does count time in that state against
/// the timeout. If this option is set to `false`, transitioning into this state will be treated the same as
/// transitioning into the `failed` state, causing immediate connection failure.
///
/// This option is only valid with `NIOTSConnectionBootstrap`.
/// This option is only valid with ``NIOTSConnectionBootstrap``.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public struct NIOTSWaitForActivityOption: ChannelOption, Equatable {
public typealias Value = Bool
@ -58,7 +64,7 @@ extension NIOTSChannelOptions {
public init() {}
}
/// `NIOTSEnablePeerToPeerOption` controls whether the `Channel` will advertise services using peer-to-peer
/// ``NIOTSEnablePeerToPeerOption`` controls whether the `Channel` will advertise services using peer-to-peer
/// connectivity. Setting this to true is the equivalent of setting `NWParameters.enablePeerToPeer` to
/// `true`. By default this option is set to `false`.
///
@ -70,8 +76,8 @@ extension NIOTSChannelOptions {
public init() {}
}
/// `NIOTSAllowLocalEndpointReuse` controls whether the `Channel` can reuse a TCP address recently used.
/// Setting this to true is the equivalent of setting at least one of REUSEADDR and REUSEPORT to
/// ``NIOTSAllowLocalEndpointReuse`` controls whether the `Channel` can reuse a TCP address recently used.
/// Setting this to true is the equivalent of setting at least one of `REUSEADDR` and `REUSEPORT` to
/// `true`. By default this option is set to `false`.
///
/// This option must be set on the bootstrap: setting it after the channel is initialized will have no effect.
@ -82,9 +88,9 @@ extension NIOTSChannelOptions {
public init() {}
}
/// `NIOTSCurrentPathOption` accesses the `NWConnection.currentPath` of the underlying connection.
/// ``NIOTSCurrentPathOption`` accesses the `NWConnection.currentPath` of the underlying connection.
///
/// This option is only valid with `NIOTSConnectionBootstrap`.
/// This option is only valid with ``NIOTSConnectionBootstrap``.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public struct NIOTSCurrentPathOption: ChannelOption, Equatable {
public typealias Value = NWPath
@ -92,9 +98,9 @@ extension NIOTSChannelOptions {
public init() {}
}
/// `NIOTSMetadataOption` accesses the metadata for a given `NWProtocol`.
/// ``NIOTSMetadataOption`` accesses the metadata for a given `NWProtocol`.
///
/// This option is only valid with `NIOTSConnectionBootstrap`.
/// This option is only valid with ``NIOTSConnectionBootstrap``.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public struct NIOTSMetadataOption: ChannelOption, Equatable {
public typealias Value = NWProtocolMetadata
@ -106,9 +112,9 @@ extension NIOTSChannelOptions {
}
}
/// `NIOTSEstablishmentReportOption` accesses the `NWConnection.EstablishmentReport` of the underlying connection.
/// ``NIOTSEstablishmentReportOption`` accesses the `NWConnection.EstablishmentReport` of the underlying connection.
///
/// This option is only valid with `NIOTSConnectionBootstrap`.
/// This option is only valid with ``NIOTSConnectionBootstrap``.
@available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct NIOTSEstablishmentReportOption: ChannelOption, Equatable {
public typealias Value = EventLoopFuture<NWConnection.EstablishmentReport?>
@ -116,9 +122,9 @@ extension NIOTSChannelOptions {
public init() {}
}
/// `NIOTSDataTransferReportOption` accesses the `NWConnection.DataTransferReport` of the underlying connection.
/// ``NIOTSDataTransferReportOption`` accesses the `NWConnection.DataTransferReport` of the underlying connection.
///
/// This option is only valid with `NIOTSConnectionBootstrap`.
/// This option is only valid with ``NIOTSConnectionBootstrap``.
@available(OSX 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct NIOTSDataTransferReportOption: ChannelOption, Equatable {
public typealias Value = NWConnection.PendingDataTransferReport
@ -128,13 +134,13 @@ extension NIOTSChannelOptions {
}
}
/// See: `NIOTSChannelOptions.Types.NIOTSWaitForActivityOption`.
/// See: ``NIOTSChannelOptions/Types/NIOTSWaitForActivityOption``.
@available(*, deprecated, renamed: "NIOTSChannelOptions.Types.NIOTSWaitForActivityOption")
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public typealias NIOTSWaitForActivityOption = NIOTSChannelOptions.Types.NIOTSWaitForActivityOption
/// See: `NIOTSChannelOptions.Types.NIOTSEnablePeerToPeerOption`
/// See: ``NIOTSChannelOptions/Types/NIOTSEnablePeerToPeerOption``
@available(*, deprecated, renamed: "NIOTSChannelOptions.Types.NIOTSEnablePeerToPeerOption")
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public typealias NIOTSEnablePeerToPeerOption = NIOTSChannelOptions.Types.NIOTSEnablePeerToPeerOption

24
Sources/NIOTransportServices/NIOTSConnectionBootstrap.swift
View File

@ -2,7 +2,7 @@
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
// Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
@ -19,7 +19,7 @@ import Network
/// A `NIOTSConnectionBootstrap` is an easy way to bootstrap a `NIOTSConnectionChannel` when creating network clients.
///
/// Usually you re-use a `NIOTSConnectionBootstrap` once you set it up and called `connect` multiple times on it.
/// Usually you re-use a `NIOTSConnectionBootstrap` once you set it up, calling `connect` multiple times on the same bootstrap.
/// This way you ensure that the same `EventLoop`s will be shared across all your connections.
///
/// Example:
@ -52,8 +52,8 @@ public final class NIOTSConnectionBootstrap {
/// Create a `NIOTSConnectionBootstrap` on the `EventLoopGroup` `group`.
///
/// The `EventLoopGroup` `group` must be compatible, otherwise the program will crash. `NIOTSConnectionBootstrap` is
/// compatible only with `NIOTSEventLoopGroup` as well as the `EventLoop`s returned by
/// `NIOTSEventLoopGroup.next`. See `init(validatingGroup:)` for a fallible initializer for
/// compatible only with ``NIOTSEventLoopGroup`` as well as the `EventLoop`s returned by
/// ``NIOTSEventLoopGroup/next()``. See ``init(validatingGroup:)`` for a fallible initializer for
/// situations where it's impossible to tell ahead of time if the `EventLoopGroup` is compatible or not.
///
/// - parameters:
@ -67,16 +67,16 @@ public final class NIOTSConnectionBootstrap {
self.init(validatingGroup: group)!
}
/// Create a `NIOTSConnectionBootstrap` on the `NIOTSEventLoopGroup` `group`.
/// Create a `NIOTSConnectionBootstrap` on the ``NIOTSEventLoopGroup`` `group`.
///
/// - parameters:
/// - group: The `NIOTSEventLoopGroup` to use.
/// - group: The ``NIOTSEventLoopGroup`` to use.
public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup)
}
/// Create a `NIOTSConnectionBootstrap` on the `NIOTSEventLoopGroup` `group`, validating
/// that the `EventLoopGroup` is compatible with `NIOTSConnectionBootstrap`.
/// Create a `NIOTSConnectionBootstrap` on the ``NIOTSEventLoopGroup`` `group`, validating
/// that the `EventLoopGroup` is compatible with ``NIOTSConnectionBootstrap``.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use.
@ -130,20 +130,12 @@ public final class NIOTSConnectionBootstrap {
}
/// Specifies the TCP options to use on the `Channel`s.
///
/// To retrieve the TCP options from connected channels, use
/// `NIOTSChannelOptions.TCPConfiguration`. It is not possible to change the
/// TCP configuration after `connect` is called.
public func tcpOptions(_ options: NWProtocolTCP.Options) -> Self {
self.tcpOptions = options
return self
}
/// Specifies the TLS options to use on the `Channel`s.
///
/// To retrieve the TLS options from connected channels, use
/// `NIOTSChannelOptions.TLSConfiguration`. It is not possible to change the
/// TLS configuration after `connect` is called.
public func tlsOptions(_ options: NWProtocolTLS.Options) -> Self {
self.tlsOptions = options
return self

18
Sources/NIOTransportServices/NIOTSErrors.swift
View File

@ -22,16 +22,16 @@ public protocol NIOTSError: Error, Equatable { }
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public enum NIOTSErrors {
/// `InvalidChannelStateTransition` is thrown when a channel has been asked to do something
/// ``InvalidChannelStateTransition`` is thrown when a channel has been asked to do something
/// that is incompatible with its current channel state: e.g. attempting to register an
/// already registered channel.
public struct InvalidChannelStateTransition: NIOTSError { }
/// `NotPreConfigured` is thrown when a channel has had `registerAlreadyConfigured`
/// ``NotPreConfigured`` is thrown when a channel has had `registerAlreadyConfigured`
/// called on it, but has not had the appropriate underlying network object provided.
public struct NotPreConfigured: NIOTSError { }
/// `UnsupportedSocketOption` is thrown when an attempt is made to configure a socket option that
/// ``UnsupportedSocketOption`` is thrown when an attempt is made to configure a socket option that
/// is not supported by Network.framework.
public struct UnsupportedSocketOption: NIOTSError {
public let optionValue: ChannelOptions.Types.SocketOption
@ -41,26 +41,26 @@ public enum NIOTSErrors {
}
}
/// `NoCurrentPath` is thrown when an attempt is made to request path details from a channel and
/// ``NoCurrentPath`` is thrown when an attempt is made to request path details from a channel and
/// that channel has no path available. This can manifest, for example, when asking for remote
/// or local addresses.
public struct NoCurrentPath: NIOTSError { }
/// `NoCurrentConnection` is thrown when an attempt is made to request connection details from a channel and
/// ``NoCurrentConnection`` is thrown when an attempt is made to request connection details from a channel and
/// that channel has no connection available.
public struct NoCurrentConnection: NIOTSError { }
/// `InvalidPort` is thrown when the port passed to a method is not valid.
/// ``InvalidPort`` is thrown when the port passed to a method is not valid.
public struct InvalidPort: NIOTSError {
/// The provided port.
public let port: Int
}
/// `UnableToResolveEndpoint` is thrown when an attempt is made to resolve a local endpoint, but
/// ``UnableToResolveEndpoint`` is thrown when an attempt is made to resolve a local endpoint, but
/// insufficient information is available to create it.
public struct UnableToResolveEndpoint: NIOTSError { }
/// `BindTimeout` is thrown when a timeout set for a `NWListenerBootstrap.bind` call has been exceeded
/// ``BindTimeout`` is thrown when a timeout set for a `NWListenerBootstrap.bind` call has been exceeded
/// without successfully binding the address.
public struct BindTimeout: NIOTSError {
public var timeout: TimeAmount
@ -70,7 +70,7 @@ public enum NIOTSErrors {
}
}
/// `InvalidHostname` is thrown when attempting to connect to an invalid host.
/// ``InvalidHostname`` is thrown when attempting to connect to an invalid host.
public struct InvalidHostname: NIOTSError {
public init() { }
}

2
Sources/NIOTransportServices/NIOTSEventLoop.swift
View File

@ -22,7 +22,7 @@ import NIOConcurrencyHelpers
/// An `EventLoop` that interacts with `DispatchQoS` to help schedule upcoming work.
///
/// `EventLoop`s that implement `QoSEventLoop` can interact with `Dispatch` to propagate information
/// `EventLoop`s that implement ``QoSEventLoop`` can interact with `Dispatch` to propagate information
/// about the QoS required for a specific task block. This allows tasks to be dispatched onto an
/// event loop with a different priority than the majority of tasks on that loop.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)

11
Sources/NIOTransportServices/NIOTSEventLoopGroup.swift
View File

@ -2,7 +2,7 @@
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
// Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
@ -43,14 +43,19 @@ import Atomics
/// take advantage of the various interfaces available on mobile devices.
///
/// In general, when building applications whose primary purpose is to be deployed on Darwin
/// platforms, the `NIOTSEventLoopGroup` should be preferred over the
/// `MultiThreadedEventLoopGroup`. In particular, on iOS, the `NIOTSEventLoopGroup` is the
/// platforms, the ``NIOTSEventLoopGroup`` should be preferred over the
/// `MultiThreadedEventLoopGroup`. In particular, on iOS, the ``NIOTSEventLoopGroup`` is the
/// preferred networking backend.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSEventLoopGroup: EventLoopGroup {
private let index = ManagedAtomic(0)
private let eventLoops: [NIOTSEventLoop]
/// Construct a ``NIOTSEventLoopGroup`` with a specified number of loops and QoS.
///
/// - parameters:
/// - loopCount: The number of independent loops to use. Defaults to `1`.
/// - defaultQoS: The default QoS for tasks enqueued on this loop. Defaults to `.default`.
public init(loopCount: Int = 1, defaultQoS: DispatchQoS = .default) {
precondition(loopCount > 0)
self.eventLoops = (0..<loopCount).map { _ in NIOTSEventLoop(qos: defaultQoS) }

44
Sources/NIOTransportServices/NIOTSListenerBootstrap.swift
View File

@ -17,7 +17,7 @@ import NIOCore
import Dispatch
import Network
/// A `NIOTSListenerBootstrap` is an easy way to bootstrap a `NIOTSListenerChannel` when creating network servers.
/// A ``NIOTSListenerBootstrap`` is an easy way to bootstrap a `NIOTSListenerChannel` when creating network servers.
///
/// Example:
///
@ -67,15 +67,15 @@ public final class NIOTSListenerBootstrap {
private var tlsOptions: NWProtocolTLS.Options?
private var bindTimeout: TimeAmount?
/// Create a `NIOTSListenerBootstrap` for the `EventLoopGroup` `group`.
/// Create a ``NIOTSListenerBootstrap`` for the `EventLoopGroup` `group`.
///
/// This initializer only exists to be more in-line with the NIO core bootstraps, in that they
/// may be constructed with an `EventLoopGroup` and by extenstion an `EventLoop`. As such an
/// existing `NIOTSEventLoop` may be used to initialize this bootstrap. Where possible the
/// initializers accepting `NIOTSEventLoopGroup` should be used instead to avoid the wrong
/// initializers accepting ``NIOTSEventLoopGroup`` should be used instead to avoid the wrong
/// type being used.
///
/// Note that the "real" solution is described in https://github.com/apple/swift-nio/issues/674.
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `NIOTSListenerChannel`.
@ -83,23 +83,23 @@ public final class NIOTSListenerBootstrap {
self.init(group: group, childGroup: group)
}
/// Create a `NIOTSListenerBootstrap` for the `NIOTSEventLoopGroup` `group`.
/// Create a ``NIOTSListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`.
///
/// - parameters:
/// - group: The `NIOTSEventLoopGroup` to use for the `NIOTSListenerChannel`.
/// - group: The ``NIOTSEventLoopGroup`` to use for the `NIOTSListenerChannel`.
public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup)
}
/// Create a `NIOTSListenerBootstrap`.
/// Create a ``NIOTSListenerBootstrap``.
///
/// This initializer only exists to be more in-line with the NIO core bootstraps, in that they
/// may be constructed with an `EventLoopGroup` and by extension an `EventLoop`. As such an
/// existing `NIOTSEventLoop` may be used to initialize this bootstrap. Where possible the
/// initializers accepting `NIOTSEventLoopGroup` should be used instead to avoid the wrong
/// initializers accepting ``NIOTSEventLoopGroup`` should be used instead to avoid the wrong
/// type being used.
///
/// Note that the "real" solution is described in https://github.com/apple/swift-nio/issues/674.
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel`
@ -115,8 +115,8 @@ public final class NIOTSListenerBootstrap {
self.init(validatingGroup: group, childGroup: childGroup)!
}
/// Create a `NIOTSListenerBootstrap` on the `EventLoopGroup` `group` which accepts `Channel`s on `childGroup`,
/// validating that the `EventLoopGroup`s are compatible with `NIOTSListenerBootstrap`.
/// Create a ``NIOTSListenerBootstrap`` on the `EventLoopGroup` `group` which accepts `Channel`s on `childGroup`,
/// validating that the `EventLoopGroup`s are compatible with ``NIOTSListenerBootstrap``.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel`
@ -135,12 +135,12 @@ public final class NIOTSListenerBootstrap {
self.childChannelOptions.append(key: ChannelOptions.socket(IPPROTO_TCP, TCP_NODELAY), value: 1)
}
/// Create a `NIOTSListenerBootstrap`.
/// Create a ``NIOTSListenerBootstrap``.
///
/// - parameters:
/// - group: The `NIOTSEventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel`
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the `NIOTSListenerChannel`
/// and to accept new `NIOTSConnectionChannel`s with.
/// - childGroup: The `NIOTSEventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted `NIOTSConnectionChannel`s on.
public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup)
}
@ -150,8 +150,8 @@ public final class NIOTSListenerBootstrap {
///
/// The `NIOTSListenerChannel` uses the accepted `NIOTSConnectionChannel`s as inbound messages.
///
/// - note: To set the initializer for the accepted `NIOTSConnectionChannel`s, look at
/// `NIOTSConnectionBootstrap.childChannelInitializer`.
/// > Note: To set the initializer for the accepted `NIOTSConnectionChannel`s, look at
/// ``childChannelInitializer(_:)``.
///
/// - parameters:
/// - initializer: A closure that initializes the provided `Channel`.
@ -175,7 +175,7 @@ public final class NIOTSListenerBootstrap {
/// Specifies a `ChannelOption` to be applied to the `NIOTSListenerChannel`.
///
/// - note: To specify options for the accepted `NIOTSConnectionChannels`s, look at `NIOTSListenerBootstrap.childChannelOption`.
/// > Note: To specify options for the accepted `NIOTSConnectionChannel`s, look at ``childChannelOption(_:value:)``.
///
/// - parameters:
/// - option: The option to be applied.
@ -196,7 +196,7 @@ public final class NIOTSListenerBootstrap {
}
/// Specifies a timeout to apply to a bind attempt.
//
///
/// - parameters:
/// - timeout: The timeout that will apply to the bind attempt.
public func bindTimeout(_ timeout: TimeAmount) -> Self {
@ -224,20 +224,12 @@ public final class NIOTSListenerBootstrap {
}
/// Specifies the TCP options to use on the child `Channel`s.
///
/// To retrieve the TCP options from connected channels, use
/// `NIOTSChannelOptions.TCPConfiguration`. It is not possible to change the
/// TCP configuration after `bind` is called.
public func tcpOptions(_ options: NWProtocolTCP.Options) -> Self {
self.tcpOptions = options
return self
}
/// Specifies the TLS options to use on the child `Channel`s.
///
/// To retrieve the TLS options from connected channels, use
/// `NIOTSChannelOptions.TLSConfiguration`. It is not possible to change the
/// TLS configuration after `bind` is called.
public func tlsOptions(_ options: NWProtocolTLS.Options) -> Self {
self.tlsOptions = options
return self

30
Sources/NIOTransportServices/NIOTSNetworkEvents.swift
View File

@ -16,7 +16,7 @@
import Network
import NIOCore
/// A tag protocol that can be used to cover all network events emitted by `NIOTS`.
/// A tag protocol that can be used to cover all network events emitted by `NIOTransportServices`.
///
/// Users are strongly encouraged not to conform their own types to this protocol.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
@ -24,7 +24,7 @@ public protocol NIOTSNetworkEvent: Equatable { }
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public enum NIOTSNetworkEvents {
/// This event is fired whenever the OS has informed NIO that there is a better
/// ``BetterPathAvailable`` is fired whenever the OS has informed NIO that there is a better
/// path available to the endpoint that this `Channel` is currently connected to,
/// e.g. the current connection is using an expensive cellular connection and
/// a cheaper WiFi connection has become available.
@ -32,59 +32,55 @@ public enum NIOTSNetworkEvents {
/// If you can handle this event, you should make a new connection attempt, and then
/// transfer your work to that connection before closing this one.
public struct BetterPathAvailable: NIOTSNetworkEvent {
/// Create a new `BetterPathAvailable` event.
/// Create a new ``NIOTSNetworkEvents/BetterPathAvailable`` event.
public init(){ }
}
/// This event is fired when the OS has informed NIO that no better path to the
/// ``BetterPathUnavailable`` is fired when the OS has informed NIO that no better path to the
/// to the remote endpoint than the one currently being used by this `Channel` is
/// currently available.
public struct BetterPathUnavailable: NIOTSNetworkEvent {
/// Create a new `BetterPathUnavailable` event.
/// Create a new ``NIOTSNetworkEvents/BetterPathUnavailable`` event.
public init(){ }
}
/// This event is fired whenever the OS has informed NIO that a new path is in use
/// ``PathChanged`` is fired whenever the OS has informed NIO that a new path is in use
/// for this `Channel`.
public struct PathChanged: NIOTSNetworkEvent {
/// The new path for this `Channel`.
public let newPath: NWPath
/// Create a new `PathChanged` event.
/// Create a new ``NIOTSNetworkEvents/PathChanged`` event.
public init(newPath: NWPath) {
self.newPath = newPath
}
}
/// This event is fired as an outbound event when NIO would like to ask Network.framework
/// ``ConnectToNWEndpoint`` is fired as an outbound event when NIO would like to ask Network.framework
/// to handle the connection logic (e.g. its own DNS resolution and happy eyeballs racing).
/// This is temporary workaround until NIO 2.0 which should allow us to use the regular
/// `Channel.connect` method instead.
public struct ConnectToNWEndpoint: NIOTSNetworkEvent {
/// The endpoint to which we want to connect.
public let endpoint: NWEndpoint
/// Create a new `ConnectToNWEndpoint` event.
/// Create a new ``NIOTSNetworkEvents/ConnectToNWEndpoint`` event.
public init(endpoint: NWEndpoint) {
self.endpoint = endpoint
}
}
/// This event is fired as an outbound event when NIO would like to ask Network.framework
/// ``BindToNWEndpoint`` is fired as an outbound event when NIO would like to ask Network.framework
/// to handle the binding logic (e.g. its own support for bonjour and interface selection).
/// This is temporary workaround until NIO 2.0 which should allow us to use the regular
/// `Channel.bind` method instead.
public struct BindToNWEndpoint: NIOTSNetworkEvent {
/// The endpoint to which we want to bind.
public let endpoint: NWEndpoint
/// Create a new `BindToNWEndpoint` event.
/// Create a new ``NIOTSNetworkEvents/BindToNWEndpoint`` event.
public init(endpoint: NWEndpoint) {
self.endpoint = endpoint
}
}
/// This event is fired when when the OS has informed NIO that it cannot immediately connect
/// ``WaitingForConnectivity`` is fired when when the OS has informed NIO that it cannot immediately connect
/// to the remote endpoint, but that it is possible that changes in network conditions may
/// allow connection in future. This can occur in cases where the route is not currently
/// satisfiable (e.g. because airplane mode is on, or because the app is forbidden from using cellular)
@ -96,7 +92,7 @@ public enum NIOTSNetworkEvents {
/// as fatal, and instead to use them as information to inform UI decisions.
public var transientError: NWError
/// Create a new `WaitingForConnectivity` event.
/// Create a new ``NIOTSNetworkEvents/WaitingForConnectivity`` event.
public init(transientError: NWError) {
self.transientError = transientError
}

1
Tests/LinuxMain.swift
View File

@ -1 +0,0 @@
print("WARNING: nio-transport-services is not Linux compatible and therefore has no tests for Linux.")

22
Tests/NIOTransportServicesTests/NIOTSWorkaroundTests.swift Normal file
View File

@ -0,0 +1,22 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2022 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import XCTest
final class NIOTSWorkaroundTests: XCTestCase {
func testWorkaround5695() {
// This test works around https://github.com/apple/swift-package-manager/issues/5695 by just
// doing nothing.
XCTAssertTrue(true)
}
}

2
docker/docker-compose.yaml
View File

@ -28,7 +28,7 @@ services:
test:
<<: *common
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
command: /bin/bash -xcl "swift test --enable-test-discovery -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
# util

6
scripts/soundness.sh
View File

@ -3,7 +3,7 @@
##
## This source file is part of the SwiftNIO open source project
##
## Copyright (c) 2017-2019 Apple Inc. and the SwiftNIO project authors
## Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
## Licensed under Apache License v2.0
##
## See LICENSE.txt for license information
@ -18,7 +18,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
function replace_acceptable_years() {
# this needs to replace all acceptable forms with 'YEARS'
sed -e 's/20[12][78901]-20[12][8901]/YEARS/' -e 's/20[12][8901]/YEARS/'
sed -e 's/20[12][789012]-20[12][89012]/YEARS/' -e 's/20[12][89012]/YEARS/'
}
# This checks for the umbrella NIO module.
@ -40,7 +40,7 @@ for language in swift-or-c bash dtrace python; do
matching_files=( -name '*' )
case "$language" in
swift-or-c)
exceptions=( -name LinuxMain.swift -o -name Package.swift )
exceptions=( -name LinuxMain.swift -o -name Package.swift -o -name 'Package@swift*.swift' )
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
cat > "$tmp" <<"EOF"
//===----------------------------------------------------------------------===//