Merge commit from fork

Add configurable HTTP/1 decoder parsing limits

### Motivation:

The HTTP/1 decoder previously enforced a single hardcoded limit (80 KB per header field) and placed no cap on the total header-block size or the number of header fields per message. That made resource use unpredictable on requests with very many or very large headers, and there was no way for users to tune the limits for their workload.

### Modifications:

- Introduce a new public `NIOHTTPDecoderLimitConfiguration` exposing three parsing limits:
  - maxHeaderFieldSize — maximum size of a single header field (name + value). Default: 80 KB.
  - maxHeaderListSize — maximum total bytes of all header field names and values combined per message. Default: 2 MB.
  - maxHeaderFieldCount — maximum number of header fields per message, including trailers. Default: 256.
- Plumb the configuration through `HTTPDecoder` / `HTTPRequestDecoder` / `HTTPResponseDecoder` initializers. The existing initializers continue to work unchanged via convenience overloads that fall back to
  default limits.
- Expose the configuration on `NIOUpgradableHTTPServerPipelineConfiguration` and `NIOUpgradableHTTPClientPipelineConfiguration` so users of the typed pipeline setup can override the defaults.
- Track per-message totals in `BetterHTTPParser` and reject with `HTTPParserError.headerOverflow` when a limit is exceeded; counters reset at each new message so HTTP/1 pipelined connections behave
  correctly.
- Add tests covering the success and error paths for each limit, the default behaviors, and that trailer fields count toward the field-count cap.

### Result:

Users can configure the HTTP/1 decoder's per-field-size, total-list-size, and field-count limits. Existing call sites continue to compile and run unchanged, now with bounded defaults across all three dimensions instead of just one.
This commit is contained in:
Fabian Fett authored and GitHub committed 2026-05-20 10:00:56 +01:00
1 parent 87f935b70c
commit b24872d3aa
5 files changed
+682 -80

No files matched your search

