Files
swift-nio/Tests/NIOTestUtilsTests/ByteToMessageDecoderVerifierTest.swift
Fabian FettandCory Benfield f5b34b27cb Allow non-copyable ByteToMessageDecoders and typed throws (#3731)
### Motivation

Decoders are state machines and state machines are a natural fit for
non-copyable types. Today `ByteToMessageDecoder` and
`NIOSingleStepByteToMessageDecoder` require their conformers to be
copyable.

While we are here we also want `NIOSingleStepByteToMessageDecoder` to be
able to declare a concrete error type, so that callers can handle decode
errors without going through an existential.

### Changes
  
- Make `ByteToMessageDecoder` and `NIOSingleStepByteToMessageDecoder`
`~Copyable`.
- Add an `associatedtype DecodeError: Error = any Error` to
`NIOSingleStepByteToMessageDecoder` and spell decode and decodeLast as
`throws(DecodeError)`. Decoders that don't declare it keep behaving
exactly as before.
- Allow `~Copyable` `ByteToMessageDecoder` in `ByteToMessageHandler`.
- Since `~Copyable` types cannot be type erased into an existential
before macOS 15, we have to work around the existing `CanDequeueWrites`
dance: instead of casting `self` to `CanDequeueWrites` in
`handlerAdded`, ByteToMessageHandler gains an optional
`deliverQueuedWrite` closure. It is formed in the constrained
`ChannelOutboundHandler.write`, the only place where `Decoder`'s
`WriteObservingByteToMessageDecoder` conformance is statically known,
the first time a write arrives re-entrantly.
This has to be a closure rather than a protocol requirement on
`ByteToMessageDecoder`. `Decoders` may conform to
`WriteObservingByteToMessageDecoder` conditionally while conforming to
`ByteToMessageDecoder` unconditionally — `HTTPDecoder` does exactly this
— and all generic instantiations share one `ByteToMessageDecoder`
witness table, so such a requirement could only ever be witnessed by a
non-observing default and the write would be silently dropped.
- Split the delivery out of `tryDecodeWrites` into an `@inline(never)
dequeueWrites()`. `decodeLoop` calls `tryDecodeWrites` on every
iteration, so the empty-queue check has to stay cheap; keeping the
delivery inline tripled that function's size (50 → 141 instructions) and
showed up directly on the normal decode path.
- `ByteToMessageDecoderVerifier` allows `~Copyable`
`ByteToMessageDecoder`s.
- Added tests that use the newly lifted `~Copyable` restriction, plus
regression coverage for a decoder whose write-observing conformance is
conditional (the HTTPDecoder shape) and for constructing the handler in
a generic context.

### Result

Decoders may be non-copyable and may declare a concrete error type.
  
The normal decode path does not change performance. The re-entrant write
path costs one extra allocation per handler, but is meaningfully cheaper
in instructions. I'm happy to provide the benchmarks used to generate
those numbers in a separate pr – leaving them out here, as we would end
up with as many benchmarks as we have unit tests sooner or later.
  
Instructions, macOS arm64, per 1000 iterations, min of 5 interleaved
rounds:
  
```
  ┌──────────────────────────────┬────────────┬────────────┬───────────────────────────────────┐
  │                              │    main    │  this PR   │                                   │
  ├──────────────────────────────┼────────────┼────────────┼───────────────────────────────────┤
  │ decode, no write observation │ 9,404,415  │ 9,360,896  │ −0.46% (noise ~0.8%, i.e. parity) │
  ├──────────────────────────────┼────────────┼────────────┼───────────────────────────────────┤
  │ decode + re-entrant write    │ 13,656,063 │ 12,541,951 │ −8.16%                            │
  ├──────────────────────────────┼────────────┼────────────┼───────────────────────────────────┤
  │ handler add / remove         │ 85,983,231 │ 83,361,791 │ −3.05% (noise ~2.2%)              │
  └──────────────────────────────┴────────────┴────────────┴───────────────────────────────────┘
```

Replacing the CanDequeueWrites existential with the closure is what
improves the reentrant write path: delivering a queued write is now a
direct closure call rather than a witness-table dispatch, and
handlerAdded no longer performs a runtime conditional-conformance
lookup.
The saving grows with the number of writes queued per decode — around
−16% with 8 queued writes, though that benchmark is noisier.

Allocations (nio-alloc-counter-tests, Swift 6.2):
  
```
  ┌────────────────────────────┬─────────┬─────────┬────────┐
  │                            │  main   │ this PR │        │
  ├────────────────────────────┼─────────┼─────────┼────────┤
  │ 1000_reqs_1_conn           │ 27,341  │ 27,342  │ +1     │
  ├────────────────────────────┼─────────┼─────────┼────────┤
  │ 1_reqs_1000_conn           │ 368,000 │ 369,000 │ +1,000 │
  ├────────────────────────────┼─────────┼─────────┼────────┤
  │ ping_pong_1000_reqs_1_conn │ 296     │ 296     │ —      │
  ├────────────────────────────┼─────────┼─────────┼────────┤
  │ decode_1000_ws_frames      │ 2,000   │ 2,000   │ —      │
  └────────────────────────────┴─────────┴─────────┴────────┘
```

Forming the closure captures Decoder.OutboundIn's metadata, so it
allocates once per handler that actually queues a re-entrant write —
1_reqs_1000_conn builds 1000 such handlers, hence +1000. main's
existential cast did not allocate, so this is a new cost rather than
staying flat. The 1_reqs_1000_conn threshold is raised by 1000 for
6.1/6.2/6.3; the nightly toolchains are unchanged (10,000 on both — they
specialize the closure away entirely).

---------

Co-authored-by: Cory Benfield <lukasa@apple.com>
2026-09-17 13:44:37 +01:00

310 lines
11 KiB
Swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2019-2021 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import NIOPosix
import NIOTestUtils
import Testing
@testable import NIOCore
typealias VerificationError = ByteToMessageDecoderVerifier.VerificationError<String>
struct ByteToMessageDecoderVerifierTests {
@Test func wrongResults() throws {
struct AlwaysProduceY: ByteToMessageDecoder {
typealias InboundOut = String
func decode(context: ChannelHandlerContext, buffer: inout ByteBuffer) throws -> DecodingState {
buffer.moveReaderIndex(to: buffer.writerIndex)
context.fireChannelRead(Self.wrapInboundOut("Y"))
return .needMoreData
}
func decodeLast(
context: ChannelHandlerContext,
buffer: inout ByteBuffer,
seenEOF: Bool
) throws -> DecodingState {
while try self.decode(context: context, buffer: &buffer) == .continue {}
return .needMoreData
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("x", ["x"])],
decoderFactory: AlwaysProduceY.init
)
}
#expect(1 == error.inputs.count)
switch error.errorCode {
case .wrongProduction(let actual, let expected):
#expect("Y" == actual)
#expect("x" == expected)
default:
Issue.record("unexpected error: \(error)")
}
}
@Test func noOutputWhenWeShouldHaveOutput() throws {
struct NeverProduce: ByteToMessageDecoder {
typealias InboundOut = String
func decode(context: ChannelHandlerContext, buffer: inout ByteBuffer) throws -> DecodingState {
buffer.moveReaderIndex(to: buffer.writerIndex)
return .needMoreData
}
func decodeLast(
context: ChannelHandlerContext,
buffer: inout ByteBuffer,
seenEOF: Bool
) throws -> DecodingState {
while try self.decode(context: context, buffer: &buffer) == .continue {}
return .needMoreData
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("x", ["x"])],
decoderFactory: NeverProduce.init
)
}
#expect(1 == error.inputs.count)
switch error.errorCode {
case .underProduction(let expected):
#expect("x" == expected)
default:
Issue.record("unexpected error: \(error)")
}
}
@Test func outputWhenWeShouldNotProduceOutput() throws {
struct ProduceTooEarly: ByteToMessageDecoder {
typealias InboundOut = String
func decode(context: ChannelHandlerContext, buffer: inout ByteBuffer) throws -> DecodingState {
context.fireChannelRead(Self.wrapInboundOut("Y"))
return .needMoreData
}
func decodeLast(
context: ChannelHandlerContext,
buffer: inout ByteBuffer,
seenEOF: Bool
) throws -> DecodingState {
while try self.decode(context: context, buffer: &buffer) == .continue {}
return .needMoreData
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("xxxxxx", ["Y"])],
decoderFactory: ProduceTooEarly.init
)
}
switch error.errorCode {
case .overProduction(let actual):
#expect("Y" == actual)
default:
Issue.record("unexpected error: \(error)")
}
}
@Test func leftovers() throws {
struct NeverDoAnything: ByteToMessageDecoder {
typealias InboundOut = String
func decode(context: ChannelHandlerContext, buffer: inout ByteBuffer) throws -> DecodingState {
.needMoreData
}
func decodeLast(
context: ChannelHandlerContext,
buffer: inout ByteBuffer,
seenEOF: Bool
) throws -> DecodingState {
while try self.decode(context: context, buffer: &buffer) == .continue {}
if buffer.readableBytes > 0 {
context.fireChannelRead(Self.wrapInboundOut("leftover"))
}
return .needMoreData
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("xxxxxx", [])],
decoderFactory: NeverDoAnything.init
)
}
switch error.errorCode {
case .leftOversOnDeconstructingChannel(
let inbound,
let outbound,
pendingOutbound: let pending
):
#expect(0 == outbound.count)
#expect(["leftover"] == inbound.map { $0.tryAs(type: String.self) })
#expect(0 == pending.count)
default:
Issue.record("unexpected error: \(error)")
}
}
// MARK: - Non-copyable decoders
/// Decodes one byte into a one character `String`.
private struct NonCopyableOneByteDecoder: NIOSingleStepByteToMessageDecoder, ~Copyable {
typealias InboundOut = String
mutating func decode(buffer: inout ByteBuffer) throws -> String? {
buffer.readString(length: 1)
}
mutating func decodeLast(buffer: inout ByteBuffer, seenEOF: Bool) throws -> String? {
try self.decode(buffer: &buffer)
}
}
@available(macOS 15, iOS 18, tvOS 18, watchOS 11, visionOS 2, *)
@Test func nonCopyableDecoderIsVerified() throws {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("x", ["x"]), ("y", ["y"])],
decoderFactory: NonCopyableOneByteDecoder.init
)
}
@available(macOS 15, iOS 18, tvOS 18, watchOS 11, visionOS 2, *)
@Test func nonCopyableDecoderWrongResults() throws {
struct AlwaysProduceY: NIOSingleStepByteToMessageDecoder, ~Copyable {
typealias InboundOut = String
mutating func decode(buffer: inout ByteBuffer) throws -> String? {
guard buffer.readableBytes > 0 else { return nil }
buffer.moveReaderIndex(to: buffer.writerIndex)
return "Y"
}
mutating func decodeLast(buffer: inout ByteBuffer, seenEOF: Bool) throws -> String? {
try self.decode(buffer: &buffer)
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("x", ["x"])],
decoderFactory: AlwaysProduceY.init
)
}
#expect(1 == error.inputs.count)
switch error.errorCode {
case .wrongProduction(let actual, let expected):
#expect("Y" == actual)
#expect("x" == expected)
default:
Issue.record("unexpected error: \(error)")
}
}
@available(macOS 15, iOS 18, tvOS 18, watchOS 11, visionOS 2, *)
@Test func nonCopyableDecoderNoOutputWhenWeShouldHaveOutput() throws {
struct NeverProduce: NIOSingleStepByteToMessageDecoder, ~Copyable {
typealias InboundOut = String
mutating func decode(buffer: inout ByteBuffer) throws -> String? {
buffer.moveReaderIndex(to: buffer.writerIndex)
return nil
}
mutating func decodeLast(buffer: inout ByteBuffer, seenEOF: Bool) throws -> String? {
try self.decode(buffer: &buffer)
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("x", ["x"])],
decoderFactory: NeverProduce.init
)
}
#expect(1 == error.inputs.count)
switch error.errorCode {
case .underProduction(let expected):
#expect("x" == expected)
default:
Issue.record("unexpected error: \(error)")
}
}
@available(macOS 15, iOS 18, tvOS 18, watchOS 11, visionOS 2, *)
@Test func nonCopyableDecoderOutputWhenWeShouldNotProduceOutput() throws {
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
// The decoder produces one message per byte, so it over-produces on the second byte.
stringInputOutputPairs: [("xy", ["x"])],
decoderFactory: NonCopyableOneByteDecoder.init
)
}
switch error.errorCode {
case .overProduction(let actual):
#expect("y" == actual)
default:
Issue.record("unexpected error: \(error)")
}
}
@available(macOS 15, iOS 18, tvOS 18, watchOS 11, visionOS 2, *)
@Test func nonCopyableDecoderLeftovers() throws {
struct NeverDoAnything: NIOSingleStepByteToMessageDecoder, ~Copyable {
typealias InboundOut = String
mutating func decode(buffer: inout ByteBuffer) throws -> String? {
nil
}
mutating func decodeLast(buffer: inout ByteBuffer, seenEOF: Bool) throws -> String? {
nil
}
}
let error = try #require(throws: VerificationError.self) {
try ByteToMessageDecoderVerifier.verifyDecoder(
stringInputOutputPairs: [("xxxxxx", [])],
decoderFactory: NeverDoAnything.init
)
}
switch error.errorCode {
case .leftOversOnDeconstructingChannel(let inbound, let outbound, pendingOutbound: let pending):
// The bytes the decoder never consumed sit in `ByteToMessageHandler`'s buffer rather than in the
// `Channel`, so the left overs are reported as empty.
#expect(0 == inbound.count)
#expect(0 == outbound.count)
#expect(0 == pending.count)
default:
Issue.record("unexpected error: \(error)")
}
}
}