Add request context capability mechanism to HTTPServer by ehaydenr · Pull Request #166 · apple/swift-http-api-proposal

ehaydenr · 2026-05-19T20:33:20Z

Introduce HTTPServerCapability namespace with a base RequestContext protocol, mirroring the client-side HTTPClientCapability.RequestOptions pattern. Servers declare a RequestContext associated type that handlers can constrain to require specific capabilities (e.g. connection info, peer certificates) at compile time.

Motivation

Clean up the client/server asymmetry. Afford the server APIs the same generic mechanism for requiring server capabilities.

Modifications

Added HTTPServerCapability.RequestContext protocol.

Result

Middleware and request handlers can now require server capabilities

Test Plan

Added a basic unit test to demonstrate the pattern.

Introduce HTTPServerCapability namespace with a base RequestContext protocol, mirroring the client-side HTTPClientCapability.RequestOptions pattern. Servers declare a RequestContext associated type that handlers can constrain to require specific capabilities (e.g. connection info, peer certificates) at compile time.

guoye-zhang · 2026-05-21T01:35:00Z

-public protocol HTTPServerRequestHandler<RequestReader, ResponseWriter>: Sendable {
+public protocol HTTPServerRequestHandler<RequestContext, RequestReader, ResponseWriter>: Sendable {
+    /// The type of the request context provided by the server.
+    associatedtype RequestContext: HTTPServerCapability.RequestContext


You'll need to redeclare ~Copyable, ~Escapable requirements here

guoye-zhang · 2026-05-21T01:43:06Z

 /// ```
 @available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
 public struct HTTPServerClosureRequestHandler<
+    RequestContext: HTTPServerCapability.RequestContext,


& ~Copyable & ~Escapable

guoye-zhang · 2026-05-21T01:43:34Z

-public struct HTTPRequestContext: Sendable {
+/// The default request context for HTTP server implementations.
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
+public struct HTTPRequestContext: HTTPServerCapability.RequestContext {


This type should be moved to swift-http-server?

Moved to HTTPServerForTesting

There's a PR for depending on the NIOHTTPServer as a submodule.
Before that lands, we'll have to make sure that we've also updated NIOHTTPServer to use this new API.

Yeah probably will land that PR when everything settles to reduce the pain of interlocked revisions

guoye-zhang · 2026-05-21T01:44:00Z

 /// incoming HTTP connections and process requests using a ``HTTPServerRequestHandler``.
-public protocol HTTPServer<RequestConcludingReader, ResponseConcludingWriter>: Sendable, ~Copyable, ~Escapable {
+public protocol HTTPServer<RequestContext, RequestConcludingReader, ResponseConcludingWriter>: Sendable, ~Copyable, ~Escapable {
+    associatedtype RequestContext: HTTPServerCapability.RequestContext


~Copyable, ~Escapable

- Add ~Copyable, ~Escapable constraints to RequestContext associated types in HTTPServer, HTTPServerRequestHandler, and HTTPServerClosureRequestHandler - Add consuming ownership to requestContext parameters - Move HTTPRequestContext concrete type out of HTTPAPIs into the test server module

# Conflicts: # Sources/HTTPAPIs/Server/HTTPServerRequestHandler.swift

guoye-zhang · 2026-05-22T16:02:28Z

 /// This middleware is useful for debugging and monitoring HTTP traffic.
 @available(anyAppleOS 26.0, *)
 public struct HTTPServerLoggingMiddleware<
+    RequestContext: HTTPServerCapability.RequestContext,


This also need ~Copyable & ~Escapable

guoye-zhang · 2026-05-22T16:03:04Z

    where
-        Input == HTTPServerMiddlewareInput<RequestReader, ResponseWriter>,
+        Input == HTTPServerMiddlewareInput<RequestContext, RequestReader, ResponseWriter>,
+        RequestContext: HTTPServerCapability.RequestContext,


This also need ~Copyable & ~Escapable

guoye-zhang · 2026-05-22T16:03:45Z

 /// convenient way to pass all request-handling components through the middleware chain.
 @available(anyAppleOS 26.0, *)
 public struct HTTPServerMiddlewareInput<
+    RequestContext: HTTPServerCapability.RequestContext,


This also need ~Copyable & ~Escapable

I think this would require HTTPServerMiddlewareInput be ~Escapable and it currently isn't. Also RequestReader/Writer aren't ~Escapable here. Should we make HTTPServerMiddlewareInput ~Escapable or only do ~Copyable here?

Yeah it makes sense to keep this Escapable

guoye-zhang · 2026-05-22T16:10:08Z

    func handle(
        request: HTTPRequest,
-        requestContext: HTTPRequestContext,
+        requestContext: consuming RequestContext,


Is consuming the right ownership model? Could the same Sendable & ~Copyable struct with a Mutex be passed to handle multiple times?

If it's non copyable, how would it be passed multiple times?

Ah I guess borrow wouldn't work since this is invoked concurrently

gjcairo · 2026-05-22T16:20:22Z

-public protocol HTTPServerRequestHandler<RequestReader, ResponseWriter>: Sendable {
+public protocol HTTPServerRequestHandler<RequestContext, RequestReader, ResponseWriter>: Sendable {
+    /// The type of the request context provided by the server.
+    associatedtype RequestContext: HTTPServerCapability.RequestContext, ~Copyable, ~Escapable


Do we want it to be ~Copyable? I really don't know, but I'm just wondering since it's basically a bag of things, I wonder if this requirement may make it hard to hold.

The server should be able to give out a Copyable type if it wants. I think it's really the middleware that might having difficulty holding it, but I can't think of a case where it would be an issue. I'm curious if you have any cases in mind.

gjcairo · 2026-05-22T16:22:54Z

+import HTTPAPIs
+import Testing
+
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)


Let's use anyAppleOS

gjcairo · 2026-05-22T16:24:11Z

 /// It is necessary to box them together so that they can be used with `Middlewares`, as this will be the `Middleware.Input`.
 @available(anyAppleOS 26.0, *)
 public struct RequestResponseMiddlewareBox<
+    RequestContext: HTTPServerCapability.RequestContext,


If we keep the ~Copyable requirement on the protocol, we should add it here too (and make it consuming below).

gjcairo · 2026-05-22T16:25:00Z

+//===----------------------------------------------------------------------===//
+
+/// The namespace for all protocols defining HTTP server capabilities.
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)


Let's use anyAppleOS

gjcairo · 2026-05-22T16:25:40Z

+//
+//===----------------------------------------------------------------------===//
+
+/// The namespace for all protocols defining HTTP server capabilities.


Can we add more docs explaining what a capability is?

gjcairo · 2026-05-22T16:26:25Z

+    /// The request context protocol.
+    ///
+    /// Child protocols define additional context that a subset of servers provide,
+    /// allowing libraries to depend on specific capabilities.


And we could maybe improve this a bit to add an example of how to implement this and how/where it will be used (i.e. middleware, request handlers, etc)?

gjcairo · 2026-05-22T16:30:17Z

+
+@Suite("Server Capability Tests")
+struct ServerCapabilityTests {
+    @Test("ConnectionInfo capability constraint compiles and context is accessible")


We're not actually asserting anything anywhere right? Like we aren't actually checking that the context contains the stuff we've filled it with from within the handler.

Correct, right now it's really just testing that it compiles. I'll add some assertions too

updated this

…ovements - Add ~Copyable to RequestContext constraints in middleware examples and RequestResponseMiddlewareBox - Add consuming ownership to requestContext parameters in middleware input types - Drop ~Escapable from RequestContext constraints (inconsistent with reader/writer types which are not ~Escapable) - Use anyAppleOS availability on HTTPServerCapability and tests - Add comprehensive documentation and examples to HTTPServerCapability and RequestContext - Improve ServerCapabilityTests to assert context values flow through the handler via TestClientAndServer

guoye-zhang approved these changes May 21, 2026

View reviewed changes

guoye-zhang added the ⚠️ semver/major Breaks existing public API. label May 21, 2026

guoye-zhang reviewed May 21, 2026

View reviewed changes

ehaydenr added 2 commits May 21, 2026 03:05

Merge remote-tracking branch 'origin/main' into requestcontext

8d83a60

# Conflicts: # Sources/HTTPAPIs/Server/HTTPServerRequestHandler.swift

ehaydenr requested review from FranzBusch, gjcairo and guoye-zhang May 21, 2026 03:09

ehaydenr added 2 commits May 22, 2026 14:24

formatting

73c0e07

fix tests

f5744a1

guoye-zhang reviewed May 22, 2026

View reviewed changes

gjcairo requested changes May 22, 2026

View reviewed changes

ehaydenr requested review from gjcairo and guoye-zhang May 22, 2026 18:03

Conversation

ehaydenr commented May 19, 2026

Motivation

Modifications

Result

Test Plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants