Add HTTP/2 and HTTP/3 error code types (#148)

### Motivation

HTTP/2 and HTTP/3 both carry a numeric error code to say why a stream or
a connection was terminated. HTTPTypes has no currency type for either,
so adopters passed bare integers around or defined their own.

### Modifications

Add HTTP2ErrorCode and HTTP3ErrorCode.

### Result

HTTP/2 and HTTP/3 error codes are first-class currency types.

---------

Co-authored-by: Fabian Fett <fabianfett@apple.com>
This commit is contained in:
Eric RosenbergandFabian Fett authored and GitHub committed 2026-08-29 00:04:31 +01:00
1 parent c12e12f7c5
commit 6226da4bb9
5 files changed
+500 -1

No files matched your search

+1 -1
View File
@@ -12,7 +12,7 @@ dependencies: [
]
```
The `HTTPTypes` library exposes the core HTTP currency types, including `HTTPRequest`, `HTTPResponse`, and `HTTPFields`.
The `HTTPTypes` library exposes the core HTTP currency types, including `HTTPRequest`, `HTTPResponse`, and `HTTPFields`, as well as the HTTP/2 and HTTP/3 error code types `HTTP2ErrorCode` and `HTTP3ErrorCode`.
The `HTTPTypesFoundation` library provides conveniences for using new HTTP types with Foundation, including bidirectional convertors between the new types and Foundation URL types, and URLSession convenience methods with the new types.
+2
View File
@@ -10,6 +10,8 @@ A set of version-independent HTTP currency types.
`HTTPFields` represents a list of HTTP header or trailer fields.
`HTTP2ErrorCode` and `HTTP3ErrorCode` represent the version-specific error codes used to terminate HTTP/2 and HTTP/3 streams and connections.
## Getting Started
#### Create a request
+199
View File
@@ -0,0 +1,199 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// An HTTP/2 error code.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@available(HTTPTypes 1.7, *)
public struct HTTP2ErrorCode: Sendable, Hashable, RawRepresentable {
/// The 32-bit error code value.
public let rawValue: UInt32
/// Create an HTTP/2 error code from its numeric value.
///
/// Every 32-bit value is a valid HTTP/2 error code, including values that are not registered.
/// - Parameter rawValue: The error code value.
@inlinable
public init(rawValue: UInt32) {
self.rawValue = rawValue
}
}
@available(HTTPTypes 1.7, *)
extension HTTP2ErrorCode {
/// NO_ERROR (0x00)
///
/// Graceful shutdown.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var noError: Self { .init(rawValue: 0x00) }
/// PROTOCOL_ERROR (0x01)
///
/// Protocol error detected.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var protocolError: Self { .init(rawValue: 0x01) }
/// INTERNAL_ERROR (0x02)
///
/// Implementation fault.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var internalError: Self { .init(rawValue: 0x02) }
/// FLOW_CONTROL_ERROR (0x03)
///
/// Flow-control limits exceeded.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var flowControlError: Self { .init(rawValue: 0x03) }
/// SETTINGS_TIMEOUT (0x04)
///
/// Settings not acknowledged.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var settingsTimeout: Self { .init(rawValue: 0x04) }
/// STREAM_CLOSED (0x05)
///
/// Frame received for closed stream.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var streamClosed: Self { .init(rawValue: 0x05) }
/// FRAME_SIZE_ERROR (0x06)
///
/// Frame size incorrect.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var frameSizeError: Self { .init(rawValue: 0x06) }
/// REFUSED_STREAM (0x07)
///
/// Stream not processed.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var refusedStream: Self { .init(rawValue: 0x07) }
/// CANCEL (0x08)
///
/// Stream cancelled.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var cancel: Self { .init(rawValue: 0x08) }
/// COMPRESSION_ERROR (0x09)
///
/// Compression state not updated.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var compressionError: Self { .init(rawValue: 0x09) }
/// CONNECT_ERROR (0x0a)
///
/// TCP connection error for CONNECT method.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var connectError: Self { .init(rawValue: 0x0a) }
/// ENHANCE_YOUR_CALM (0x0b)
///
/// Processing capacity exceeded.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var enhanceYourCalm: Self { .init(rawValue: 0x0b) }
/// INADEQUATE_SECURITY (0x0c)
///
/// Negotiated TLS parameters not acceptable.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var inadequateSecurity: Self { .init(rawValue: 0x0c) }
/// HTTP_1_1_REQUIRED (0x0d)
///
/// Use HTTP/1.1 for the request.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#section-7
@inlinable
public static var http11Required: Self { .init(rawValue: 0x0d) }
}
@available(HTTPTypes 1.7, *)
extension HTTP2ErrorCode: CustomStringConvertible {
/// The registered name of the error code, or nil if the code is not registered.
private var name: String? {
switch self.rawValue {
case 0x00:
return "NO_ERROR"
case 0x01:
return "PROTOCOL_ERROR"
case 0x02:
return "INTERNAL_ERROR"
case 0x03:
return "FLOW_CONTROL_ERROR"
case 0x04:
return "SETTINGS_TIMEOUT"
case 0x05:
return "STREAM_CLOSED"
case 0x06:
return "FRAME_SIZE_ERROR"
case 0x07:
return "REFUSED_STREAM"
case 0x08:
return "CANCEL"
case 0x09:
return "COMPRESSION_ERROR"
case 0x0a:
return "CONNECT_ERROR"
case 0x0b:
return "ENHANCE_YOUR_CALM"
case 0x0c:
return "INADEQUATE_SECURITY"
case 0x0d:
return "HTTP_1_1_REQUIRED"
default:
return nil
}
}
/// A textual representation of the error code.
///
/// Registered codes are rendered as their registered name followed by their hexadecimal value,
/// such as `CANCEL (0x8)`. Codes that are not registered are rendered as their hexadecimal
/// value alone, such as `0xe`.
public var description: String {
let hexValue = "0x\(String(self.rawValue, radix: 16))"
if let name = self.name {
return "\(name) (\(hexValue))"
} else {
return hexValue
}
}
}
+275
View File
@@ -0,0 +1,275 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// An HTTP/3 error code.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@available(HTTPTypes 1.7, *)
public struct HTTP3ErrorCode: Sendable, Hashable, RawRepresentable {
/// The largest valid HTTP/3 error code, 2^62 - 1.
///
/// HTTP/3 error codes are encoded as QUIC variable-length integers, which cannot represent
/// larger values.
///
/// https://www.rfc-editor.org/rfc/rfc9000.html#section-16
private static let maxRawValue: UInt64 = 0x3fff_ffff_ffff_ffff
/// The error code value, which is never greater than 2^62 - 1.
public let rawValue: UInt64
/// Create an HTTP/3 error code from its numeric value.
///
/// Values that are not registered are allowed, but the value must be representable as a QUIC
/// variable-length integer.
///
/// https://www.rfc-editor.org/rfc/rfc9000.html#section-16
/// - Parameter rawValue: The error code value. It must not be greater than 2^62 - 1.
public init(rawValue: UInt64) {
precondition(rawValue <= Self.maxRawValue, "Invalid HTTP/3 error code")
self.rawValue = rawValue
}
@inlinable
init(uncheckedRawValue: UInt64) {
self.rawValue = uncheckedRawValue
}
}
@available(HTTPTypes 1.7, *)
extension HTTP3ErrorCode {
/// H3_NO_ERROR (0x0100)
///
/// No error.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var noError: Self { .init(uncheckedRawValue: 0x0100) }
/// H3_GENERAL_PROTOCOL_ERROR (0x0101)
///
/// General protocol error.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var generalProtocolError: Self { .init(uncheckedRawValue: 0x0101) }
/// H3_INTERNAL_ERROR (0x0102)
///
/// Internal error.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var internalError: Self { .init(uncheckedRawValue: 0x0102) }
/// H3_STREAM_CREATION_ERROR (0x0103)
///
/// Stream creation error.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var streamCreationError: Self { .init(uncheckedRawValue: 0x0103) }
/// H3_CLOSED_CRITICAL_STREAM (0x0104)
///
/// Critical stream was closed.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var closedCriticalStream: Self { .init(uncheckedRawValue: 0x0104) }
/// H3_FRAME_UNEXPECTED (0x0105)
///
/// Frame not permitted in the current state.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var frameUnexpected: Self { .init(uncheckedRawValue: 0x0105) }
/// H3_FRAME_ERROR (0x0106)
///
/// Frame violated layout or size rules.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var frameError: Self { .init(uncheckedRawValue: 0x0106) }
/// H3_EXCESSIVE_LOAD (0x0107)
///
/// Peer generating excessive load.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var excessiveLoad: Self { .init(uncheckedRawValue: 0x0107) }
/// H3_ID_ERROR (0x0108)
///
/// An identifier was used incorrectly.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var idError: Self { .init(uncheckedRawValue: 0x0108) }
/// H3_SETTINGS_ERROR (0x0109)
///
/// SETTINGS frame contained invalid values.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var settingsError: Self { .init(uncheckedRawValue: 0x0109) }
/// H3_MISSING_SETTINGS (0x010a)
///
/// No SETTINGS frame received.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var missingSettings: Self { .init(uncheckedRawValue: 0x010a) }
/// H3_REQUEST_REJECTED (0x010b)
///
/// Request not processed.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var requestRejected: Self { .init(uncheckedRawValue: 0x010b) }
/// H3_REQUEST_CANCELLED (0x010c)
///
/// Data no longer needed.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var requestCancelled: Self { .init(uncheckedRawValue: 0x010c) }
/// H3_REQUEST_INCOMPLETE (0x010d)
///
/// Stream terminated early.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var requestIncomplete: Self { .init(uncheckedRawValue: 0x010d) }
/// H3_MESSAGE_ERROR (0x010e)
///
/// Malformed message.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var messageError: Self { .init(uncheckedRawValue: 0x010e) }
/// H3_CONNECT_ERROR (0x010f)
///
/// TCP reset or error on CONNECT request.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var connectError: Self { .init(uncheckedRawValue: 0x010f) }
/// H3_VERSION_FALLBACK (0x0110)
///
/// Retry over HTTP/1.1.
///
/// https://www.rfc-editor.org/rfc/rfc9114.html#section-8.1
@inlinable
public static var versionFallback: Self { .init(uncheckedRawValue: 0x0110) }
/// QPACK_DECOMPRESSION_FAILED (0x0200)
///
/// Decoding of a field section failed.
///
/// https://www.rfc-editor.org/rfc/rfc9204.html#section-6
@inlinable
public static var qpackDecompressionFailed: Self { .init(uncheckedRawValue: 0x0200) }
/// QPACK_ENCODER_STREAM_ERROR (0x0201)
///
/// Error on the encoder stream.
///
/// https://www.rfc-editor.org/rfc/rfc9204.html#section-6
@inlinable
public static var qpackEncoderStreamError: Self { .init(uncheckedRawValue: 0x0201) }
/// QPACK_DECODER_STREAM_ERROR (0x0202)
///
/// Error on the decoder stream.
///
/// https://www.rfc-editor.org/rfc/rfc9204.html#section-6
@inlinable
public static var qpackDecoderStreamError: Self { .init(uncheckedRawValue: 0x0202) }
}
@available(HTTPTypes 1.7, *)
extension HTTP3ErrorCode: CustomStringConvertible {
/// The registered name of the error code, or nil if the code is not registered.
private var name: String? {
switch self.rawValue {
case 0x0100:
return "H3_NO_ERROR"
case 0x0101:
return "H3_GENERAL_PROTOCOL_ERROR"
case 0x0102:
return "H3_INTERNAL_ERROR"
case 0x0103:
return "H3_STREAM_CREATION_ERROR"
case 0x0104:
return "H3_CLOSED_CRITICAL_STREAM"
case 0x0105:
return "H3_FRAME_UNEXPECTED"
case 0x0106:
return "H3_FRAME_ERROR"
case 0x0107:
return "H3_EXCESSIVE_LOAD"
case 0x0108:
return "H3_ID_ERROR"
case 0x0109:
return "H3_SETTINGS_ERROR"
case 0x010a:
return "H3_MISSING_SETTINGS"
case 0x010b:
return "H3_REQUEST_REJECTED"
case 0x010c:
return "H3_REQUEST_CANCELLED"
case 0x010d:
return "H3_REQUEST_INCOMPLETE"
case 0x010e:
return "H3_MESSAGE_ERROR"
case 0x010f:
return "H3_CONNECT_ERROR"
case 0x0110:
return "H3_VERSION_FALLBACK"
case 0x0200:
return "QPACK_DECOMPRESSION_FAILED"
case 0x0201:
return "QPACK_ENCODER_STREAM_ERROR"
case 0x0202:
return "QPACK_DECODER_STREAM_ERROR"
default:
return nil
}
}
/// A textual representation of the error code.
///
/// Registered codes are rendered as their registered name followed by their hexadecimal value,
/// such as `H3_REQUEST_CANCELLED (0x10c)`. Codes that are not registered are rendered as their
/// hexadecimal value alone, such as `0x21`.
public var description: String {
let hexValue = "0x\(String(self.rawValue, radix: 16))"
if let name = self.name {
return "\(name) (\(hexValue))"
} else {
return hexValue
}
}
}
+23
View File
@@ -300,6 +300,8 @@ extension HTTPField.Name {
let response: HTTPResponse = .init(status: .ok)
let status: HTTPResponse.Status = response.status
let responsePseudoHeaderFields: HTTPResponse.PseudoHeaderFields = response.pseudoHeaderFields
let http2ErrorCode: HTTP2ErrorCode = .cancel
let http3ErrorCode: HTTP3ErrorCode = .requestCancelled
#expect(isSendable(field))
#expect(isSendable(indexingStrategy))
@@ -311,6 +313,8 @@ extension HTTPField.Name {
#expect(isSendable(response))
#expect(isSendable(status))
#expect(isSendable(responsePseudoHeaderFields))
#expect(isSendable(http2ErrorCode))
#expect(isSendable(http3ErrorCode))
}
@Test func requestCoding() throws {
@@ -417,5 +421,24 @@ extension HTTPField.Name {
#expect(MemoryLayout<HTTPRequest>.size == MemoryLayout<AnyObject>.size * 2)
#expect(MemoryLayout<HTTPResponse>.size == MemoryLayout<AnyObject>.size * 2)
#expect(MemoryLayout<HTTPFields>.size == MemoryLayout<AnyObject>.size)
#expect(MemoryLayout<HTTP2ErrorCode>.size == 4)
#expect(MemoryLayout<HTTP3ErrorCode>.size == 8)
}
@Test func errorCodes() {
#expect(HTTP2ErrorCode.cancel.description == "CANCEL (0x8)")
#expect("\(HTTP2ErrorCode.enhanceYourCalm)" == "ENHANCE_YOUR_CALM (0xb)")
#expect(HTTP3ErrorCode.requestCancelled.description == "H3_REQUEST_CANCELLED (0x10c)")
#expect(HTTP3ErrorCode.qpackDecompressionFailed.description == "QPACK_DECOMPRESSION_FAILED (0x200)")
// Codes that are not registered render as a bare hexadecimal value.
#expect(HTTP2ErrorCode(rawValue: 0x0e).description == "0xe")
#expect(HTTP2ErrorCode(rawValue: .max).description == "0xffffffff")
#expect(HTTP3ErrorCode(rawValue: 0x0111).description == "0x111")
// An HTTP/3 code is a QUIC variable-length integer, so it tops out below UInt64.max.
let maxRawValue: UInt64 = (1 << 62) - 1
#expect(HTTP3ErrorCode(rawValue: maxRawValue).rawValue == maxRawValue)
#expect(HTTP3ErrorCode(rawValue: maxRawValue).description == "0x3fffffffffffffff")
}
}