1616import NIOCore
1717import NIOHTTP1
1818
19+ /// A representation of an HTTP request for the Swift Concurrency HTTPClient API.
20+ ///
21+ /// This object is similar to ``HTTPClient/Request``, but used for the Swift Concurrency API.
1922@available ( macOS 10 . 15 , iOS 13 . 0 , watchOS 6 . 0 , tvOS 13 . 0 , * )
2023public struct HTTPClientRequest {
24+ /// The request URL, including scheme, hostname, and optionally port.
2125 public var url : String
26+
27+ /// The request method.
2228 public var method : HTTPMethod
29+
30+ /// The request headers.
2331 public var headers : HTTPHeaders
2432
33+ /// The request body, if any.
2534 public var body : Body ?
2635
2736 public init ( url: String ) {
@@ -34,6 +43,10 @@ public struct HTTPClientRequest {
3443
3544@available ( macOS 10 . 15 , iOS 13 . 0 , watchOS 6 . 0 , tvOS 13 . 0 , * )
3645extension HTTPClientRequest {
46+ /// An HTTP request body.
47+ ///
48+ /// This object encapsulates the difference between streamed HTTP request bodies and those bodies that
49+ /// are already entirely in memory.
3750 public struct Body {
3851 @usableFromInline
3952 internal enum Mode {
@@ -54,10 +67,20 @@ extension HTTPClientRequest {
5467
5568@available ( macOS 10 . 15 , iOS 13 . 0 , watchOS 6 . 0 , tvOS 13 . 0 , * )
5669extension HTTPClientRequest . Body {
70+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `ByteBuffer`.
71+ ///
72+ /// - parameter byteBuffer: The bytes of the body.
5773 public static func bytes( _ byteBuffer: ByteBuffer ) -> Self {
5874 self . init ( . byteBuffer( byteBuffer) )
5975 }
6076
77+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `RandomAccessCollection` of bytes.
78+ ///
79+ /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
80+ /// usage of this construction will be double the size of the original collection. The construction
81+ /// of the `ByteBuffer` will be delayed until it's needed.
82+ ///
83+ /// - parameter bytes: The bytes of the request body.
6184 @inlinable
6285 public static func bytes< Bytes: RandomAccessCollection > (
6386 _ bytes: Bytes
@@ -75,6 +98,23 @@ extension HTTPClientRequest.Body {
7598 } )
7699 }
77100
101+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `Sequence` of bytes.
102+ ///
103+ /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
104+ /// usage of this construction will be double the size of the original collection. The construction
105+ /// of the `ByteBuffer` will be delayed until it's needed.
106+ ///
107+ /// Unlike ``bytes(_:)-1uns7``, this construction does not assume that the body can be replayed. As a result,
108+ /// if a redirect is encountered that would need us to replay the request body, the redirect will instead
109+ /// not be followed. Prefer ``bytes(_:)-1uns7`` wherever possible.
110+ ///
111+ /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
112+ /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
113+ /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
114+ ///
115+ /// - parameters:
116+ /// - bytes: The bytes of the request body.
117+ /// - length: The length of the request body.
78118 @inlinable
79119 public static func bytes< Bytes: Sequence > (
80120 _ bytes: Bytes ,
@@ -93,6 +133,19 @@ extension HTTPClientRequest.Body {
93133 } )
94134 }
95135
136+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from a `Collection` of bytes.
137+ ///
138+ /// This construction will flatten the bytes into a `ByteBuffer`. As a result, the peak memory
139+ /// usage of this construction will be double the size of the original collection. The construction
140+ /// of the `ByteBuffer` will be delayed until it's needed.
141+ ///
142+ /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
143+ /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
144+ /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
145+ ///
146+ /// - parameters:
147+ /// - bytes: The bytes of the request body.
148+ /// - length: The length of the request body.
96149 @inlinable
97150 public static func bytes< Bytes: Collection > (
98151 _ bytes: Bytes ,
@@ -111,6 +164,17 @@ extension HTTPClientRequest.Body {
111164 } )
112165 }
113166
167+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from an `AsyncSequence` of `ByteBuffer`s.
168+ ///
169+ /// This construction will stream the upload one `ByteBuffer` at a time.
170+ ///
171+ /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
172+ /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
173+ /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
174+ ///
175+ /// - parameters:
176+ /// - sequenceOfBytes: The bytes of the request body.
177+ /// - length: The length of the request body.
114178 @inlinable
115179 public static func stream< SequenceOfBytes: AsyncSequence > (
116180 _ sequenceOfBytes: SequenceOfBytes ,
@@ -123,6 +187,19 @@ extension HTTPClientRequest.Body {
123187 return body
124188 }
125189
190+ /// Create an ``HTTPClientRequest/Body-swift.struct`` from an `AsyncSequence` of bytes.
191+ ///
192+ /// This construction will consume 1kB chunks from the `Bytes` and send them at once. This optimizes for
193+ /// `AsyncSequence`s where larger chunks are buffered up and available without actually suspending, such
194+ /// as those provided by `FileHandle`.
195+ ///
196+ /// Caution should be taken with this method to ensure that the `length` is correct. Incorrect lengths
197+ /// will cause unnecessary runtime failures. Setting `length` to ``Length/unknown`` will trigger the upload
198+ /// to use `chunked` `Transfer-Encoding`, while using ``Length/known(_:)`` will use `Content-Length`.
199+ ///
200+ /// - parameters:
201+ /// - bytes: The bytes of the request body.
202+ /// - length: The length of the request body.
126203 @inlinable
127204 public static func stream< Bytes: AsyncSequence > (
128205 _ bytes: Bytes ,
@@ -157,10 +234,12 @@ extension Optional where Wrapped == HTTPClientRequest.Body {
157234
158235@available ( macOS 10 . 15 , iOS 13 . 0 , watchOS 6 . 0 , tvOS 13 . 0 , * )
159236extension HTTPClientRequest . Body {
237+ /// The length of a HTTP request body.
160238 public struct Length {
161- /// size of the request body is not known before starting the request
239+ /// The size of the request body is not known before starting the request
162240 public static let unknown : Self = . init( storage: . unknown)
163- /// size of the request body is fixed and exactly `count` bytes
241+
242+ /// The size of the request body is known and exactly `count` bytes
164243 public static func known( _ count: Int ) -> Self {
165244 . init( storage: . known( count) )
166245 }
0 commit comments