+71 -7
View File
@@ -39,9 +39,9 @@ private enum HTTPDecodingState {
}
private class BetterHTTPParser {
/// Maximum size of a HTTP header field name or value.
/// This number is derived largely from the historical behaviour of NIO.
private static let maximumHeaderFieldSize = 80 * 1024
private let maximumHeaderFieldSize: Int
private let maximumTotalHeadersSize: Int
private let maximumHeaderFieldCount: Int
var delegate: HTTPDecoderDelegate! = nil
private var parser: llhttp_t? = llhttp_t() // nil if unaccessible because reference passed away exclusively
@@ -49,6 +49,8 @@ private class BetterHTTPParser {
private var decodingState: HTTPDecodingState = .beforeMessageBegin
private var firstNonDiscardableOffset: Int? = nil
private var currentFieldByteLength = 0
private var totalHeadersByteLength = 0
private var headerFieldCount = 0
private var httpParserOffset = 0
private var rawBytesView: UnsafeRawBufferPointer = .init(start: UnsafeRawPointer(bitPattern: 0xcafbabe), count: 0)
private var httpErrno: llhttp_errno_t? = nil
@@ -66,8 +68,11 @@ private class BetterHTTPParser {
Unmanaged<BetterHTTPParser>.fromOpaque(UnsafeRawPointer(opaque!.pointee.data)).takeUnretainedValue()
}
init(kind: HTTPDecoderKind) {
init(kind: HTTPDecoderKind, configuration: NIOHTTPDecoderLimitConfiguration) {
self.kind = kind
self.maximumHeaderFieldSize = configuration.maxHeaderFieldSize
self.maximumTotalHeadersSize = configuration.maxHeaderListSize
self.maximumHeaderFieldCount = configuration.maxHeaderFieldCount
self.settings = UnsafeMutablePointer.allocate(capacity: 1)
c_nio_llhttp_settings_init(self.settings)
self.settings.pointee.on_body = { opaque, bytes, len in
@@ -164,6 +169,7 @@ private class BetterHTTPParser {
}
private func didReceiveHeaderFieldData(_ bytes: UnsafeRawBufferPointer) -> CInt {
var isNewField = false
switch self.decodingState {
case .headerName, .trailerName:
()
@@ -172,25 +178,37 @@ private class BetterHTTPParser {
delegate.didReceiveHeaderValue(bytes)
}
self.start(bytes: bytes, newState: .headerName)
isNewField = true
case .trailerValue:
self.finish { delegate, bytes in
delegate.didReceiveTrailerValue(bytes)
}
self.start(bytes: bytes, newState: .trailerName)
isNewField = true
case .url:
self.finish { delegate, bytes in
delegate.didReceiveURL(bytes)
}
self.start(bytes: bytes, newState: .headerName)
isNewField = true
case .headersComplete:
// these are trailers
self.start(bytes: bytes, newState: .trailerName)
isNewField = true
case .afterMessageBegin:
// in case we're parsing responses
self.start(bytes: bytes, newState: .headerName)
isNewField = true
case .beforeMessageBegin:
preconditionFailure()
}
if isNewField {
self.headerFieldCount += 1
if self.headerFieldCount > self.maximumHeaderFieldCount {
self.richerError = HTTPParserError.headerOverflow
return -1
}
}
return self.validateHeaderLength(bytes.count)
}
@@ -246,6 +264,8 @@ private class BetterHTTPParser {
private func didReceiveMessageBeginNotification() {
switch self.decodingState {
case .beforeMessageBegin:
self.totalHeadersByteLength = 0
self.headerFieldCount = 0
self.decodingState = .afterMessageBegin
case .headersComplete, .headerName, .headerValue, .trailerName, .trailerValue, .afterMessageBegin, .url:
preconditionFailure()
@@ -369,7 +389,13 @@ private class BetterHTTPParser {
private func validateHeaderLength(_ newLength: Int) -> CInt {
self.currentFieldByteLength += newLength
if self.currentFieldByteLength > Self.maximumHeaderFieldSize {
if self.currentFieldByteLength > self.maximumHeaderFieldSize {
self.richerError = HTTPParserError.headerOverflow
return -1
}
self.totalHeadersByteLength += newLength
if self.totalHeadersByteLength > self.maximumTotalHeadersSize {
self.richerError = HTTPParserError.headerOverflow
return -1
}
@@ -515,6 +541,24 @@ where In == HTTPClientResponsePart, Out == HTTPClientRequestPart {
}
}
/// Configuration for the HTTP/1 decoder's parsing limits.
public struct NIOHTTPDecoderLimitConfiguration: Sendable, Hashable {
/// Maximum size (in bytes) of a single header field (name + value). Default: 81,920 (80 KB).
public var maxHeaderFieldSize: Int
/// Maximum total size (in bytes) of all header field names and values combined in a single message. Default: 2,097,152 (2 MB).
public var maxHeaderListSize: Int
/// Maximum number of header fields allowed in a single message (including trailers). Default: 256.
public var maxHeaderFieldCount: Int
public init() {
self.maxHeaderFieldSize = 80 * 1024
self.maxHeaderListSize = 16384 * 128
self.maxHeaderFieldCount = 256
}
}
/// A `ChannelInboundHandler` that parses HTTP/1-style messages, converting them from
/// unstructured bytes to a sequence of HTTP messages.
///
@@ -553,6 +597,24 @@ public final class HTTPDecoder<In, Out>: ByteToMessageDecoder, HTTPDecoderDelega
self.init(leftOverBytesStrategy: leftOverBytesStrategy, informationalResponseStrategy: .drop)
}
/// Creates a new instance of `HTTPDecoder` with default parsing limits.
///
/// - Parameters:
/// - leftOverBytesStrategy: The strategy to use when removing the decoder from the pipeline and an upgrade was,
/// detected. Note that this does not affect what happens on EOF.
/// - informationalResponseStrategy: Should informational responses (like http status 100) be forwarded or dropped.
/// Default is `.drop`. This property is only respected when decoding responses.
public convenience init(
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
informationalResponseStrategy: NIOInformationalResponseStrategy = .drop
) {
self.init(
leftOverBytesStrategy: leftOverBytesStrategy,
informationalResponseStrategy: informationalResponseStrategy,
limitConfiguration: .init()
)
}
/// Creates a new instance of `HTTPDecoder`.
///
/// - Parameters:
@@ -560,9 +622,11 @@ public final class HTTPDecoder<In, Out>: ByteToMessageDecoder, HTTPDecoderDelega
/// detected. Note that this does not affect what happens on EOF.
/// - informationalResponseStrategy: Should informational responses (like http status 100) be forwarded or dropped.
/// Default is `.drop`. This property is only respected when decoding responses.
/// - limitConfiguration: The configuration for the decoder's parsing limits.
public init(
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
informationalResponseStrategy: NIOInformationalResponseStrategy = .drop
informationalResponseStrategy: NIOInformationalResponseStrategy = .drop,
limitConfiguration: NIOHTTPDecoderLimitConfiguration = .init()
) {
self.headers.reserveCapacity(16)
if In.self == HTTPServerRequestPart.self {
@@ -572,7 +636,7 @@ public final class HTTPDecoder<In, Out>: ByteToMessageDecoder, HTTPDecoderDelega
} else {
preconditionFailure("unknown HTTP message type \(In.self)")
}
self.parser = BetterHTTPParser(kind: kind)
self.parser = BetterHTTPParser(kind: kind, configuration: limitConfiguration)
self.leftOverBytesStrategy = leftOverBytesStrategy
self.informationalResponseStrategy = informationalResponseStrategy
}
+210 -67
View File
@@ -77,44 +77,14 @@ extension ChannelPipeline {
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
withClientUpgrade upgrade: NIOHTTPClientUpgradeSendableConfiguration?
) -> EventLoopFuture<Void> {
self._addHTTPClientHandlers(
self.addHTTPClientHandlers(
position: position,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: true,
withClientUpgrade: upgrade
)
}
private func _addHTTPClientHandlers(
position: Position = .last,
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
withClientUpgrade upgrade: NIOHTTPClientUpgradeSendableConfiguration?
) -> EventLoopFuture<Void> {
let future: EventLoopFuture<Void>
if self.eventLoop.inEventLoop {
let syncPosition = ChannelPipeline.SynchronousOperations.Position(position)
let result = Result<Void, Error> {
try self.syncOperations.addHTTPClientHandlers(
position: syncPosition,
leftOverBytesStrategy: leftOverBytesStrategy,
withClientUpgrade: upgrade
)
}
future = self.eventLoop.makeCompletedFuture(result)
} else {
future = self.eventLoop.submit {
let syncPosition = ChannelPipeline.SynchronousOperations.Position(position)
try self.syncOperations.addHTTPClientHandlers(
position: syncPosition,
leftOverBytesStrategy: leftOverBytesStrategy,
withClientUpgrade: upgrade
)
}
}
return future
}
/// Configure a `ChannelPipeline` for use as a HTTP client.
///
/// - Parameters:
@@ -135,32 +105,14 @@ extension ChannelPipeline {
enableOutboundHeaderValidation: Bool = true,
withClientUpgrade upgrade: NIOHTTPClientUpgradeSendableConfiguration? = nil
) -> EventLoopFuture<Void> {
let future: EventLoopFuture<Void>
if self.eventLoop.inEventLoop {
let syncPosition = ChannelPipeline.SynchronousOperations.Position(position)
let result = Result<Void, Error> {
try self.syncOperations.addHTTPClientHandlers(
position: syncPosition,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
withClientUpgrade: upgrade
)
}
future = self.eventLoop.makeCompletedFuture(result)
} else {
future = self.eventLoop.submit {
let syncPosition = ChannelPipeline.SynchronousOperations.Position(position)
try self.syncOperations.addHTTPClientHandlers(
position: syncPosition,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
withClientUpgrade: upgrade
)
}
}
return future
self.addHTTPClientHandlers(
position: position,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: .init(),
decoderLimitConfiguration: .init(),
withClientUpgrade: upgrade
)
}
/// Configure a `ChannelPipeline` for use as a HTTP client.
@@ -184,6 +136,39 @@ extension ChannelPipeline {
enableOutboundHeaderValidation: Bool = true,
encoderConfiguration: HTTPRequestEncoder.Configuration = .init(),
withClientUpgrade upgrade: NIOHTTPClientUpgradeSendableConfiguration? = nil
) -> EventLoopFuture<Void> {
self.addHTTPClientHandlers(
position: position,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: .init(),
withClientUpgrade: upgrade
)
}
/// Configure a `ChannelPipeline` for use as a HTTP client.
///
/// - Parameters:
/// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`.
/// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder`
/// from the pipeline.
/// - enableOutboundHeaderValidation: Whether the pipeline should confirm that outbound headers are well-formed.
/// Defaults to `true`.
/// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``.
/// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for
/// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientUpgradeHandler`` and
/// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler``
/// for more details.
/// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured.
@preconcurrency
public func addHTTPClientHandlers(
position: Position = .last,
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
enableOutboundHeaderValidation: Bool = true,
encoderConfiguration: HTTPRequestEncoder.Configuration = .init(),
decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init(),
withClientUpgrade upgrade: NIOHTTPClientUpgradeSendableConfiguration? = nil
) -> EventLoopFuture<Void> {
let future: EventLoopFuture<Void>
@@ -195,6 +180,7 @@ extension ChannelPipeline {
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: decoderLimitConfiguration,
withClientUpgrade: upgrade
)
}
@@ -207,6 +193,7 @@ extension ChannelPipeline {
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: decoderLimitConfiguration,
withClientUpgrade: upgrade
)
}
@@ -350,13 +337,67 @@ extension ChannelPipeline {
)
}
/// Configure a `ChannelPipeline` for use as a HTTP server.
///
/// This function knows how to set up all first-party HTTP channel handlers appropriately
/// for server use. It supports the following features:
///
/// 1. Providing assistance handling clients that pipeline HTTP requests, using the
/// ``HTTPServerPipelineHandler``.
/// 2. Supporting HTTP upgrade, using the ``HTTPServerUpgradeHandler``.
/// 3. Providing assistance handling protocol errors.
/// 4. Validating outbound header fields to protect against response splitting attacks.
///
/// This method will likely be extended in future with more support for other first-party
/// features.
///
/// - Parameters:
/// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`.
/// - pipelining: Whether to provide assistance handling HTTP clients that pipeline
/// their requests. Defaults to `true`. If `false`, users will need to handle
/// clients that pipeline themselves.
/// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for
/// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If
/// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade
/// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more
/// details.
/// - errorHandling: Whether to provide assistance handling protocol errors (e.g.
/// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`.
/// - headerValidation: Whether to validate outbound request headers to confirm that they meet
/// spec compliance. Defaults to `true`.
/// - encoderConfiguration: The configuration for the ``HTTPResponseEncoder``.
/// - decoderLimitConfiguration: The limit configuration for the ``HTTPDecoder``.
/// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured.
@preconcurrency
public func configureHTTPServerPipeline(
position: ChannelPipeline.Position = .last,
withPipeliningAssistance pipelining: Bool = true,
withServerUpgrade upgrade: NIOHTTPServerUpgradeSendableConfiguration? = nil,
withErrorHandling errorHandling: Bool = true,
withOutboundHeaderValidation headerValidation: Bool = true,
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration = .init(),
withDecoderLimitConfiguration decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init()
) -> EventLoopFuture<Void> {
self._configureHTTPServerPipeline(
position: position,
withPipeliningAssistance: pipelining,
withServerUpgrade: upgrade,
withErrorHandling: errorHandling,
withOutboundHeaderValidation: headerValidation,
withEncoderConfiguration: encoderConfiguration,
withDecoderLimitConfiguration: decoderLimitConfiguration
)
}
private func _configureHTTPServerPipeline(
position: ChannelPipeline.Position = .last,
withPipeliningAssistance pipelining: Bool = true,
withServerUpgrade upgrade: NIOHTTPServerUpgradeSendableConfiguration? = nil,
withErrorHandling errorHandling: Bool = true,
withOutboundHeaderValidation headerValidation: Bool = true,
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration = .init()
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration = .init(),
withDecoderLimitConfiguration decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init()
) -> EventLoopFuture<Void> {
let future: EventLoopFuture<Void>
@@ -369,7 +410,8 @@ extension ChannelPipeline {
withServerUpgrade: upgrade,
withErrorHandling: errorHandling,
withOutboundHeaderValidation: headerValidation,
withEncoderConfiguration: encoderConfiguration
withEncoderConfiguration: encoderConfiguration,
withDecoderLimitConfiguration: decoderLimitConfiguration
)
}
future = self.eventLoop.makeCompletedFuture(result)
@@ -382,7 +424,8 @@ extension ChannelPipeline {
withServerUpgrade: upgrade,
withErrorHandling: errorHandling,
withOutboundHeaderValidation: headerValidation,
withEncoderConfiguration: encoderConfiguration
withEncoderConfiguration: encoderConfiguration,
withDecoderLimitConfiguration: decoderLimitConfiguration
)
}
}
@@ -531,6 +574,39 @@ extension ChannelPipeline.SynchronousOperations {
)
}
/// Configure a `ChannelPipeline` for use as a HTTP client.
///
/// - important: This **must** be called on the Channel's event loop.
/// - Parameters:
/// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`.
/// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder`
/// from the pipeline.
/// - enableOutboundHeaderValidation: Whether or not request header validation is enforced.
/// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``.
/// - decoderLimitConfiguration: The limit configuration for the ``HTTPDecoder``.
/// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for
/// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientProtocolUpgrader`` and
/// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler``
/// for more details.
/// - Throws: If the pipeline could not be configured.
public func addHTTPClientHandlers(
position: ChannelPipeline.SynchronousOperations.Position = .last,
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
enableOutboundHeaderValidation: Bool = true,
encoderConfiguration: HTTPRequestEncoder.Configuration = .init(),
decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init(),
withClientUpgrade upgrade: NIOHTTPClientUpgradeConfiguration? = nil
) throws {
try self._addHTTPClientHandlers(
position: position,
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: decoderLimitConfiguration,
withClientUpgrade: upgrade
)
}
/// Configure a `ChannelPipeline` for use as a HTTP client.
///
/// - important: This **must** be called on the Channel's event loop.
@@ -569,6 +645,7 @@ extension ChannelPipeline.SynchronousOperations {
leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes,
enableOutboundHeaderValidation: Bool = true,
encoderConfiguration: HTTPRequestEncoder.Configuration = .init(),
decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init(),
withClientUpgrade upgrade: NIOHTTPClientUpgradeConfiguration? = nil
) throws {
// Why two separate functions? With the fast-path (no upgrader, yes header validator) we can promote the Array of handlers
@@ -579,13 +656,15 @@ extension ChannelPipeline.SynchronousOperations {
leftOverBytesStrategy: leftOverBytesStrategy,
enableOutboundHeaderValidation: enableOutboundHeaderValidation,
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: decoderLimitConfiguration,
withClientUpgrade: upgrade
)
} else {
try self._addHTTPClientHandlers(
position: position,
leftOverBytesStrategy: leftOverBytesStrategy,
encoderConfiguration: encoderConfiguration
encoderConfiguration: encoderConfiguration,
decoderLimitConfiguration: decoderLimitConfiguration
)
}
}
@@ -593,11 +672,15 @@ extension ChannelPipeline.SynchronousOperations {
private func _addHTTPClientHandlers(
position: ChannelPipeline.SynchronousOperations.Position,
leftOverBytesStrategy: RemoveAfterUpgradeStrategy,
encoderConfiguration: HTTPRequestEncoder.Configuration
encoderConfiguration: HTTPRequestEncoder.Configuration,
decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration
) throws {
self.eventLoop.assertInEventLoop()
let requestEncoder = HTTPRequestEncoder(configuration: encoderConfiguration)
let responseDecoder = HTTPResponseDecoder(leftOverBytesStrategy: leftOverBytesStrategy)
let responseDecoder = HTTPResponseDecoder(
leftOverBytesStrategy: leftOverBytesStrategy,
limitConfiguration: decoderLimitConfiguration
)
let requestHeaderValidator = NIOHTTPRequestHeadersValidator()
let handlers: [ChannelHandler] = [
requestEncoder, ByteToMessageHandler(responseDecoder), requestHeaderValidator,
@@ -610,11 +693,15 @@ extension ChannelPipeline.SynchronousOperations {
leftOverBytesStrategy: RemoveAfterUpgradeStrategy,
enableOutboundHeaderValidation: Bool,
encoderConfiguration: HTTPRequestEncoder.Configuration,
decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration,
withClientUpgrade upgrade: NIOHTTPClientUpgradeConfiguration?
) throws {
self.eventLoop.assertInEventLoop()
let requestEncoder = HTTPRequestEncoder(configuration: encoderConfiguration)
let responseDecoder = HTTPResponseDecoder(leftOverBytesStrategy: leftOverBytesStrategy)
let responseDecoder = HTTPResponseDecoder(
leftOverBytesStrategy: leftOverBytesStrategy,
limitConfiguration: decoderLimitConfiguration
)
var handlers: [RemovableChannelHandler] = [requestEncoder, ByteToMessageHandler(responseDecoder)]
if enableOutboundHeaderValidation {
@@ -861,6 +948,58 @@ extension ChannelPipeline.SynchronousOperations {
)
}
/// Configure a `ChannelPipeline` for use as a HTTP server.
///
/// This function knows how to set up all first-party HTTP channel handlers appropriately
/// for server use. It supports the following features:
///
/// 1. Providing assistance handling clients that pipeline HTTP requests, using the
/// `HTTPServerPipelineHandler`.
/// 2. Supporting HTTP upgrade, using the `HTTPServerUpgradeHandler`.
/// 3. Providing assistance handling protocol errors.
/// 4. Validating outbound header fields to protect against response splitting attacks.
///
/// This method will likely be extended in future with more support for other first-party
/// features.
///
/// - important: This **must** be called on the Channel's event loop.
/// - Parameters:
/// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`.
/// - pipelining: Whether to provide assistance handling HTTP clients that pipeline
/// their requests. Defaults to `true`. If `false`, users will need to handle
/// clients that pipeline themselves.
/// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for
/// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If
/// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade
/// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more
/// details.
/// - errorHandling: Whether to provide assistance handling protocol errors (e.g.
/// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`.
/// - headerValidation: Whether to validate outbound request headers to confirm that they meet
/// spec compliance. Defaults to `true`.
/// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``.
/// - decoderLimitConfiguration: The limit configuration for the ``HTTPDecoder``.
/// - Throws: If the pipeline could not be configured.
public func configureHTTPServerPipeline(
position: ChannelPipeline.SynchronousOperations.Position = .last,
withPipeliningAssistance pipelining: Bool = true,
withServerUpgrade upgrade: NIOHTTPServerUpgradeConfiguration? = nil,
withErrorHandling errorHandling: Bool = true,
withOutboundHeaderValidation headerValidation: Bool = true,
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration,
withDecoderLimitConfiguration decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration,
) throws {
try self._configureHTTPServerPipeline(
position: position,
withPipeliningAssistance: pipelining,
withServerUpgrade: upgrade,
withErrorHandling: errorHandling,
withOutboundHeaderValidation: headerValidation,
withEncoderConfiguration: encoderConfiguration,
withDecoderLimitConfiguration: decoderLimitConfiguration
)
}
/// Configure a `ChannelPipeline` for use as a HTTP server.
///
/// This function knows how to set up all first-party HTTP channel handlers appropriately
@@ -919,12 +1058,16 @@ extension ChannelPipeline.SynchronousOperations {
withServerUpgrade upgrade: NIOHTTPServerUpgradeConfiguration? = nil,
withErrorHandling errorHandling: Bool = true,
withOutboundHeaderValidation headerValidation: Bool = true,
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration = .init()
withEncoderConfiguration encoderConfiguration: HTTPResponseEncoder.Configuration = .init(),
withDecoderLimitConfiguration decoderLimitConfiguration: NIOHTTPDecoderLimitConfiguration = .init()
) throws {
self.eventLoop.assertInEventLoop()
let responseEncoder = HTTPResponseEncoder(configuration: encoderConfiguration)
let requestDecoder = HTTPRequestDecoder(leftOverBytesStrategy: upgrade == nil ? .dropBytes : .forwardBytes)
let requestDecoder = HTTPRequestDecoder(
leftOverBytesStrategy: upgrade == nil ? .dropBytes : .forwardBytes,
limitConfiguration: decoderLimitConfiguration
)
var handlers: [RemovableChannelHandler] = [responseEncoder, ByteToMessageHandler(requestDecoder)]
+16 -2
View File
@@ -33,6 +33,9 @@ public struct NIOUpgradableHTTPServerPipelineConfiguration<UpgradeResult: Sendab
/// The configuration for the ``HTTPResponseEncoder``.
public var encoderConfiguration = HTTPResponseEncoder.Configuration()
/// The configuration for the ``HTTPRequestDecoder``'s parsing limits.
public var decoderConfiguration = NIOHTTPDecoderLimitConfiguration()
/// The configuration for the ``NIOTypedHTTPServerUpgradeHandler``.
public var upgradeConfiguration: NIOTypedHTTPServerUpgradeConfiguration<UpgradeResult>
@@ -103,7 +106,12 @@ extension ChannelPipeline.SynchronousOperations {
self.eventLoop.assertInEventLoop()
let responseEncoder = HTTPResponseEncoder(configuration: configuration.encoderConfiguration)
let requestDecoder = ByteToMessageHandler(HTTPRequestDecoder(leftOverBytesStrategy: .forwardBytes))
let requestDecoder = ByteToMessageHandler(
HTTPRequestDecoder(
leftOverBytesStrategy: .forwardBytes,
limitConfiguration: configuration.decoderConfiguration
)
)
var extraHTTPHandlers = [RemovableChannelHandler]()
extraHTTPHandlers.reserveCapacity(4)
@@ -156,6 +164,9 @@ public struct NIOUpgradableHTTPClientPipelineConfiguration<UpgradeResult: Sendab
/// The configuration for the ``HTTPRequestEncoder``.
public var encoderConfiguration = HTTPRequestEncoder.Configuration()
/// The configuration for the ``HTTPResponseDecoder``'s parsing limits.
public var decoderConfiguration = NIOHTTPDecoderLimitConfiguration()
/// The configuration for the ``NIOTypedHTTPClientUpgradeHandler``.
public var upgradeConfiguration: NIOTypedHTTPClientUpgradeConfiguration<UpgradeResult>
@@ -223,7 +234,10 @@ extension ChannelPipeline.SynchronousOperations {
let requestEncoder = HTTPRequestEncoder(configuration: configuration.encoderConfiguration)
let responseDecoder = ByteToMessageHandler(
HTTPResponseDecoder(leftOverBytesStrategy: configuration.leftOverBytesStrategy)
HTTPResponseDecoder(
leftOverBytesStrategy: configuration.leftOverBytesStrategy,
limitConfiguration: configuration.decoderConfiguration
)
)
var httpHandlers = [RemovableChannelHandler]()
httpHandlers.reserveCapacity(3)
+23 -4
View File
@@ -157,7 +157,14 @@ class HTTPDecoderTest: XCTestCase {
}
}
XCTAssertNoThrow(try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder())))
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldCount = 10_000
config.maxHeaderListSize = .max
XCTAssertNoThrow(
try channel.pipeline.syncOperations.addHandler(
ByteToMessageHandler(HTTPRequestDecoder(limitConfiguration: config))
)
)
XCTAssertNoThrow(try channel.pipeline.syncOperations.addHandler(Receiver()))
// This is a hypothetical HTTP/2.0 protocol response, assuming it is
@@ -1072,8 +1079,12 @@ class HTTPDecoderTest: XCTestCase {
func testDecodingLongHeaderFieldNames() {
// Our maximum field size is 80kB, so we're going to write an 80kB + 1 byte field name to confirm it fails.
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = .max
XCTAssertNoThrow(
try self.channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
try self.channel.pipeline.syncOperations.addHandler(
ByteToMessageHandler(HTTPRequestDecoder(limitConfiguration: config))
)
)
var buffer = ByteBuffer(string: "GET / HTTP/1.1\r\nHost: example.com\r\n")
@@ -1100,8 +1111,12 @@ class HTTPDecoderTest: XCTestCase {
func testDecodingLongHeaderFieldValues() {
// Our maximum field size is 80kB, so we're going to write an 80kB + 1 byte field value to confirm it fails.
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = .max
XCTAssertNoThrow(
try self.channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
try self.channel.pipeline.syncOperations.addHandler(
ByteToMessageHandler(HTTPRequestDecoder(limitConfiguration: config))
)
)
var buffer = ByteBuffer(string: "GET / HTTP/1.1\r\nHost: example.com\r\nx: ")
@@ -1128,8 +1143,12 @@ class HTTPDecoderTest: XCTestCase {
func testDecodingLongURLs() {
// Our maximum field size is 80kB, so we're going to write an 80kB + 1 byte URL to confirm it fails.
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = .max
XCTAssertNoThrow(
try self.channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
try self.channel.pipeline.syncOperations.addHandler(
ByteToMessageHandler(HTTPRequestDecoder(limitConfiguration: config))
)
)
var buffer = ByteBuffer(string: "GET ")
@@ -0,0 +1,362 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
import NIOCore
import NIOEmbedded
import NIOHTTP1
import Testing
@Suite struct HTTPDecoderTesting {
// MARK: - Default limit tests
@Test func requestWithExcessiveNumberOfHeadersErrors() throws {
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
var buffer = channel.allocator.buffer(capacity: 64)
buffer.writeString("GET / HTTP/1.1\r\nHost: example.com\r\n")
try channel.writeInbound(buffer)
var threwError = false
for i in 0..<1_000_000 {
let headerBuffer = ByteBuffer(string: "X-Hdr-\(i): v\r\n")
do {
try channel.writeInbound(headerBuffer)
} catch {
threwError = true
break
}
}
#expect(threwError, "Expected the decoder to reject a request with an excessive number of headers")
_ = try? channel.finish()
}
@Test func requestWithOversizedURIErrors() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = 100 * 1024
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 8)
buffer.writeString("GET ")
try channel.writeInbound(buffer)
#expect(try channel.readInbound(as: HTTPServerRequestPart.self) == nil)
var chunk = channel.allocator.buffer(capacity: 1024)
chunk.writeRepeatingByte(UInt8(ascii: "x"), count: 1024)
for _ in 0..<80 {
try channel.writeInbound(chunk)
#expect(try channel.readInbound(as: HTTPServerRequestPart.self) == nil)
}
let lastByte = chunk.getSlice(at: chunk.readerIndex, length: 1)!
let error = #expect(throws: HTTPParserError.self) {
try channel.writeInbound(lastByte)
}
#expect(error == .headerOverflow)
_ = try? channel.finish()
}
@Test func requestWithOversizedMethodErrors() throws {
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
var chunk = channel.allocator.buffer(capacity: 3)
chunk.writeRepeatingByte(UInt8(ascii: "X"), count: 3)
var threwError = false
var caughtError: (any Error)?
for _ in 0..<81 {
do {
try channel.writeInbound(chunk)
} catch {
threwError = true
caughtError = error
break
}
}
#expect(threwError, "Expected the decoder to reject a request with an oversized method")
if let parserError = caughtError as? HTTPParserError {
#expect(parserError == .invalidMethod)
}
_ = try? channel.finish()
}
// MARK: - Field count limit tests
@Test func requestAtFieldCountLimitSucceeds() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldCount = 10
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
// Write exactly 10 headers (at the limit)
for i in 0..<10 {
buffer.writeString("X-Hdr-\(i): value\r\n")
}
buffer.writeString("\r\n")
try channel.writeInbound(buffer)
let head = try channel.readInbound(as: HTTPServerRequestPart.self)
guard case .head(let requestHead) = head else {
Issue.record("Expected .head, got \(String(describing: head))")
return
}
#expect(requestHead.headers.count == 10)
_ = try? channel.finish()
}
@Test func requestExceedingFieldCountLimitErrors() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldCount = 10
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
// Write 11 headers (one over the limit)
for i in 0..<11 {
buffer.writeString("X-Hdr-\(i): value\r\n")
}
buffer.writeString("\r\n")
let error = #expect(throws: HTTPParserError.self) {
try channel.writeInbound(buffer)
}
#expect(error == .headerOverflow)
_ = try? channel.finish()
}
@Test func defaultFieldCountLimitRejectsExcessiveHeaders() throws {
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(HTTPRequestDecoder()))
var buffer = channel.allocator.buffer(capacity: 64)
buffer.writeString("GET / HTTP/1.1\r\nHost: example.com\r\n")
try channel.writeInbound(buffer)
// Default limit is 256 fields. Sending 257 should fail.
var threwError = false
for i in 0..<257 {
let headerBuffer = ByteBuffer(string: "X-H-\(i): v\r\n")
do {
try channel.writeInbound(headerBuffer)
} catch {
threwError = true
break
}
}
#expect(threwError, "Expected default field count limit to reject request with 257+ headers")
_ = try? channel.finish()
}
// MARK: - Max header list size tests
@Test func requestExceedingMaxHeaderListSizeErrors() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = 256
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 512)
buffer.writeString("GET / HTTP/1.1\r\n")
// Create a header that pushes total over 256 bytes
let bigValue = String(repeating: "x", count: 300)
buffer.writeString("X-Big: \(bigValue)\r\n\r\n")
let error = #expect(throws: HTTPParserError.self) {
try channel.writeInbound(buffer)
}
#expect(error == .headerOverflow)
_ = try? channel.finish()
}
@Test func requestWithinMaxHeaderListSizeSucceeds() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderListSize = 1024
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
let value = String(repeating: "x", count: 100)
buffer.writeString("X-Hdr: \(value)\r\n\r\n")
try channel.writeInbound(buffer)
let head = try channel.readInbound(as: HTTPServerRequestPart.self)
guard case .head = head else {
Issue.record("Expected .head, got \(String(describing: head))")
return
}
_ = try? channel.finish()
}
@Test func defaultMaxHeaderListSizeIs2MB() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldCount = 10_000
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 64)
buffer.writeString("GET / HTTP/1.1\r\n")
try channel.writeInbound(buffer)
// Default maxHeaderListSize is 16384 * 128 = 2 MB. Send headers totaling > 2 MB.
// Use values just under the default 16 KB field-size limit so the field-size
// limit doesn't trigger first.
let valueSize = 16000
var totalBytes = 0
var threwError = false
for i in 0..<200 {
let name = "X-H-\(i)"
let value = String(repeating: "a", count: valueSize)
let headerBuffer = ByteBuffer(string: "\(name): \(value)\r\n")
totalBytes += name.utf8.count + value.utf8.count
do {
try channel.writeInbound(headerBuffer)
} catch {
threwError = true
break
}
}
#expect(threwError, "Expected default 2 MB header list size limit to reject request")
#expect(totalBytes > 16384 * 128, "Test should have exceeded 2 MB before error")
_ = try? channel.finish()
}
// MARK: - Max header field size tests
@Test func requestExceedingMaxHeaderFieldSizeErrors() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldSize = 128
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
let bigValue = String(repeating: "x", count: 200)
buffer.writeString("X-Hdr: \(bigValue)\r\n\r\n")
let error = #expect(throws: HTTPParserError.self) {
try channel.writeInbound(buffer)
}
#expect(error == .headerOverflow)
_ = try? channel.finish()
}
@Test func requestWithinMaxHeaderFieldSizeSucceeds() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldSize = 256
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
let value = String(repeating: "x", count: 100)
buffer.writeString("X-Hdr: \(value)\r\n\r\n")
try channel.writeInbound(buffer)
let head = try channel.readInbound(as: HTTPServerRequestPart.self)
guard case .head = head else {
Issue.record("Expected .head, got \(String(describing: head))")
return
}
_ = try? channel.finish()
}
// MARK: - Custom configuration allows larger traffic
@Test func customLargerLimitsAllowPreviouslyRejectedTraffic() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldSize = 200 * 1024 // 200 KB per field
config.maxHeaderListSize = 10 * 1024 * 1024 // 10 MB total
config.maxHeaderFieldCount = 10_000
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 256)
buffer.writeString("GET / HTTP/1.1\r\n")
// Write a header value larger than the default 80KB limit
let bigValue = String(repeating: "x", count: 100 * 1024)
buffer.writeString("X-Big: \(bigValue)\r\n\r\n")
try channel.writeInbound(buffer)
let head = try channel.readInbound(as: HTTPServerRequestPart.self)
guard case .head(let requestHead) = head else {
Issue.record("Expected .head, got \(String(describing: head))")
return
}
#expect(requestHead.headers["X-Big"].first?.count == 100 * 1024)
_ = try? channel.finish()
}
// MARK: - Trailer field count tests
@Test func trailersCountTowardFieldCountLimit() throws {
var config = NIOHTTPDecoderLimitConfiguration()
config.maxHeaderFieldCount = 5
config.maxHeaderListSize = 1024 * 1024
let decoder = HTTPRequestDecoder(limitConfiguration: config)
let channel = EmbeddedChannel()
try channel.pipeline.syncOperations.addHandler(ByteToMessageHandler(decoder))
var buffer = channel.allocator.buffer(capacity: 512)
// 4 headers (within limit of 5)
buffer.writeString("GET / HTTP/1.1\r\n")
buffer.writeString("Host: example.com\r\n")
buffer.writeString("Transfer-Encoding: chunked\r\n")
buffer.writeString("X-A: a\r\n")
buffer.writeString("X-B: b\r\n")
buffer.writeString("\r\n")
// chunked body
buffer.writeString("5\r\nhello\r\n0\r\n")
// 2 trailers (pushing total fields to 6, over limit of 5)
buffer.writeString("X-Trailer-1: t1\r\n")
buffer.writeString("X-Trailer-2: t2\r\n")
buffer.writeString("\r\n")
let error = #expect(throws: HTTPParserError.self) {
try channel.writeInbound(buffer)
}
#expect(error == .headerOverflow)
_ = try? channel.finish()
}
}