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

Change naming of datagram-related types to make them more consistent + fix docs (#233) 

### Motivation:

The datagram-related types logically mirror the TCP-based ones
(`NIOTSDatagramListenerBootstrap` vs `NIOTSListenerBootstrap`;
`NIOTSListenerChannel` vs `NIOTSDatagramListenerChannel`;
`NIOTSDatagramChannel` vs `NIOTSDatagramConnectionChannel`;
`NIOTSDatagramBootstrap` vs `NIOTSConnectionBootstrap`).
However, some of the type names could more closely resemble their TCP
counterparts to make it easier to navigate the code/understand what
their purpose is.
Additionally, the docs for some of these types are wrong, as they've
been copy-pasted into the datagram versions without changes.

### Modifications:

There are separate commits for each of the following changes:
- Fix docs for `NIOTSDatagramListenerBootstrap` and rename the file to
match the type name.
- Rename `NIOTSDatagramConnectionChannelTests` to
`NIOTSDatagramBootstrapTests` (to match `NIOTSBootstrapTests`).
- Rename `NIOTSDatagramChannel` to `NIOTSDatagramConnectionChannel` (to
match `NIOTSConnectionChannel`)
- Fix docs for `NIOTSConnectionBootstrap`.
- Rename `NIOTSDatagramBootstrap` to `NIOTSDatagramConnectionBootstrap`
(to match `NIOTSConnectionBootstrap`). This one required a deprecate and
replace since it's a public type.

### Result:

Better docs and more consistency in our type names.
This commit is contained in:
Gus Cairo 2025-04-29 13:56:21 +01:00 committed by GitHub
parent cd1e89816d
commit d8443227d1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 104 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Sources/NIOTransportServices/Datagram/NIOTSDatagramBootstrap.swift → Sources/NIOTransportServices/Datagram/NIOTSDatagramConnectionBootstrap.swift
View File

@ -17,9 +17,13 @@ import NIOCore
import Dispatch import Dispatch
import Network import Network
/// A `NIOTSDatagramBootstrap` is an easy way to bootstrap a `NIOTSDatagramChannel` when creating network clients. @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public typealias NIOTSDatagramBootstrap = NIOTSDatagramConnectionBootstrap
/// A ``NIOTSDatagramConnectionBootstrap`` is an easy way to bootstrap a UDP channel when creating network clients.
/// ///
/// Usually you re-use a `NIOTSDatagramBootstrap` once you set it up, calling `connect` multiple times on the same bootstrap. /// Usually you re-use a ``NIOTSDatagramConnectionBootstrap`` 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. /// This way you ensure that the same `EventLoop`s will be shared across all your connections.
/// ///
/// Example: /// Example:
@ -29,7 +33,7 @@ import Network
/// defer { /// defer {
/// try! group.syncShutdownGracefully() /// try! group.syncShutdownGracefully()
/// } /// }
/// let bootstrap = NIOTSDatagramBootstrap(group: group) /// let bootstrap = NIOTSDatagramConnectionBootstrap(group: group)
/// .channelInitializer { channel in /// .channelInitializer { channel in
/// channel.pipeline.addHandler(MyChannelHandler()) /// channel.pipeline.addHandler(MyChannelHandler())
/// } /// }
@ -37,9 +41,9 @@ import Network
/// /* the Channel is now connected */ /// /* the Channel is now connected */
/// ``` /// ```
/// ///
/// The connected `NIOTSDatagramChannel` will operate on `ByteBuffer` as inbound and outbound messages. /// The connected channel will operate on `ByteBuffer` as inbound and outbound messages.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSDatagramBootstrap { public final class NIOTSDatagramConnectionBootstrap {
private let group: EventLoopGroup private let group: EventLoopGroup
private var channelInitializer: (@Sendable (Channel) -> EventLoopFuture<Void>)? private var channelInitializer: (@Sendable (Channel) -> EventLoopFuture<Void>)?
private var connectTimeout: TimeAmount = TimeAmount.seconds(10) private var connectTimeout: TimeAmount = TimeAmount.seconds(10)
@ -73,7 +77,7 @@ public final class NIOTSDatagramBootstrap {
self.init(group: group as EventLoopGroup) self.init(group: group as EventLoopGroup)
} }
/// Initialize the connected `NIOTSDatagramConnectionChannel` with `initializer`. The most common task in initializer is to add /// Initialize the connected channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. /// `ChannelHandler`s to the `ChannelPipeline`.
/// ///
/// The connected `Channel` will operate on `ByteBuffer` as inbound and outbound messages. /// The connected `Channel` will operate on `ByteBuffer` as inbound and outbound messages.
@ -86,7 +90,7 @@ public final class NIOTSDatagramBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the `NIOTSDatagramConnectionChannel`. /// Specifies a `ChannelOption` to be applied to the channel.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.
@ -193,7 +197,7 @@ public final class NIOTSDatagramBootstrap {
private func connect0( private func connect0(
_ binder: @Sendable @escaping (Channel, EventLoopPromise<Void>) -> Void _ binder: @Sendable @escaping (Channel, EventLoopPromise<Void>) -> Void
) -> EventLoopFuture<Channel> { ) -> EventLoopFuture<Channel> {
let conn: Channel = NIOTSDatagramChannel( let conn: Channel = NIOTSDatagramConnectionChannel(
eventLoop: self.group.next() as! NIOTSEventLoop, eventLoop: self.group.next() as! NIOTSEventLoop,
qos: self.qos, qos: self.qos,
udpOptions: self.udpOptions, udpOptions: self.udpOptions,
@ -229,5 +233,5 @@ public final class NIOTSDatagramBootstrap {
} }
@available(*, unavailable) @available(*, unavailable)
extension NIOTSDatagramBootstrap: Sendable {} extension NIOTSDatagramConnectionBootstrap: Sendable {}
#endif #endif

14
Sources/NIOTransportServices/Datagram/NIOTSDatagramChannel.swift → Sources/NIOTransportServices/Datagram/NIOTSDatagramConnectionChannel.swift
View File

@ -24,7 +24,7 @@ import Network
import Security import Security
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
internal final class NIOTSDatagramChannel: StateManagedNWConnectionChannel { internal final class NIOTSDatagramConnectionChannel: StateManagedNWConnectionChannel {
typealias ActiveSubstate = UDPSubstate typealias ActiveSubstate = UDPSubstate
enum UDPSubstate: NWConnectionSubstate { enum UDPSubstate: NWConnectionSubstate {
@ -34,11 +34,11 @@ internal final class NIOTSDatagramChannel: StateManagedNWConnectionChannel {
self = .open self = .open
} }
static func closeInput(state: inout ChannelState<NIOTSDatagramChannel.UDPSubstate>) throws { static func closeInput(state: inout ChannelState<NIOTSDatagramConnectionChannel.UDPSubstate>) throws {
throw NIOTSErrors.InvalidChannelStateTransition() throw NIOTSErrors.InvalidChannelStateTransition()
} }
static func closeOutput(state: inout ChannelState<NIOTSDatagramChannel.UDPSubstate>) throws { static func closeOutput(state: inout ChannelState<NIOTSDatagramConnectionChannel.UDPSubstate>) throws {
throw NIOTSErrors.InvalidChannelStateTransition() throw NIOTSErrors.InvalidChannelStateTransition()
} }
} }
@ -230,11 +230,11 @@ internal final class NIOTSDatagramChannel: StateManagedNWConnectionChannel {
} }
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
extension NIOTSDatagramChannel { extension NIOTSDatagramConnectionChannel {
internal struct SynchronousOptions: NIOSynchronousChannelOptions { internal struct SynchronousOptions: NIOSynchronousChannelOptions {
private let channel: NIOTSDatagramChannel private let channel: NIOTSDatagramConnectionChannel
fileprivate init(channel: NIOTSDatagramChannel) { fileprivate init(channel: NIOTSDatagramConnectionChannel) {
self.channel = channel self.channel = channel
} }
@ -253,5 +253,5 @@ extension NIOTSDatagramChannel {
} }
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
extension NIOTSDatagramChannel: @unchecked Sendable {} extension NIOTSDatagramConnectionChannel: @unchecked Sendable {}
#endif #endif

74
Sources/NIOTransportServices/Datagram/NIOTSDatagramListener.swift → Sources/NIOTransportServices/Datagram/NIOTSDatagramListenerBootstrap.swift
View File

@ -17,7 +17,7 @@ import NIOCore
import Dispatch import Dispatch
import Network import Network
/// A ``NIOTSListenerBootstrap`` is an easy way to bootstrap a `NIOTSListenerChannel` when creating network servers. /// A ``NIOTSDatagramListenerBootstrap`` is an easy way to bootstrap a listener channel when creating network servers.
/// ///
/// Example: /// Example:
/// ///
@ -26,7 +26,7 @@ import Network
/// defer { /// defer {
/// try! group.syncShutdownGracefully() /// try! group.syncShutdownGracefully()
/// } /// }
/// let bootstrap = NIOTSListenerBootstrap(group: group) /// let bootstrap = NIOTSDatagramListenerBootstrap(group: group)
/// // Specify backlog and enable SO_REUSEADDR for the server itself /// // Specify backlog and enable SO_REUSEADDR for the server itself
/// .serverChannelOption(ChannelOptions.backlog, value: 256) /// .serverChannelOption(ChannelOptions.backlog, value: 256)
/// .serverChannelOption(ChannelOptions.socketOption(.reuseaddr), value: 1) /// .serverChannelOption(ChannelOptions.socketOption(.reuseaddr), value: 1)
@ -46,13 +46,12 @@ import Network
/// try! channel.closeFuture.wait() // wait forever as we never close the Channel /// try! channel.closeFuture.wait() // wait forever as we never close the Channel
/// ``` /// ```
/// ///
/// The `EventLoopFuture` returned by `bind` will fire with a `NIOTSListenerChannel`. This is the channel that owns the /// The `EventLoopFuture` returned by `bind` will fire with a channel. This is the channel that owns the listening socket. Each
/// listening socket. Each time it accepts a new connection it will fire a `NIOTSConnectionChannel` through the /// time it accepts a new connection it will fire a new child channel for the new connection through the `ChannelPipeline` via
/// `ChannelPipeline` via `fireChannelRead`: as a result, the `NIOTSListenerChannel` operates on `Channel`s as inbound /// `fireChannelRead`: as a result, the listening channel operates on `Channel`s as inbound messages. Outbound messages are
/// messages. Outbound messages are not supported on a `NIOTSListenerChannel` which means that each write attempt will /// not supported on these listening channels, which means that each write attempt will fail.
/// fail.
/// ///
/// Accepted `NIOTSConnectionChannel`s operate on `ByteBuffer` as inbound data, and `IOData` as outbound data. /// Accepted channels operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSDatagramListenerBootstrap { public final class NIOTSDatagramListenerBootstrap {
private let group: EventLoopGroup private let group: EventLoopGroup
@ -71,7 +70,7 @@ public final class NIOTSDatagramListenerBootstrap {
private var nwParametersConfigurator: (@Sendable (NWParameters) -> Void)? private var nwParametersConfigurator: (@Sendable (NWParameters) -> Void)?
private var childNWParametersConfigurator: (@Sendable (NWParameters) -> Void)? private var childNWParametersConfigurator: (@Sendable (NWParameters) -> Void)?
/// Create a ``NIOTSListenerBootstrap`` for the `EventLoopGroup` `group`. /// Create a ``NIOTSDatagramListenerBootstrap`` for the `EventLoopGroup` `group`.
/// ///
/// This initializer only exists to be more in-line with the NIO core bootstraps, in that they /// 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 /// may be constructed with an `EventLoopGroup` and by extension an `EventLoop`. As such an
@ -82,20 +81,20 @@ public final class NIOTSDatagramListenerBootstrap {
/// > Note: 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: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `NIOTSListenerChannel`. /// - group: The `EventLoopGroup` to use for the listening channel.
public convenience init(group: EventLoopGroup) { public convenience init(group: EventLoopGroup) {
self.init(group: group, childGroup: group) self.init(group: group, childGroup: group)
} }
/// Create a ``NIOTSListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`. /// Create a ``NIOTSDatagramListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`.
/// ///
/// - parameters: /// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `NIOTSListenerChannel`. /// - group: The ``NIOTSEventLoopGroup`` to use for the listening channel.
public convenience init(group: NIOTSEventLoopGroup) { public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup) self.init(group: group as EventLoopGroup)
} }
/// Create a ``NIOTSListenerBootstrap``. /// Create a ``NIOTSDatagramListenerBootstrap``.
/// ///
/// This initializer only exists to be more in-line with the NIO core bootstraps, in that they /// 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 /// may be constructed with an `EventLoopGroup` and by extension an `EventLoop`. As such an
@ -106,9 +105,8 @@ public final class NIOTSDatagramListenerBootstrap {
/// > Note: 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: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The `EventLoopGroup` to use for the `bind` of the listening channel and to accept new child channels with.
/// and to accept new `NIOTSConnectionChannel`s with. /// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on.
public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) { public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) {
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else { guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
preconditionFailure( preconditionFailure(
@ -121,13 +119,12 @@ public final class NIOTSDatagramListenerBootstrap {
self.init(validatingGroup: group, childGroup: childGroup)! self.init(validatingGroup: group, childGroup: childGroup)!
} }
/// Create a ``NIOTSListenerBootstrap`` on the `EventLoopGroup` `group` which accepts `Channel`s on `childGroup`, /// Create a ``NIOTSDatagramListenerBootstrap`` on the `EventLoopGroup` `group` which accepts `Channel`s
/// validating that the `EventLoopGroup`s are compatible with ``NIOTSListenerBootstrap``. /// on `childGroup`, validating that the `EventLoopGroup`s are compatible with ``NIOTSDatagramListenerBootstrap``.
/// ///
/// - parameters: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The `EventLoopGroup` to use for the `bind` of the listening channel and to accept new child channels with.
/// and to accept new `NIOTSConnectionChannel`s with. /// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on.
public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) { public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) {
let childGroup = childGroup ?? group let childGroup = childGroup ?? group
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else { guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
@ -138,23 +135,22 @@ public final class NIOTSDatagramListenerBootstrap {
self.childGroup = childGroup self.childGroup = childGroup
} }
/// Create a ``NIOTSListenerBootstrap``. /// Create a ``NIOTSDatagramListenerBootstrap``.
/// ///
/// - parameters: /// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the listening channel and to accept new child
/// and to accept new `NIOTSConnectionChannel`s with. /// channels with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted `NIOTSConnectionChannel`s on. /// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted child channels on.
public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) { public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup) self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup)
} }
/// Initialize the `NIOTSListenerChannel` with `initializer`. The most common task in initializer is to add /// Initialize the listening channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. /// `ChannelHandler`s to the `ChannelPipeline`.
/// ///
/// The `NIOTSListenerChannel` uses the accepted `NIOTSConnectionChannel`s as inbound messages. /// The listening channel uses the accepted child channels as inbound messages.
/// ///
/// > Note: To set the initializer for the accepted `NIOTSConnectionChannel`s, look at /// > Note: To set the initializer for the accepted child channels, look at ``childChannelInitializer(_:)``.
/// ``childChannelInitializer(_:)``.
/// ///
/// - parameters: /// - parameters:
/// - initializer: A closure that initializes the provided `Channel`. /// - initializer: A closure that initializes the provided `Channel`.
@ -165,7 +161,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self return self
} }
/// Initialize the accepted `NIOTSConnectionChannel`s with `initializer`. The most common task in initializer is to add /// Initialize the accepted child channels with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be /// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be
/// fired in the *parent* channel. /// fired in the *parent* channel.
/// ///
@ -179,9 +175,9 @@ public final class NIOTSDatagramListenerBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the `NIOTSListenerChannel`. /// Specifies a `ChannelOption` to be applied to the listening channel.
/// ///
/// > Note: To specify options for the accepted `NIOTSConnectionChannel`s, look at ``childChannelOption(_:value:)``. /// > Note: To specify options for the accepted child channels, look at ``childChannelOption(_:value:)``.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.
@ -191,7 +187,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the accepted `NIOTSConnectionChannel`s. /// Specifies a `ChannelOption` to be applied to the accepted child channels.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.
@ -268,7 +264,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self return self
} }
/// Bind the `NIOTSListenerChannel` to `host` and `port`. /// Bind the listening channel to `host` and `port`.
/// ///
/// - parameters: /// - parameters:
/// - host: The host to bind on. /// - host: The host to bind on.
@ -292,7 +288,7 @@ public final class NIOTSDatagramListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to `address`. /// Bind the listening channel to `address`.
/// ///
/// - parameters: /// - parameters:
/// - address: The `SocketAddress` to bind on. /// - address: The `SocketAddress` to bind on.
@ -302,7 +298,7 @@ public final class NIOTSDatagramListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to a UNIX Domain Socket. /// Bind the listening channel to a UNIX Domain Socket.
/// ///
/// - parameters: /// - parameters:
/// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system. /// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system.
@ -317,7 +313,7 @@ public final class NIOTSDatagramListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to a given `NWEndpoint`. /// Bind the listening channel to a given `NWEndpoint`.
/// ///
/// - parameters: /// - parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to. /// - endpoint: The `NWEndpoint` to bind this channel to.
@ -327,7 +323,7 @@ public final class NIOTSDatagramListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to an existing `NWListener`. /// Bind the listening channel to an existing `NWListener`.
/// ///
/// - parameters: /// - parameters:
/// - listener: The NWListener to wrap. /// - listener: The NWListener to wrap.
@ -388,7 +384,7 @@ public final class NIOTSDatagramListenerBootstrap {
eventLoop.assertInEventLoop() eventLoop.assertInEventLoop()
return eventLoop.makeCompletedFuture { return eventLoop.makeCompletedFuture {
try serverChannel.pipeline.syncOperations.addHandler( try serverChannel.pipeline.syncOperations.addHandler(
AcceptHandler<NIOTSDatagramChannel>( AcceptHandler<NIOTSDatagramConnectionChannel>(
childChannelInitializer: childChannelInit, childChannelInitializer: childChannelInit,
childChannelOptions: childChannelOptions childChannelOptions: childChannelOptions
) )

4
Sources/NIOTransportServices/Datagram/NIOTSDatagramListenerChannel.swift
View File

@ -22,7 +22,7 @@ import Network
import Atomics import Atomics
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
internal final class NIOTSDatagramListenerChannel: StateManagedListenerChannel<NIOTSDatagramChannel> { internal final class NIOTSDatagramListenerChannel: StateManagedListenerChannel<NIOTSDatagramConnectionChannel> {
/// The TCP options for this listener. /// The TCP options for this listener.
private var udpOptions: NWProtocolUDP.Options { private var udpOptions: NWProtocolUDP.Options {
get { get {
@ -135,7 +135,7 @@ internal final class NIOTSDatagramListenerChannel: StateManagedListenerChannel<N
return return
} }
let newChannel = NIOTSDatagramChannel( let newChannel = NIOTSDatagramConnectionChannel(
wrapping: connection, wrapping: connection,
on: self.childLoopGroup.next() as! NIOTSEventLoop, on: self.childLoopGroup.next() as! NIOTSEventLoop,
parent: self, parent: self,

18
Sources/NIOTransportServices/NIOTSConnectionBootstrap.swift
View File

@ -17,9 +17,9 @@ import NIOCore
import Dispatch import Dispatch
import Network import Network
/// A `NIOTSConnectionBootstrap` is an easy way to bootstrap a `NIOTSConnectionChannel` when creating network clients. /// A ``NIOTSConnectionBootstrap`` is an easy way to bootstrap a channel when creating network clients.
/// ///
/// Usually you re-use a `NIOTSConnectionBootstrap` once you set it up, calling `connect` multiple times on the same bootstrap. /// 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. /// This way you ensure that the same `EventLoop`s will be shared across all your connections.
/// ///
/// Example: /// Example:
@ -37,7 +37,7 @@ import Network
/// /* the Channel is now connected */ /// /* the Channel is now connected */
/// ``` /// ```
/// ///
/// The connected `NIOTSConnectionChannel` will operate on `ByteBuffer` as inbound and on `IOData` as outbound messages. /// The connected channel will operate on `ByteBuffer` as inbound and on `IOData` as outbound messages.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSConnectionBootstrap { public final class NIOTSConnectionBootstrap {
private let group: EventLoopGroup private let group: EventLoopGroup
@ -64,9 +64,9 @@ public final class NIOTSConnectionBootstrap {
private var protocolHandlers: (@Sendable () -> [ChannelHandler])? = nil private var protocolHandlers: (@Sendable () -> [ChannelHandler])? = nil
private var nwParametersConfigurator: (@Sendable (NWParameters) -> Void)? private var nwParametersConfigurator: (@Sendable (NWParameters) -> Void)?
/// Create a `NIOTSConnectionBootstrap` on the `EventLoopGroup` `group`. /// Create a ``NIOTSConnectionBootstrap`` on the `EventLoopGroup` `group`.
/// ///
/// The `EventLoopGroup` `group` must be compatible, otherwise the program will crash. `NIOTSConnectionBootstrap` is /// 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 /// compatible only with ``NIOTSEventLoopGroup`` as well as the `EventLoop`s returned by
/// ``NIOTSEventLoopGroup/next()``. See ``init(validatingGroup:)`` for a fallible initializer for /// ``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. /// situations where it's impossible to tell ahead of time if the `EventLoopGroup` is compatible or not.
@ -84,7 +84,7 @@ public final class NIOTSConnectionBootstrap {
self.init(validatingGroup: group)! self.init(validatingGroup: group)!
} }
/// Create a `NIOTSConnectionBootstrap` on the ``NIOTSEventLoopGroup`` `group`. /// Create a ``NIOTSConnectionBootstrap`` on the ``NIOTSEventLoopGroup`` `group`.
/// ///
/// - parameters: /// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use. /// - group: The ``NIOTSEventLoopGroup`` to use.
@ -92,7 +92,7 @@ public final class NIOTSConnectionBootstrap {
self.init(group: group as EventLoopGroup) self.init(group: group as EventLoopGroup)
} }
/// Create a `NIOTSConnectionBootstrap` on the ``NIOTSEventLoopGroup`` `group`, validating /// Create a ``NIOTSConnectionBootstrap`` on the ``NIOTSEventLoopGroup`` `group`, validating
/// that the `EventLoopGroup` is compatible with ``NIOTSConnectionBootstrap``. /// that the `EventLoopGroup` is compatible with ``NIOTSConnectionBootstrap``.
/// ///
/// - parameters: /// - parameters:
@ -107,7 +107,7 @@ public final class NIOTSConnectionBootstrap {
self._channelInitializer = { channel in channel.eventLoop.makeSucceededVoidFuture() } self._channelInitializer = { channel in channel.eventLoop.makeSucceededVoidFuture() }
} }
/// Initialize the connected `NIOTSConnectionChannel` with `initializer`. The most common task in initializer is to add /// Initialize the connected channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. /// `ChannelHandler`s to the `ChannelPipeline`.
/// ///
/// The connected `Channel` will operate on `ByteBuffer` as inbound and `IOData` as outbound messages. /// The connected `Channel` will operate on `ByteBuffer` as inbound and `IOData` as outbound messages.
@ -120,7 +120,7 @@ public final class NIOTSConnectionBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the `NIOTSConnectionChannel`. /// Specifies a `ChannelOption` to be applied to the channel.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.

67
Sources/NIOTransportServices/NIOTSListenerBootstrap.swift
View File

@ -17,7 +17,7 @@ import NIOCore
import Dispatch import Dispatch
import Network 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 listener channel when creating network servers.
/// ///
/// Example: /// Example:
/// ///
@ -46,13 +46,12 @@ import Network
/// try! channel.closeFuture.wait() // wait forever as we never close the Channel /// try! channel.closeFuture.wait() // wait forever as we never close the Channel
/// ``` /// ```
/// ///
/// The `EventLoopFuture` returned by `bind` will fire with a `NIOTSListenerChannel`. This is the channel that owns the /// The `EventLoopFuture` returned by `bind` will fire with a channel. This is the channel that owns the listening socket. Each
/// listening socket. Each time it accepts a new connection it will fire a `NIOTSConnectionChannel` through the /// time it accepts a new connection it will fire a new child channel for the new connection through the `ChannelPipeline` via
/// `ChannelPipeline` via `fireChannelRead`: as a result, the `NIOTSListenerChannel` operates on `Channel`s as inbound /// `fireChannelRead`: as a result, the listening channel operates on `Channel`s as inbound messages. Outbound messages are
/// messages. Outbound messages are not supported on a `NIOTSListenerChannel` which means that each write attempt will /// not supported on these listening channels, which means that each write attempt will fail.
/// fail.
/// ///
/// Accepted `NIOTSConnectionChannel`s operate on `ByteBuffer` as inbound data, and `IOData` as outbound data. /// Accepted channels operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) @available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSListenerBootstrap { public final class NIOTSListenerBootstrap {
private let group: EventLoopGroup private let group: EventLoopGroup
@ -82,7 +81,7 @@ public final class NIOTSListenerBootstrap {
/// > Note: 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: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `NIOTSListenerChannel`. /// - group: The `EventLoopGroup` to use for the listening channel.
public convenience init(group: EventLoopGroup) { public convenience init(group: EventLoopGroup) {
self.init(group: group, childGroup: group) self.init(group: group, childGroup: group)
} }
@ -90,7 +89,7 @@ public final class NIOTSListenerBootstrap {
/// Create a ``NIOTSListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`. /// Create a ``NIOTSListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`.
/// ///
/// - parameters: /// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `NIOTSListenerChannel`. /// - group: The ``NIOTSEventLoopGroup`` to use for the listening channel.
public convenience init(group: NIOTSEventLoopGroup) { public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup) self.init(group: group as EventLoopGroup)
} }
@ -106,9 +105,9 @@ public final class NIOTSListenerBootstrap {
/// > Note: 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: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The `EventLoopGroup` to use for the `bind` of the listening channel
/// and to accept new `NIOTSConnectionChannel`s with. /// and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on. /// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) { public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) {
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else { guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
preconditionFailure( preconditionFailure(
@ -125,9 +124,9 @@ public final class NIOTSListenerBootstrap {
/// validating that the `EventLoopGroup`s are compatible with ``NIOTSListenerBootstrap``. /// validating that the `EventLoopGroup`s are compatible with ``NIOTSListenerBootstrap``.
/// ///
/// - parameters: /// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The `EventLoopGroup` to use for the `bind` of the listening channel
/// and to accept new `NIOTSConnectionChannel`s with. /// and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on. /// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) { public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) {
let childGroup = childGroup ?? group let childGroup = childGroup ?? group
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else { guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
@ -144,19 +143,19 @@ public final class NIOTSListenerBootstrap {
/// Create a ``NIOTSListenerBootstrap``. /// Create a ``NIOTSListenerBootstrap``.
/// ///
/// - parameters: /// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the `NIOTSListenerChannel` /// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the listening channel
/// and to accept new `NIOTSConnectionChannel`s with. /// and to accept new child channels with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted `NIOTSConnectionChannel`s on. /// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted child channels on.
public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) { public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup) self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup)
} }
/// Initialize the `NIOTSListenerChannel` with `initializer`. The most common task in initializer is to add /// Initialize the listening channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. /// `ChannelHandler`s to the `ChannelPipeline`.
/// ///
/// The `NIOTSListenerChannel` uses the accepted `NIOTSConnectionChannel`s as inbound messages. /// The listening channel uses the accepted child channels as inbound messages.
/// ///
/// > Note: To set the initializer for the accepted `NIOTSConnectionChannel`s, look at /// > Note: To set the initializer for the accepted child channels, look at
/// ``childChannelInitializer(_:)``. /// ``childChannelInitializer(_:)``.
/// ///
/// - parameters: /// - parameters:
@ -168,7 +167,7 @@ public final class NIOTSListenerBootstrap {
return self return self
} }
/// Initialize the accepted `NIOTSConnectionChannel`s with `initializer`. The most common task in initializer is to add /// Initialize the accepted child channels with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be /// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be
/// fired in the *parent* channel. /// fired in the *parent* channel.
/// ///
@ -182,9 +181,9 @@ public final class NIOTSListenerBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the `NIOTSListenerChannel`. /// Specifies a `ChannelOption` to be applied to the listening channel.
/// ///
/// > Note: To specify options for the accepted `NIOTSConnectionChannel`s, look at ``childChannelOption(_:value:)``. /// > Note: To specify options for the accepted child channels, look at ``childChannelOption(_:value:)``.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.
@ -194,7 +193,7 @@ public final class NIOTSListenerBootstrap {
return self return self
} }
/// Specifies a `ChannelOption` to be applied to the accepted `NIOTSConnectionChannel`s. /// Specifies a `ChannelOption` to be applied to the accepted child channels.
/// ///
/// - parameters: /// - parameters:
/// - option: The option to be applied. /// - option: The option to be applied.
@ -281,7 +280,7 @@ public final class NIOTSListenerBootstrap {
self.serverChannelOption(NIOTSChannelOptions.multipathServiceType, value: type) self.serverChannelOption(NIOTSChannelOptions.multipathServiceType, value: type)
} }
/// Bind the `NIOTSListenerChannel` to `host` and `port`. /// Bind the listening channel to `host` and `port`.
/// ///
/// - parameters: /// - parameters:
/// - host: The host to bind on. /// - host: The host to bind on.
@ -305,7 +304,7 @@ public final class NIOTSListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to `address`. /// Bind the listening channel to `address`.
/// ///
/// - parameters: /// - parameters:
/// - address: The `SocketAddress` to bind on. /// - address: The `SocketAddress` to bind on.
@ -315,7 +314,7 @@ public final class NIOTSListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to a UNIX Domain Socket. /// Bind the listening channel to a UNIX Domain Socket.
/// ///
/// - parameters: /// - parameters:
/// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system. /// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system.
@ -330,7 +329,7 @@ public final class NIOTSListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to a given `NWEndpoint`. /// Bind the listening channel to a given `NWEndpoint`.
/// ///
/// - parameters: /// - parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to. /// - endpoint: The `NWEndpoint` to bind this channel to.
@ -340,7 +339,7 @@ public final class NIOTSListenerBootstrap {
} }
} }
/// Bind the `NIOTSListenerChannel` to an existing `NWListener`. /// Bind the listening channel to an existing `NWListener`.
/// ///
/// - parameters: /// - parameters:
/// - listener: The NWListener to wrap. /// - listener: The NWListener to wrap.
@ -441,7 +440,7 @@ public final class NIOTSListenerBootstrap {
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
extension NIOTSListenerBootstrap { extension NIOTSListenerBootstrap {
/// Bind the `NIOTSListenerChannel` to `host` and `port`. /// Bind the listening channel to `host` and `port`.
/// ///
/// - Parameters: /// - Parameters:
/// - host: The host to bind on. /// - host: The host to bind on.
@ -486,7 +485,7 @@ extension NIOTSListenerBootstrap {
).get() ).get()
} }
/// Bind the `NIOTSListenerChannel` to `address`. /// Bind the listening channel to `address`.
/// ///
/// - Parameters: /// - Parameters:
/// - address: The `SocketAddress` to bind on. /// - address: The `SocketAddress` to bind on.
@ -516,7 +515,7 @@ extension NIOTSListenerBootstrap {
).get() ).get()
} }
/// Bind the `NIOTSListenerChannel` to a given `NWEndpoint`. /// Bind the listening channel to a given `NWEndpoint`.
/// ///
/// - Parameters: /// - Parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to. /// - endpoint: The `NWEndpoint` to bind this channel to.
@ -549,7 +548,7 @@ extension NIOTSListenerBootstrap {
).get() ).get()
} }
/// Bind the `NIOTSListenerChannel` to an existing `NWListener`. /// Bind the listening channel to an existing `NWListener`.
/// ///
/// - Parameters: /// - Parameters:
/// - listener: The NWListener to wrap. /// - listener: The NWListener to wrap.

10
Tests/NIOTransportServicesTests/NIOTSDatagramConnectionChannelTests.swift → Tests/NIOTransportServicesTests/NIOTSDatagramBootstrapTests.swift
View File

@ -114,7 +114,7 @@ final class ReadRecorder<DataType: Sendable>: ChannelInboundHandler {
// Mimicks the DatagramChannelTest from apple/swift-nio // Mimicks the DatagramChannelTest from apple/swift-nio
@available(macOS 10.14, iOS 12.0, tvOS 12.0, watchOS 6, *) @available(macOS 10.14, iOS 12.0, tvOS 12.0, watchOS 6, *)
final class NIOTSDatagramConnectionChannelTests: XCTestCase { final class NIOTSDatagramBootstrapTests: XCTestCase {
private var group: NIOTSEventLoopGroup! private var group: NIOTSEventLoopGroup!
private func buildServerChannel( private func buildServerChannel(
@ -142,7 +142,7 @@ final class NIOTSDatagramConnectionChannelTests: XCTestCase {
host: String = "127.0.0.1", host: String = "127.0.0.1",
port: Int port: Int
) throws -> Channel { ) throws -> Channel {
try NIOTSDatagramBootstrap(group: group) try NIOTSDatagramConnectionBootstrap(group: group)
.channelInitializer { channel in .channelInitializer { channel in
channel.eventLoop.makeCompletedFuture { channel.eventLoop.makeCompletedFuture {
try channel.pipeline.syncOperations.addHandler( try channel.pipeline.syncOperations.addHandler(
@ -219,7 +219,7 @@ final class NIOTSDatagramConnectionChannelTests: XCTestCase {
XCTAssertNoThrow(try listener.close().wait()) XCTAssertNoThrow(try listener.close().wait())
} }
let connection = try! NIOTSDatagramBootstrap(group: self.group) let connection = try! NIOTSDatagramConnectionBootstrap(group: self.group)
.channelInitializer { channel in .channelInitializer { channel in
testSyncOptions(channel) testSyncOptions(channel)
return channel.eventLoop.makeSucceededVoidFuture() return channel.eventLoop.makeSucceededVoidFuture()
@ -257,7 +257,7 @@ final class NIOTSDatagramConnectionChannelTests: XCTestCase {
.bind(host: "localhost", port: 0) .bind(host: "localhost", port: 0)
.get() .get()
let connectionChannel: Channel = try await NIOTSDatagramBootstrap(group: group) let connectionChannel: Channel = try await NIOTSDatagramConnectionBootstrap(group: group)
.configureNWParameters { _ in .configureNWParameters { _ in
configuratorClientConnectionCounter.withLockedValue { $0 += 1 } configuratorClientConnectionCounter.withLockedValue { $0 += 1 }
} }
@ -292,7 +292,7 @@ final class NIOTSDatagramConnectionChannelTests: XCTestCase {
XCTAssertNoThrow(try listener.close().wait()) XCTAssertNoThrow(try listener.close().wait())
} }
_ = try NIOTSDatagramBootstrap(group: self.group) _ = try NIOTSDatagramConnectionBootstrap(group: self.group)
.channelInitializer { channel in .channelInitializer { channel in
let conn = try! channel.syncOptions!.getOption(NIOTSChannelOptions.connection) let conn = try! channel.syncOptions!.getOption(NIOTSChannelOptions.connection)
XCTAssertNil(conn) XCTAssertNil(conn)