[RFC] Add async/await proposal

docs/async-await.md

@@ -147,7 +147,7 @@ extension HTTPClient {
 }
 ```
 
-Usage example:
+Simple usage example:
 
 ```swift
 var request = HTTPClientRequest(url: "https://swift.org")
@@ -168,6 +168,40 @@ default:
 }
 ```
 
+Stream upload and download example using the new `FileHandle` api:
+
+```swift
+let readHandle = FileHandle(forReadingFrom: URL(string: "file:///tmp/readfile")!))
+let writeHandle = FileHandle(forWritingTo: URL(string: "file:///tmp/writefile")!))
+
+var request = HTTPClientRequest(url: "https://swift.org/echo")
+request.method = .POST
+request.headers = [
+  "content-type": "text/plain; charset=UTF-8"
+  "x-my-fancy-header": "super-awesome"
+]
+request.body = .stream(readHandle.bytes)
+
+var response = try await client.execute(request, deadline: .now() + .seconds(5))
+
+switch response.status {
+case .ok:
+  Task {
+    var streamIterator = response.body.makeAsyncIterator()
+    writeHandle.writeabilityHandler = { handle in
+      switch try await streamIterator.next() {
+      case .some(let buffer):
+        handle.write(buffer.readData(buffer.readableBytes)!)
+      case .none:
+        handle.close()
+      }
+    }
+  }
+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.