Merge branch 'main' into jw-more-pcap

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [NIOExtras, NIOHTTPCompression, NIOSOCKS]

Package.swift

@@ -1,9 +1,9 @@
-// swift-tools-version:5.4
+// swift-tools-version:5.6
 //===----------------------------------------------------------------------===//
 //
 // 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
@@ -31,31 +31,31 @@ var targets: [PackageDescription.Target] = [
             .product(name: "NIOCore", package: "swift-nio"),
             .product(name: "NIOHTTP1", package: "swift-nio"),
         ]),
-    .target(
+    .executableTarget(
         name: "HTTPServerWithQuiescingDemo",
         dependencies: [
             "NIOExtras",
             .product(name: "NIOCore", package: "swift-nio"),
             .product(name: "NIOPosix", package: "swift-nio"),
             .product(name: "NIOHTTP1", package: "swift-nio"),
         ]),
-    .target(
+    .executableTarget(
         name: "NIOWritePCAPDemo",
         dependencies: [
             "NIOExtras",
             .product(name: "NIOCore", package: "swift-nio"),
             .product(name: "NIOPosix", package: "swift-nio"),
             .product(name: "NIOHTTP1", package: "swift-nio"),
         ]),
-    .target(
+    .executableTarget(
         name: "NIOWritePartialPCAPDemo",
         dependencies: [
             "NIOExtras",
             .product(name: "NIOCore", package: "swift-nio"),
             .product(name: "NIOPosix", package: "swift-nio"),
             .product(name: "NIOHTTP1", package: "swift-nio"),
         ]),
-    .target(
+    .executableTarget(
         name: "NIOExtrasPerformanceTester",
         dependencies: [
             "NIOExtras",
@@ -70,7 +70,7 @@ var targets: [PackageDescription.Target] = [
             .product(name: "NIO", package: "swift-nio"),
             .product(name: "NIOCore", package: "swift-nio"),
         ]),
-    .target(
+    .executableTarget(
         name: "NIOSOCKSClient",
         dependencies: [
             .product(name: "NIOCore", package: "swift-nio"),
@@ -125,7 +125,8 @@ let package = Package(
         .library(name: "NIOHTTPCompression", targets: ["NIOHTTPCompression"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.42.0"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: targets
 )

Package@swift-5.5.swift

@@ -0,0 +1,125 @@
+// swift-tools-version:5.5
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2017-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 PackageDescription
+
+var targets: [PackageDescription.Target] = [
+    .target(
+        name: "NIOExtras",
+        dependencies: [
+            .product(name: "NIO", package: "swift-nio"),
+            .product(name: "NIOCore", package: "swift-nio"),
+        ]),
+    .target(
+        name: "NIOHTTPCompression",
+        dependencies: [
+            "CNIOExtrasZlib",
+            .product(name: "NIO", package: "swift-nio"),
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+        ]),
+    .executableTarget(
+        name: "HTTPServerWithQuiescingDemo",
+        dependencies: [
+            "NIOExtras",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+        ]),
+    .executableTarget(
+        name: "NIOWritePCAPDemo",
+        dependencies: [
+            "NIOExtras",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+        ]),
+    .executableTarget(
+        name: "NIOWritePartialPCAPDemo",
+        dependencies: [
+            "NIOExtras",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+        ]),
+    .executableTarget(
+        name: "NIOExtrasPerformanceTester",
+        dependencies: [
+            "NIOExtras",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            .product(name: "NIOEmbedded", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+        ]),
+    .target(
+        name: "NIOSOCKS",
+        dependencies: [
+            .product(name: "NIO", package: "swift-nio"),
+            .product(name: "NIOCore", package: "swift-nio"),
+        ]),
+    .executableTarget(
+        name: "NIOSOCKSClient",
+        dependencies: [
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            "NIOSOCKS"
+        ]),
+    .target(
+        name: "CNIOExtrasZlib",
+        dependencies: [],
+        linkerSettings: [
+            .linkedLibrary("z")
+        ]),
+    .testTarget(
+        name: "NIOExtrasTests",
+        dependencies: [
+            "NIOExtras",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOEmbedded", package: "swift-nio"),
+            .product(name: "NIOPosix", package: "swift-nio"),
+            .product(name: "NIOTestUtils", package: "swift-nio"),
+            .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+        ]),
+    .testTarget(
+        name: "NIOHTTPCompressionTests",
+        dependencies: [
+            "CNIOExtrasZlib",
+            "NIOHTTPCompression",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOEmbedded", package: "swift-nio"),
+            .product(name: "NIOHTTP1", package: "swift-nio"),
+            .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+        ]),
+    .testTarget(
+        name: "NIOSOCKSTests",
+        dependencies: [
+            "NIOSOCKS",
+            .product(name: "NIOCore", package: "swift-nio"),
+            .product(name: "NIOEmbedded", package: "swift-nio"),
+        ])
+]
+
+let package = Package(
+    name: "swift-nio-extras",
+    products: [
+        .library(name: "NIOExtras", targets: ["NIOExtras"]),
+        .library(name: "NIOSOCKS", targets: ["NIOSOCKS"]),
+        .library(name: "NIOHTTPCompression", targets: ["NIOHTTPCompression"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.34.0"),
+    ],
+    targets: targets
+)

README.md

@@ -14,7 +14,7 @@ All code will go through code review like in the other repositories related to t
 `swift-nio-extras` part of the SwiftNIO 2 family of repositories and depends on the following:
 
 - [`swift-nio`](https://github.com/apple/swift-nio), version 2.30.0 or better.
-- Swift 5.4.
+- Swift 5.5.2
 - `zlib` and its development headers installed on the system. But don't worry, you'll find `zlib` on pretty much any UNIX system that can compile any sort of code.
 
 To depend on `swift-nio-extras`, put the following in the `dependencies` of your `Package.swift`:
@@ -25,7 +25,14 @@ To depend on `swift-nio-extras`, put the following in the `dependencies` of your
 
 ### Support for older Swift versions
 
-Earlier versions of SwiftNIO (2.39.x and lower) and SwiftNIOExtras (1.10.x and lower) supported Swift 5.2 and 5.3, SwiftNIO (2.29.x and lower) and SwiftNIOExtras (1.9.x and lower) supported Swift 5.0 and 5.1. 
+The most recent versions of SwiftNIO Extras support Swift 5.5.2 and newer. The minimum Swift version supported by SwiftNIO Extras releases are detailed below:
+
+SwiftNIO Extras     | Minimum Swift Version
+--------------------|----------------------
+`1.0.0 ..< 1.10.0`  | 5.0
+`1.10.0 ..< 1.11.0` | 5.2
+`1.11.0 ..< 1.14.0` | 5.4
+`1.14.0 ...`        | 5.5.2
 
 On the [`nio-extras-0.1`](https://github.com/apple/swift-nio-extras/tree/nio-extras-0.1) branch, you can find the `swift-nio-extras` version for the SwiftNIO 1 family. It requires Swift 4.1 or better.
 

Sources/NIOExtras/DebugInboundEventsHandler.swift

@@ -19,76 +19,135 @@ import Glibc
 
 import NIOCore
 
-/// ChannelInboundHandler that prints all inbound events that pass through the pipeline by default,
-/// overridable by providing your own closure for custom logging. See DebugOutboundEventsHandler for outbound events.
+/// `ChannelInboundHandler` that prints all inbound events that pass through the pipeline by default,
+/// overridable by providing your own closure for custom logging. See ``DebugOutboundEventsHandler`` for outbound events.
 public class DebugInboundEventsHandler: ChannelInboundHandler {
-
+    /// The type of the inbound data which is wrapped in `NIOAny`.
     public typealias InboundIn = Any
+    /// The type of the inbound data which will be forwarded to the next `ChannelInboundHandler` in the `ChannelPipeline`.
     public typealias InboudOut = Any
-
+
+    /// Enumeration of possible `ChannelHandler` events which can occur.
     public enum Event {
+        /// Channel was registered.
         case registered
+        /// Channel was unregistered.
         case unregistered
+        /// Channel became active.
         case active
+        /// Channel became inactive.
         case inactive
+        /// Data was received.
         case read(data: NIOAny)
+        ///  Current read loop finished.
         case readComplete
+        /// Writability state of the channel changed.
         case writabilityChanged(isWritable: Bool)
+        /// A user inbound event was received.
         case userInboundEventTriggered(event: Any)
+        /// An error was caught.
         case errorCaught(Error)
     }
 
     var logger: (Event, ChannelHandlerContext) -> ()
-
+
+    /// Initialiser.
+    /// - Parameter logger: Method for logging events which occur.
     public init(logger: @escaping (Event, ChannelHandlerContext) -> () = DebugInboundEventsHandler.defaultPrint) {
         self.logger = logger
     }
-
+
+    /// Logs ``Event.registered`` to ``logger``
+    /// Called when the `Channel` has successfully registered with its `EventLoop` to handle I/O.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelRegistered(context: ChannelHandlerContext) {
         logger(.registered, context)
         context.fireChannelRegistered()
     }
-
+
+    /// Logs ``Event.unregistered`` to ``logger``
+    /// Called when the `Channel` has unregistered from its `EventLoop`, and so will no longer be receiving I/O events.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelUnregistered(context: ChannelHandlerContext) {
         logger(.unregistered, context)
         context.fireChannelUnregistered()
     }
-
+
+    /// Logs ``Event.active`` to ``logger``
+    /// Called when the `Channel` has become active, and is able to send and receive data.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelActive(context: ChannelHandlerContext) {
         logger(.active, context)
         context.fireChannelActive()
     }
-
+
+    /// Logs ``Event.inactive`` to ``logger``
+    /// Called when the `Channel` has become inactive and is no longer able to send and receive data`.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelInactive(context: ChannelHandlerContext) {
         logger(.inactive, context)
         context.fireChannelInactive()
     }
-
+
+    /// Logs ``Event.read`` to ``logger``
+    /// Called when some data has been read from the remote peer.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
+    ///     - data: The data read from the remote peer, wrapped in a `NIOAny`.
     public func channelRead(context: ChannelHandlerContext, data: NIOAny) {
         logger(.read(data: data), context)
         context.fireChannelRead(data)
     }
-
+
+    /// Logs ``Event.readComplete`` to ``logger``
+    /// Called when the `Channel` has completed its current read loop, either because no more data is available
+    /// to read from the transport at this time, or because the `Channel` needs to yield to the event loop to process
+    /// other I/O events for other `Channel`s.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelReadComplete(context: ChannelHandlerContext) {
         logger(.readComplete, context)
         context.fireChannelReadComplete()
     }
-
+
+    /// Logs ``Event.writabilityChanged`` to ``logger``
+    /// The writability state of the `Channel` has changed, either because it has buffered more data than the writability
+    /// high water mark, or because the amount of buffered data has dropped below the writability low water mark.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     public func channelWritabilityChanged(context: ChannelHandlerContext) {
         logger(.writabilityChanged(isWritable: context.channel.isWritable), context)
         context.fireChannelWritabilityChanged()
     }
-
+
+    /// Logs ``Event.userInboundEventTriggered`` to ``logger``
+    /// Called when a user inbound event has been triggered.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
+    ///     - event: The event.
     public func userInboundEventTriggered(context: ChannelHandlerContext, event: Any) {
         logger(.userInboundEventTriggered(event: event), context)
         context.fireUserInboundEventTriggered(event)
     }
-
+
+    /// Logs ``Event.errorCaught`` to ``logger``
+    /// An error was encountered earlier in the inbound `ChannelPipeline`.
+    /// - parameters:
+    ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
+    ///     - error: The `Error` that was encountered.
     public func errorCaught(context: ChannelHandlerContext, error: Error) {
         logger(.errorCaught(error), context)
         context.fireErrorCaught(error)
     }
-
+
+    /// Print and flush a textual description of an ``Event``.
+    /// - parameters:
+    ///     - event: The ``Event`` to print.
+    ///     - context: The context `event` was received in.
     public static func defaultPrint(event: Event, in context: ChannelHandlerContext) {
         let message: String
         switch event {
@@ -114,5 +173,9 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         print(message + " in \(context.name)")
         fflush(stdout)
     }
-
 }
+
+#if swift(>=5.6)
+@available(*, unavailable)
+extension DebugInboundEventsHandler: Sendable {}
+#endif