Close the channel when input closes during the TLS handshake (#603)

### Motivation

`NIOSSLHandler` treats input closure during the handshake as a fatal
handshake
failure: `userInboundInputClosedTriggered` synthesises
`NIOSSLError.handshakeFailed(.sslError([.eofDuringHandshake]))`, fires
it, and
forwards `ChannelEvent.inputClosed`. Unlike every other fatal handshake
failure
it then returns without closing the channel and without leaving
`.handshaking`.

When the channel has `allowRemoteHalfClosure` set, nothing else closes
it
either — NIO deliberately does not close on FIN, and a pipeline still
waiting on
ALPN may contain no handler that owns the closure. The descriptor stays
in
`CLOSE_WAIT` for the lifetime of the process, and a graceful shutdown
that waits
on all child channels never completes.

Compare `doHandshakeStep`'s `.failed` branch, which fires the same
`handshakeFailed` error and then calls `channelClose`. Both are fatal;
only one
closed.

A related hole sits underneath. `channelClose` and `channelInactive`
complete
`shutdownPromise` and `closePromise` but never `closeOutputPromise`. A
`close(mode: .output)` issued while handshaking is buffered with its
promise
stored there, and `discardBufferedActions` only fails `.write` promises,
so that
promise was never completed: the caller hangs, or trips NIO's
leaked-promise
`fatalError`. Closing the channel on this path makes it reliably
reachable.

### Modifications

- In `userInboundInputClosedTriggered`, mark `.handshaking` and
`.additionalVerification` as fatal and call `channelClose` after firing
the
error and forwarding `inputClosed`. The post-handshake ragged-EOF branch
is
  unchanged: half closure is legitimate once the connection is up.
- Complete `closeOutputPromise` in `channelClose` and `channelInactive`,
  alongside the promises they already fail.
- Added tests for input closure during the handshake (`EmbeddedChannel`
and real
  sockets), during additional peer certificate verification — including
completing the verification callback after the close — and for the
buffered
`close(mode: .output)` promise. A control test asserts that input
closure
after the handshake still fires `uncleanShutdown`, forwards
`inputClosed`, and
  leaves the channel open.

### Result

A peer that connects and half-closes before completing the handshake no
longer
leaks a descriptor. Post-handshake half closure is unaffected.

Two observable changes for callers on the mid-handshake path: buffered
writes
now fail with `ChannelError.ioOnClosedChannel` rather than the TLS
error, and
`errorCaught` fires once rather than twice. Both match the existing
`doHandshakeStep(.failed)` behaviour.
This commit is contained in:
Sam Amin authored and GitHub committed 2026-09-02 13:38:37 +00:00
1 parent dea6ebb773
commit 03827c1a9f
2 files changed
+223

No files matched your search

+21
View File
@@ -158,10 +158,13 @@ public class NIOSSLHandler: ChannelInboundHandler, ChannelOutboundHandler, Remov
}
let shutdownPromise = self.shutdownPromise
self.shutdownPromise = nil
let closeOutputPromise = self.closeOutputPromise
self.closeOutputPromise = nil
let closePromise = self.closePromise
self.closePromise = nil
shutdownPromise?.fail(channelError)
closeOutputPromise?.fail(channelError)
closePromise?.fail(channelError)
context.fireErrorCaught(channelError)
discardBufferedActions(reason: channelError)
@@ -213,6 +216,8 @@ public class NIOSSLHandler: ChannelInboundHandler, ChannelOutboundHandler, Remov
private func userInboundInputClosedTriggered(context: ChannelHandlerContext) {
let channelError: NIOSSLError
let fatal: Bool
switch self.state {
case .inputClosed:
return
@@ -226,6 +231,7 @@ public class NIOSSLHandler: ChannelInboundHandler, ChannelOutboundHandler, Remov
// We use a synthetic error here as the error stack will be empty, and we should try to
// provide some diagnostic help.
channelError = NIOSSLError.handshakeFailed(.sslError([.eofDuringHandshake]))
fatal = true
case .additionalVerification:
// In this case the channel is going through the doHandshake steps and
// a channelInactive is fired taking down the connection.
@@ -233,14 +239,25 @@ public class NIOSSLHandler: ChannelInboundHandler, ChannelOutboundHandler, Remov
// We use a synthetic error here as the error stack will be empty, and we should try to
// provide some diagnostic help.
channelError = NIOSSLError.handshakeFailed(.sslError([.eofDuringAdditionalCertficiateChainValidation]))
fatal = true
default:
// This is a ragged EOF: we weren't sent a CLOSE_NOTIFY. We want to send a user
// event to notify about this before we propagate channelInactive. We also want to fail all
// these writes.
// Half closure is legitimate here, so we deliberately leave the state alone.
channelError = NIOSSLError.uncleanShutdown
fatal = false
}
context.fireErrorCaught(channelError)
context.fireUserInboundEventTriggered(ChannelEvent.inputClosed)
if fatal {
// We have declared the handshake failed, so this connection can never be used: close it
// rather than leave it half-closed. Nothing else necessarily owns the closure, as NIO
// does not close on FIN when allowRemoteHalfClosure is set.
self.channelClose(context: context, reason: channelError)
}
}
public func write(context: ChannelHandlerContext, data: NIOAny, promise: EventLoopPromise<Void>?) {
@@ -738,10 +755,14 @@ public class NIOSSLHandler: ChannelInboundHandler, ChannelOutboundHandler, Remov
let shutdownPromise = self.shutdownPromise
self.shutdownPromise = nil
let closeOutputPromise = self.closeOutputPromise
self.closeOutputPromise = nil
let closePromise = self.closePromise
self.closePromise = nil
shutdownPromise?.fail(reason)
closeOutputPromise?.fail(reason)
context.close(promise: closePromise)
}
@@ -135,6 +135,19 @@ private final class ChannelInactiveHandler: ChannelInboundHandler, Sendable {
}
}
private final class InputClosedRecorder: ChannelInboundHandler {
typealias InboundIn = ByteBuffer
private(set) var inputClosedCount = 0
func userInboundEventTriggered(context: ChannelHandlerContext, event: Any) {
if case .some(.inputClosed) = event as? ChannelEvent {
self.inputClosedCount += 1
}
context.fireUserInboundEventTriggered(event)
}
}
// Modified version taken from swift-nio/ChannelTests.swift
enum ShutDownEvent {
case input
@@ -971,6 +984,195 @@ class NIOSSLIntegrationTest: XCTestCase {
XCTAssertNoThrow(try clientChannelInactivePromise.futureResult.wait())
}
func testInputClosedDuringHandshakeClosesTheChannel() throws {
let context = try configuredSSLContext()
let channel = EmbeddedChannel()
let errorCatcher = ErrorCatcher<NIOSSLError>()
XCTAssertNoThrow(
try channel.pipeline.syncOperations.addHandlers(
NIOSSLServerHandler(context: context),
errorCatcher
)
)
XCTAssertNoThrow(try channel.connect(to: .init(ipAddress: "1.2.3.4", port: 5)).wait())
XCTAssertTrue(channel.isActive)
// This is what NIO's socket channel fires on FIN when allowRemoteHalfClosure is set.
channel.pipeline.fireUserInboundEventTriggered(ChannelEvent.inputClosed)
XCTAssertEqual(errorCatcher.errors.count, 1)
XCTAssertEqual(errorCatcher.errors.first, .handshakeFailed(.sslError([.eofDuringHandshake])))
XCTAssertFalse(channel.isActive)
XCTAssertNoThrow(XCTAssertTrue(try channel.finish(acceptAlreadyClosed: true).isClean))
}
func testCloseOutputDuringHandshakeIsFailedWhenInputCloses() throws {
let context = try configuredSSLContext()
let channel = EmbeddedChannel()
XCTAssertNoThrow(try channel.pipeline.syncOperations.addHandler(NIOSSLServerHandler(context: context)))
XCTAssertNoThrow(try channel.connect(to: .init(ipAddress: "1.2.3.4", port: 5)).wait())
// Buffered until the handshake completes, which the FIN below makes impossible.
let closeOutput = channel.eventLoop.makePromise(of: Void.self)
let closeOutputResult = NIOLockedValueBox<Result<Void, Error>?>(nil)
closeOutput.futureResult.whenComplete { result in
closeOutputResult.withLockedValue { $0 = result }
}
channel.close(mode: .output, promise: closeOutput)
channel.pipeline.fireUserInboundEventTriggered(ChannelEvent.inputClosed)
channel.embeddedEventLoop.run()
guard let result = closeOutputResult.withLockedValue({ $0 }) else {
XCTFail("close(mode: .output) promise was never completed")
return
}
XCTAssertThrowsError(try result.get()) { error in
XCTAssertEqual(error as? NIOSSLError, .handshakeFailed(.sslError([.eofDuringHandshake])))
}
}
func testInputClosedBeforeHandshakeClosesRealSockets() throws {
let context = try configuredSSLContext()
let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
defer {
XCTAssertNoThrow(try group.syncShutdownGracefully())
}
let childChannelPromise: EventLoopPromise<Channel> = group.next().makePromise()
let serverChannel: Channel = try ServerBootstrap(group: group)
.childChannelOption(ChannelOptions.allowRemoteHalfClosure, value: true) // Important!
.serverChannelOption(ChannelOptions.socket(SocketOptionLevel(SOL_SOCKET), SO_REUSEADDR), value: 1)
.childChannelInitializer { channel in
childChannelPromise.succeed(channel)
return channel.eventLoop.makeCompletedFuture {
try channel.pipeline.syncOperations.addHandler(NIOSSLServerHandler(context: context))
}
}
.bind(host: "127.0.0.1", port: 0)
.wait()
defer {
XCTAssertNoThrow(try serverChannel.close().wait())
}
// A plain TCP client that half-closes without sending a single TLS byte.
let clientChannel = try ClientBootstrap(group: group)
.connect(to: serverChannel.localAddress!)
.wait()
defer {
_ = try? clientChannel.close().wait()
}
let childChannel = try childChannelPromise.futureResult.wait()
// Bounded, because a plain closeFuture.wait() hangs the suite if the channel is never reaped.
let childChannelClosed = XCTestExpectation(description: "server reaps the half-closed connection")
childChannel.closeFuture.whenComplete { _ in childChannelClosed.fulfill() }
XCTAssertNoThrow(try clientChannel.close(mode: .output).wait())
XCTAssertEqual(XCTWaiter.wait(for: [childChannelClosed], timeout: 10.0), .completed)
}
func testInputClosedAfterHandshakeDoesNotCloseTheChannel() throws {
let serverChannel = EmbeddedChannel()
let clientChannel = EmbeddedChannel()
defer {
// The CloseNotify exchange has to be pumped, and both ends have TLS state left over.
serverChannel.close(promise: nil)
clientChannel.close(promise: nil)
_ = try? interactInMemory(clientChannel: clientChannel, serverChannel: serverChannel)
serverChannel.embeddedEventLoop.advanceTime(by: .hours(1))
clientChannel.embeddedEventLoop.advanceTime(by: .hours(1))
_ = try? serverChannel.finish()
_ = try? clientChannel.finish()
}
let handshakeHandler = HandshakeCompletedHandler()
let errorCatcher = ErrorCatcher<NIOSSLError>()
let inputClosedRecorder = InputClosedRecorder()
XCTAssertNoThrow(
try serverChannel.pipeline.syncOperations.addHandler(
NIOSSLServerHandler(context: try configuredSSLContext())
)
)
XCTAssertNoThrow(
try clientChannel.pipeline.syncOperations.addHandlers(
NIOSSLClientHandler(context: try configuredClientContext(), serverHostname: "localhost"),
handshakeHandler,
inputClosedRecorder,
errorCatcher
)
)
XCTAssertNoThrow(try connectInMemory(client: clientChannel, server: serverChannel))
XCTAssertNoThrow(try interactInMemory(clientChannel: clientChannel, serverChannel: serverChannel))
XCTAssertTrue(handshakeHandler.handshakeSucceeded)
// Half closure is legitimate once the connection is up: the rest of the pipeline owns it.
clientChannel.pipeline.fireUserInboundEventTriggered(ChannelEvent.inputClosed)
XCTAssertTrue(clientChannel.isActive)
XCTAssertEqual(inputClosedRecorder.inputClosedCount, 1)
XCTAssertEqual(errorCatcher.errors, [.uncleanShutdown])
}
func testInputClosedDuringAdditionalVerificationClosesTheChannel() throws {
let serverChannel = EmbeddedChannel()
let clientChannel = EmbeddedChannel()
defer {
// The server is still active, so its CloseNotify exchange has to be pumped.
serverChannel.close(promise: nil)
_ = try? interactInMemory(clientChannel: clientChannel, serverChannel: serverChannel)
serverChannel.embeddedEventLoop.advanceTime(by: .hours(1))
_ = try? serverChannel.finish()
_ = try? clientChannel.finish()
}
// Left unfulfilled so the client stays parked in .additionalVerification.
let verificationPromise = clientChannel.eventLoop.makePromise(of: Void.self)
let handshakeHandler = HandshakeCompletedHandler()
let errorCatcher = ErrorCatcher<NIOSSLError>()
XCTAssertNoThrow(
try serverChannel.pipeline.syncOperations.addHandler(
NIOSSLServerHandler(context: try configuredSSLContext())
)
)
XCTAssertNoThrow(
try clientChannel.pipeline.syncOperations.addHandlers(
NIOSSLClientHandler._makeSSLClientHandler(
context: try configuredClientContext(),
serverHostname: "localhost",
additionalPeerCertificateVerificationCallback: { _, _ in verificationPromise.futureResult }
),
handshakeHandler,
errorCatcher
)
)
XCTAssertNoThrow(try connectInMemory(client: clientChannel, server: serverChannel))
XCTAssertNoThrow(try interactInMemory(clientChannel: clientChannel, serverChannel: serverChannel))
XCTAssertFalse(handshakeHandler.handshakeSucceeded)
clientChannel.pipeline.fireUserInboundEventTriggered(ChannelEvent.inputClosed)
XCTAssertEqual(
errorCatcher.errors,
[.handshakeFailed(.sslError([.eofDuringAdditionalCertficiateChainValidation]))]
)
XCTAssertFalse(clientChannel.isActive)
// The callback is still outstanding: completing it after the close must not resurrect the
// handshake or trip the state machine.
verificationPromise.succeed(())
clientChannel.embeddedEventLoop.run()
XCTAssertFalse(handshakeHandler.handshakeSucceeded)
XCTAssertFalse(clientChannel.isActive)
}
func testCloseModeOutputTriggersFlush() throws {
let context = try configuredSSLContext()