Files
swift-http-types/Sources/HTTPTypes/HTTPFieldName.swift
T
Fabian Fett bff4b6903c Regression fix: HTTPField.Name.init(parsed:) rejects uppercased names again (#155)
### Motivation

#144 introduced a regression in `HTTPField.Name(parsed:)`.

HTTP/2 and HTTP/3 require field names to be lowercased on the wire (RFC
9113 § 8.2.1, RFC 9114 § 4.1.2). Previously we enforced this by only
accepting lowercase ASCII letters.

In #144 we replaced a specific scan with `HTTPField.isValidToken`, which
is shared in multiple token validation places and returns `valid` for
uppercased names. We checked for `isValid`, which is true for `valid` as
well as `canonical` representations. Allowing `valid` and not just
`canonical` representations is the regression.

This lead to this unwanted behavior:
- `HTTPField.Name(parsed: "Content-Type")` now succeeds, so a decoder
can no longer detect the malformed message it has to reject.
- The returned name violates the documented invariant that
`canonicalName` is lowercased, so it compares and hashes unequal to
`HTTPField.Name("Content-Type")`, which does canonicalise.

This path had no test coverage, so neither regression was caught.

### Changes

Require `.canonical` rather than merely valid token validity in
`init(parsed:)`, restoring the pre-#144 behavior, and document why. Add
`HTTPFieldNameTests` covering both initializers: valid names, pseudo
header fields, invalid characters, the mixed-case canonicalisation that
`init(_:)` performs, and the uppercase rejection that `init(parsed:)`
performs.

### Result

`init(parsed:)` rejects uppercased names again and `canonicalName` is
lowercased for every name it returns.
2026-09-07 09:56:43 +02:00

686 lines
23 KiB
Swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift open source project
//
// Copyright (c) 2023 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
//
//===----------------------------------------------------------------------===//
@available(HTTPTypes 1.0, *)
extension HTTPField {
/// A case-insensitive but case-preserving ASCII string with an allowed character set defined
/// in RFC 9110.
///
/// https://www.rfc-editor.org/rfc/rfc9110.html#name-field-names
///
/// Common HTTP field names are provided as convenience static properties, and for custom field
/// names, it is recommended to extend the `HTTPField.Name` struct with new static members.
///
/// ```
/// extension HTTPField.Name {
/// static let example = Self("X-Example")!
/// }
/// ```
public struct Name: Sendable {
/// The original name of the HTTP field received or supplied to the initializer.
public let rawName: String
/// The lowercased canonical name of the HTTP field used for hashing and comparison.
public let canonicalName: String
/// Create an HTTP field name from a string. Returns nil if the name contains invalid
/// characters defined in RFC 9110.
///
/// https://www.rfc-editor.org/rfc/rfc9110.html#name-field-names
///
/// - Parameter name: The name of the HTTP field. It can be accessed from the `rawName`
/// property.
@inlinable
public init?(_ name: String) {
guard let canonicalName = HTTPField.validatedCanonicalName(name) else {
return nil
}
self.rawName = name
self.canonicalName = canonicalName
}
/// Create an HTTP field name from a string produced by HPACK or QPACK decoders used in
/// modern HTTP versions.
///
/// Returns nil if the name contains invalid characters defined in RFC 9110, or if it is not
/// already lowercased. Names arriving over HTTP/2 or HTTP/3 must be lowercased on the wire,
/// and a message carrying an uppercase field name has to be treated as malformed, so this
/// initializer rejects rather than canonicalises such a name. Use `init?(_:)` for names from
/// sources which are allowed to use mixed case.
///
/// https://www.rfc-editor.org/rfc/rfc9113.html#name-field-validity
/// https://www.rfc-editor.org/rfc/rfc9114.html#name-field-formatting-and-compre
///
/// - Warning: Do not use directly with the `HTTPFields` struct which does not allow pseudo
/// header fields.
///
/// - Parameter name: The name of the HTTP field or the HTTP pseudo header field. It must
/// be lowercased.
@available(HTTPTypes 1.2, *)
@inlinable
public init?(parsed name: String) {
let token: Substring
if name.utf8.first == UInt8(ascii: ":") {
token = name.dropFirst()
} else {
token = Substring(name)
}
switch HTTPField.tokenValidity(token) {
case .canonical:
self.rawName = name
self.canonicalName = name
case .invalid, .valid:
// valid also allows uppercased characters
return nil
}
}
@inlinable
init(rawName: String, canonicalName: String) {
self.rawName = rawName
self.canonicalName = canonicalName
}
@inlinable
var isPseudo: Bool {
self.rawName.utf8.first == UInt8(ascii: ":")
}
}
}
@available(HTTPTypes 1.0, *)
extension HTTPField.Name: Hashable {
public func hash(into hasher: inout Hasher) {
hasher.combine(self.canonicalName)
}
public static func == (lhs: HTTPField.Name, rhs: HTTPField.Name) -> Bool {
lhs.canonicalName == rhs.canonicalName
}
}
@available(HTTPTypes 1.0, *)
extension HTTPField.Name: LosslessStringConvertible {
public var description: String {
self.rawName
}
}
#if !hasFeature(Embedded)
@available(HTTPTypes 1.0, *)
extension HTTPField.Name: CustomPlaygroundDisplayConvertible {
public var playgroundDescription: Any {
self.description
}
}
@available(HTTPTypes 1.0, *)
extension HTTPField.Name: Codable {
public func encode(to encoder: Encoder) throws {
var container = encoder.singleValueContainer()
try container.encode(self.rawName)
}
public init(from decoder: Decoder) throws {
let container = try decoder.singleValueContainer()
let nameString = try container.decode(String.self)
if nameString.utf8.first == UInt8(ascii: ":") {
guard nameString.lowercased() == nameString,
HTTPField.isValidToken(nameString.dropFirst())
else {
throw DecodingError.dataCorruptedError(
in: container,
debugDescription: "HTTP pseudo field name \"\(nameString)\" contains invalid characters"
)
}
self.init(rawName: nameString, canonicalName: nameString)
} else {
guard let name = Self(nameString) else {
throw DecodingError.dataCorruptedError(
in: container,
debugDescription: "HTTP field name \"\(nameString)\" contains invalid characters"
)
}
self = name
}
}
}
#endif
@available(HTTPTypes 1.0, *)
extension HTTPField.Name {
@inlinable static var method: Self { .init(rawName: ":method", canonicalName: ":method") }
@inlinable static var scheme: Self { .init(rawName: ":scheme", canonicalName: ":scheme") }
@inlinable static var authority: Self { .init(rawName: ":authority", canonicalName: ":authority") }
@inlinable static var path: Self { .init(rawName: ":path", canonicalName: ":path") }
@inlinable static var `protocol`: Self { .init(rawName: ":protocol", canonicalName: ":protocol") }
@inlinable static var status: Self { .init(rawName: ":status", canonicalName: ":status") }
/// Accept
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var accept: Self { .init(rawName: "Accept", canonicalName: "accept") }
/// Accept-Encoding
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var acceptEncoding: Self { .init(rawName: "Accept-Encoding", canonicalName: "accept-encoding") }
/// Accept-Language
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var acceptLanguage: Self { .init(rawName: "Accept-Language", canonicalName: "accept-language") }
/// Accept-Ranges
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var acceptRanges: Self { .init(rawName: "Accept-Ranges", canonicalName: "accept-ranges") }
/// Access-Control-Allow-Credentials
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlAllowCredentials: Self {
.init(rawName: "Access-Control-Allow-Credentials", canonicalName: "access-control-allow-credentials")
}
/// Access-Control-Allow-Headers
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlAllowHeaders: Self {
.init(rawName: "Access-Control-Allow-Headers", canonicalName: "access-control-allow-headers")
}
/// Access-Control-Allow-Methods
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlAllowMethods: Self {
.init(rawName: "Access-Control-Allow-Methods", canonicalName: "access-control-allow-methods")
}
/// Access-Control-Allow-Origin
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlAllowOrigin: Self {
.init(rawName: "Access-Control-Allow-Origin", canonicalName: "access-control-allow-origin")
}
/// Access-Control-Expose-Headers
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlExposeHeaders: Self {
.init(rawName: "Access-Control-Expose-Headers", canonicalName: "access-control-expose-headers")
}
/// Access-Control-Max-Age
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlMaxAge: Self {
.init(rawName: "Access-Control-Max-Age", canonicalName: "access-control-max-age")
}
/// Access-Control-Request-Headers
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlRequestHeaders: Self {
.init(rawName: "Access-Control-Request-Headers", canonicalName: "access-control-request-headers")
}
/// Access-Control-Request-Method
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var accessControlRequestMethod: Self {
.init(rawName: "Access-Control-Request-Method", canonicalName: "access-control-request-method")
}
/// Age
///
/// https://www.rfc-editor.org/rfc/rfc9111.html
@inlinable
public static var age: Self { .init(rawName: "Age", canonicalName: "age") }
/// Allow
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var allow: Self { .init(rawName: "Allow", canonicalName: "allow") }
/// Authentication-Info
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var authenticationInfo: Self {
.init(rawName: "Authentication-Info", canonicalName: "authentication-info")
}
/// Authorization
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var authorization: Self { .init(rawName: "Authorization", canonicalName: "authorization") }
/// Available-Dictionary
///
/// https://www.rfc-editor.org/rfc/rfc9842.html
@available(HTTPTypes 1.6, *)
@inlinable
public static var availableDictionary: Self {
.init(rawName: "Available-Dictionary", canonicalName: "available-dictionary")
}
/// Cache-Control
///
/// https://www.rfc-editor.org/rfc/rfc9111.html
@inlinable
public static var cacheControl: Self { .init(rawName: "Cache-Control", canonicalName: "cache-control") }
/// Connection
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var connection: Self { .init(rawName: "Connection", canonicalName: "connection") }
/// Content-Disposition
///
/// https://www.rfc-editor.org/rfc/rfc6266.html
@inlinable
public static var contentDisposition: Self {
.init(rawName: "Content-Disposition", canonicalName: "content-disposition")
}
/// Content-Encoding
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentEncoding: Self { .init(rawName: "Content-Encoding", canonicalName: "content-encoding") }
/// Content-Language
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentLanguage: Self { .init(rawName: "Content-Language", canonicalName: "content-language") }
/// Content-Length
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentLength: Self { .init(rawName: "Content-Length", canonicalName: "content-length") }
/// Content-Location
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentLocation: Self { .init(rawName: "Content-Location", canonicalName: "content-location") }
/// Content-Range
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentRange: Self { .init(rawName: "Content-Range", canonicalName: "content-range") }
/// Content-Security-Policy
///
/// https://www.w3.org/TR/CSP/
@inlinable
public static var contentSecurityPolicy: Self {
.init(rawName: "Content-Security-Policy", canonicalName: "content-security-policy")
}
/// Content-Security-Policy-Report-Only
///
/// https://www.w3.org/TR/CSP/
@inlinable
public static var contentSecurityPolicyReportOnly: Self {
.init(rawName: "Content-Security-Policy-Report-Only", canonicalName: "content-security-policy-report-only")
}
/// Content-Type
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var contentType: Self { .init(rawName: "Content-Type", canonicalName: "content-type") }
/// Cookie
///
/// https://www.rfc-editor.org/rfc/rfc6265.html
@inlinable
public static var cookie: Self { .init(rawName: "Cookie", canonicalName: "cookie") }
/// Cross-Origin-Resource-Policy
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var crossOriginResourcePolicy: Self {
.init(rawName: "Cross-Origin-Resource-Policy", canonicalName: "cross-origin-resource-policy")
}
/// Date
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var date: Self { .init(rawName: "Date", canonicalName: "date") }
/// Dictionary-ID
///
/// https://www.rfc-editor.org/rfc/rfc9842.html
@available(HTTPTypes 1.6, *)
@inlinable
public static var dictionaryID: Self { .init(rawName: "Dictionary-ID", canonicalName: "dictionary-id") }
/// Early-Data
///
/// https://www.rfc-editor.org/rfc/rfc8470.html
@inlinable
public static var earlyData: Self { .init(rawName: "Early-Data", canonicalName: "early-data") }
/// ETag
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var eTag: Self { .init(rawName: "ETag", canonicalName: "etag") }
/// Expect
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var expect: Self { .init(rawName: "Expect", canonicalName: "expect") }
/// Expires
///
/// https://www.rfc-editor.org/rfc/rfc9111.html
@inlinable
public static var expires: Self { .init(rawName: "Expires", canonicalName: "expires") }
/// From
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var from: Self { .init(rawName: "From", canonicalName: "from") }
/// Host
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@available(*, unavailable, message: "Use HTTPRequest.authority instead")
@inlinable
public static var host: Self { .init(rawName: "Host", canonicalName: "host") }
/// If-Match
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var ifMatch: Self { .init(rawName: "If-Match", canonicalName: "if-match") }
/// If-Modified-Since
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var ifModifiedSince: Self { .init(rawName: "If-Modified-Since", canonicalName: "if-modified-since") }
/// If-None-Match
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var ifNoneMatch: Self { .init(rawName: "If-None-Match", canonicalName: "if-none-match") }
/// If-Range
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var ifRange: Self { .init(rawName: "If-Range", canonicalName: "if-range") }
/// If-Unmodified-Since
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var ifUnmodifiedSince: Self {
.init(rawName: "If-Unmodified-Since", canonicalName: "if-unmodified-since")
}
/// Last-Modified
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var lastModified: Self { .init(rawName: "Last-Modified", canonicalName: "last-modified") }
/// Location
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var location: Self { .init(rawName: "Location", canonicalName: "location") }
/// Max-Forwards
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var maxForwards: Self { .init(rawName: "Max-Forwards", canonicalName: "max-forwards") }
/// Origin
///
/// https://www.rfc-editor.org/rfc/rfc6454.html
@inlinable
public static var origin: Self { .init(rawName: "Origin", canonicalName: "origin") }
/// Priority
///
/// https://www.rfc-editor.org/rfc/rfc9218.html
@inlinable
public static var priority: Self { .init(rawName: "Priority", canonicalName: "priority") }
/// Proxy-Authenticate
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var proxyAuthenticate: Self {
.init(rawName: "Proxy-Authenticate", canonicalName: "proxy-authenticate")
}
/// Proxy-Authentication-Info
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var proxyAuthenticationInfo: Self {
.init(rawName: "Proxy-Authentication-Info", canonicalName: "proxy-authentication-info")
}
/// Proxy-Authorization
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var proxyAuthorization: Self {
.init(rawName: "Proxy-Authorization", canonicalName: "proxy-authorization")
}
/// Proxy-Status
///
/// https://www.rfc-editor.org/rfc/rfc9209.html
@available(HTTPTypes 1.3, *)
@inlinable
public static var proxyStatus: Self { .init(rawName: "Proxy-Status", canonicalName: "proxy-status") }
/// Range
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var range: Self { .init(rawName: "Range", canonicalName: "range") }
/// Referer
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var referer: Self { .init(rawName: "Referer", canonicalName: "referer") }
/// Retry-After
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var retryAfter: Self { .init(rawName: "Retry-After", canonicalName: "retry-after") }
/// Sec-Purpose
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var secPurpose: Self { .init(rawName: "Sec-Purpose", canonicalName: "sec-purpose") }
/// Sec-WebSocket-Accept
///
/// https://www.rfc-editor.org/rfc/rfc6455.html
@inlinable
public static var secWebSocketAccept: Self {
.init(rawName: "Sec-WebSocket-Accept", canonicalName: "sec-websocket-accept")
}
/// Sec-WebSocket-Extensions
///
/// https://www.rfc-editor.org/rfc/rfc6455.html
@inlinable
public static var secWebSocketExtensions: Self {
.init(rawName: "Sec-WebSocket-Extensions", canonicalName: "sec-websocket-extensions")
}
/// Sec-WebSocket-Key
///
/// https://www.rfc-editor.org/rfc/rfc6455.html
@inlinable
public static var secWebSocketKey: Self { .init(rawName: "Sec-WebSocket-Key", canonicalName: "sec-websocket-key") }
/// Sec-WebSocket-Protocol
///
/// https://www.rfc-editor.org/rfc/rfc6455.html
@inlinable
public static var secWebSocketProtocol: Self {
.init(rawName: "Sec-WebSocket-Protocol", canonicalName: "sec-websocket-protocol")
}
/// Sec-WebSocket-Version
///
/// https://www.rfc-editor.org/rfc/rfc6455.html
@inlinable
public static var secWebSocketVersion: Self {
.init(rawName: "Sec-WebSocket-Version", canonicalName: "sec-websocket-version")
}
/// Server
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var server: Self { .init(rawName: "Server", canonicalName: "server") }
/// Set-Cookie
///
/// https://www.rfc-editor.org/rfc/rfc6265.html
@inlinable
public static var setCookie: Self { .init(rawName: "Set-Cookie", canonicalName: "set-cookie") }
/// Strict-Transport-Security
///
/// https://www.rfc-editor.org/rfc/rfc6797.html
@inlinable
public static var strictTransportSecurity: Self {
.init(rawName: "Strict-Transport-Security", canonicalName: "strict-transport-security")
}
/// TE
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var te: Self { .init(rawName: "TE", canonicalName: "te") }
/// Traceparent
///
/// https://www.w3.org/TR/trace-context/
@available(HTTPTypes 1.6, *)
@inlinable
public static var traceparent: Self { .init(rawName: "Traceparent", canonicalName: "traceparent") }
/// Tracestate
///
/// https://www.w3.org/TR/trace-context/
@available(HTTPTypes 1.6, *)
@inlinable
public static var tracestate: Self { .init(rawName: "Tracestate", canonicalName: "tracestate") }
/// Trailer
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var trailer: Self { .init(rawName: "Trailer", canonicalName: "trailer") }
/// Transfer-Encoding
///
/// https://www.rfc-editor.org/rfc/rfc9112.html
@inlinable
public static var transferEncoding: Self { .init(rawName: "Transfer-Encoding", canonicalName: "transfer-encoding") }
/// Upgrade
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var upgrade: Self { .init(rawName: "Upgrade", canonicalName: "upgrade") }
/// Use-As-Dictionary
///
/// https://www.rfc-editor.org/rfc/rfc9842.html
@available(HTTPTypes 1.6, *)
@inlinable
public static var useAsDictionary: Self { .init(rawName: "Use-As-Dictionary", canonicalName: "use-as-dictionary") }
/// User-Agent
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var userAgent: Self { .init(rawName: "User-Agent", canonicalName: "user-agent") }
/// Vary
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var vary: Self { .init(rawName: "Vary", canonicalName: "vary") }
/// Via
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var via: Self { .init(rawName: "Via", canonicalName: "via") }
/// WWW-Authenticate
///
/// https://www.rfc-editor.org/rfc/rfc9110.html
@inlinable
public static var wwwAuthenticate: Self { .init(rawName: "WWW-Authenticate", canonicalName: "www-authenticate") }
/// X-Content-Type-Options
///
/// https://fetch.spec.whatwg.org/
@inlinable
public static var xContentTypeOptions: Self {
.init(rawName: "X-Content-Type-Options", canonicalName: "x-content-type-options")
}
}