Skip to content

Commit 82678a7

Browse files
czechboy0czechboy0
authored
[Proposal] SOAR-0005: Adopting the Swift HTTP Types package (#255)
### Motivation See the proposal at https://github.com/czechboy0/swift-openapi-generator/blob/hd-soar-0005/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md ### Modifications N/A ### Result N/A ### Test Plan N/A
1 parent c8b0008 commit 82678a7

File tree

2 files changed

+218
-0
lines changed

2 files changed

+218
-0
lines changed

‎Sources/swift-openapi-generator/Documentation.docc/Proposals/Proposals.md

+1
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,4 @@ If you have any questions, tag [Honza Dvorsky](https://github.com/czechboy0) or
4747
- <doc:SOAR-0002>
4848
- <doc:SOAR-0003>
4949
- <doc:SOAR-0004>
50+
- <doc:SOAR-0005>

‎Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md

+217
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# SOAR-0005: Adopting the Swift HTTP Types package
2+
3+
Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols.
4+
5+
## Overview
6+
7+
- Proposal: SOAR-0005
8+
- Author(s): [Honza Dvorsky](https://github.com/czechboy0)
9+
- Status: **Ready for Implementation**
10+
- Issue: [apple/swift-openapi-generator#101](https://github.com/apple/swift-openapi-generator/issues/101)
11+
- Implementation:
12+
- [apple/swift-openapi-generator#245](https://github.com/apple/swift-openapi-generator/pull/245)
13+
- [apple/swift-openapi-runtime#47](https://github.com/apple/swift-openapi-runtime/pull/47)
14+
- [apple/swift-openapi-urlsession#15](https://github.com/apple/swift-openapi-urlsession/pull/15)
15+
- [swift-server/swift-openapi-async-http-client#16](https://github.com/swift-server/swift-openapi-async-http-client/pull/16)
16+
- Feature flag: none, lands as a breaking change to main, gets released as 0.3.0
17+
- Affected components:
18+
- generator
19+
- runtime
20+
- client transports
21+
- server transports
22+
- Versions:
23+
- v1 (2023-09-08): Initial version
24+
- v1.1: In `ServerTransport` and `ServerMiddleware`, make the response `HTTPBody` optional to preserve the intent of the OpenAPI document author for the transport.
25+
- v1.2 (2023-09-13): Made response bodies optional.
26+
27+
### Introduction
28+
29+
Use the HTTP request and response types from the [Swift HTTP Types](https://github.com/apple/swift-http-types) package instead of maintaining our own currency types.
30+
31+
### Motivation
32+
33+
The purpose of the Swift OpenAPI Runtime library is to be an "API package", in the meaning established by earlier packages in the Swift ecosystem, such as swift-log. The API package contains generally useful abstractions, which adopters can implement their logic against, and plug in any concrete implementation provided by anyone else in the ecosystem.
34+
35+
Similarly in Swift OpenAPI Generator, the most important abstractions in the runtime library are the transport and middleware protocols. There are concrete implementations of client and server protocols maintained as separate packages, and an adopter can use any of those concrete implementations with the adopter's generated code. No need to regenerate any code when switching between different transport implementations.
36+
37+
```swift
38+
// Instantiate a concrete transport implementation.
39+
let transport: any ClientTransport = ... // any client transport
40+
41+
// Instantiate the generated client by providing it with the transport.
42+
let client = Client(transport: transport)
43+
44+
// Make API calls
45+
let response = try await client.getStats(...)
46+
...
47+
```
48+
49+
The definitions of the transport and middleware protocols currently use currency types provided by the runtime library, representing the HTTP request and response.
50+
51+
These types need to be maintained and them being specific to the runtime library makes _implementing_ a transport or middleware a little more work, as you need to write code that converts, for example, from `OpenAPIRuntime.Request` to `Foundation.URLRequest`.
52+
53+
A new package open sourced earlier in 2023 called [Swift HTTP Types](https://github.com/apple/swift-http-types) opens the door to unifying the HTTP request and response types across the Swift ecosystem. By adopting it, we can get following benefits:
54+
55+
1. No need to maintain `OpenAPIRuntime.Request`, `OpenAPIRuntime.Response`, and friends.
56+
2. Get improvements to Swift HTTP Types for free.
57+
3. Simplify implementing concrete transports and middlewares for libraries that also use Swift HTTP Types (as no manual conversion needed).
58+
59+
### Proposed solution
60+
61+
We propose to use the `HTTPRequest` and `HTTPResponse` types (and other types they refer to, such as `HTTPFields`) provided by Swift HTTP Types in the transport and middleware protocols, and delete the request, response, and related types from the runtime library.
62+
63+
> Note: The Swift HTTP Types library does _not_ contain a currency type that represents HTTP bodies, so we are pitching a new one as part of [SOAR-0004](https://github.com/czechboy0/swift-openapi-generator/blob/hd-soar-0004/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md) called `OpenAPIRuntime.HTTPBody`. These two proposals are related and below we assume the `HTTPBody` type is available to use.
64+
65+
### Detailed design
66+
67+
Let's compare each of the transport and middleware protocols as they are today to what they can be with Swift HTTP Types. Note that in the code snippets below, details not relevant to the proposal, such as code comments, are omitted.
68+
69+
> Tip: Check out the [source code](https://github.com/apple/swift-http-types) of Swift HTTP Types for more details on the functionality provided by the `HTTPRequest` and `HTTPResponse` types.
70+
71+
#### Client transport
72+
73+
The existing `ClientTransport` protocol:
74+
75+
```swift
76+
public protocol ClientTransport {
77+
func send(
78+
_ request: Request,
79+
baseURL: URL,
80+
operationID: String
81+
) async throws -> Response
82+
}
83+
```
84+
85+
The proposed `ClientTransport` protocol:
86+
87+
```swift
88+
public protocol ClientTransport {
89+
func send(
90+
_ request: HTTPRequest, // <<< changed
91+
body: HTTPBody?, // <<< added
92+
baseURL: URL,
93+
operationID: String
94+
) async throws -> (HTTPResponse, HTTPBody?) // <<< changed
95+
}
96+
```
97+
98+
Notable changes:
99+
- The request and response bodies are passed separately from the request and response metadata types.
100+
- The fully qualified type names used are:
101+
- `HTTPTypes.HTTPRequest`
102+
- `HTTPTypes.HTTPResponse`
103+
- `OpenAPIRuntime.HTTPBody`
104+
105+
#### Client middleware
106+
107+
The existing `ClientMiddleware` protocol:
108+
109+
```swift
110+
public protocol ClientMiddleware: Sendable {
111+
func intercept(
112+
_ request: Request,
113+
baseURL: URL,
114+
operationID: String,
115+
next: @Sendable (Request, URL) async throws -> Response
116+
) async throws -> Response
117+
}
118+
```
119+
120+
The proposed `ClientMiddleware` protocol:
121+
122+
```swift
123+
public protocol ClientMiddleware {
124+
func intercept(
125+
_ request: HTTPRequest, // <<< changed
126+
body: HTTPBody?, // <<< added
127+
baseURL: URL,
128+
operationID: String,
129+
next: @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) // <<< changed
130+
) async throws -> (HTTPResponse, HTTPBody?) // <<< changed
131+
}
132+
```
133+
134+
The changes are of the same nature as those to the client transport.
135+
136+
#### Server transport
137+
138+
The existing `ServerTransport` protocol:
139+
140+
```swift
141+
public protocol ServerTransport {
142+
func register(
143+
_ handler: @Sendable @escaping (Request, ServerRequestMetadata) async throws -> Response,
144+
method: HTTPMethod,
145+
path: [RouterPathComponent],
146+
queryItemNames: Set<String>
147+
) throws
148+
}
149+
```
150+
151+
The proposed `ServerTransport` protocol:
152+
153+
```swift
154+
public protocol ServerTransport {
155+
func register(
156+
_ handler: @Sendable @escaping (HTTPRequest, HTTPBody?, ServerRequestMetadata) async throws -> (HTTPResponse, HTTPBody?), // <<< changed
157+
method: HTTPRequest.Method, // <<< changed
158+
path: String // <<< changed
159+
) throws
160+
}
161+
```
162+
163+
Notable changes:
164+
- The `OpenAPIRuntime.ServerRequestMetadata` type removes its `queryParameters` property, as it's not needed as of version 0.2.0, where the query string is decoded directly, instead of receiving the key-value pairs from the transport. We held off the breaking change until 0.3.0, as 0.2.0 did not make breaking changes to the transport and middleware protocols.
165+
- The `path` parameter is now a string instead of an array of parsed components. The string is the templated URI, for example `/pets/{petId}`. This change was made to support [#199](https://github.com/apple/swift-openapi-generator/issues/199) path components that are parameters but also have a constant component, and it is up to the server transport implementation to parse the string and pull parameter names from it.
166+
- Just like client transport, the request and response bodies are passed separately from the request and response metadata types.
167+
- The fully qualified type names used are:
168+
- `HTTPTypes.HTTPRequest`
169+
- `HTTPTypes.HTTPResponse`
170+
- `OpenAPIRuntime.HTTPBody`
171+
172+
#### Server middleware
173+
174+
The existing `ServerMiddleware` protocol:
175+
176+
```swift
177+
public protocol ServerMiddleware: Sendable {
178+
func intercept(
179+
_ request: Request,
180+
metadata: ServerRequestMetadata,
181+
operationID: String,
182+
next: @Sendable (Request, ServerRequestMetadata) async throws -> Response
183+
) async throws -> Response
184+
}
185+
186+
```
187+
188+
The proposed `ServerMiddleware` protocol:
189+
190+
```swift
191+
public protocol ServerMiddleware {
192+
func intercept(
193+
_ request: HTTPRequest, // <<< changed
194+
body: HTTPBody?, // <<< added
195+
metadata: ServerRequestMetadata,
196+
operationID: String,
197+
next: @Sendable (HTTPRequest, HTTPBody?, ServerRequestMetadata) async throws -> (HTTPResponse, HTTPBody?) // <<< changed
198+
) async throws -> (HTTPResponse, HTTPBody?) // <<< changed
199+
}
200+
```
201+
202+
The changes are of the same nature as those to client transport, client middleware, and server transport.
203+
204+
205+
### API stability
206+
207+
The users of concrete transport and middleware implementations will not have to make any changes, only the _implementors_ of transports and middlewares will need to adapt their packages to work with the new currency types.
208+
209+
### Future directions
210+
211+
Nothing beyond the same point about the async writer pattern from [SOAR-0004](https://github.com/czechboy0/swift-openapi-generator/blob/hd-soar-0004/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md).
212+
213+
### Alternatives considered
214+
215+
#### Not adopting the package
216+
217+
An alternative here is to do nothing and not adopt the new package, however since the common HTTP types work so similarly to the types we had to maintain, it was never seriously considered not to take advantage of the common types. While the package is new right now, we expect wider adoption throughout the ecosystem in the coming years, at which point having our own currency types for HTTP requests and responses might be the exception rather than the rule.

0 commit comments

Comments
 (0)