diff --git a/NOTICE.txt b/NOTICE.txt index 9c25a7f..89102cd 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -59,3 +59,12 @@ This product contains a fuzz testing harness derived from Swift Protobuf. * https://github.com/apple/swift-protobuf/blob/main/LICENSE.txt * HOMEPAGE: * https://github.com/apple/swift-protobuf + +--- + +This product contains a graceful shutdown connection manager derived from gRPC Swift NIO Transport. + + * LICENSE (Apache License 2.0): + * https://github.com/grpc/grpc-swift-nio-transport/blob/main/LICENSE + * HOMEPAGE: + * https://github.com/gRPC/gRPC-swift-nio-transport diff --git a/Sources/NIOHTTP2/HTTP2PipelineHelpers.swift b/Sources/NIOHTTP2/HTTP2PipelineHelpers.swift index 12c3b01..f67f433 100644 --- a/Sources/NIOHTTP2/HTTP2PipelineHelpers.swift +++ b/Sources/NIOHTTP2/HTTP2PipelineHelpers.swift @@ -927,6 +927,65 @@ extension ChannelPipeline.SynchronousOperations { ) } + /// Configures a `ChannelPipeline` to speak HTTP/2 and sets up mapping functions so that it may be interacted with + /// from concurrent code. This variant includes a ``NIOHTTP2ServerConnectionManagementHandler`` argument, and links + /// its stream and frame delegates with ``NIOHTTP2Handler``. + /// + /// This operation **must** be called on the event loop. + /// + /// In general this is not entirely useful by itself, as HTTP/2 is a negotiated protocol. This helper does not + /// handle negotiation. Instead, this simply adds the handler required to speak HTTP/2 after negotiation has + /// completed, or when agreed by prior knowledge. Use this function to setup a HTTP/2 pipeline if you wish to use + /// async sequence abstractions over inbound and outbound streams, as it allows that pipeline to evolve without + /// breaking your code. + /// + /// - Parameters: + /// - mode: The mode this pipeline will operate in, server or client. + /// - connectionManagerConfiguration: The configuration for a ``NIOHTTP2ServerConnectionManagementHandler`` + /// instance that will be initialized and used alongside the ``NIOHTTP2Handler``. + /// - http2HandlerConfiguration: The settings that will be used when establishing the connection and new streams. + /// - streamInitializer: A closure that will be called whenever the remote peer initiates a new stream. + /// The output of this closure is the element type of the returned multiplexer + /// - Returns: An `EventLoopFuture` containing the `AsyncStreamMultiplexer` inserted into this pipeline, which can + /// be used to initiate new streams and iterate over inbound HTTP/2 stream channels. + @inlinable + @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) + public func configureAsyncHTTP2Pipeline( + mode: NIOHTTP2Handler.ParserMode, + connectionManagerConfiguration: NIOHTTP2ServerConnectionManagementHandler.Configuration, + http2HandlerConfiguration: NIOHTTP2Handler.Configuration = NIOHTTP2Handler.Configuration(), + streamInitializer: @escaping NIOChannelInitializerWithOutput + ) throws -> NIOHTTP2Handler.AsyncStreamMultiplexer { + let connectionManager = NIOHTTP2ServerConnectionManagementHandler( + eventLoop: self.eventLoop, + configuration: connectionManagerConfiguration + ) + + let handler = NIOHTTP2Handler( + mode: mode, + eventLoop: self.eventLoop, + connectionConfiguration: http2HandlerConfiguration.connection, + streamConfiguration: http2HandlerConfiguration.stream, + streamDelegate: connectionManager.http2StreamDelegate, + frameDelegate: nil, + inboundStreamInitializerWithAnyOutput: { channel in + streamInitializer(channel).map { $0 } + } + ) + + try self.addHandler(handler) + try self.addHandler(connectionManager) + + let (inboundStreamChannels, continuation) = NIOHTTP2AsyncSequence.initialize( + inboundStreamInitializerOutput: Output.self + ) + + return try handler.syncAsyncStreamMultiplexer( + continuation: continuation, + inboundStreamChannels: inboundStreamChannels + ) + } + @inlinable func configureHTTP2AsyncSecureUpgrade( on channel: any Channel, diff --git a/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler+StateMachine.swift b/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler+StateMachine.swift new file mode 100644 index 0000000..33d7f1a --- /dev/null +++ b/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler+StateMachine.swift @@ -0,0 +1,239 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 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 +// +//===----------------------------------------------------------------------===// + +// swift-format-ignore: NoBlockComments +/* + * Copyright 2024, gRPC Authors All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import NIOCore + +extension NIOHTTP2ServerConnectionManagementHandler { + /// Tracks the state of TCP connections at the server. + /// + /// The state machine manages the state for the graceful shutdown procedure. + struct StateMachine { + /// Current state. + private var state: State + + /// Opaque data sent to the client in a PING frame after emitting the first GOAWAY frame + /// as part of graceful shutdown. + private let goAwayPingData: HTTP2PingData + + /// Create a new state machine. + /// + /// - Parameters: + /// - goAwayPingData: Opaque data sent to the client in a PING frame when the server + /// initiates graceful shutdown. + init(goAwayPingData: HTTP2PingData = HTTP2PingData(withInteger: .random(in: .min ... .max))) { + self.state = .active(State.Active()) + self.goAwayPingData = goAwayPingData + } + + /// Record that the stream with the given ID has been opened. + mutating func streamOpened(_ id: HTTP2StreamID) { + switch self.state { + case .active(var state): + self.state = ._modifying + state.lastStreamID = id + let (inserted, _) = state.openStreams.insert(id) + assert(inserted, "Can't open stream \(Int(id)), it's already open") + self.state = .active(state) + + case .closing(var state): + self.state = ._modifying + state.lastStreamID = id + let (inserted, _) = state.openStreams.insert(id) + assert(inserted, "Can't open stream \(Int(id)), it's already open") + self.state = .closing(state) + + case .closed: + () + + case ._modifying: + preconditionFailure() + } + } + + enum OnStreamClosed: Equatable { + /// Start the idle timer, after which the connection should be closed gracefully. + case startIdleTimer + /// Close the connection. + case close + /// Do nothing. + case none + } + + /// Record that the stream with the given ID has been closed. + mutating func streamClosed(_ id: HTTP2StreamID) -> OnStreamClosed { + let onStreamClosed: OnStreamClosed + + switch self.state { + case .active(var state): + self.state = ._modifying + let removedID = state.openStreams.remove(id) + assert(removedID != nil, "Can't close stream \(Int(id)), it wasn't open") + onStreamClosed = state.openStreams.isEmpty ? .startIdleTimer : .none + self.state = .active(state) + + case .closing(var state): + self.state = ._modifying + let removedID = state.openStreams.remove(id) + assert(removedID != nil, "Can't close stream \(Int(id)), it wasn't open") + // If the second GOAWAY hasn't been sent it isn't safe to close if there are no open + // streams: the client may have opened a stream which the server doesn't know about yet. + let canClose = state.sentSecondGoAway && state.openStreams.isEmpty + onStreamClosed = canClose ? .close : .none + self.state = .closing(state) + + case .closed: + onStreamClosed = .none + + case ._modifying: + preconditionFailure() + } + + return onStreamClosed + } + + enum OnPingAck: Equatable { + /// Send a GOAWAY frame with no error and the given last stream ID, optionally closing the + /// connection immediately afterwards. + case sendGoAway(lastStreamID: HTTP2StreamID, close: Bool) + /// Ignore the ack. + case none + } + + /// Received a PING frame with the 'ack' flag set. + mutating func receivedPingAck(data: HTTP2PingData) -> OnPingAck { + let onPingAck: OnPingAck + + switch self.state { + case .closing(var state): + self.state = ._modifying + + // If only one GOAWAY has been sent and the data matches the data from the GOAWAY ping then + // the server should send another GOAWAY ratcheting down the last stream ID. If no streams + // are open then the server can close the connection immediately after, otherwise it must + // wait until all streams are closed. + if !state.sentSecondGoAway, data == self.goAwayPingData { + state.sentSecondGoAway = true + + if state.openStreams.isEmpty { + self.state = .closed + onPingAck = .sendGoAway(lastStreamID: state.lastStreamID, close: true) + } else { + self.state = .closing(state) + onPingAck = .sendGoAway(lastStreamID: state.lastStreamID, close: false) + } + } else { + onPingAck = .none + } + + self.state = .closing(state) + + case .active, .closed: + onPingAck = .none + + case ._modifying: + preconditionFailure() + } + + return onPingAck + } + + enum OnStartGracefulShutdown: Equatable { + /// Initiate graceful shutdown by sending a GOAWAY frame with the last stream ID set as the max + /// stream ID and no error. Follow it immediately with a PING frame with the given data. + case sendGoAwayAndPing(HTTP2PingData) + /// Ignore the request to start graceful shutdown. + case none + } + + /// Request that the connection begins graceful shutdown. + mutating func startGracefulShutdown() -> OnStartGracefulShutdown { + let onStartGracefulShutdown: OnStartGracefulShutdown + + switch self.state { + case .active(let state): + self.state = .closing(State.Closing(from: state)) + onStartGracefulShutdown = .sendGoAwayAndPing(self.goAwayPingData) + + case .closing, .closed: + onStartGracefulShutdown = .none + + case ._modifying: + preconditionFailure() + } + + return onStartGracefulShutdown + } + + /// Marks the state as closed. + mutating func markClosed() { + self.state = .closed + } + } +} + +extension NIOHTTP2ServerConnectionManagementHandler.StateMachine { + fileprivate enum State { + /// The connection is active. + struct Active { + /// The number of open streams. + var openStreams: Set + /// The ID of the most recently opened stream (zero indicates no streams have been opened yet). + var lastStreamID: HTTP2StreamID + + init() { + self.openStreams = [] + self.lastStreamID = .rootStream + } + } + + /// The connection is closing gracefully, an initial GOAWAY frame has been sent (with the + /// last stream ID set to max). + struct Closing { + /// The number of open streams. + var openStreams: Set + /// The ID of the most recently opened stream (zero indicates no streams have been opened yet). + var lastStreamID: HTTP2StreamID + /// Whether the second GOAWAY frame has been sent with a lower stream ID. + var sentSecondGoAway: Bool + + init(from state: Active) { + self.openStreams = state.openStreams + self.lastStreamID = state.lastStreamID + self.sentSecondGoAway = false + } + } + + case active(Active) + case closing(Closing) + case closed + case _modifying + } +} diff --git a/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler.swift b/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler.swift new file mode 100644 index 0000000..bafcf60 --- /dev/null +++ b/Sources/NIOHTTP2/NIOHTTP2ServerConnectionManagementHandler.swift @@ -0,0 +1,577 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 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 +// +//===----------------------------------------------------------------------===// + +// swift-format-ignore: NoBlockComments +/* + * Copyright 2024, gRPC Authors All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import NIOCore +import NIOTLS + +/// A `ChannelHandler` which manages the lifecycle of an HTTP/2 connection. +/// +/// This handler is responsible for managing several aspects of the connection. These include: +/// 1. Handling the graceful close of connections. When gracefully closing a connection the server +/// sends a GOAWAY frame with the last stream ID set to the maximum stream ID allowed followed by +/// a PING frame. On receipt of the PING frame the server sends another GOAWAY frame with the +/// highest ID of all streams which have been opened. After this, the handler closes the +/// connection once all streams are closed. +/// 2. Enforcing that graceful shutdown doesn't exceed a configured limit (if configured). +/// 3. Gracefully closing the connection once it reaches the maximum configured age (if configured). +/// 4. Gracefully closing the connection once it has been idle for a given period of time (if +/// configured). +/// 5. Periodically sending keep alive pings to the client (if configured) and closing the +/// connection if necessary. +public final class NIOHTTP2ServerConnectionManagementHandler: ChannelDuplexHandler { + public typealias InboundIn = HTTP2Frame + public typealias InboundOut = HTTP2Frame + public typealias OutboundIn = HTTP2Frame + public typealias OutboundOut = HTTP2Frame + + /// The `EventLoop` of the `Channel` this handler exists in. + private let eventLoop: any EventLoop + + /// The timer used to gracefully close idle connections. + private var maxIdleTimerHandler: Timer? + + /// The timer used to gracefully close old connections. + private var maxAgeTimerHandler: Timer? + + /// The timer used to forcefully close a connection during a graceful close. + /// The timer starts after the second GOAWAY frame has been sent. + private var maxGraceTimerHandler: Timer? + + /// The timer used to send keep-alive pings. + private var keepaliveTimerHandler: Timer? + + /// The timer used to detect keep alive timeouts, if keep-alive pings are enabled. + private var keepaliveTimeoutHandler: Timer? + + /// Opaque data sent in keep alive pings. + private let keepalivePingData: HTTP2PingData + + /// Whether a flush is pending. + private var flushPending: Bool + + /// Whether `channelRead` has been called and `channelReadComplete` hasn't yet been called. + /// Resets once `channelReadComplete` returns. + private var inReadLoop: Bool + + /// The context of the channel this handler is in. + private var context: ChannelHandlerContext? + + /// The current state of the connection. + private var state: StateMachine + + /// Configuration parameters for ``NIOHTTP2ServerConnectionManagementHandler``. + /// + /// This configuration provides several ways to manage the lifetime of HTTP/2 connections: + /// - When `maxIdleTime` is set, graceful shutdown will be triggered when the connection has had no active streams + /// for the specified duration. + /// - When `maxAge` is set, graceful shutdown will be triggered when the connection has been alive for the specified + /// duration. + /// - When `maxGraceTime` is set, the connection will be forcefully closed if active streams don't finish within the + /// specified duration after graceful shutdown is triggered. + /// - When `keepalive` is set, clients will be periodically pinged to verify they're still responsive; unresponsive + /// clients will trigger graceful connection closure. + /// + /// Each parameter is optional; when set to `nil`, that particular behavior is disabled. + /// + /// ## Example + /// + /// ```swift + /// let configuration = NIOHTTP2ServerConnectionManagementHandler.Configuration( + /// maxIdleTime: .minutes(5), + /// maxAge: .hours(1), + /// maxGraceTime: .seconds(20), + /// keepalive: .init(pingInterval: .seconds(30), ackTimeout: .seconds(20)) + /// ) + /// ``` + /// + /// This configuration: + /// - Closes idle connections after 5 minutes; + /// - Closes connections that have been active for 1 hour regardless of activity; + /// - Forces connection closure after 20 seconds if active streams haven't finished after graceful shutdown is + /// triggered; + /// - Sends keep-alive pings every 30 seconds with a 20 second response timeout. + /// + /// The created configuration can then be used to initialize a ``NIOHTTP2ServerConnectionManagementHandler`` + /// instance: + /// + /// ```swift + /// let handler = NIOHTTP2ServerConnectionManagementHandler( + /// eventLoop: eventLoop, + /// configuration: configuration + /// ) + /// ``` + public struct Configuration: Sendable { + /// The maximum amount of time a connection may be idle for before being closed. When `nil`, connections can + /// remain idle indefinitely. + public var maxIdleTime: TimeAmount? + + /// The maximum amount of time a connection may exist before being gracefully closed. When `nil`, connections + /// can live indefinitely. + public var maxAge: TimeAmount? + + /// The maximum amount of time that the connection has to close gracefully. When `nil`, no time + /// limit is enforced for active streams to finish during graceful shutdown. + public var maxGraceTime: TimeAmount? + + /// Configuration for keep-alive ping behavior. Defaults to `nil`, disabling keep-alive pings. + public var keepalive: Keepalive? + + /// Configuration for HTTP/2 keep-alive ping behavior. + /// + /// Keep-alive pings verify that the client is still responsive by periodically sending pings and expecting + /// acknowledgements. If the client responds within the specified timeout, the connection remains open. + /// Otherwise, the connection is shut down. + public struct Keepalive: Sendable, Hashable { + /// The amount of time to wait after reading data before sending a keep-alive ping. + public var pingInterval: TimeAmount + + /// The amount of time the client has to reply after the server sends a keep-alive ping to keep the + /// connection open. The connection is closed if no reply is received. + public var ackTimeout: TimeAmount + + /// - Parameters: + /// - pingInterval: The amount of time to wait after reading data before sending a keep-alive ping. + /// - ackTimeout: The amount of time the client has to reply after the server sends a keep-alive ping to + /// keep the connection open. The connection is closed if no reply is received. + public init(pingInterval: TimeAmount, ackTimeout: TimeAmount) { + self.pingInterval = pingInterval + self.ackTimeout = ackTimeout + } + } + + /// - Parameters: + /// - maxIdleTime: The maximum amount of time a connection may be idle for before being closed. When `nil`, + /// connections can remain idle indefinitely. + /// - maxAge: The maximum amount of time a connection may exist before being gracefully closed. When `nil`, + /// connections can live indefinitely. + /// - maxGraceTime: The maximum amount of time that the connection has to close gracefully. When `nil`, no + /// time limit is enforced for active streams to finish during graceful shutdown. + /// - keepalive: Configuration for keep-alive ping behavior. Defaults to `nil`, disabling keep-alive pings. + public init( + maxIdleTime: TimeAmount?, + maxAge: TimeAmount?, + maxGraceTime: TimeAmount?, + keepalive: Keepalive? + ) { + self.maxIdleTime = maxIdleTime + self.maxAge = maxAge + self.maxGraceTime = maxGraceTime + self.keepalive = keepalive + } + + /// A recommended default configuration. + /// + /// This configuration enforces a 5 minute limit for active streams to finish during graceful shutdown and + /// sends keep-alive pings every 2 hours with a 20 second response timeout. Both maximum connection idle time + /// and connection age limit are disabled. + public static var defaults: Self { + Self( + maxIdleTime: nil, + maxAge: nil, + maxGraceTime: .minutes(5), + keepalive: .init(pingInterval: .hours(2), ackTimeout: .seconds(20)) + ) + } + } + + /// Creates a new handler which manages the lifecycle of a connection. + /// + /// - Parameters: + /// - eventLoop: The `EventLoop` of the `Channel` this handler is placed in. + /// - configuration: Configuration parameters for managing the connection lifecycle. + public init(eventLoop: any EventLoop, configuration: Configuration) { + self.eventLoop = eventLoop + + // Generate a random value to be used as keep alive ping data. + let pingData = UInt64.random(in: .min ... .max) + self.keepalivePingData = HTTP2PingData(withInteger: pingData) + + self.state = StateMachine(goAwayPingData: HTTP2PingData(withInteger: ~pingData)) + + self.flushPending = false + self.inReadLoop = false + + if let maxIdleTime = configuration.maxIdleTime { + self.maxIdleTimerHandler = Timer( + eventLoop: eventLoop, + duration: maxIdleTime, + handler: MaxIdleTimerHandlerView(self) + ) + } + if let maxAge = configuration.maxAge { + self.maxAgeTimerHandler = Timer( + eventLoop: eventLoop, + duration: maxAge, + handler: MaxAgeTimerHandlerView(self) + ) + } + if let maxGraceTime = configuration.maxGraceTime { + self.maxGraceTimerHandler = Timer( + eventLoop: eventLoop, + duration: maxGraceTime, + handler: MaxGraceTimerHandlerView(self) + ) + } + + if let keepaliveConfiguration = configuration.keepalive { + self.keepaliveTimerHandler = Timer( + eventLoop: eventLoop, + duration: keepaliveConfiguration.pingInterval, + handler: KeepaliveTimerHandlerView(self) + ) + self.keepaliveTimeoutHandler = Timer( + eventLoop: eventLoop, + duration: keepaliveConfiguration.ackTimeout, + handler: KeepaliveTimeoutHandlerView(self) + ) + } + } + + public func handlerAdded(context: ChannelHandlerContext) { + context.eventLoop.preconditionInEventLoop() + self.context = context + } + + public func handlerRemoved(context: ChannelHandlerContext) { + self.context = nil + } + + public func channelActive(context: ChannelHandlerContext) { + self.maxAgeTimerHandler?.start() + self.maxIdleTimerHandler?.start() + self.keepaliveTimerHandler?.start() + context.fireChannelActive() + } + + public func channelInactive(context: ChannelHandlerContext) { + self.maxIdleTimerHandler?.cancel() + self.maxIdleTimerHandler = nil + + self.maxAgeTimerHandler?.cancel() + self.maxAgeTimerHandler = nil + + self.maxGraceTimerHandler?.cancel() + self.maxGraceTimerHandler = nil + + self.keepaliveTimerHandler?.cancel() + self.keepaliveTimerHandler = nil + + self.keepaliveTimeoutHandler?.cancel() + self.keepaliveTimeoutHandler = nil + + context.fireChannelInactive() + } + + public func userInboundEventTriggered(context: ChannelHandlerContext, event: Any) { + switch event { + case let event as NIOHTTP2StreamCreatedEvent: + self._streamCreated(event.streamID) + + case let event as StreamClosedEvent: + self._streamClosed(event.streamID) + + case is ChannelShouldQuiesceEvent: + self.initiateGracefulShutdown() + + default: + () + } + + context.fireUserInboundEventTriggered(event) + } + + public func channelRead(context: ChannelHandlerContext, data: NIOAny) { + self.inReadLoop = true + + // Any read data indicates that the connection is alive so cancel the keep-alive timers. + self.keepaliveTimerHandler?.cancel() + self.keepaliveTimeoutHandler?.cancel() + + let frame = self.unwrapInboundIn(data) + switch frame.payload { + case .ping(let data, let ack) where ack == true: + self.handlePingAck(context: context, data: data) + + default: + // Only interested in PING frames with the ACK flag set. + // NIOHTTP2Handler handles all other frames (including PING frames where the ACK flag is *not* set), so we + // can ignore them here. + () + } + + context.fireChannelRead(data) + } + + public func channelReadComplete(context: ChannelHandlerContext) { + while self.flushPending { + self.flushPending = false + context.flush() + } + + self.inReadLoop = false + + // Done reading: schedule the keep-alive timer. + self.keepaliveTimerHandler?.start() + + context.fireChannelReadComplete() + } + + public func flush(context: ChannelHandlerContext) { + self.maybeFlush(context: context) + } +} + +// Timer handler views. +extension NIOHTTP2ServerConnectionManagementHandler { + struct MaxIdleTimerHandlerView: Sendable, NIOScheduledCallbackHandler { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + func handleScheduledCallback(eventLoop: some EventLoop) { + self.handler.value.initiateGracefulShutdown() + } + } + + struct MaxAgeTimerHandlerView: Sendable, NIOScheduledCallbackHandler { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + func handleScheduledCallback(eventLoop: some EventLoop) { + self.handler.value.initiateGracefulShutdown() + } + } + + struct MaxGraceTimerHandlerView: Sendable, NIOScheduledCallbackHandler { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + func handleScheduledCallback(eventLoop: some EventLoop) { + self.handler.value.context?.close(promise: nil) + } + } + + struct KeepaliveTimerHandlerView: Sendable, NIOScheduledCallbackHandler { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + func handleScheduledCallback(eventLoop: some EventLoop) { + self.handler.value.keepaliveTimerFired() + } + } + + struct KeepaliveTimeoutHandlerView: Sendable, NIOScheduledCallbackHandler { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + func handleScheduledCallback(eventLoop: some EventLoop) { + self.handler.value.initiateGracefulShutdown() + } + } +} + +extension NIOHTTP2ServerConnectionManagementHandler { + /// A delegate for receiving HTTP/2 stream lifecycle events. + public struct HTTP2StreamDelegate: Sendable, NIOHTTP2StreamDelegate { + private let handler: NIOLoopBound + + init(_ handler: NIOHTTP2ServerConnectionManagementHandler) { + self.handler = .init(handler, eventLoop: handler.eventLoop) + } + + /// Notifies the handler that a new HTTP/2 stream was created. + /// - Parameters: + /// - id: The ID of the created stream. + /// - channel: The channel on which the stream was created. + public func streamCreated(_ id: HTTP2StreamID, channel: any Channel) { + if self.handler.eventLoop.inEventLoop { + self.handler.value._streamCreated(id) + } else { + self.handler.eventLoop.execute { + self.handler.value._streamCreated(id) + } + } + } + + /// Notifies the handler that an HTTP/2 stream was closed. + /// - Parameters: + /// - id: The ID of the closed stream. + /// - channel: The channel on which the stream was closed. + public func streamClosed(_ id: HTTP2StreamID, channel: any Channel) { + if self.handler.eventLoop.inEventLoop { + self.handler.value._streamClosed(id) + } else { + self.handler.eventLoop.execute { + self.handler.value._streamClosed(id) + } + } + } + } + + public var http2StreamDelegate: HTTP2StreamDelegate { + HTTP2StreamDelegate(self) + } + + private func _streamCreated(_ id: HTTP2StreamID) { + // The connection isn't idle if a stream is open. + self.maxIdleTimerHandler?.cancel() + self.state.streamOpened(id) + } + + private func _streamClosed(_ id: HTTP2StreamID) { + guard let context = self.context else { return } + + switch self.state.streamClosed(id) { + case .startIdleTimer: + self.maxIdleTimerHandler?.start() + case .close: + // Defer closing until the next tick of the event loop. + // + // This point is reached because the server is shutting down gracefully and the stream count + // has dropped to zero, meaning the connection is no longer required and can be closed. + // However, the stream would've been closed by writing and flushing a frame with end stream + // set. These are two distinct events in the channel pipeline. The HTTP/2 handler updates the + // state machine when a frame is written, which in this case results in the stream closed + // event which we're reacting to here. + // + // Importantly the HTTP/2 handler hasn't yet seen the flush event, so the bytes of the frame + // with end-stream set - and potentially some other frames - are sitting in a buffer in the + // HTTP/2 handler. If we close on this event loop tick then those frames will be dropped. + // Delaying the close by a loop tick will allow the flush to happen before the close. + let loopBound = NIOLoopBound(context, eventLoop: context.eventLoop) + context.eventLoop.execute { + loopBound.value.close(mode: .all, promise: nil) + } + + case .none: + () + } + } +} + +extension NIOHTTP2ServerConnectionManagementHandler { + private func maybeFlush(context: ChannelHandlerContext) { + if self.inReadLoop { + self.flushPending = true + } else { + context.flush() + } + } + + private func initiateGracefulShutdown() { + guard let context = self.context else { return } + context.eventLoop.assertInEventLoop() + + // Cancel any timers if initiating shutdown. + self.maxIdleTimerHandler?.cancel() + self.maxAgeTimerHandler?.cancel() + self.keepaliveTimerHandler?.cancel() + self.keepaliveTimeoutHandler?.cancel() + + switch self.state.startGracefulShutdown() { + case .sendGoAwayAndPing(let pingData): + // There's a time window between the server sending a GOAWAY frame and the client receiving + // it. During this time the client may open new streams as it doesn't yet know about the + // GOAWAY frame. + // + // The server therefore sends a GOAWAY with the last stream ID set to the maximum stream ID + // and follows it with a PING frame. When the server receives the ack for the PING frame it + // knows that the client has received the initial GOAWAY frame and that no more streams may + // be opened. The server can then send an additional GOAWAY frame with a more representative + // last stream ID. + let goAway = HTTP2Frame( + streamID: .rootStream, + payload: .goAway( + lastStreamID: .maxID, + errorCode: .noError, + opaqueData: nil + ) + ) + + let ping = HTTP2Frame(streamID: .rootStream, payload: .ping(pingData, ack: false)) + + context.write(self.wrapOutboundOut(goAway), promise: nil) + context.write(self.wrapOutboundOut(ping), promise: nil) + self.maybeFlush(context: context) + + case .none: + () // Already shutting down. + } + } + + private func handlePingAck(context: ChannelHandlerContext, data: HTTP2PingData) { + switch self.state.receivedPingAck(data: data) { + case .sendGoAway(let streamID, let close): + let goAway = HTTP2Frame( + streamID: .rootStream, + payload: .goAway(lastStreamID: streamID, errorCode: .noError, opaqueData: nil) + ) + + context.write(self.wrapOutboundOut(goAway), promise: nil) + self.maybeFlush(context: context) + + if close { + context.close(promise: nil) + } else { + // We may have a grace period for finishing once the second GOAWAY frame has finished. + // If this is set close the connection abruptly once the grace period passes. + self.maxGraceTimerHandler?.start() + } + + case .none: + () + } + } + + private func keepaliveTimerFired() { + guard let context = self.context else { return } + let ping = HTTP2Frame(streamID: .rootStream, payload: .ping(self.keepalivePingData, ack: false)) + context.write(self.wrapInboundOut(ping), promise: nil) + self.maybeFlush(context: context) + + // Schedule a timeout on waiting for the response. + self.keepaliveTimeoutHandler?.start() + } +} diff --git a/Sources/NIOHTTP2/Timer.swift b/Sources/NIOHTTP2/Timer.swift new file mode 100644 index 0000000..d8f6f34 --- /dev/null +++ b/Sources/NIOHTTP2/Timer.swift @@ -0,0 +1,67 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 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 +// +//===----------------------------------------------------------------------===// + +// swift-format-ignore: NoBlockComments +/* + * Copyright 2024, gRPC Authors All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import NIOCore + +/// A timer backed by `NIOScheduledCallback`. +struct Timer: Sendable where Handler: Sendable { + /// The event loop on which to run this timer. + private let eventLoop: any EventLoop + + /// The duration of the timer. + private let duration: TimeAmount + + /// The handler to call when the timer fires. + private let handler: Handler + + /// The currently scheduled callback if the timer is running. + private var scheduledCallback: NIOScheduledCallback? + + init(eventLoop: any EventLoop, duration: TimeAmount, handler: Handler) { + self.eventLoop = eventLoop + self.duration = duration + self.handler = handler + self.scheduledCallback = nil + } + + /// Cancel the timer, if it is running. + func cancel() { + guard let scheduledCallback = self.scheduledCallback else { return } + scheduledCallback.cancel() + } + + /// Start or restart the timer. + mutating func start() { + self.scheduledCallback?.cancel() + // Only throws if the event loop is shutting down, so we'll just swallow the error here. + self.scheduledCallback = try? self.eventLoop.scheduleCallback(in: self.duration, handler: self.handler) + } +} diff --git a/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandler+StateMachineTests.swift b/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandler+StateMachineTests.swift new file mode 100644 index 0000000..7f0d0cb --- /dev/null +++ b/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandler+StateMachineTests.swift @@ -0,0 +1,177 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 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 +// +//===----------------------------------------------------------------------===// + +// swift-format-ignore: NoBlockComments +/* + * Copyright 2024, gRPC Authors All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import NIOCore +import Testing + +@testable import NIOHTTP2 + +struct NIOHTTP2ServerConnectionManagementHandlerStateMachineTests { + private func makeStateMachine( + goAwayPingData: HTTP2PingData = HTTP2PingData(withInteger: 42) + ) -> NIOHTTP2ServerConnectionManagementHandler.StateMachine { + .init(goAwayPingData: goAwayPingData) + } + + @Test("Closing last stream starts idle timer") + func testCloseAllStreamsWhenActive() { + var state = self.makeStateMachine() + state.streamOpened(1) + #expect(state.streamClosed(1) == .startIdleTimer) + } + + @Test("Closing stream with others open returns no action") + func testCloseSomeStreamsWhenActive() { + var state = self.makeStateMachine() + state.streamOpened(1) + state.streamOpened(2) + #expect(state.streamClosed(2) == .none) + } + + @Test("Stream operations after close are no-ops") + func testOpenAndCloseStreamWhenClosed() { + var state = self.makeStateMachine() + state.markClosed() + state.streamOpened(1) + #expect(state.streamClosed(1) == .none) + } + + @Test("Graceful shutdown when no open streams") + func testGracefulShutdownWhenNoOpenStreams() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + } + + @Test("Repeated graceful shutdown is idempotent") + func testGracefulShutdownWhenClosing() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + #expect(state.startGracefulShutdown() == .none) + } + + @Test("Graceful shutdown after close is a no-op") + func testGracefulShutdownWhenClosed() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + state.markClosed() + #expect(state.startGracefulShutdown() == .none) + } + + @Test("Stream opened just before sending first ping") + func testReceiveAckForGoAwayPingWhenStreamsOpenedBeforeShutdownOnly() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + state.streamOpened(1) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + #expect(state.receivedPingAck(data: pingData) == .sendGoAway(lastStreamID: 1, close: false)) + } + + @Test("Stream opened after sending first ping but before receiving ack") + func testReceiveAckForGoAwayPingWhenStreamsOpenedBeforeAck() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + state.streamOpened(1) + #expect(state.receivedPingAck(data: pingData) == .sendGoAway(lastStreamID: 1, close: false)) + } + + @Test("Receiving ping ack with no streams sends final GOAWAY and closes") + func testReceiveAckForGoAwayPingWhenNoOpenStreams() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + #expect(state.receivedPingAck(data: pingData) == .sendGoAway(lastStreamID: .rootStream, close: true)) + } + + @Test("Non-matching ping ack is ignored") + func testReceiveAckNotForGoAwayPing() { + let pingData = HTTP2PingData(withInteger: 42) + var state = self.makeStateMachine(goAwayPingData: pingData) + #expect(state.startGracefulShutdown() == .sendGoAwayAndPing(pingData)) + + let otherPingData = HTTP2PingData(withInteger: 0) + #expect(state.receivedPingAck(data: otherPingData) == .none) + } + + @Test("Ping ack when not shutting down is ignored") + func testReceivePingAckWhenActive() { + var state = self.makeStateMachine() + #expect(state.receivedPingAck(data: HTTP2PingData()) == .none) + } + + @Test("Ping ack after close is ignored") + func testReceivePingAckWhenClosed() { + var state = self.makeStateMachine() + state.markClosed() + #expect(state.receivedPingAck(data: HTTP2PingData()) == .none) + } + + @Test("Full graceful shutdown waits for all streams to close") + func testGracefulShutdownFlow() { + var state = self.makeStateMachine() + // Open a few streams. + state.streamOpened(1) + state.streamOpened(2) + + switch state.startGracefulShutdown() { + case .sendGoAwayAndPing(let pingData): + // Open another stream and then receive the ping ack. + state.streamOpened(3) + #expect(state.receivedPingAck(data: pingData) == .sendGoAway(lastStreamID: 3, close: false)) + case .none: + Issue.record("Expected '.sendGoAwayAndPing'") + } + + // Both GOAWAY frames have been sent. Start closing streams. + #expect(state.streamClosed(1) == .none) + #expect(state.streamClosed(2) == .none) + #expect(state.streamClosed(3) == .close) + } + + @Test("Only close after receiving ping ack even when no streams are open") + func testGracefulShutdownWhenNoOpenStreamsBeforeSecondGoAway() { + var state = self.makeStateMachine() + // Open a stream. + state.streamOpened(1) + + switch state.startGracefulShutdown() { + case .sendGoAwayAndPing(let pingData): + // Close the stream. This shouldn't lead to a close. + #expect(state.streamClosed(1) == .none) + // Only on receiving the ack do we send a GOAWAY and close. + #expect(state.receivedPingAck(data: pingData) == .sendGoAway(lastStreamID: 1, close: true)) + case .none: + Issue.record("Expected '.sendGoAwayAndPing'") + } + } +} diff --git a/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandlerTests.swift b/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandlerTests.swift new file mode 100644 index 0000000..effa6b4 --- /dev/null +++ b/Tests/NIOHTTP2Tests/NIOHTTP2ServerConnectionManagementHandlerTests.swift @@ -0,0 +1,389 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 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 +// +//===----------------------------------------------------------------------===// + +// swift-format-ignore: NoBlockComments +/* + * Copyright 2024, gRPC Authors All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import NIOCore +import NIOEmbedded +import NIOHPACK +import Testing + +@testable import NIOHTTP2 + +struct NIOHTTP2ServerConnectionManagementHandlerTests { + @Test("Idle timeout on new connection") + func idleTimeoutOnNewConnection() throws { + let connection = try Connection(maxIdleTime: .minutes(1)) + try connection.activate() + // Hit the max idle time. + connection.advanceTime(by: .minutes(1)) + + // Follow the graceful shutdown flow. + try self.testGracefulShutdown(connection: connection, lastStreamID: 0) + + // Closed because no streams were open. + try connection.waitUntilClosed() + } + + @Test("Idle timeout is cancelled when stream is opened") + func idleTimerIsCancelledWhenStreamIsOpened() throws { + let connection = try Connection(maxIdleTime: .minutes(1)) + try connection.activate() + + // Open a stream to cancel the idle timer and run through the max idle time. + connection.streamOpened(1) + connection.advanceTime(by: .minutes(1)) + + // No GOAWAY frame means the timer was cancelled. + #expect(try connection.readFrame() == nil) + } + + @Test("Idle timer starts when all streams are closed") + func idleTimerStartsWhenAllStreamsAreClosed() throws { + let connection = try Connection(maxIdleTime: .minutes(1)) + try connection.activate() + + // Open a stream to cancel the idle timer and run through the max idle time. + connection.streamOpened(1) + connection.advanceTime(by: .minutes(1)) + #expect(try connection.readFrame() == nil) + + // Close the stream to start the timer again. + connection.streamClosed(1) + connection.advanceTime(by: .minutes(1)) + + // Follow the graceful shutdown flow. + try self.testGracefulShutdown(connection: connection, lastStreamID: 1) + + // Closed because no streams were open. + try connection.waitUntilClosed() + } + + @Test("Connection shutdown after max age is reached") + func maxAge() throws { + let connection = try Connection(maxAge: .minutes(1)) + try connection.activate() + + // Open some streams. + connection.streamOpened(1) + connection.streamOpened(3) + + // Run to the max age and follow the graceful shutdown flow. + connection.advanceTime(by: .minutes(1)) + try self.testGracefulShutdown(connection: connection, lastStreamID: 3) + + // Close the streams. + connection.streamClosed(1) + connection.streamClosed(3) + + // Connection will be closed now. + try connection.waitUntilClosed() + } + + @Test("Graceful shutdown ratchets down last stream ID") + func gracefulShutdownRatchetsDownStreamID() throws { + // This test uses the idle timeout to trigger graceful shutdown. The mechanism is the same + // regardless of how it's triggered. + let connection = try Connection(maxIdleTime: .minutes(1)) + try connection.activate() + + // Trigger the shutdown, but open a stream during shutdown. + connection.advanceTime(by: .minutes(1)) + try self.testGracefulShutdown( + connection: connection, + lastStreamID: 1, + streamToOpenBeforePingAck: 1 + ) + + // Close the stream to trigger closing the connection. + connection.streamClosed(1) + try connection.waitUntilClosed() + } + + @Test("Graceful shutdown promoted to close after grace period") + func gracefulShutdownGracePeriod() throws { + // This test uses the idle timeout to trigger graceful shutdown. The mechanism is the same + // regardless of how it's triggered. + let connection = try Connection( + maxIdleTime: .minutes(1), + maxGraceTime: .seconds(5) + ) + try connection.activate() + + // Trigger the shutdown, but open a stream during shutdown. + connection.advanceTime(by: .minutes(1)) + try self.testGracefulShutdown( + connection: connection, + lastStreamID: 1, + streamToOpenBeforePingAck: 1 + ) + + // Wait out the grace period without closing the stream. + connection.advanceTime(by: .seconds(5)) + try connection.waitUntilClosed() + } + + @Test("Keepalive works on new connection") + func keepaliveOnNewConnection() throws { + let connection = try Connection( + keepaliveConfiguration: .init( + pingInterval: .minutes(5), + ackTimeout: .seconds(5) + ) + ) + try connection.activate() + + // Wait for the keep alive timer to fire which should cause the server to send a keep + // alive PING. + connection.advanceTime(by: .minutes(5)) + let frame1 = try #require(try connection.readFrame()) + #expect(frame1.streamID == .rootStream) + let (data, ack) = try #require(frame1.payload.ping) + #expect(!ack) + // Data is opaque, send it back. + try connection.ping(data: data, ack: true) + + // Run past the timeout, nothing should happen. + connection.advanceTime(by: .seconds(5)) + #expect(try connection.readFrame() == nil) + } + + @Test("Keepalive starts after read loop") + func keepaliveStartsAfterReadLoop() throws { + let connection = try Connection( + keepaliveConfiguration: .init( + pingInterval: .minutes(5), + ackTimeout: .seconds(5) + ) + ) + try connection.activate() + + // Write a frame into the channel _without_ calling channel read complete. This will cancel + // the keep alive timer. + let settings = HTTP2Frame(streamID: .rootStream, payload: .settings(.settings([]))) + connection.channel.pipeline.fireChannelRead(settings) + + // Run out the keep alive timer, it shouldn't fire. + connection.advanceTime(by: .minutes(5)) + #expect(try connection.readFrame() == nil) + + // Fire channel read complete to start the keep alive timer again. + connection.channel.pipeline.fireChannelReadComplete() + + // Now expire the keep alive timer again, we should read out a PING frame. + connection.advanceTime(by: .minutes(5)) + let frame1 = try #require(try connection.readFrame()) + #expect(frame1.streamID == .rootStream) + let (_, ack) = try #require(frame1.payload.ping) + #expect(!ack) + } + + @Test("Keepalive works on new connection without response") + func keepaliveOnNewConnectionWithoutResponse() throws { + let connection = try Connection( + keepaliveConfiguration: .init( + pingInterval: .minutes(5), + ackTimeout: .seconds(5) + ) + ) + try connection.activate() + + // Wait for the keep alive timer to fire which should cause the server to send a keep + // alive PING. + connection.advanceTime(by: .minutes(5)) + let frame1 = try #require(try connection.readFrame()) + #expect(frame1.streamID == .rootStream) + let (_, ack) = try #require(frame1.payload.ping) + #expect(!ack) + + // We didn't ack the PING, the connection should shutdown after the timeout. + connection.advanceTime(by: .seconds(5)) + try self.testGracefulShutdown(connection: connection, lastStreamID: 0) + + // Connection is closed now. + try connection.waitUntilClosed() + } + + @Test("Doesn't close on error") + func doesNotCloseOnError() throws { + let connection = try Connection(maxIdleTime: .minutes(1)) + try connection.activate() + + // Fire an arbitrary error: `ServerConnectionManagementHandler` should just be propagating it down the pipeline + // and not be doing anything special. + connection.channel.pipeline.fireErrorCaught(TestCaseError()) + + // The channel should still be open. + #expect(connection.channel.isActive == true) + + // Check the error has propagated. + #expect(throws: TestCaseError.self) { + try connection.channel.throwIfErrorCaught() + } + + // Follow a normal flow to check the connection wasn't closed. + // + // Advance halfway through the max idle time. + connection.advanceTime(by: .seconds(30)) + // Graceful shutdown shouldn't have been triggered yet. + #expect(try connection.readFrame() == nil) + + // Now hit the max idle time. + connection.advanceTime(by: .seconds(30)) + + // Follow the graceful shutdown flow. + try self.testGracefulShutdown(connection: connection, lastStreamID: 0) + // Closed because no streams were open. + try connection.waitUntilClosed() + } +} + +extension NIOHTTP2ServerConnectionManagementHandlerTests { + private func testGracefulShutdown( + connection: Connection, + lastStreamID: HTTP2StreamID, + streamToOpenBeforePingAck: HTTP2StreamID? = nil + ) throws { + do { + let frame = try #require(try connection.readFrame()) + #expect(frame.streamID == .rootStream) + + let (streamID, errorCode, _) = try #require(frame.payload.goAway) + #expect(streamID == .maxID) + #expect(errorCode == .noError) + } + + // Followed by a PING + do { + let frame = try #require(try connection.readFrame()) + #expect(frame.streamID == .rootStream) + + let (data, ack) = try #require(frame.payload.ping) + #expect(!ack) + + if let id = streamToOpenBeforePingAck { + connection.streamOpened(id) + } + + // Send the PING ACK. + try connection.ping(data: data, ack: true) + } + + // PING ACK triggers another GOAWAY. + do { + let frame = try #require(try connection.readFrame()) + #expect(frame.streamID == .rootStream) + + let (streamID, errorCode, _) = try #require(frame.payload.goAway) + #expect(streamID == lastStreamID) + #expect(errorCode == .noError) + } + } +} +extension NIOHTTP2ServerConnectionManagementHandlerTests { + struct Connection { + let channel: EmbeddedChannel + let streamDelegate: any NIOHTTP2StreamDelegate + + var loop: EmbeddedEventLoop { + self.channel.embeddedEventLoop + } + + init( + maxIdleTime: TimeAmount? = nil, + maxAge: TimeAmount? = nil, + maxGraceTime: TimeAmount? = nil, + keepaliveConfiguration: NIOHTTP2ServerConnectionManagementHandler.Configuration.Keepalive? = nil + ) throws { + let loop = EmbeddedEventLoop() + let handler = NIOHTTP2ServerConnectionManagementHandler( + eventLoop: loop, + configuration: .init( + maxIdleTime: maxIdleTime, + maxAge: maxAge, + maxGraceTime: maxGraceTime, + keepalive: keepaliveConfiguration + ) + ) + + self.streamDelegate = handler.http2StreamDelegate + self.channel = EmbeddedChannel(handler: handler, loop: loop) + } + + func activate() throws { + try self.channel.connect(to: SocketAddress(ipAddress: "127.0.0.1", port: 0)).wait() + } + + func advanceTime(by delta: TimeAmount) { + self.loop.advanceTime(by: delta) + } + + func streamOpened(_ id: HTTP2StreamID) { + self.streamDelegate.streamCreated(id, channel: self.channel) + } + + func streamClosed(_ id: HTTP2StreamID) { + self.streamDelegate.streamClosed(id, channel: self.channel) + } + + func ping(data: HTTP2PingData, ack: Bool) throws { + let frame = HTTP2Frame(streamID: .rootStream, payload: .ping(data, ack: ack)) + try self.channel.writeInbound(frame) + } + + func readFrame() throws -> HTTP2Frame? { + try self.channel.readOutbound(as: HTTP2Frame.self) + } + + func waitUntilClosed() throws { + self.channel.embeddedEventLoop.run() + try self.channel.closeFuture.wait() + } + } +} + +extension HTTP2Frame.FramePayload { + var goAway: (lastStreamID: HTTP2StreamID, errorCode: HTTP2ErrorCode, opaqueData: ByteBuffer?)? { + switch self { + case .goAway(let lastStreamID, let errorCode, let opaqueData): + return (lastStreamID, errorCode, opaqueData) + default: + return nil + } + } + + var ping: (data: HTTP2PingData, ack: Bool)? { + switch self { + case .ping(let data, let ack): + return (data, ack) + default: + return nil + } + } +}