Add QuerySpaceNormalizingMiddleware.

Add an opt-in ServerMiddleware that rewrites unencoded "+"
characters in the request's query string to "%20" before the
request reaches the decoder. This lets servers interoperate
with clients that encode query parameter spaces using the
application/x-www-form-urlencoded convention (as used by
Python requests, Java URLEncoder, Scala sttp, and JavaScript
URLSearchParams) without changing the default RFC 3986
behavior of the generated server code.

Only the query of the request is modified; the path, fragment,
and body are untouched. Literal "+" characters that were
correctly percent-encoded as "%2B" by the client are unaffected.
A malformed input where "?" appears inside the fragment (e.g.
"/a#b?c+d") is left untouched rather than crashing.

The rewrite builds the new path with reserveCapacity and
character-by-character append to avoid the intermediate string
allocations of replacingOccurrences and concatenation.

Also add an "Additional middlewares" section to the DocC
documentation that lists ErrorHandlingMiddleware alongside the
new middleware, so built-in middlewares are discoverable from
the top-level docs. Move HTTPResponseConvertible into the
existing "Errors" section, where it belongs.

Author: Ryan Branche

Sources/OpenAPIRuntime/Documentation.docc/Documentation.md

@@ -78,6 +78,7 @@ You can also publish your transport or middleware as a Swift package to allow ot
 - ``ClientError``
 - ``ServerError``
 - ``UndocumentedPayload``
+- ``HTTPResponseConvertible``
 
 ### HTTP Currency Types
 - ``HTTPBody``
@@ -91,5 +92,9 @@ You can also publish your transport or middleware as a Swift package to allow ot
 - ``OpenAPIObjectContainer``
 - ``OpenAPIArrayContainer``
 
+### Additional middlewares
+- ``ErrorHandlingMiddleware``
+- ``QuerySpaceNormalizingMiddleware``
+
 [0]: https://github.com/apple/swift-openapi-generator
 [1]: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation

Sources/OpenAPIRuntime/Interface/QuerySpaceNormalizingMiddleware.swift

@@ -0,0 +1,85 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2026 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+public import HTTPTypes
+
+/// An opt-in middleware that normalizes `+`-encoded spaces in the request's
+/// query string to `%20`, so that requests from clients that use
+/// `application/x-www-form-urlencoded` conventions decode correctly.
+///
+/// The OpenAPI specification follows RFC 3986, which requires spaces in query
+/// strings to be percent-encoded as `%20`. However, many widely-used HTTP
+/// client libraries — including Python's `requests`, Java's `URLEncoder`,
+/// Scala's `sttp`, and JavaScript's `URLSearchParams` — encode spaces as `+`,
+/// following the `application/x-www-form-urlencoded` convention. Without this
+/// middleware, query parameters sent from such clients arrive at handlers with
+/// literal `+` characters instead of spaces.
+///
+/// This middleware rewrites `+` to `%20` in the query portion of the request
+/// path before the request is parsed, so both encoding conventions produce the
+/// same decoded value. A literal `+` in the original input should already be
+/// sent as `%2B` by any client; such values are unaffected because this
+/// middleware only rewrites unencoded `+` characters.
+///
+/// ## Example usage
+///
+/// ```swift
+/// let handler = RequestHandler()
+/// try handler.registerHandlers(on: transport, middlewares: [QuerySpaceNormalizingMiddleware()])
+/// ```
+///
+/// - Note: Only the query of the request is modified. The path, fragment, and
+///   body are not touched.
+public struct QuerySpaceNormalizingMiddleware: ServerMiddleware {
+    /// Creates a new middleware.
+    public init() {}
+
+    // swift-format-ignore: AllPublicDeclarationsHaveDocumentation
+    public func intercept(
+        _ request: HTTPTypes.HTTPRequest,
+        body: OpenAPIRuntime.HTTPBody?,
+        metadata: OpenAPIRuntime.ServerRequestMetadata,
+        operationID: String,
+        next:
+            @Sendable (HTTPTypes.HTTPRequest, OpenAPIRuntime.HTTPBody?, OpenAPIRuntime.ServerRequestMetadata)
+            async throws -> (HTTPTypes.HTTPResponse, OpenAPIRuntime.HTTPBody?)
+    ) async throws -> (HTTPTypes.HTTPResponse, OpenAPIRuntime.HTTPBody?) {
+        var request = request
+        if let path = request.path {
+            let fragmentStart = path.firstIndex(of: "#") ?? path.endIndex
+            let pathAndQuery = path[..<fragmentStart]
+            if let queryStart = pathAndQuery.firstIndex(of: "?") {
+                let queryContentStart = path.index(after: queryStart)
+                let query = path[queryContentStart..<fragmentStart]
+                if query.contains("+") {
+                    // Each "+" expands to 3 bytes ("%20"), so the worst-case
+                    // length is path.count + 2 * query.count.
+                    var newPath = ""
+                    newPath.reserveCapacity(path.count + 2 * query.count)
+                    newPath.append(contentsOf: path[..<queryContentStart])
+                    for character in query {
+                        if character == "+" {
+                            newPath.append("%20")
+                        } else {
+                            newPath.append(character)
+                        }
+                    }
+                    newPath.append(contentsOf: path[fragmentStart...])
+                    request.path = newPath
+                }
+            }
+        }
+        return try await next(request, body, metadata)
+    }
+}

