This package provides an HTTP Client library built on top of SwiftNIO.
This library provides the following:
- First class support for Swift Concurrency
- Asynchronous and non-blocking request methods
- Simple follow-redirects (cookie headers are dropped)
- Streaming body download
- TLS support
- Automatic HTTP/2 over HTTPS
- Cookie parsing (but not storage)
Add the following entry in your Package.swift to start using HTTPClient:
.package(url:"https://github.com/swift-server/async-http-client.git", from:"1.9.0")and AsyncHTTPClient dependency to your target:
.target(name:"MyApp", dependencies:[.product(name:"AsyncHTTPClient",package:"async-http-client")]),The code snippet below illustrates how to make a simple GET request to a remote server.
Please note that the example will spawn a new EventLoopGroup which will create fresh threads which is a very costly operation. In a real-world application that uses SwiftNIO for other parts of your application (for example a web server), please prefer eventLoopGroupProvider: .shared(myExistingEventLoopGroup) to share the EventLoopGroup used by AsyncHTTPClient with other parts of your application.
If your application does not use SwiftNIO yet, it is acceptable to use eventLoopGroupProvider: .createNew but please make sure to share the returned HTTPClient instance throughout your whole application. Do not create a large number of HTTPClient instances with eventLoopGroupProvider: .createNew, this is very wasteful and might exhaust the resources of your program.
import AsyncHTTPClient lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew) /// MARK: - Using Swift Concurrency letrequest=HTTPClientRequest(url:"https://apple.com/")letresponse=tryawait httpClient.execute(request, timeout:.seconds(30))print("HTTP head", response)if response.status ==.ok {letbody=tryawait response.body.collect(upTo:1024*1024) // 1 MB // handle body }else{ // handle remote error } /// MARK: - Using SwiftNIO EventLoopFuture httpClient.get(url:"https://apple.com/").whenComplete{ result inswitch result {case.failure(let error): // process error case .success(let response):if response.status ==.ok { // handle response }else{ // handle remote error }}}You should always shut down HTTPClient instances you created using try httpClient.shutdown(). Please note that you must not call httpClient.shutdown before all requests of the HTTP client have finished, or else the in-flight requests will likely fail because their network connections are interrupted.
Examples for the async/await API can be found in the Examples folder in this Repository.
The default HTTP Method is GET. In case you need to have more control over the method, or you want to add headers or body, use the HTTPClientRequest struct:
import AsyncHTTPClient lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew)do{varrequest=HTTPClientRequest(url:"https://apple.com/") request.method =.POST request.headers.add(name:"User-Agent", value:"Swift HTTPClient") request.body =.bytes(ByteBuffer(string:"some data"))letresponse=tryawait httpClient.execute(request, timeout:.seconds(30))if response.status ==.ok { // handle response }else{ // handle remote error }}catch{ // handle error } // it's important to shutdown the httpClient after all requests are done, even if one failed tryawait httpClient.shutdown()import AsyncHTTPClient lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew)defer{try? httpClient.syncShutdown()}varrequest=tryHTTPClient.Request(url:"https://apple.com/", method:.POST) request.headers.add(name:"User-Agent", value:"Swift HTTPClient") request.body =.string("some-body") httpClient.execute(request: request).whenComplete{ result inswitch result {case.failure(let error): // process error case .success(let response):if response.status ==.ok { // handle response }else{ // handle remote error }}}Enable follow-redirects behavior using the client configuration:
lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew, configuration:HTTPClient.Configuration(followRedirects:true))Timeouts (connect and read) can also be set using the client configuration:
lettimeout=HTTPClient.Configuration.Timeout(connect:.seconds(1), read:.seconds(1))lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew, configuration:HTTPClient.Configuration(timeout: timeout))or on a per-request basis:
httpClient.execute(request: request, deadline:.now()+.milliseconds(1))When dealing with larger amount of data, it's critical to stream the response body instead of aggregating in-memory. The following example demonstrates how to count the number of bytes in a streaming response body:
lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew)do{letrequest=HTTPClientRequest(url:"https://apple.com/")letresponse=tryawait httpClient.execute(request, timeout:.seconds(30))print("HTTP head", response) // if defined, the content-length headers announces the size of the body letexpectedBytes= response.headers.first(name:"content-length").flatMap(Int.init)varreceivedBytes=0 // asynchronously iterates over all body fragments // this loop will automatically propagate backpressure correctly fortryawaitbufferin response.body { // for this example, we are just interested in the size of the fragment receivedBytes += buffer.readableBytes iflet expectedBytes = expectedBytes { // if the body size is known, we calculate a progress indicator letprogress=Double(receivedBytes)/ Double(expectedBytes)print("progress: \(Int(progress *100))%")}}print("did receive \(receivedBytes) bytes")}catch{print("request failed:", error)} // it is important to shutdown the httpClient after all requests are done, even if one failed tryawait httpClient.shutdown()import NIOCore import NIOHTTP1 classCountingDelegate:HTTPClientResponseDelegate{typealiasResponse=Intvarcount=0func didSendRequestHead(task:HTTPClient.Task<Response>, _ head:HTTPRequestHead){ // this is executed right after request head was sent, called once }func didSendRequestPart(task:HTTPClient.Task<Response>, _ part:IOData){ // this is executed when request body part is sent, could be called zero or more times }func didSendRequest(task:HTTPClient.Task<Response>){ // this is executed when request is fully sent, called once }func didReceiveHead( task:HTTPClient.Task<Response>, _ head:HTTPResponseHead)->EventLoopFuture<Void>{ // this is executed when we receive HTTP response head part of the request // (it contains response code and headers), called once in case backpressure // is needed, all reads will be paused until returned future is resolved return task.eventLoop.makeSucceededFuture(())}func didReceiveBodyPart( task:HTTPClient.Task<Response>, _ buffer:ByteBuffer)->EventLoopFuture<Void>{ // this is executed when we receive parts of the response body, could be called zero or more times count += buffer.readableBytes // in case backpressure is needed, all reads will be paused until returned future is resolved return task.eventLoop.makeSucceededFuture(())}func didFinishRequest(task:HTTPClient.Task<Response>)throws->Int{ // this is called when the request is fully read, called once // this is where you return a result or throw any errors you require to propagate to the client return count }func didReceiveError(task:HTTPClient.Task<Response>, _ error:Error){ // this is called when we receive any network-related error, called once }}letrequest=tryHTTPClient.Request(url:"https://apple.com/")letdelegate=CountingDelegate() httpClient.execute(request: request, delegate: delegate).futureResult.whenSuccess{ count inprint(count)}Based on the HTTPClientResponseDelegate example above you can build more complex delegates, the built-in FileDownloadDelegate is one of them. It allows streaming the downloaded data asynchronously, while reporting the download progress at the same time, like in the following example:
letclient=HTTPClient(eventLoopGroupProvider:.createNew)letrequest=tryHTTPClient.Request( url:"https://swift.org/builds/development/ubuntu1804/latest-build.yml")letdelegate=tryFileDownloadDelegate(path:"/tmp/latest-build.yml", reportProgress:{iflet totalBytes = $0.totalBytes {print("Total bytes count: \(totalBytes)")}print("Downloaded \($0.receivedBytes) bytes so far")}) client.execute(request: request, delegate: delegate).futureResult .whenSuccess{ progress iniflet totalBytes = progress.totalBytes {print("Final total bytes count: \(totalBytes)")}print("Downloaded finished with \(progress.receivedBytes) bytes downloaded")}Connecting to servers bound to socket paths is easy:
lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew) httpClient.execute(.GET, socketPath:"/tmp/myServer.socket", urlPath:"/path/to/resource").whenComplete(...)Connecting over TLS to a unix domain socket path is possible as well:
lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew) httpClient.execute(.POST, secureSocketPath:"/tmp/myServer.socket", urlPath:"/path/to/resource", body:.string("hello")).whenComplete(...)Direct URLs can easily be constructed to be executed in other scenarios:
letsocketPathBasedURL=URL( httpURLWithSocketPath:"/tmp/myServer.socket", uri:"/path/to/resource")letsecureSocketPathBasedURL=URL( httpsURLWithSocketPath:"/tmp/myServer.socket", uri:"/path/to/resource")The exclusive use of HTTP/1 is possible by setting httpVersion to .http1Only on HTTPClient.Configuration:
varconfiguration=HTTPClient.Configuration() configuration.httpVersion =.http1Only letclient=HTTPClient( eventLoopGroupProvider:.createNew, configuration: configuration )Please have a look at SECURITY.md for AsyncHTTPClient's security process.
The most recent versions of AsyncHTTPClient support Swift 5.6 and newer. The minimum Swift version supported by AsyncHTTPClient releases are detailed below:
| AsyncHTTPClient | Minimum Swift Version |
|---|---|
1.0.0 ..< 1.5.0 | 5.0 |
1.5.0 ..< 1.10.0 | 5.2 |
1.10.0 ..< 1.13.0 | 5.4 |
1.13.0 ..< 1.18.0 | 5.5.2 |
1.18.0 ... | 5.6 |