Don't trap when QUIC reservedCapacity isn't a valid integer length (#3747)

## Motivation

`QUICBinaryEncodingStrategy.writeInteger(_:reservedCapacity:to:)`
switches on `max(reservedCapacity, bytesNeededForInteger(integer))` and
handles only 1, 2, 4 and 8, falling through to
`fatalError("Unreachable")` otherwise.

`bytesNeededForInteger` only ever returns those four values, but
`reservedCapacity` is guarded solely against being greater than 8. A
reserved capacity of 3, 5, 6 or 7 therefore reaches the unreachable case
and traps:

```swift
var buffer = ByteBuffer()
let strategy = ByteBuffer.QUICBinaryEncodingStrategy.quic
strategy.writeInteger(1, reservedCapacity: 3, to: &buffer)
// NIOCore/ByteBuffer-quicBinaryEncodingStrategy.swift:126: Fatal error: Unreachable
```

This is reachable without calling that method directly.
`requiredBytesHint` is a public `var Int` with no validation — the
initialiser takes the 1/2/4/8 `IntegerLength` enum, but the property can
be assigned any value afterwards, and
`writeLengthPrefixed(strategy:writeData:)` passes it straight through as
the reserved capacity:

```swift
var strategy = ByteBuffer.QUICBinaryEncodingStrategy(requiredBytesHint: .one)
strategy.requiredBytesHint = 3          // public var, accepted silently
var buffer = ByteBuffer()
buffer.writeLengthPrefixed(strategy: strategy) { $0.writeString("hi") }
// Fatal error: Unreachable
```

## Modifications

Round the length up to the next valid QUIC integer length rather than
trapping, which is what the surrounding comment already intends by "use
more space than necessary in order to fill the reserved space":

```diff
-            case 4:
+            case 3, 4:
-            case 8:
+            case 5, 6, 7, 8:
```

RFC 9000 § 16 permits encoding a value in more bytes than it strictly
requires, and `writeLengthPrefixed` already shifts the payload when the
integer turns out longer than was reserved (`case reservedCapacity...`),
so writing 4 bytes for a reservation of 3 is handled by existing code.

## Result

No trap for any `reservedCapacity` in `0...8`, and the encoded value
still round-trips.

I checked every combination of `reservedCapacity` in `0...8` against the
boundary values `0, 1, 63, 64, 16383, 16384, 1073741823, 1073741824,
4611686018427387903`: all 81 encode, decode back to the original value,
and leave no bytes behind. On `main` the same check traps.

## Testing

The existing `testRoundtripWithReservedCapacity` iterates over `[0, 1,
2, 4, 8]` — skipping exactly the values that trap, which is presumably
why this went unnoticed. I've added a companion
`testRoundtripWithNonPowerOfTwoReservedCapacity` covering 3, 5, 6 and 7,
asserting both the encoded length and that the value round-trips. It
fails on `main` and passes with this change.

Full test suite: **2455 tests, 0 failures.**

## A note on the alternative

Rounding *down* to the largest valid length that still fits the
reservation would also avoid the trap and waste fewer bytes — for
`reservedCapacity: 3` that would write 2 bytes rather than 4. I went
with rounding up because the existing comment says to use more space
rather than less, and because it keeps the guarantee that at least the
reserved number of bytes is written. Happy to switch if you'd prefer the
other behaviour.

If you would rather fix this at the source by validating
`requiredBytesHint` or changing its type to `IntegerLength`, that would
be source-breaking, so I left it alone — but the public setter is what
makes this reachable in ordinary use.

---------

Co-authored-by: Raphael Hiesgen <r_hiesgen@apple.com>
This commit is contained in:
Nikhil GuptaandRaphael Hiesgen authored and GitHub committed 2026-10-16 16:54:15 +01:00
1 parent fcc5b9c153
commit eabcc14f9d
2 files changed
+118 -9

No files matched your search

@@ -21,15 +21,54 @@ extension ByteBuffer {
case two = 2
case four = 4
case eight = 8
/// The QUIC integer length closest to `value`.
///
/// A QUIC variable-length integer occupies 1, 2, 4 or 8 bytes, so a value such as
/// 3 has no exact representation. Values below eight round up to the next valid
/// length; values above it saturate at ``IntegerLength/eight``.
@inlinable
public init(roundingFrom value: Int) {
switch value {
case ...1: self = .one
case 2: self = .two
case 3, 4: self = .four
default: self = .eight
}
}
}
/// The number of bytes used to write integers with this strategy.
///
/// This is only relevant when calling ``ByteBuffer/writeLengthPrefixed(strategy:writeData:)``.
public var requiredBytesIntegerLength: IntegerLength
/// An estimate of the bytes required to write integers using this strategy
public var requiredBytesHint: Int
///
/// A QUIC variable-length integer is 1, 2, 4 or 8 bytes long, so only those values are
/// representable. Prefer ``requiredBytesIntegerLength``, which can only hold a valid
/// length. Assigning a value here rounds to the closest valid length.
@inlinable
public var requiredBytesHint: Int {
get {
self.requiredBytesIntegerLength.rawValue
}
@available(
*,
deprecated,
message:
"Set requiredBytesIntegerLength instead: a QUIC integer is 1, 2, 4 or 8 bytes long, so other values cannot be represented exactly."
)
set {
self.requiredBytesIntegerLength = IntegerLength(roundingFrom: newValue)
}
}
/// Note: Prefer to use the APIs directly on ByteBuffer such as ``ByteBuffer/writeEncodedInteger(_:strategy:)`` and pass `.quic` rather than directly initialising an instance of this strategy
/// - Parameter requiredBytesHint: An estimate of the bytes required to write integers using this strategy. This parameter is only relevant if calling ``ByteBuffer/writeLengthPrefixed(strategy:writeData:)``
@inlinable
public init(requiredBytesHint: IntegerLength) {
self.requiredBytesHint = requiredBytesHint.rawValue
self.requiredBytesIntegerLength = requiredBytesHint
}
@inlinable
@@ -106,24 +145,22 @@ extension ByteBuffer {
// Use more space than necessary in order to fill the reserved space
// This will avoid a memmove
// If the needed space is more than the reserved, we can't avoid the move
switch max(reservedCapacity, Self.bytesNeededForInteger(integer)) {
case 1:
switch IntegerLength(roundingFrom: max(reservedCapacity, Self.bytesNeededForInteger(integer))) {
case .one:
// Easy, store the value. The top two bits are 0 so we don't need to do any masking.
return buffer.writeInteger(UInt8(truncatingIfNeeded: integer))
case 2:
case .two:
// Set the top two bit mask, then write the value.
let value = UInt16(truncatingIfNeeded: integer) | (0x40 << 8)
return buffer.writeInteger(value)
case 4:
case .four:
// Set the top two bit mask, then write the value.
let value = UInt32(truncatingIfNeeded: integer) | (0x80 << 24)
return buffer.writeInteger(value)
case 8:
case .eight:
// Set the top two bit mask, then write the value.
let value = UInt64(truncatingIfNeeded: integer) | (0xC0 << 56)
return buffer.writeInteger(value)
default:
fatalError("Unreachable")
}
}
}
@@ -147,6 +147,78 @@ final class ByteBufferQUICBinaryEncodingStrategyTests: XCTestCase {
}
}
// The typed `requiredBytesIntegerLength` closes the route through the strategy, but
// `writeInteger(_:reservedCapacity:to:)` is public and still takes a plain `Int`, so a
// caller can hand it a 3 directly. This covers that remaining entry point.
func testRoundtripWithNonPowerOfTwoReservedCapacity() {
for reservedCapacity in [3, 5, 6, 7] {
let testNumbers: [Int64] = [0, 63, 15293, 494_878_333, 151_288_809_941_952_652]
for testNumber in testNumbers {
var buffer = ByteBuffer()
let strategy = ByteBuffer.QUICBinaryEncodingStrategy.quic
let bytesWritten = strategy.writeInteger(
testNumber,
reservedCapacity: reservedCapacity,
to: &buffer
)
let minRequiredBytes = ByteBuffer.QUICBinaryEncodingStrategy.bytesNeededForInteger(testNumber)
let wanted = max(minRequiredBytes, reservedCapacity)
let expectedUsedBytes = wanted <= 2 ? wanted : (wanted <= 4 ? 4 : 8)
XCTAssertEqual(bytesWritten, expectedUsedBytes)
XCTAssertEqual(strategy.readInteger(as: UInt64.self, from: &buffer), UInt64(testNumber))
XCTAssertEqual(buffer.readableBytes, 0)
}
}
}
@available(*, deprecated, message: "Tests the deprecated requiredBytesHint setter")
func testRequiredBytesHintSetterRoundsToAValidLength() {
typealias Length = ByteBuffer.QUICBinaryEncodingStrategy.IntegerLength
// Grouped by expected length, and the strategy starts each case at a different
// length, so an assertion cannot pass on a value the setter never wrote.
let cases: [(expected: Length, inputs: [Int], startingFrom: Length)] = [
(.one, [0, 1], .eight),
(.two, [2], .eight),
(.four, [3, 4], .one),
(.eight, [5, 6, 7, 8, 9, 64], .one),
]
for (expected, inputs, start) in cases {
for input in inputs {
var strategy = ByteBuffer.QUICBinaryEncodingStrategy(requiredBytesHint: start)
XCTAssertNotEqual(
strategy.requiredBytesIntegerLength,
expected,
"input \(input) starts at its expected value"
)
strategy.requiredBytesHint = input
XCTAssertEqual(strategy.requiredBytesIntegerLength, expected, "input \(input)")
}
}
// A value that is already a valid length reads back unchanged.
for length in [Length.one, .two, .four, .eight] {
var strategy = ByteBuffer.QUICBinaryEncodingStrategy(requiredBytesHint: .one)
strategy.requiredBytesHint = length.rawValue
XCTAssertEqual(strategy.requiredBytesHint, length.rawValue)
}
}
@available(*, deprecated, message: "Tests the deprecated requiredBytesHint setter")
func testWriteLengthPrefixedWithRoundedHintDoesNotTrap() {
var strategy = ByteBuffer.QUICBinaryEncodingStrategy(requiredBytesHint: .one)
strategy.requiredBytesHint = 3
var buffer = ByteBuffer()
buffer.writeLengthPrefixed(strategy: strategy) { buffer in
buffer.writeString("hello")
}
XCTAssertEqual(buffer.readLengthPrefixedSlice(strategy: strategy).map { String(buffer: $0) }, "hello")
XCTAssertEqual(buffer.readableBytes, 0)
}
// MARK: - readEncodedInteger tests
func testReadEmptyQUICVariableLengthInteger() {