Tests/OpenAPIRuntimeTests/Interface/Test_QuerySpaceNormalizingMiddleware.swift

@@ -0,0 +1,102 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2026 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import HTTPTypes
+
+import XCTest
+@_spi(Generated) @testable import OpenAPIRuntime
+
+final class Test_QuerySpaceNormalizingMiddleware: XCTestCase {
+    static let middleware = QuerySpaceNormalizingMiddleware()
+
+    func testPlusInQueryIsReplacedWithPercent20() async throws {
+        try await assertNormalizedPath(input: "/search?q=hello+world", expected: "/search?q=hello%20world")
+    }
+
+    func testMultiplePlusesAreReplaced() async throws {
+        try await assertNormalizedPath(
+            input: "/search?a=one+two&b=three+four+five",
+            expected: "/search?a=one%20two&b=three%20four%20five"
+        )
+    }
+
+    func testPercent20InQueryIsUntouched() async throws {
+        try await assertNormalizedPath(input: "/search?q=hello%20world", expected: "/search?q=hello%20world")
+    }
+
+    func testLiteralPlusEncodedAsPercent2BIsUntouched() async throws {
+        try await assertNormalizedPath(input: "/search?q=hello%2Bworld", expected: "/search?q=hello%2Bworld")
+    }
+
+    func testPlusInPathIsNotReplaced() async throws {
+        try await assertNormalizedPath(input: "/a+b/c+d?q=e+f", expected: "/a+b/c+d?q=e%20f")
+    }
+
+    func testPlusInFragmentIsNotReplaced() async throws {
+        try await assertNormalizedPath(input: "/search?q=a+b#c+d", expected: "/search?q=a%20b#c+d")
+    }
+
+    func testQuestionMarkInsideFragmentDoesNotCrash() async throws {
+        try await assertNormalizedPath(input: "/a#b?c+d", expected: "/a#b?c+d")
+    }
+
+    func testQueryBeforeFragmentContainingQuestionMark() async throws {
+        try await assertNormalizedPath(input: "/a?b+c#d?e+f", expected: "/a?b%20c#d?e+f")
+    }
+
+    func testPathWithoutQueryIsUntouched() async throws {
+        try await assertNormalizedPath(input: "/search", expected: "/search")
+    }
+
+    func testQueryWithoutPlusIsUntouched() async throws {
+        try await assertNormalizedPath(input: "/search?q=hello", expected: "/search?q=hello")
+    }
+
+    func testEmptyQueryIsUntouched() async throws {
+        try await assertNormalizedPath(input: "/search?", expected: "/search?")
+    }
+
+    func testResponseIsForwardedUnchanged() async throws {
+        let request = HTTPRequest(soar_path: "/search?q=hello+world", method: .get)
+        let (response, responseBody) = try await Test_QuerySpaceNormalizingMiddleware.middleware.intercept(
+            request,
+            body: nil,
+            metadata: .init(),
+            operationID: "testop",
+            next: { _, _, _ in (HTTPResponse(status: .accepted), HTTPBody("ok")) }
+        )
+        XCTAssertEqual(response.status, .accepted)
+        let bodyBytes = try await String(collecting: responseBody!, upTo: .max)
+        XCTAssertEqual(bodyBytes, "ok")
+    }
+
+    private func assertNormalizedPath(
+        input: String,
+        expected: String,
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) async throws {
+        let request = HTTPRequest(soar_path: input, method: .get)
+        _ = try await Test_QuerySpaceNormalizingMiddleware.middleware.intercept(
+            request,
+            body: nil,
+            metadata: .init(),
+            operationID: "testop",
+            next: { forwarded, _, _ in
+                XCTAssertEqual(forwarded.path, expected, file: file, line: line)
+                return (HTTPResponse(status: .ok), nil)
+            }
+        )
+    }
+}