mirror of
https://github.com/apple/swift-nio-http2
synced 2026-11-22 04:30:43 +00:00
Add a server connection manager (#532)
Motivation: `NIOHTTP2Handler` currently does not support graceful shutdown because it does not action upon a `ChannelShouldQuiesceEvent` event. See issue https://github.com/apple/swift-nio-http2/issues/336. Per the [comment](https://github.com/apple/swift-nio-http2/issues/336#issuecomment-2252862397) on that issue, [`gRPC-swift-nio-transport`](https://github.com/grpc/grpc-swift-nio-transport) implements this functionality in a separate channel handler, named [`ServerConnectionManagementHandler`](https://github.com/grpc/grpc-swift-nio-transport/blob/main/Sources/GRPCNIOTransportCore/Server/Connection/ServerConnectionManagementHandler.swift). We should introduce this to this repo too. Modifications: - Added `ServerConnectionManagementHandler` from `gRPC-swift-nio-transport` with some slight modifications such as removing gRPC-specific functionality like policing client pings. - Added a new `configureAsyncHTTP2Pipeline` helper, which takes a connection manager configuration as an argument and sets the connection manager up alongside `NIOHTTP2Handler`. Result: Addresses issue https://github.com/apple/swift-nio-http2/issues/336.
This commit is contained in:
1 parent
979f431f1f
commit
b6571f3db4
7 files changed
+1517
No files matched your search
@@ -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
|
||||
@@ -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<Output: Sendable>(
|
||||
mode: NIOHTTP2Handler.ParserMode,
|
||||
connectionManagerConfiguration: NIOHTTP2ServerConnectionManagementHandler.Configuration,
|
||||
http2HandlerConfiguration: NIOHTTP2Handler.Configuration = NIOHTTP2Handler.Configuration(),
|
||||
streamInitializer: @escaping NIOChannelInitializerWithOutput<Output>
|
||||
) throws -> NIOHTTP2Handler.AsyncStreamMultiplexer<Output> {
|
||||
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<HTTP1Output: Sendable, HTTP2Output: Sendable>(
|
||||
on channel: any Channel,
|
||||
|
||||
@@ -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<HTTP2StreamID>
|
||||
/// 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<HTTP2StreamID>
|
||||
/// 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
|
||||
}
|
||||
}
|
||||
@@ -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<MaxIdleTimerHandlerView>?
|
||||
|
||||
/// The timer used to gracefully close old connections.
|
||||
private var maxAgeTimerHandler: Timer<MaxAgeTimerHandlerView>?
|
||||
|
||||
/// 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<MaxGraceTimerHandlerView>?
|
||||
|
||||
/// The timer used to send keep-alive pings.
|
||||
private var keepaliveTimerHandler: Timer<KeepaliveTimerHandlerView>?
|
||||
|
||||
/// The timer used to detect keep alive timeouts, if keep-alive pings are enabled.
|
||||
private var keepaliveTimeoutHandler: Timer<KeepaliveTimeoutHandlerView>?
|
||||
|
||||
/// 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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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<NIOHTTP2ServerConnectionManagementHandler>
|
||||
|
||||
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()
|
||||
}
|
||||
}
|
||||
@@ -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<Handler: NIOScheduledCallbackHandler>: 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)
|
||||
}
|
||||
}
|
||||
+177
@@ -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'")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user