Skip to content

Commit dd87cdf

Browse files
gjcairogjcairo
committed
Fix docs
1 parent 6448d6f commit dd87cdf

File tree

4 files changed

+55
-54
lines changed

4 files changed

+55
-54
lines changed

‎Sources/HTTPServer/HTTPResponseSender.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ public import HTTPTypes
33
/// This type ensures that a single non-informational (1xx) `HTTPResponse` is sent back to the client when handling a request.
44
///
55
/// The user will get a ``HTTPResponseSender`` as part of
6-
/// ``HTTPServerRequestHandler/handle(request:requestBodyAndTrailers:responseSender:)``, and they
6+
/// ``HTTPServerRequestHandler/handle(request:requestContext:requestBodyAndTrailers:responseSender:)``, and they
77
/// will only be allowed to call ``send(_:)`` once before the sender is consumed and cannot be referenced again.
88
/// ``sendInformational(_:)`` may be called zero or more times.
99
///

‎Sources/HTTPServer/HTTPServerClosureRequestHandler.swift‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ public import HTTPTypes
88
///
99
/// - Example:
1010
/// ```swift
11-
/// let echoHandler = HTTPServerClosureRequestHandler { request, bodyReader, sendResponse in
11+
/// let echoHandler = HTTPServerClosureRequestHandler { request, context, bodyReader, responseSender in
1212
/// // Read the entire request body
1313
/// let (bodyData, _) = try await bodyReader.consumeAndConclude { reader in
1414
/// // ... body reading code ...
1515
/// }
1616
///
1717
/// // Create and send response
1818
/// var response = HTTPResponse(status: .ok)
19-
/// let responseWriter = try await sendResponse(response)
19+
/// let responseWriter = try await responseSender.send(response)
2020
/// try await responseWriter.produceAndConclude { writer in
2121
/// try await writer.write(bodyData.span)
2222
/// return ((), nil)
@@ -72,3 +72,46 @@ public struct HTTPServerClosureRequestHandler<
7272
try await self._handler(request, requestContext, requestBodyAndTrailers, responseSender)
7373
}
7474
}
75+
76+
@available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
77+
extension HTTPServerProtocol where RequestHandler == HTTPServerClosureRequestHandler<
78+
HTTPRequestConcludingAsyncReader,
79+
HTTPRequestConcludingAsyncReader.Underlying,
80+
HTTPResponseConcludingAsyncWriter,
81+
HTTPResponseConcludingAsyncWriter.Underlying
82+
> {
83+
/// Starts an HTTP server with a closure-based request handler.
84+
///
85+
/// This method provides a convenient way to start an HTTP server using a closure to handle incoming requests.
86+
///
87+
/// - Parameters:
88+
/// - handler: An async closure that processes HTTP requests. The closure receives:
89+
/// - `HTTPRequest`: The incoming HTTP request with headers and metadata.
90+
/// - ``HTTPRequestContext``: The request's context.
91+
/// - ``HTTPRequestConcludingAsyncReader``: An async reader for consuming the request body and trailers.
92+
/// - ``HTTPResponseSender``: A non-copyable wrapper for a function that accepts an `HTTPResponse` and provides access to an ``HTTPResponseConcludingAsyncWriter``.
93+
///
94+
/// ## Example
95+
///
96+
/// ```swift
97+
/// try await server.serve { request, bodyReader, responseSender in
98+
/// // Process the request
99+
/// let response = HTTPResponse(status: .ok)
100+
/// let writer = try await responseSender.send(response)
101+
/// try await writer.produceAndConclude { writer in
102+
/// try await writer.write("Hello, World!".utf8)
103+
/// return ((), nil)
104+
/// }
105+
/// }
106+
/// ```
107+
public func serve(
108+
handler: @Sendable @escaping (
109+
_ request: HTTPRequest,
110+
_ requestContext: HTTPRequestContext,
111+
_ requestBodyAndTrailers: consuming HTTPRequestConcludingAsyncReader,
112+
_ responseSender: consuming HTTPResponseSender<HTTPResponseConcludingAsyncWriter>
113+
) async throws -> Void
114+
) async throws {
115+
try await self.serve(handler: HTTPServerClosureRequestHandler(handler: handler))
116+
}
117+
}

‎Sources/HTTPServer/HTTPServerProtocol.swift‎

