Make RequestContext a concrete type instead of protocol

Author: gjcairo

Sources/Example/Example.swift

@@ -23,7 +23,6 @@ struct Example {
         // Using the new extension method that doesn't require type hints
         let privateKey = P256.Signing.PrivateKey()
         let server = NIOHTTPServer<HTTPServerClosureRequestHandler<
-            HTTPServerRequestContext,
             HTTPRequestConcludingAsyncReader,
             HTTPRequestConcludingAsyncReader.Underlying,
             HTTPResponseConcludingAsyncWriter,
@@ -63,7 +62,6 @@ struct Example {
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 extension NIOHTTPServer
 where RequestHandler == HTTPServerClosureRequestHandler<
-    HTTPServerRequestContext,
     HTTPRequestConcludingAsyncReader,
     HTTPRequestConcludingAsyncReader.Underlying,
     HTTPResponseConcludingAsyncWriter,
@@ -75,7 +73,6 @@ where RequestHandler == HTTPServerClosureRequestHandler<
         @MiddlewareChainBuilder
         withMiddleware middlewareBuilder: () -> some Middleware<
             RequestResponseMiddlewareBox<
-                HTTPServerRequestContext,
                 HTTPRequestConcludingAsyncReader,
                 HTTPResponseConcludingAsyncWriter
             >,

Sources/Example/Middlewares/HTTPRequestLoggingMiddleware.swift

@@ -5,7 +5,6 @@ import Middleware
 
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 struct HTTPRequestLoggingMiddleware<
-    RequestContext: HTTPRequestContext,
     RequestConcludingAsyncReader: ConcludingAsyncReader & ~Copyable,
     ResponseConcludingAsyncWriter: ConcludingAsyncWriter & ~Copyable
 >: Middleware
@@ -15,9 +14,8 @@ where
     ResponseConcludingAsyncWriter.Underlying.WriteElement == Span<UInt8>,
     ResponseConcludingAsyncWriter.FinalElement == HTTPFields?
 {
-    typealias Input = RequestResponseMiddlewareBox<RequestContext, RequestConcludingAsyncReader, ResponseConcludingAsyncWriter>
+    typealias Input = RequestResponseMiddlewareBox<RequestConcludingAsyncReader, ResponseConcludingAsyncWriter>
     typealias NextInput = RequestResponseMiddlewareBox<
-        RequestContext,
         HTTPRequestLoggingConcludingAsyncReader<RequestConcludingAsyncReader>,
         HTTPResponseLoggingConcludingAsyncWriter<ResponseConcludingAsyncWriter>
     >

Sources/Example/Middlewares/RouteHandlerMiddleware.swift

@@ -4,7 +4,6 @@ import Middleware
 
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 struct RouteHandlerMiddleware<
-    RequestContext: HTTPRequestContext,
     RequestConcludingAsyncReader: ConcludingAsyncReader & ~Copyable,
     ResponseConcludingAsyncWriter: ConcludingAsyncWriter & ~Copyable,
 >: Middleware, Sendable
@@ -14,7 +13,7 @@ where
     ResponseConcludingAsyncWriter.Underlying: AsyncWriter<Span<UInt8>, any Error>,
     ResponseConcludingAsyncWriter.FinalElement == HTTPFields?
 {
-    typealias Input = RequestResponseMiddlewareBox<RequestContext, RequestConcludingAsyncReader, ResponseConcludingAsyncWriter>
+    typealias Input = RequestResponseMiddlewareBox<RequestConcludingAsyncReader, ResponseConcludingAsyncWriter>
     typealias NextInput = Never
 
     func intercept(

Sources/HTTPServer/HTTPRequestContext.swift

@@ -1,16 +1,37 @@
-/// A protocol that defines the context for an HTTP request.
+/// A context object that carries additional information about an HTTP request.
 ///
-/// Conforming types represent contextual information that can be associated with
-/// an HTTP request throughout its lifecycle.
-public protocol HTTPRequestContext: Sendable {
+/// `HTTPRequestContext` provides a way to pass metadata and implementation-specific
+/// information through the HTTP request pipeline. This is particularly useful when
+/// you need to attach custom data that should be available throughout the request's
+/// lifecycle.
+///
+/// ## Implementation-Specific Data
+///
+/// Different server implementations can store their own specific data by conforming to the
+/// ``ImplementationSpecific`` protocol:
+///
+/// ```swift
+/// struct MyCustomContext: HTTPRequestContext.ImplementationSpecific {
+///     let requestID: UUID
+///     let startTime: Date
+/// }
+///
+/// var context = HTTPRequestContext()
+/// context.implementationSpecific = MyCustomContext(
+///     requestID: UUID(),
+///     startTime: Date()
+/// )
+/// ```
+public struct HTTPRequestContext: Sendable {
 
-}
+    /// Conform your custom types to this protocol to store implementation-specific
+    /// data within an ``HTTPRequestContext``.
+    public protocol ImplementationSpecific: Sendable {}
 
-/// The default implementation of an ``HTTPRequestContext`` for HTTP server requests.
-///
-/// This struct provides a concrete type for representing the context of HTTP requests
-/// handled by a server.
-public struct HTTPServerRequestContext: HTTPRequestContext {
-    /// Creates a new HTTP server request context.
-    public init() {}
+    /// Optional implementation-specific data associated with this request context.
+    ///
+    /// Use this property to store custom data that is specific to your HTTP
+    /// implementation. The stored value can be any type that conforms to
+    /// ``ImplementationSpecific``.
+    public var implementationSpecific: (any ImplementationSpecific)?
 }

Sources/HTTPServer/HTTPServerClosureRequestHandler.swift

@@ -25,7 +25,6 @@ public import HTTPTypes
 /// ```
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 public struct HTTPServerClosureRequestHandler<
-    RequestContext: HTTPRequestContext,
     ConcludingRequestReader: ConcludingAsyncReader<RequestReader, HTTPFields?> & ~Copyable,
     RequestReader: AsyncReader<Span<UInt8>, any Error> & ~Copyable,
     ConcludingResponseWriter: ConcludingAsyncWriter<RequestWriter, HTTPFields?> & ~Copyable,
@@ -35,7 +34,7 @@ public struct HTTPServerClosureRequestHandler<
     private let _handler:
         nonisolated(nonsending) @Sendable (
             HTTPRequest,
-            RequestContext,
+            HTTPRequestContext,
             consuming ConcludingRequestReader,
             consuming HTTPResponseSender<ConcludingResponseWriter>
         ) async throws -> Void
@@ -47,7 +46,7 @@ public struct HTTPServerClosureRequestHandler<
     public init(
         handler: nonisolated(nonsending) @Sendable @escaping (
             HTTPRequest,
-            RequestContext,
+            HTTPRequestContext,
             consuming ConcludingRequestReader,
             consuming HTTPResponseSender<ConcludingResponseWriter>
         ) async throws -> Void
@@ -61,12 +60,12 @@ public struct HTTPServerClosureRequestHandler<
     ///
     /// - Parameters:
     ///   - request: The HTTP request headers and metadata.
-    ///   - requestContext: The request's context.
+    ///   - requestContext: A ``HTTPRequestContext``.
     ///   - requestBodyAndTrailers: A reader for accessing the request body data and trailing headers.
     ///   - responseSender: An ``HTTPResponseSender`` to send the HTTP response.
     public func handle(
         request: HTTPRequest,
-        requestContext: RequestContext,
+        requestContext: HTTPRequestContext,
         requestBodyAndTrailers: consuming ConcludingRequestReader,
         responseSender: consuming HTTPResponseSender<ConcludingResponseWriter>
     ) async throws {

Sources/HTTPServer/HTTPServerProtocol.swift

@@ -45,7 +45,6 @@ public protocol HTTPServerProtocol: Sendable, ~Copyable, ~Escapable {
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 extension HTTPServerProtocol
 where RequestHandler == HTTPServerClosureRequestHandler<
-    HTTPServerRequestContext,
     HTTPRequestConcludingAsyncReader,
     HTTPRequestConcludingAsyncReader.Underlying,
     HTTPResponseConcludingAsyncWriter,
@@ -77,7 +76,7 @@ where RequestHandler == HTTPServerClosureRequestHandler<
     public func serve(
         handler: @Sendable @escaping (
             _ request: HTTPRequest,
-            _ requestContext: HTTPServerRequestContext,
+            _ requestContext: HTTPRequestContext,
             _ requestBodyAndTrailers: consuming HTTPRequestConcludingAsyncReader,
             _ responseSender: consuming HTTPResponseSender<HTTPResponseConcludingAsyncWriter>
         ) async throws -> Void

Sources/HTTPServer/HTTPServerRequestHandler.swift

@@ -75,8 +75,6 @@ public protocol HTTPServerRequestHandler: Sendable {
     /// be `Span<UInt8>`.
     associatedtype RequestWriter: AsyncWriter<Span<UInt8>, any Error> & ~Copyable
 
-    associatedtype RequestContext: HTTPRequestContext
-
     /// Handles an incoming HTTP request and generates a response.
     ///
     /// This method is called by the HTTP server for each incoming client request. Implementations should:
@@ -89,6 +87,7 @@ public protocol HTTPServerRequestHandler: Sendable {
     ///
     /// - Parameters:
     ///   - request: The HTTP request headers and metadata.
+    ///   - requestContext: A ``HTTPRequestContext``.
     ///   - requestBodyAndTrailers: A reader for accessing the request body data and trailing headers.
     ///     This follows the `ConcludingAsyncReader` pattern, allowing for incremental reading of request body data
     ///     and concluding with any trailer fields sent at the end of the request.
@@ -98,7 +97,7 @@ public protocol HTTPServerRequestHandler: Sendable {
     /// - Throws: Any error encountered during request processing or response generation.
     func handle(
         request: HTTPRequest,
-        requestContext: RequestContext,
+        requestContext: HTTPRequestContext,
         requestBodyAndTrailers: consuming ConcludingRequestReader,
         responseSender: consuming HTTPResponseSender<ConcludingResponseWriter>
     ) async throws

Sources/HTTPServer/NIOHTTPServer.swift

@@ -64,8 +64,7 @@ import Synchronization
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 public struct NIOHTTPServer<RequestHandler: HTTPServerRequestHandler>: HTTPServerProtocol
 where RequestHandler.ConcludingRequestReader == HTTPRequestConcludingAsyncReader,
-        RequestHandler.ConcludingResponseWriter == HTTPResponseConcludingAsyncWriter,
-      RequestHandler.RequestContext == HTTPServerRequestContext {
+        RequestHandler.ConcludingResponseWriter == HTTPResponseConcludingAsyncWriter {
     private let logger: Logger
     private let configuration: HTTPServerConfiguration
 
@@ -425,7 +424,7 @@ where RequestHandler.ConcludingRequestReader == HTTPRequestConcludingAsyncReader
                     do {
                         try await handler.handle(
                             request: httpRequest,
-                            requestContext: HTTPServerRequestContext(),
+                            requestContext: HTTPRequestContext(),
                             requestBodyAndTrailers: HTTPRequestConcludingAsyncReader(
                                 iterator: iterator,
                                 readerState: readerState

Sources/HTTPServer/RequestResponseMiddlewareBox.swift

@@ -4,12 +4,11 @@ public import HTTPTypes
 /// It is necessary to box them together so that they can be used with `Middlewares`, as this will be the `Middleware.Input`.
 @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
 public struct RequestResponseMiddlewareBox<
-    RequestContext: HTTPRequestContext,
     RequestReader: ConcludingAsyncReader & ~Copyable,
     ResponseWriter: ConcludingAsyncWriter & ~Copyable
 >: ~Copyable {
     private let request: HTTPRequest
-    private let requestContext: RequestContext
+    private let requestContext: HTTPRequestContext
     private let requestReader: RequestReader
     private let responseSender: HTTPResponseSender<ResponseWriter>
 
@@ -20,7 +19,7 @@ public struct RequestResponseMiddlewareBox<
     ///   - responseSender: The ``HTTPResponseSender``.
     public init(
         request: HTTPRequest,
-        requestContext: RequestContext,
+        requestContext: HTTPRequestContext,
         requestReader: consuming RequestReader,
         responseSender: consuming HTTPResponseSender<ResponseWriter>
     ) {
@@ -36,7 +35,7 @@ public struct RequestResponseMiddlewareBox<
     public consuming func withContents<T>(
         _ handler: nonisolated(nonsending) (
             HTTPRequest,
-            RequestContext,
+            HTTPRequestContext,
             consuming RequestReader,
             consuming HTTPResponseSender<ResponseWriter>
         ) async throws -> T