You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/async-await.md
+24-18
Original file line number
Diff line number
Diff line change
@@ -12,12 +12,12 @@ This proposal describes what these APIs could look like and explores some of the
12
12
13
13
## Proposed API additions
14
14
15
-
### New `AsyncRequest` type
15
+
### New `HTTPClientRequest` type
16
16
17
-
The proposed new `AsyncRequest` shall be a simple swift structure.
17
+
The proposed new `HTTPClientRequest` shall be a simple swift structure.
18
18
19
19
```swift
20
-
structAsyncRequest {
20
+
structHTTPClientRequest {
21
21
/// The requests url.
22
22
var url: String
23
23
@@ -39,7 +39,7 @@ struct AsyncRequest {
39
39
}
40
40
```
41
41
42
-
A notable change from the current [`HTTPRequest`][HTTPRequest] is that the url is not of type `URL`. This makes the creation of a request non throwing. Existing issues regarding current API:
42
+
A notable change from the current [`HTTPClient.Request`][HTTPClient.Request] is that the url is not of type `URL`. This makes the creation of a request non throwing. Existing issues regarding current API:
43
43
44
44
-[HTTPClient.Request.url is a let constant][issue-395]
45
45
-[refactor to make request non-throwing](https://github.com/swift-server/async-http-client/pull/56)
@@ -51,18 +51,18 @@ In normal try/catch flows this should not change the control flow:
If the library code throws from the AsyncRequest creation or the request invocation the user will, in normal use cases, handle the error in the same catch block.
61
+
If the library code throws from the `HTTPClientRequest` creation or the request invocation the user will, in normal use cases, handle the error in the same catch block.
62
62
63
-
#### Body streaming
63
+
#### Request body streaming
64
64
65
-
The new AsyncRequest has a new body type, that is wrapper around an internal enum. This allows us to evolve this type for use-cases that we are not aware of today.
65
+
The new `HTTPClientRequest` has a new body type, that is wrapper around an internal enum. This allows us to evolve this type for use-cases that we are not aware of today.
66
66
67
67
```swift
68
68
publicstructBody {
@@ -74,16 +74,16 @@ public struct Body {
74
74
}
75
75
```
76
76
77
-
The main difference to today's `Request.Body` type is the lack of a `StreamWriter` for streaming scenarios. The existing StreamWriter offered the user an API to write into (thus the user was in control of when writing happened). The new `AsyncRequest.Body` uses `AsyncSequence`s to stream requests. By iterating over the provided AsyncSequence, the HTTPClient is in control when writes happen, and can ask for more data efficiently.
77
+
The main difference to today's `Request.Body` type is the lack of a `StreamWriter` for streaming scenarios. The existing StreamWriter offered the user an API to write into (thus the user was in control of when writing happened). The new `HTTPClientRequest.Body` uses `AsyncSequence`s to stream requests. By iterating over the provided AsyncSequence, the HTTPClient is in control when writes happen, and can ask for more data efficiently.
78
78
79
79
Using the `AsyncSequence` from the Swift standard library as our upload stream mechanism dramatically reduces the learning curve for new users.
80
80
81
-
### New `AsyncResponse` type
81
+
### New `HTTPClientResponse` type
82
82
83
-
The `AsyncResponse` looks more similar to the existing `Response` type. The biggest difference is again the `body` property, which is now an `AsyncSequence` of `ByteBuffer`s instead of a single optional `ByteBuffer?`. This will make every response on AsyncHTTPClient streaming by default.
83
+
The `HTTPClientResponse` looks more similar to the existing [`HTTPClient.Response`][HTTPClient.Response] type. The biggest difference is again the `body` property, which is now an `AsyncSequence` of `ByteBuffer`s instead of a single optional `ByteBuffer?`. This will make every response on AsyncHTTPClient streaming by default. As with `HTTPClientRequest`, we dropped the namespacing on `HTTPClient` to allow easier discovery with autocompletion.
84
84
85
85
```swift
86
-
publicstructAsyncResponse {
86
+
publicstructHTTPClientResponse {
87
87
/// the used http version
88
88
publicvar version: HTTPVersion
89
89
/// the http response status
@@ -94,7 +94,7 @@ public struct AsyncResponse {
94
94
publicvar body: Body
95
95
}
96
96
97
-
extensionAsyncResponse {
97
+
extensionHTTPClientResponse {
98
98
publicstructBody: AsyncSequence {
99
99
publictypealiasElement= ByteBuffer
100
100
publictypealiasAsyncIterator=Iterator
@@ -110,7 +110,11 @@ extension AsyncResponse {
110
110
}
111
111
```
112
112
113
-
At a later point we could add trailers to the AsyncResponse as effectful properties.
113
+
Note: The user must consume the `Body` stream or drop the `HTTPClientResponse`, to ensure that the
114
+
internal HTTPClient connection can move forward. Dropping the `HTTPClientResponse` would lead to a
115
+
request cancellation which in turn would lead to a close of an exisiting HTTP/1.1 connection.
116
+
117
+
At a later point we could add trailers to the `HTTPClientResponse` as effectful properties:
114
118
115
119
```swift
116
120
publicvar trailers: HTTPHeaders? { async throws }
@@ -120,23 +124,24 @@ However we will need to make sure that the user has consumed the body stream com
120
124
121
125
```swift
122
126
do {
123
-
var request =AsyncRequest(url: "https://swift.org/")
127
+
var request =HTTPClientRequest(url: "https://swift.org/")
124
128
let response =tryawait httpClient.execute(request, deadline: .now() + .seconds(3))
125
129
126
130
var trailers =tryawait response.trailers// can not move forward since body must be consumed before.
127
131
} catch {
128
132
print(error)
129
133
}
130
-
131
134
```
132
135
136
+
In such a case we can either throw an error or crash.
137
+
133
138
### New invocation
134
139
135
140
The new way to invoke a request shall look like this:
0 commit comments