Lines changed: 2 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ public import HTTPTypes
33
@available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
44
/// A generic HTTP server protocol that can handle incoming HTTP requests.
55
public protocol HTTPServerProtocol: Sendable, ~Copyable, ~Escapable {
6-
// TODO: write down in the proposal why we can't make the serve method generic over the handler (closure-based APIs can't
7-
// be implemented)
6+
// TODO: write down in the proposal we can't make the serve method generic over the handler
7+
// because otherwise, closure-based APIs can't be implemented.
88

99
/// The ``HTTPServerRequestHandler`` to use when handling requests.
1010
associatedtype RequestHandler: HTTPServerRequestHandler
@@ -41,46 +41,3 @@ public protocol HTTPServerProtocol: Sendable, ~Copyable, ~Escapable {
4141
/// ```
4242
func serve(handler: RequestHandler) async throws
4343
}
44-
45-
@available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
46-
extension HTTPServerProtocol
47-
where RequestHandler == HTTPServerClosureRequestHandler<
48-
HTTPRequestConcludingAsyncReader,
49-
HTTPRequestConcludingAsyncReader.Underlying,
50-
HTTPResponseConcludingAsyncWriter,
51-
HTTPResponseConcludingAsyncWriter.Underlying
52-
> {
53-
/// Starts an HTTP server with a closure-based request handler.
54-
///
55-
/// This method provides a convenient way to start an HTTP server using a closure to handle incoming requests.
56-
///
57-
/// - Parameters:
58-
/// - handler: An async closure that processes HTTP requests. The closure receives:
59-
/// - `HTTPRequest`: The incoming HTTP request with headers and metadata
60-
/// - ``HTTPRequestConcludingAsyncReader``: An async reader for consuming the request body and trailers
61-
/// - ``HTTPResponseSender``: A non-copyable wrapper for a function that accepts an `HTTPResponse` and provides access to an ``HTTPResponseConcludingAsyncWriter``
62-
///
63-
/// ## Example
64-
///
65-
/// ```swift
66-
/// try await server.serve { request, bodyReader, sendResponse in
67-
/// // Process the request
68-
/// let response = HTTPResponse(status: .ok)
69-
/// let writer = try await sendResponse(response)
70-
/// try await writer.produceAndConclude { writer in
71-
/// try await writer.write("Hello, World!".utf8)
72-
/// return ((), nil)
73-
/// }
74-
/// }
75-
/// ```
76-
public func serve(
77-
handler: @Sendable @escaping (
78-
_ request: HTTPRequest,
79-
_ requestContext: HTTPRequestContext,
80-
_ requestBodyAndTrailers: consuming HTTPRequestConcludingAsyncReader,
81-
_ responseSender: consuming HTTPResponseSender<HTTPResponseConcludingAsyncWriter>
82-
) async throws -> Void
83-
) async throws {
84-
try await self.serve(handler: HTTPServerClosureRequestHandler(handler: handler))
85-
}
86-
}

‎Sources/HTTPServer/HTTPServerRequestHandler.swift‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@ public import HTTPTypes
1616
///
1717
/// ```swift
1818
/// struct EchoHandler: HTTPServerRequestHandler {
19-
/// func handle(
19+
/// func handle(
2020
/// request: HTTPRequest,
21-
/// requestBodyAndTrailers: consuming HTTPRequestConcludingAsyncReader,
22-
/// responseSender: consuming HTTPResponseSender<HTTPResponseConcludingAsyncWriter>
23-
/// ) async throws {
21+
/// requestContext: HTTPRequestContext,
22+
/// requestConcludingAsyncReader: consuming sending HTTPRequestConcludingAsyncReader,
23+
/// responseSender: consuming sending HTTPResponseSender<HTTPResponseConcludingAsyncWriter>
24+
/// ) async throws {
2425
/// // Read the entire request body
2526
/// let (bodyData, trailers) = try await requestConcludingAsyncReader.consumeAndConclude { reader in
2627
/// var reader = reader
@@ -81,8 +82,8 @@ public protocol HTTPServerRequestHandler: Sendable {
8182
/// 1. Examine the request headers in the `request` parameter
8283
/// 2. Read the request body data from the ``RequestConcludingAsyncReader`` as needed
8384
/// 3. Process the request and prepare a response
84-
/// 4. Optionally call ``HTTPResponseSender/sendInformationalResponse(_:)`` as needed
85-
/// 4. Call the ``HTTPResponseSender/sendResponse(_:)`` with an appropriate HTTP response
85+
/// 4. Optionally call ``HTTPResponseSender/sendInformational(_:)`` as needed
86+
/// 4. Call the ``HTTPResponseSender/send(_:)`` with an appropriate HTTP response
8687
/// 5. Write the response body data to the returned ``HTTPResponseConcludingAsyncWriter``
8788
///
8889
/// - Parameters:

0 commit comments

Comments
 (0)