From c1153fcf9df2cec8bc751c6179a56c4f7fd92489 Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Fri, 13 Sep 2024 16:48:28 +0100 Subject: [PATCH 1/2] Documentation fixes --- Sources/HummingbirdWSClient/Exports.swift | 2 +- .../HummingbirdWSClient/WebSocketClient.swift | 2 +- .../WebSocketExtension.swift | 1 - .../WebSocketInboundMessageStream.swift | 2 +- Sources/HummingbirdWebSocket/Exports.swift | 2 +- .../WebSocketChannel.swift | 23 +++++++++++++------ .../WebSocketRouter.swift | 13 +++++------ 7 files changed, 26 insertions(+), 19 deletions(-) diff --git a/Sources/HummingbirdWSClient/Exports.swift b/Sources/HummingbirdWSClient/Exports.swift index 6a282d2..95ade0c 100644 --- a/Sources/HummingbirdWSClient/Exports.swift +++ b/Sources/HummingbirdWSClient/Exports.swift @@ -12,4 +12,4 @@ // //===----------------------------------------------------------------------===// -@_exported import HummingbirdWSCore +@_exported @_documentation(visibility: internal) import HummingbirdWSCore diff --git a/Sources/HummingbirdWSClient/WebSocketClient.swift b/Sources/HummingbirdWSClient/WebSocketClient.swift index 09de8be..0ca37b9 100644 --- a/Sources/HummingbirdWSClient/WebSocketClient.swift +++ b/Sources/HummingbirdWSClient/WebSocketClient.swift @@ -40,7 +40,7 @@ import NIOWebSocket /// } /// ``` public struct WebSocketClient { - /// Basic context implementation of ``WebSocketContext``. + /// Basic context implementation of ``/HummingbirdWSCore/WebSocketContext``. /// Used by non-router web socket handle function public struct Context: WebSocketContext { public let logger: Logger diff --git a/Sources/HummingbirdWSCore/WebSocketExtension.swift b/Sources/HummingbirdWSCore/WebSocketExtension.swift index 67e978a..248e07e 100644 --- a/Sources/HummingbirdWSCore/WebSocketExtension.swift +++ b/Sources/HummingbirdWSCore/WebSocketExtension.swift @@ -157,7 +157,6 @@ public struct WebSocketExtensionHTTPParameters: Sendable, Equatable { /// Parse all `Sec-WebSocket-Extensions` header values /// - Parameters: /// - headers: headers coming from other - /// - type: client or server /// - Returns: Array of extensions public static func parseHeaders(_ headers: HTTPFields) -> [WebSocketExtensionHTTPParameters] { let extHeaders = headers[values: .secWebSocketExtensions] diff --git a/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift b/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift index 6fa5aa1..4d0bdda 100644 --- a/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift +++ b/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift @@ -43,7 +43,7 @@ extension WebSocketInboundStream { /// converts the inbound stream of WebSocket data frames into a sequence of WebSocket /// messages. /// - /// - Parameter maxMessageSize: The maximum size of message we are allowed to create + /// - Parameter maxSize: The maximum size of message we are allowed to create public func messages(maxSize: Int) -> WebSocketInboundMessageStream { .init(inboundStream: self, maxSize: maxSize) } diff --git a/Sources/HummingbirdWebSocket/Exports.swift b/Sources/HummingbirdWebSocket/Exports.swift index 6a282d2..95ade0c 100644 --- a/Sources/HummingbirdWebSocket/Exports.swift +++ b/Sources/HummingbirdWebSocket/Exports.swift @@ -12,4 +12,4 @@ // //===----------------------------------------------------------------------===// -@_exported import HummingbirdWSCore +@_exported @_documentation(visibility: internal) import HummingbirdWSCore diff --git a/Sources/HummingbirdWebSocket/WebSocketChannel.swift b/Sources/HummingbirdWebSocket/WebSocketChannel.swift index 5276d6d..9be1417 100644 --- a/Sources/HummingbirdWebSocket/WebSocketChannel.swift +++ b/Sources/HummingbirdWebSocket/WebSocketChannel.swift @@ -39,7 +39,7 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl public let channel: Channel } - /// Basic context implementation of ``WebSocketContext``. + /// Basic context implementation of ``/HummingbirdWSCore/WebSocketContext``. /// Used by non-router web socket handle function public struct Context: WebSocketContext { public let logger: Logger @@ -51,11 +51,10 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl /// Initialize HTTP1AndWebSocketChannel with synchronous `shouldUpgrade` function /// - Parameters: - /// - additionalChannelHandlers: Additional channel handlers to add /// - responder: HTTP responder - /// - maxFrameSize: Max frame size WebSocket will allow + /// - configuration: WebSocket configuration + /// - additionalChannelHandlers: Additional channel handlers to add /// - shouldUpgrade: Function returning whether upgrade should be allowed - /// - Returns: Upgrade result future public init( responder: @escaping HTTPChannelHandler.Responder, configuration: WebSocketServerConfiguration, @@ -97,13 +96,23 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl self.responder = responder } + @available(*, deprecated, renamed: "init(responder:configuration:additionalChannelHandlers:shouldUpgrade:)") + @_documentation(visibility: internal) + public init( + responder: @escaping HTTPChannelHandler.Responder, + additionalChannelHandlers: @escaping @Sendable () -> [any RemovableChannelHandler] = { [] }, + configuration: WebSocketServerConfiguration, + shouldUpgrade: @escaping @Sendable (HTTPRequest, Channel, Logger) async throws -> ShouldUpgradeResult> + ) { + self.init(responder: responder, configuration: configuration, additionalChannelHandlers: additionalChannelHandlers, shouldUpgrade: shouldUpgrade) + } + /// Initialize HTTP1AndWebSocketChannel with async `shouldUpgrade` function /// - Parameters: - /// - additionalChannelHandlers: Additional channel handlers to add /// - responder: HTTP responder - /// - maxFrameSize: Max frame size WebSocket will allow + /// - additionalChannelHandlers: Additional channel handlers to add + /// - configuration: WebSocket configuration /// - shouldUpgrade: Function returning whether upgrade should be allowed - /// - Returns: Upgrade result future public init( responder: @escaping HTTPChannelHandler.Responder, configuration: WebSocketServerConfiguration, diff --git a/Sources/HummingbirdWebSocket/WebSocketRouter.swift b/Sources/HummingbirdWebSocket/WebSocketRouter.swift index 1c25eec..32738c0 100644 --- a/Sources/HummingbirdWebSocket/WebSocketRouter.swift +++ b/Sources/HummingbirdWebSocket/WebSocketRouter.swift @@ -85,7 +85,7 @@ extension RouterMethods { /// - Parameters: /// - path: Path to match /// - shouldUpgrade: Should request be upgraded - /// - handler: WebSocket channel handler + /// - handler: WebSocket channel handler function @discardableResult public func ws( _ path: RouterPath = "", shouldUpgrade: @Sendable @escaping (Request, Context) async throws -> RouterShouldUpgrade = { _, _ in .upgrade([:]) }, @@ -115,7 +115,7 @@ public struct WebSocketUpgradeMiddleware: Rout /// Initialize WebSocketUpgradeMiddleare /// - Parameters: /// - shouldUpgrade: Return whether the WebSocket upgrade should occur - /// - handle: WebSocket handler + /// - handler: WebSocket handler function public init( shouldUpgrade: @Sendable @escaping (Request, Context) async throws -> RouterShouldUpgrade = { _, _ in .upgrade([:]) }, onUpgrade handler: @escaping WebSocketDataHandler> @@ -140,11 +140,10 @@ public struct WebSocketUpgradeMiddleware: Rout extension HTTP1WebSocketUpgradeChannel { /// Initialize HTTP1WebSocketUpgradeChannel with async `shouldUpgrade` function /// - Parameters: - /// - additionalChannelHandlers: Additional channel handlers to add /// - responder: HTTP responder - /// - maxFrameSize: Max frame size WebSocket will allow - /// - webSocketRouter: WebSocket router - /// - Returns: Upgrade result future + /// - webSocketResponder: WebSocket initial request responder + /// - configuration: WebSocket configuration + /// - additionalChannelHandlers: Additional channel handlers to add public init( responder: @escaping HTTPChannelHandler.Responder, webSocketResponder: WSResponder, @@ -207,7 +206,7 @@ extension HTTPServerBuilder { /// - webSocketRouter: Router used for testing whether a WebSocket upgrade should occur /// - configuration: WebSocket server configuration /// - additionalChannelHandlers: Additional channel handlers to add to channel pipeline - /// - Returns: + /// - Returns: HTTP server builder that builds an HTTP1 with WebSocket upgrade server public static func http1WebSocketUpgrade( webSocketRouter: WSResponderBuilder, configuration: WebSocketServerConfiguration = .init(), From 1bdd93092aef40b7c6032dd9cd4b6f3dca17f33a Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Sat, 14 Sep 2024 08:32:56 +0100 Subject: [PATCH 2/2] Update Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift Co-authored-by: Joannis Orlandos --- Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift b/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift index 4d0bdda..8133f7a 100644 --- a/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift +++ b/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift @@ -43,7 +43,7 @@ extension WebSocketInboundStream { /// converts the inbound stream of WebSocket data frames into a sequence of WebSocket /// messages. /// - /// - Parameter maxSize: The maximum size of message we are allowed to create + /// - Parameter maxSize: The maximum size of message we are allowed to read public func messages(maxSize: Int) -> WebSocketInboundMessageStream { .init(inboundStream: self, maxSize: maxSize) }