optimized connect method init

Author: codingiran

Sources/NetworkConnectivityKit/ConnectivityConfiguration.swift

@@ -10,17 +10,54 @@ import Foundation
 // MARK: - ConnectivityConfiguration
 
 public extension NetworkConnectivityKit {
+    /// Configuration settings for network connectivity testing.
+    ///
+    /// This struct encapsulates URLSession configuration options specifically optimized
+    /// for connectivity testing scenarios. It provides sensible defaults for timeout,
+    /// caching behavior, and cellular access that work well for quick connectivity checks.
+    ///
+    /// ## Example
+    /// ```swift
+    /// // Use default configuration (3s timeout, ignore cache)
+    /// let config = ConnectivityConfiguration.default
+    ///
+    /// // Create custom configuration
+    /// let customConfig = ConnectivityConfiguration(
+    ///     timeout: 5.0,
+    ///     cachePolicy: .ignoreCache,
+    ///     allowsCellularAccess: true
+    /// )
+    /// ```
     struct ConnectivityConfiguration: Sendable {
+        /// The underlying URLSession used for network requests.
         public let urlSession: URLSession
 
+        /// Creates a configuration with an existing URLSession.
+        ///
+        /// - Parameter urlSession: The URLSession to use for connectivity testing
         public init(urlSession: URLSession) {
             self.urlSession = urlSession
         }
 
+        /// Creates a configuration with a URLSessionConfiguration.
+        ///
+        /// - Parameter urlSessionConfig: The URLSessionConfiguration to use
         public init(urlSessionConfig: URLSessionConfiguration) {
             self.init(urlSession: URLSession(configuration: urlSessionConfig))
         }
 
+        /// Creates a configuration with specific timeout and caching settings.
+        ///
+        /// This is the most commonly used initializer, providing fine-grained control
+        /// over the key parameters that affect connectivity testing performance.
+        ///
+        /// - Parameters:
+        ///   - timeout: Request timeout in seconds. Defaults to 3 seconds for quick results.
+        ///     Use `nil` to apply system default timeouts.
+        ///   - cachePolicy: Caching strategy for requests. Defaults to `.ignoreCache` for
+        ///     accurate connectivity testing.
+        ///   - allowsCellularAccess: Whether to allow requests over cellular connections.
+        ///     Defaults to `true`.
         public init(timeout: TimeInterval? = 3,
                     cachePolicy: ConnectivityConfiguration.CachePolicy = .ignoreCache,
                     allowsCellularAccess: Bool = true)
@@ -32,42 +69,87 @@ public extension NetworkConnectivityKit {
             self.init(urlSessionConfig: config)
         }
 
-        /// Default configuration for URLSession
-        /// Using 3 seconds timeout and ignore cache
+        /// Default configuration optimized for connectivity testing.
+        ///
+        /// This configuration uses:
+        /// - 3-second timeout for quick results
+        /// - Cache ignored to ensure fresh connectivity tests
+        /// - Cellular access allowed for comprehensive testing
         public static let `default` = ConnectivityConfiguration()
     }
 }
 
 // MARK: - CachePolicy
 
 public extension NetworkConnectivityKit.ConnectivityConfiguration {
+    /// Caching policies for connectivity testing requests.
+    ///
+    /// Different caching strategies affect how fresh the connectivity test results are.
+    /// For most connectivity testing scenarios, ignoring cache provides the most
+    /// accurate real-time connectivity status.
     enum CachePolicy {
+        /// Ignores all cached responses and always makes fresh network requests.
+        ///
+        /// This is the recommended policy for connectivity testing as it ensures
+        /// you're testing actual network connectivity rather than cached responses.
         case ignoreCache
+
+        /// Uses a custom caching policy with optional URLCache.
+        ///
+        /// - Parameters:
+        ///   - policy: The URLRequest cache policy to use
+        ///   - urlCache: Optional custom URLCache instance, or `nil` to use default
         case useCache(policy: URLRequest.CachePolicy, urlCache: URLCache?)
     }
 }
 
 // MARK: - Method chaining
 
 public extension NetworkConnectivityKit.ConnectivityConfiguration {
+    /// Returns a new configuration with the specified timeout.
+    ///
+    /// This method follows a fluent interface pattern, allowing you to chain
+    /// configuration modifications.
+    ///
+    /// - Parameter timeout: The new timeout value in seconds, or `nil` for system defaults
+    /// - Returns: A new configuration instance with the updated timeout
+    ///
+    /// ## Example
+    /// ```swift
+    /// let config = ConnectivityConfiguration.default
+    ///     .timeout(5.0)
+    ///     .ignoreCache()
+    /// ```
     func timeout(_ timeout: TimeInterval?) -> Self {
         let urlSessionConfig = urlSession.configuration
         urlSessionConfig.setTimeout(timeout)
         return .init(urlSessionConfig: urlSessionConfig)
     }
 
+    /// Returns a new configuration with the specified cache policy.
+    ///
+    /// - Parameter cachePolicy: The cache policy to use for requests
+    /// - Returns: A new configuration instance with the updated cache policy
     func cachePolicy(_ cachePolicy: NetworkConnectivityKit.ConnectivityConfiguration.CachePolicy) -> Self {
         let urlSessionConfig = urlSession.configuration
         urlSessionConfig.setCachePolicy(cachePolicy)
         return .init(urlSessionConfig: urlSessionConfig)
     }
 
+    /// Returns a new configuration that ignores cache.
+    ///
+    /// This is a convenience method equivalent to `.cachePolicy(.ignoreCache)`.
+    ///
+    /// - Returns: A new configuration instance that ignores cache
     func ignoreCache() -> Self {
         cachePolicy(.ignoreCache)
     }
 }
 
 private extension URLSessionConfiguration {
+    /// Sets timeout intervals for requests and resources.
+    ///
+    /// - Parameter timeout: The timeout interval in seconds, or `nil` for defaults
     func setTimeout(_ timeout: TimeInterval?) {
         if let timeout {
             timeoutIntervalForRequest = timeout
@@ -78,26 +160,38 @@ private extension URLSessionConfiguration {
         }
     }
 
+    /// Configures the caching policy for the session.
+    ///
+    /// - Parameter policy: The cache policy to apply
     func setCachePolicy(_ policy: NetworkConnectivityKit.ConnectivityConfiguration.CachePolicy) {
         switch policy {
-            case .ignoreCache:
-                requestCachePolicy = .reloadIgnoringCacheData
-                urlCache = nil
-            case .useCache(let policy, let urlCache):
-                requestCachePolicy = policy
-                self.urlCache = urlCache
+        case .ignoreCache:
+            requestCachePolicy = .reloadIgnoringCacheData
+            urlCache = nil
+        case let .useCache(policy, urlCache):
+            requestCachePolicy = policy
+            self.urlCache = urlCache
         }
     }
 
+    /// Sets whether cellular access is allowed for requests.
+    ///
+    /// - Parameter allowsCellularAccess: Whether to allow cellular connections
     func setAllowsCellularAccess(_ allowsCellularAccess: Bool) {
         self.allowsCellularAccess = allowsCellularAccess
     }
 }
 
 private extension NetworkConnectivityKit {
-    /// Default timeout interval of URLSession, Apple doc:
+    /// Default timeout interval for URLSession requests.
+    ///
+    /// Based on Apple's documentation for NSURLSessionConfiguration.timeoutIntervalForRequest:
     /// https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1408259-timeoutintervalforrequest
-    /// https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1408153-timeoutintervalforresource
     static let defaultTimeoutIntervalForRequest: TimeInterval = 60.0
+
+    /// Default timeout interval for URLSession resources.
+    ///
+    /// Based on Apple's documentation for NSURLSessionConfiguration.timeoutIntervalForResource:
+    /// https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1408153-timeoutintervalforresource
     static let defaultTimeoutIntervalForResource: TimeInterval = 7 * 24 * 60 * 60.0
 }

Sources/NetworkConnectivityKit/ConnectivityMethod.swift

@@ -10,21 +10,83 @@ import Foundation
 // MARK: - ConnectivityMethod
 
 public extension NetworkConnectivityKit {
+    /// Represents a method for testing network connectivity to a specific endpoint.
+    ///
+    /// A connectivity method encapsulates:
+    /// - The target URL request
+    /// - Validation logic for determining success
+    /// - Configuration settings for the network request
+    ///
+    /// ## Example
+    /// ```swift
+    /// // Create a custom connectivity method
+    /// let method = ConnectivityMethod(
+    ///     url: URL(string: "https://example.com/ping")!,
+    ///     validation: .generate200Validation
+    /// )
+    /// ```
     struct ConnectivityMethod: Sendable {
+        /// The URL request to be performed for connectivity testing.
         public let urlRequest: URLRequest
+
+        /// The validation logic used to determine if the response indicates successful connectivity.
         public let validation: ConnectivityValidation
+
+        /// The configuration settings for the underlying URLSession.
         public let configuration: ConnectivityConfiguration
 
+        /// Creates a connectivity method with a custom URL request.
+        ///
+        /// - Parameters:
+        ///   - urlRequest: The URL request to perform
+        ///   - validation: The validation logic for the response
+        ///   - configuration: The URLSession configuration (defaults to `.default`)
         public init(urlRequest: URLRequest, validation: ConnectivityValidation, configuration: ConnectivityConfiguration = .default) {
             self.urlRequest = urlRequest
             self.validation = validation
             self.configuration = configuration
         }
 
+        /// Creates a connectivity method with a URL.
+        ///
+        /// - Parameters:
+        ///   - url: The target URL for connectivity testing
+        ///   - validation: The validation logic for the response
+        ///   - configuration: The URLSession configuration (defaults to `.default`)
         public init(url: URL, validation: ConnectivityValidation, configuration: ConnectivityConfiguration = .default) {
             self.init(urlRequest: URLRequest(url: url, configuration: configuration), validation: validation, configuration: configuration)
         }
 
+        /// Creates a connectivity method with a static URL string.
+        ///
+        /// This initializer is designed for compile-time URL strings that are guaranteed to be valid.
+        /// It provides better safety and eliminates the need for optional handling when working with
+        /// hardcoded URLs like built-in connectivity endpoints.
+        ///
+        /// - Parameters:
+        ///   - staticURLString: The static URL string for connectivity testing (must be valid at compile time)
+        ///   - validation: The validation logic for the response
+        ///   - configuration: The URLSession configuration (defaults to `.default`)
+        ///
+        /// ## Example
+        /// ```swift
+        /// let method = ConnectivityMethod(
+        ///     staticURLString: "http://www.gstatic.com/generate_204",
+        ///     validation: .generate204Validation
+        /// )
+        /// ```
+        public init(staticURLString: StaticString, validation: ConnectivityValidation, configuration: ConnectivityConfiguration = .default) {
+            let url = URL(staticString: staticURLString)
+            self.init(url: url, validation: validation, configuration: configuration)
+        }
+
+        /// Creates a connectivity method with a URL string.
+        ///
+        /// - Parameters:
+        ///   - urlString: The target URL string for connectivity testing
+        ///   - validation: The validation logic for the response
+        ///   - configuration: The URLSession configuration (defaults to `.default`)
+        /// - Returns: A new connectivity method, or `nil` if the URL string is invalid
         public init?(urlString: String, validation: ConnectivityValidation, configuration: ConnectivityConfiguration = .default) {
             guard let url = URL(string: urlString) else {
                 return nil
@@ -39,24 +101,79 @@ public extension NetworkConnectivityKit {
 // refer: https://en.wikipedia.org/wiki/Captive_portal
 
 public extension NetworkConnectivityKit.ConnectivityMethod {
-    static let appleCaptive = Self(urlString: "http://captive.apple.com", validation: .generate200Validation)
-
-    static let appleLibrary = Self(urlString: "http://www.apple.com/library/test/success.html", validation: .generate200Validation)
-
-    static let googleGstatic = Self(urlString: "http://www.gstatic.com/generate_204", validation: .generate204Validation)
-
-    static let cloudflare = Self(urlString: "http://cp.cloudflare.com/generate_204", validation: .generate204Validation)
-
-    static let microsoft = Self(urlString: "http://www.msftconnecttest.com/connecttest.txt", validation: .generate200Validation)
-
-    static let vivoWifi = Self(urlString: "http://wifi.vivo.com.cn/generate_204", validation: .generate204Validation)
-
-    static let miuiConnect = Self(urlString: "http://connect.rom.miui.com/generate_204", validation: .generate204Validation)
+    /// Apple's captive portal detection endpoint.
+    ///
+    /// This endpoint is used by Apple devices to detect captive portals and network connectivity.
+    /// It expects a 200 status code with specific content for successful connectivity.
+    ///
+    /// **URL**: `http://captive.apple.com`
+    /// **Expected Response**: HTTP 200 with "Success" content
+    static let appleCaptive = Self(staticURLString: "http://captive.apple.com", validation: .generate200Validation)
+
+    /// Apple's library test endpoint for connectivity verification.
+    ///
+    /// This is an alternative Apple endpoint that provides a reliable connectivity test
+    /// with a simple success page response.
+    ///
+    /// **URL**: `http://www.apple.com/library/test/success.html`
+    /// **Expected Response**: HTTP 200 status code
+    static let appleLibrary = Self(staticURLString: "http://www.apple.com/library/test/success.html", validation: .generate200Validation)
+
+    /// Google's lightweight connectivity check endpoint.
+    ///
+    /// This endpoint returns a 204 (No Content) status code for successful connectivity
+    /// and is widely used for network connectivity testing due to its minimal response size.
+    ///
+    /// **URL**: `http://www.gstatic.com/generate_204`
+    /// **Expected Response**: HTTP 204 (No Content)
+    static let googleGstatic = Self(staticURLString: "http://www.gstatic.com/generate_204", validation: .generate204Validation)
+
+    /// Cloudflare's connectivity check endpoint.
+    ///
+    /// Cloudflare provides this endpoint specifically for captive portal detection
+    /// and connectivity verification with a 204 response.
+    ///
+    /// **URL**: `http://cp.cloudflare.com/generate_204`
+    /// **Expected Response**: HTTP 204 (No Content)
+    static let cloudflare = Self(staticURLString: "http://cp.cloudflare.com/generate_204", validation: .generate204Validation)
+
+    /// Microsoft's connectivity test endpoint.
+    ///
+    /// This endpoint is used by Microsoft systems for network connectivity verification
+    /// and returns a simple text response.
+    ///
+    /// **URL**: `http://www.msftconnecttest.com/connecttest.txt`
+    /// **Expected Response**: HTTP 200 status code
+    static let microsoft = Self(staticURLString: "http://www.msftconnecttest.com/connecttest.txt", validation: .generate200Validation)
+
+    /// Vivo WiFi connectivity check endpoint.
+    ///
+    /// This endpoint is commonly used in networks with Vivo devices and provides
+    /// reliable connectivity testing in those environments.
+    ///
+    /// **URL**: `http://wifi.vivo.com.cn/generate_204`
+    /// **Expected Response**: HTTP 204 (No Content)
+    static let vivoWifi = Self(staticURLString: "http://wifi.vivo.com.cn/generate_204", validation: .generate204Validation)
+
+    /// MIUI (Xiaomi) connectivity check endpoint.
+    ///
+    /// This endpoint is used by MIUI systems for network connectivity verification
+    /// and captive portal detection.
+    ///
+    /// **URL**: `http://connect.rom.miui.com/generate_204`
+    /// **Expected Response**: HTTP 204 (No Content)
+    static let miuiConnect = Self(staticURLString: "http://connect.rom.miui.com/generate_204", validation: .generate204Validation)
 }
 
 // MARK: - Perform Request
 
 extension NetworkConnectivityKit.ConnectivityMethod {
+    /// Performs the connectivity check request and validates the response.
+    ///
+    /// This method executes the network request using the configured URLSession
+    /// and applies the validation logic to determine connectivity success.
+    ///
+    /// - Returns: `true` if the request succeeds and passes validation, `false` otherwise
     func performRequest() async -> Bool {
         do {
             let response = try await configuration.urlSession.data(for: urlRequest)
@@ -82,6 +199,8 @@ extension NetworkConnectivityKit.ConnectivityMethod: Hashable, Equatable {
     }
 }
 
+// MARK: - URLRequest Extension
+
 private extension URLRequest {
     init(url: URL, configuration: NetworkConnectivityKit.ConnectivityConfiguration) {
         let configuration = configuration.urlSession.configuration
@@ -92,3 +211,21 @@ private extension URLRequest {
         self = request
     }
 }
+
+// MARK: - URL Extension for StaticString
+
+extension URL {
+    /// Creates a URL from a static string, providing compile-time safety for hardcoded URLs.
+    ///
+    /// This initializer is designed for cases where the URL string is known at compile time
+    /// and should always be valid. If the static string cannot be converted to a valid URL,
+    /// the application will terminate with a fatal error, helping catch invalid URLs early.
+    ///
+    /// - Parameter staticString: A static string containing a valid URL
+    init(staticString: StaticString) {
+        guard let url = Self(string: "\(staticString)") else {
+            fatalError("Invalid static URL string: \(staticString)")
+        }
+        self = url
+    }
+}