[RFC] Add async/await proposal

docs/async-await.md

@@ -65,12 +65,14 @@ If the library code throws from the `HTTPClientRequest` creation or the request
 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. 
 
 ```swift
-public struct Body {
-  static func bytes<S: Sequence>(_ sequence: S) -> Body where S.Element == UInt8
-
-  static func stream<S: AsyncSequence>(_ sequence: S) -> Body where S.Element == ByteBuffer
-
-  static func stream<S: AsyncSequence>(_ sequence: S) -> Body where S.Element == UInt8
+extension HTTPClientRequest {
+  public struct Body {
+    static func bytes<S: Sequence>(_ sequence: S) -> Body where S.Element == UInt8
+
+    static func stream<S: AsyncSequence>(_ sequence: S) -> Body where S.Element == ByteBuffer
+
+    static func stream<S: AsyncSequence>(_ sequence: S) -> Body where S.Element == UInt8
+  }
 }
 ```
 
@@ -145,6 +147,27 @@ extension HTTPClient {
 }
 ```
 
+Usage example:
+
+```swift
+var request = HTTPClientRequest(url: "https://swift.org")
+request.method = .POST
+request.headers = [
+  "content-type": "text/plain; charset=UTF-8"
+  "x-my-fancy-header": "super-awesome"
+]
+request.body = .sequence("Hello world!".utf8)
+
+var response = try await client.execute(request, deadline: .now() + .seconds(5))
+
+switch response.status {
+case .ok:
+  let body = try await response.body.collect(maxBytes: 1024 * 1024)
+default:
+  throw MyUnexpectedHTTPStatusError
+}
+```
+
 - **Why do we have a deadline in the function signature?** 
     Task deadlines are not part of the Swift 5.5 release. However we think that they are an important tool to not overload the http client accidentally. For this reason we will not default them.
 - **What happened to the Logger?** We will use Task locals to propagate the logger metadata. @slashmo and @ktoso are currently working on this.