document public API (#62)

Co-Authored-By: Joe Smith <[email protected]>

Author: 2 people

Sources/AsyncHTTPClient/HTTPClient+HTTPCookie.swift

@@ -16,18 +16,33 @@ import Foundation
 import NIOHTTP1
 
 extensionHTTPClient{
+ /// A representation of an HTTP cookie.
 publicstructCookie{
+ /// The name of the cookie.
 publicvarname:String
+ /// The cookie's string value.
 publicvarvalue:String
+ /// The cookie's path.
 publicvarpath:String
+ /// The domain of the cookie.
 publicvardomain:String?
+ /// The cookie's expiration date.
 publicvarexpires:Date?
+ /// The cookie's age in seconds.
 publicvarmaxAge:Int?
+ /// Whether the cookie should only be sent to HTTP servers.
 publicvarhttpOnly:Bool
+ /// Whether the cookie should only be sent over secure channels.
 publicvarsecure:Bool
 
-publicinit?(from string:String, defaultDomain:String){
-letcomponents= string.components(separatedBy:";").map{
+ /// Create a Cookie by parsing a `Set-Cookie` header.
+ ///
+ /// - parameters:
+ /// - header: String representation of the `Set-Cookie` response header.
+ /// - defaultDomain: Default domain to use if cookie was sent without one.
+ /// - returns: nil if the header is invalid.
+publicinit?(header:String, defaultDomain:String){
+letcomponents= header.components(separatedBy:";").map{
  $0.trimmingCharacters(in:.whitespaces)
 }
 
@@ -90,6 +105,17 @@ extension HTTPClient{
 }
 }
 
+ /// Create HTTP cookie.
+ ///
+ /// - parameters:
+ /// - name: The name of the cookie.
+ /// - value: The cookie's string value.
+ /// - path: The cookie's path.
+ /// - domain: The domain of the cookie, defaults to nil.
+ /// - expires: The cookie's expiration date, defaults to nil.
+ /// - maxAge: The cookie's age in seconds, defaults to nil.
+ /// - httpOnly: Whether this cookie should be used by HTTP servers only, defaults to false.
+ /// - secure: Whether this cookie should only be sent using secure channels, defaults to false.
 publicinit(name:String, value:String, path:String="/", domain:String?=nil, expires:Date?=nil, maxAge:Int?=nil, httpOnly:Bool=false, secure:Bool=false){
 self.name = name
 self.value = value
@@ -112,12 +138,13 @@ extension HTTPClient{
 }
 }
 
-publicextensionHTTPClient.Response{
-internalvarcookieHeaders:[HTTPHeaders.Element]{
+extensionHTTPClient.Response{
+varcookieHeaders:[HTTPHeaders.Element]{
 return headers.filter{ $0.name.lowercased()=="set-cookie"}
 }
 
-varcookies:[HTTPClient.Cookie]{
-returnself.cookieHeaders.compactMap{HTTPClient.Cookie(from: $0.value, defaultDomain:self.host)}
+ /// List of HTTP cookies returned by the server.
+publicvarcookies:[HTTPClient.Cookie]{
+returnself.cookieHeaders.compactMap{HTTPClient.Cookie(header: $0.value, defaultDomain:self.host)}
 }
 }

Sources/AsyncHTTPClient/HTTPClient.swift

@@ -18,12 +18,42 @@ import NIOConcurrencyHelpers
 import NIOHTTP1
 import NIOSSL
 
+/// HTTPClient class provides API for request execution.
+///
+/// Example:
+///
+/// ```swift
+/// let client = HTTPClient(eventLoopGroupProvider = .createNew)
+/// client.get(url: "https://swift.org", deadline: .now() + .seconds(1)).whenComplete{result in
+/// switch result{
+/// case .failure(let error):
+/// // process error
+/// case .success(let response):
+/// if let response.status == .ok{
+/// // handle response
+/// } else{
+/// // handle remote error
+/// }
+/// }
+/// }
+/// ```
+///
+/// It is important to close the client instance, for example in a defer statement, after use to cleanly shutdown the underlying NIO `EventLoopGroup`:
+///
+/// ```swift
+/// try client.syncShutdown()
+/// ```
 publicclassHTTPClient{
 publicleteventLoopGroup:EventLoopGroup
 leteventLoopGroupProvider:EventLoopGroupProvider
 letconfiguration:Configuration
 letisShutdown=Atomic<Bool>(value:false)
 
+ /// Create an `HTTPClient` with specified `EventLoopGroup` provider and configuration.
+ ///
+ /// - parameters:
+ /// - eventLoopGroupProvider: Specify how `EventLoopGroup` will be created.
+ /// - configuration: Client configuration.
 publicinit(eventLoopGroupProvider:EventLoopGroupProvider, configuration:Configuration=Configuration()){
 self.eventLoopGroupProvider = eventLoopGroupProvider
 switchself.eventLoopGroupProvider {
@@ -44,6 +74,7 @@ public class HTTPClient{
 }
 }
 
+ /// Shuts down the client and `EventLoopGroup` if it was created by the client.
 publicfunc syncShutdown()throws{
 switchself.eventLoopGroupProvider {
 case.shared:
@@ -58,6 +89,11 @@ public class HTTPClient{
 }
 }
 
+ /// Execute `GET` request using specified URL.
+ ///
+ /// - parameters:
+ /// - url: Remote URL.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc get(url:String, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 do{
 letrequest=tryRequest(url: url, method:.GET)
@@ -67,6 +103,12 @@ public class HTTPClient{
 }
 }
 
+ /// Execute `POST` request using specified URL.
+ ///
+ /// - parameters:
+ /// - url: Remote URL.
+ /// - body: Request body.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc post(url:String, body:Body?=nil, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 do{
 letrequest=tryHTTPClient.Request(url: url, method:.POST, body: body)
@@ -76,6 +118,12 @@ public class HTTPClient{
 }
 }
 
+ /// Execute `PATCH` request using specified URL.
+ ///
+ /// - parameters:
+ /// - url: Remote URL.
+ /// - body: Request body.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc patch(url:String, body:Body?=nil, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 do{
 letrequest=tryHTTPClient.Request(url: url, method:.PATCH, body: body)
@@ -85,6 +133,12 @@ public class HTTPClient{
 }
 }
 
+ /// Execute `PUT` request using specified URL.
+ ///
+ /// - parameters:
+ /// - url: Remote URL.
+ /// - body: Request body.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc put(url:String, body:Body?=nil, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 do{
 letrequest=tryHTTPClient.Request(url: url, method:.PUT, body: body)
@@ -94,6 +148,11 @@ public class HTTPClient{
 }
 }
 
+ /// Execute `DELETE` request using specified URL.
+ ///
+ /// - parameters:
+ /// - url: Remote URL.
+ /// - deadline: The time when the request must have been completed by.
 publicfunc delete(url:String, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 do{
 letrequest=tryRequest(url: url, method:.DELETE)
@@ -103,11 +162,22 @@ public class HTTPClient{
 }
 }
 
+ /// Execute arbitrary HTTP request using specified URL.
+ ///
+ /// - parameters:
+ /// - request: HTTP request to execute.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc execute(request:Request, deadline:NIODeadline?=nil)->EventLoopFuture<Response>{
 letaccumulator=ResponseAccumulator(request: request)
 returnself.execute(request: request, delegate: accumulator, deadline: deadline).futureResult
 }
 
+ /// Execute arbitrary HTTP request and handle response processing using provided delegate.
+ ///
+ /// - parameters:
+ /// - request: HTTP request to execute.
+ /// - delegate: Delegate to process response parts.
+ /// - deadline: Point in time by which the request must complete.
 publicfunc execute<T:HTTPClientResponseDelegate>(request:Request, delegate:T, deadline:NIODeadline?=nil)->Task<T.Response>{
 leteventLoop=self.eventLoopGroup.next()
 
@@ -187,10 +257,24 @@ public class HTTPClient{
 }
 }
 
+ /// `HTTPClient` configuration.
 publicstructConfiguration{
+ /// TLS configuration, defaults to `TLSConfiguration.forClient()`.
 publicvartlsConfiguration:TLSConfiguration?
+ /// Enables following 3xx redirects automatically, defaults to `false`.
+ ///
+ /// Following redirects are supported:
+ /// - `301: Moved Permanently`
+ /// - `302: Found`
+ /// - `303: See Other`
+ /// - `304: Not Modified`
+ /// - `305: Use Proxy`
+ /// - `307: Temporary Redirect`
+ /// - `308: Permanent Redirect`
 publicvarfollowRedirects:Bool
+ /// Default client timeout, defaults to no timeouts.
 publicvartimeout:Timeout
+ /// Upstream proxy, defaults to no proxy.
 publicvarproxy:Proxy?
 
 publicinit(tlsConfiguration:TLSConfiguration?=nil, followRedirects:Bool=false, timeout:Timeout=Timeout(), proxy:Proxy?=nil){
@@ -208,15 +292,26 @@ public class HTTPClient{
 }
 }
 
+ /// Specifies how `EventLoopGroup` will be created and establishes lifecycle ownership.
 publicenumEventLoopGroupProvider{
+ /// `EventLoopGroup` will be provided by the user. Owner of this group is responsible for its lifecycle.
 case shared(EventLoopGroup)
+ /// `EventLoopGroup` will be created by the client. When `syncShutdown` is called, created `EventLoopGroup` will be shut down as well.
 case createNew
 }
 
+ /// Timeout configuration
 publicstructTimeout{
+ /// Specifies connect timeout.
 publicvarconnect:TimeAmount?
+ /// Specifies read timeout.
 publicvarread:TimeAmount?
 
+ /// Create timeout.
+ ///
+ /// - parameters:
+ /// - connect: `connect` timeout.
+ /// - read: `read` timeout.
 publicinit(connect:TimeAmount?=nil, read:TimeAmount?=nil){
 self.connect = connect
 self.read = read
@@ -255,6 +350,7 @@ private extension ChannelPipeline{
 }
 }
 
+/// Possible client errors.
 publicstructHTTPClientError:Error,Equatable,CustomStringConvertible{
 privateenumCode:Equatable{
 case invalidURL
@@ -281,16 +377,28 @@ public struct HTTPClientError: Error, Equatable, CustomStringConvertible{
 return"HTTPClientError.\(String(describing:self.code))"
 }
 
+ /// URL provided is invalid.
 publicstaticletinvalidURL=HTTPClientError(code:.invalidURL)
+ /// URL does not contain host.
 publicstaticletemptyHost=HTTPClientError(code:.emptyHost)
+ /// Client is shutdown and cannot be used for new requests.
 publicstaticletalreadyShutdown=HTTPClientError(code:.alreadyShutdown)
+ /// URL does not contain scheme.
 publicstaticletemptyScheme=HTTPClientError(code:.emptyScheme)
+ /// Provided URL scheme is not supported, supported schemes are: `http` and `https`
 publicstaticfunc unsupportedScheme(_ scheme:String)->HTTPClientError{returnHTTPClientError(code:.unsupportedScheme(scheme))}
+ /// Request timed out.
 publicstaticletreadTimeout=HTTPClientError(code:.readTimeout)
+ /// Remote connection was closed unexpectedly.
 publicstaticletremoteConnectionClosed=HTTPClientError(code:.remoteConnectionClosed)
+ /// Request was cancelled.
 publicstaticletcancelled=HTTPClientError(code:.cancelled)
+ /// Request contains invalid identity encoding.
 publicstaticletidentityCodingIncorrectlyPresent=HTTPClientError(code:.identityCodingIncorrectlyPresent)
+ /// Request contains multiple chunks definitions.
 publicstaticletchunkedSpecifiedMultipleTimes=HTTPClientError(code:.chunkedSpecifiedMultipleTimes)
+ /// Proxy response was invalid.
 publicstaticletinvalidProxyResponse=HTTPClientError(code:.invalidProxyResponse)
+ /// Request does not contain `Content-Length` header.
 publicstaticletcontentLengthMissing=HTTPClientError(code:.contentLengthMissing)
 }