HTTPClient.shared a globally shared singleton & .browserLike configuration

Author: Johannes Weiss

Sources/AsyncHTTPClient/Configuration+BrowserLike.swift

@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the AsyncHTTPClient open source project
+//
+// Copyright (c) 2023 Apple Inc. and the AsyncHTTPClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of AsyncHTTPClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+extension HTTPClient.Configuration {
+    /// A ``HTTPClient/Configuration`` that tries to mimick the platform's default or prevalent browser as closely as possible.
+    ///
+    /// Platform's default/prevalent browsers that we're trying to match (these might change over time):
+    ///  - macOS: Safari
+    ///  - iOS: Safari
+    ///  - Android: Google Chrome
+    ///  - Linux (non-Android): Google Chrome
+    ///
+    /// - note: Don't rely on the values in here never changing, they will be adapted to better match the platform's default/prevalent browser.
+    public static var browserLike: HTTPClient.Configuration {
+        // To start with, let's go with these values. Obtained from Firefox's config.
+        return HTTPClient.Configuration(
+            certificateVerification: .fullVerification,
+            redirectConfiguration: .follow(max: 20, allowCycles: false),
+            timeout: Timeout(connect: .seconds(90), read: .seconds(90)),
+            connectionPool: .seconds(600),
+            proxy: nil,
+            ignoreUncleanSSLShutdown: false,
+            decompression: .enabled(limit: .ratio(10)),
+            backgroundActivityLogger: nil
+        )
+    }
+}

Sources/AsyncHTTPClient/HTTPClient.swift

@@ -78,6 +78,7 @@ public class HTTPClient {
 
     private var state: State
     private let stateLock = NIOLock()
+    private let canBeShutDown: Bool
 
     internal static let loggingDisabled = Logger(label: "AHC-do-not-log", factory: { _ in SwiftLogNoOpLogHandler() })
 
@@ -133,9 +134,20 @@ public class HTTPClient {
     ///     - eventLoopGroup: The `EventLoopGroup` that the ``HTTPClient`` will use.
     ///     - configuration: Client configuration.
     ///     - backgroundActivityLogger: The `Logger` that will be used to log background any activity that's not associated with a request.
-    public required init(eventLoopGroup: any EventLoopGroup,
-                         configuration: Configuration = Configuration(),
-                         backgroundActivityLogger: Logger) {
+    public convenience init(eventLoopGroup: any EventLoopGroup,
+                            configuration: Configuration = Configuration(),
+                            backgroundActivityLogger: Logger) {
+        self.init(eventLoopGroup: eventLoopGroup,
+                  configuration: configuration,
+                  backgroundActivityLogger: backgroundActivityLogger,
+                  canBeShutDown: true)
+    }
+
+    internal required init(eventLoopGroup: EventLoopGroup,
+                           configuration: Configuration = Configuration(),
+                           backgroundActivityLogger: Logger,
+                           canBeShutDown: Bool) {
+        self.canBeShutDown = canBeShutDown
         self.eventLoopGroup = eventLoopGroup
         self.configuration = configuration
         self.poolManager = HTTPConnectionPool.Manager(
@@ -247,6 +259,12 @@ public class HTTPClient {
     }
 
     private func shutdown(requiresCleanClose: Bool, queue: DispatchQueue, _ callback: @escaping ShutdownCallback) {
+        guard self.canBeShutDown else {
+            queue.async {
+                callback(HTTPClientError.shutdownUnsupported)
+            }
+            return
+        }
         do {
             try self.stateLock.withLock {
                 guard case .upAndRunning = self.state else {
@@ -1069,6 +1087,7 @@ public struct HTTPClientError: Error, Equatable, CustomStringConvertible {
         case getConnectionFromPoolTimeout
         case deadlineExceeded
         case httpEndReceivedAfterHeadWith1xx
+        case shutdownUnsupported
     }
 
     private var code: Code
@@ -1150,6 +1169,8 @@ public struct HTTPClientError: Error, Equatable, CustomStringConvertible {
             return "Deadline exceeded"
         case .httpEndReceivedAfterHeadWith1xx:
             return "HTTP end received after head with 1xx"
+        case .shutdownUnsupported:
+            return "The global singleton HTTP client cannot be shut down"
         }
     }
 
@@ -1214,6 +1235,11 @@ public struct HTTPClientError: Error, Equatable, CustomStringConvertible {
         return HTTPClientError(code: .serverOfferedUnsupportedApplicationProtocol(proto))
     }
 
+    /// The globally shared singleton ``HTTPClient`` cannot be shut down.
+    public static var shutdownUnsupported: HTTPClientError {
+        return HTTPClientError(code: .shutdownUnsupported)
+    }
+
     /// The request deadline was exceeded. The request was cancelled because of this.
     public static let deadlineExceeded = HTTPClientError(code: .deadlineExceeded)
 

Sources/AsyncHTTPClient/Singleton.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the AsyncHTTPClient open source project
+//
+// Copyright (c) 2023 Apple Inc. and the AsyncHTTPClient project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of AsyncHTTPClient project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+extension HTTPClient {
+    /// A globally shared, singleton ``HTTPClient``.
+    ///
+    /// The returned client uses the following settings:
+    /// - configuration is ``HTTPClient/Configuration/browserLike`` (matching the platform's default/prevalent browser as well as possible)
+    /// - `EventLoopGroup` is ``HTTPClient/defaultEventLoopGroup`` (matching the platform default)
+    /// - logging is disabled
+    public static var shared: HTTPClient {
+        return globallySharedHTTPClient
+    }
+}
+
+private let globallySharedHTTPClient: HTTPClient = {
+    let httpClient = HTTPClient(
+        eventLoopGroup: HTTPClient.defaultEventLoopGroup,
+        configuration: .browserLike,
+        backgroundActivityLogger: HTTPClient.loggingDisabled,
+        canBeShutDown: false
+    )
+    return httpClient
+}()

Tests/AsyncHTTPClientTests/HTTPClientTests.swift

@@ -3525,4 +3525,15 @@ final class HTTPClientTests: XCTestCaseHTTPClientTestsBaseClass {
         let response = try client.get(url: self.defaultHTTPBinURLPrefix + "get").wait()
         XCTAssertEqual(.ok, response.status)
     }
+
+    func testSingletonClientWorks() throws {
+        let response = try HTTPClient.shared.get(url: self.defaultHTTPBinURLPrefix + "get").wait()
+        XCTAssertEqual(.ok, response.status)
+    }
+
+    func testSingletonClientCannotBeShutDown() {
+        XCTAssertThrowsError(try HTTPClient.shared.shutdown().wait()) { error in
+            XCTAssertEqual(.shutdownUnsupported, error as? HTTPClientError)
+        }
+    }
 }