Implement documentation

Author: ns-vasilev

…ification/AuthenticatorInterceptor.swift …fication/AuthenticationInterceptor.swiftSources/NetworkLayer/Classes/Core/Authentification/AuthenticatorInterceptor.swift renamed to Sources/NetworkLayer/Classes/Core/Authentification/AuthenticationInterceptor.swift Sources/NetworkLayer/Classes/Core/Authentification/AuthenticatorInterceptor.swift renamed to Sources/NetworkLayer/Classes/Core/Authentification/AuthenticationInterceptor.swift

@@ -7,9 +7,9 @@ import Atomic
 import Foundation
 import NetworkLayerInterfaces
 
-/// A custom AuthenticatorInterceptor implementation that works with a specific type
+/// A custom AuthenticationInterceptor implementation that works with a specific type
 /// of Authenticator conforming to the IAuthenticator protocol.
-public final class AuthenticatorInterceptor<Authenticator: IAuthenticator>: IAuthenticatorInterceptor {
+public final class AuthenticationInterceptor<Authenticator: IAuthenticator>: IAuthenticationInterceptor {
     // MARK: Types
 
     public typealias Credential = Authenticator.Credential
@@ -21,13 +21,23 @@ public final class AuthenticatorInterceptor<Authenticator: IAuthenticator>: IAut
 
     // MARK: Initialization
 
+    /// Creates a new instance of `AuthenticationInterceptor`.
+    ///
+    /// - Parameters:
+    ///   - authenticator: The authenticator.
+    ///   - credential: The credential.
     public init(authenticator: Authenticator, credential: Credential? = nil) {
         self.authenticator = authenticator
         self.credential = credential
     }
 
     // MARK: IAuthentificatorInterceptor
 
+    /// Adapts the request with credentials.
+    ///
+    /// - Parameters:
+    ///   - request: The URLRequest to be adapted.
+    ///   - session: The URLSession for which the request is being adapted.
     public func adapt(request: inout URLRequest, for session: URLSession) async throws {
         guard let credential else {
             throw AuthenticatorInterceptorError.missingCredential
@@ -40,6 +50,11 @@ public final class AuthenticatorInterceptor<Authenticator: IAuthenticator>: IAut
         }
     }
 
+    /// Refreshes credential for the request.
+    ///
+    /// - Parameters:
+    ///   - request: The URLRequest to be refreshed.
+    ///   - session: The URLSession for which the request is being refreshed.
     public func refresh(
         _ request: URLRequest,
         with response: HTTPURLResponse,
@@ -60,6 +75,13 @@ public final class AuthenticatorInterceptor<Authenticator: IAuthenticator>: IAut
         try await refresh(credential, for: session)
     }
 
+    /// Determines whether a request requires a credential refresh.
+    ///
+    /// - Parameters:
+    ///   - request: The URLRequest to check.
+    ///   - response: The HTTPURLResponse received for the request.
+    ///
+    /// - Returns: A boolean indicating whether a credential refresh is required.
     public func isRequireRefresh(_ request: URLRequest, response: HTTPURLResponse) -> Bool {
         authenticator.didRequest(request, with: response)
     }

Sources/NetworkLayer/Classes/Core/Services/RequestProcessor/RequestProcessor.swift

@@ -24,7 +24,7 @@ actor RequestProcessor {
     /// The retry policy service.
     private let retryPolicyService: IRetryPolicyService
     /// The authenticator interceptor.
-    private let interceptor: IAuthenticatorInterceptor?
+    private let interceptor: IAuthenticationInterceptor?
     /// The delegate.
     private weak var delegate: RequestProcessorDelegate?
 
@@ -43,7 +43,7 @@ actor RequestProcessor {
         dataRequestHandler: any IDataRequestHandler,
         retryPolicyService: IRetryPolicyService,
         delegate: RequestProcessorDelegate?,
-        interceptor: IAuthenticatorInterceptor?
+        interceptor: IAuthenticationInterceptor?
     ) {
         self.configuration = configuration
         self.requestBuilder = requestBuilder

Sources/NetworkLayer/Classes/DI/NetworkLayerAssembly.swift

@@ -17,18 +17,23 @@ public final class NetworkLayerAssembly: INetworkLayerAssembly {
     /// The request processor delegate.
     private let delegate: RequestProcessorDelegate?
     /// The authenticator interceptor.
-    private let interceptor: IAuthenticatorInterceptor?
+    private let interceptor: IAuthenticationInterceptor?
     /// The json encoder.
     private let jsonEncoder: JSONEncoder
 
     // MARK: Initialization
 
     public init(
-        configure: Configuration,
-        retryPolicyStrategy: RetryPolicyStrategy?,
-        delegate: RequestProcessorDelegate?,
-        interceptor: IAuthenticatorInterceptor?,
-        jsonEncoder: JSONEncoder
+        configure: Configuration = .init(
+            sessionConfiguration: .default,
+            sessionDelegate: nil,
+            sessionDelegateQueue: nil,
+            jsonDecoder: JSONDecoder()
+        ),
+        retryPolicyStrategy: RetryPolicyStrategy? = nil,
+        delegate: RequestProcessorDelegate? = nil,
+        interceptor: IAuthenticationInterceptor? = nil,
+        jsonEncoder: JSONEncoder = JSONEncoder()
     ) {
         self.configure = configure
         self.retryPolicyStrategy = retryPolicyStrategy

Sources/NetworkLayer/NetworkLayer.docc/Articles/Authentication.md

@@ -0,0 +1,72 @@
+# Authentication
+
+Learn how to implement authentication.
+
+## Overview
+
+The `network-layer` includes an ``AuthenticationInterceptor`` responsible for handling authentication options.
+
+## Access Tokens
+
+``AuthenticationInterceptor`` requires passing an `IAuthenticator` as initialization parameters that contain logic for updating the access token.
+
+A credential object must conform to `IAuthenticationCredential` protocol that indicates whether the credential is valid.
+
+```swift
+import NetworkLayerInterfaces
+
+// Defines a credential model
+struct Credential: IAuthenticationCredential {
+    let expires: Date
+    let requiresRefresh: Bool { expires < Date() }
+}
+```
+
+Define a `Authenticator` object that confrorms to `IAuthenticator` and implement your own logic for validation and refreshing an access token.
+
+```swift
+import NetworkLayerInterfaces
+
+struct Authenticator: IAuthenticator {
+
+    /// Applies the `Credential` to the `URLRequest`.
+    ///
+    /// - Parameters:
+    ///   - credential: The `Credential`.
+    ///   - urlRequest: The `URLRequest`.
+    func apply(_ credential: Credential, to urlRequest: URLRequest) async throws {
+        request.addValue("Bearer <token>", forHTTPHeaderField: "Authorization")
+    }
+
+    /// Refreshes the `Credential`.
+    ///
+    /// - Parameters:
+    ///   - credential: The `Credential` to refresh.
+    ///   - session: The `URLSession` requiring the refresh.
+    func refresh(_ credential: Credential, for session: URLSession) async throws -> Credential {
+        // Token refresh logic here
+    }
+
+    ///  Determines whether the `URLRequest` failed due to an authentication error based on the `HTTPURLResponse`.
+    ///
+    /// - Parameters:
+    ///   - urlRequest: The `URLRequest`.
+    ///   - response: The `HTTPURLResponse`.
+    ///
+    /// - Returns: `true` if the `URLRequest` failed due to an authentication error, `false` otherwise.
+    func didRequest(_ urlRequest: URLRequest, with response: HTTPURLResponse) -> Bool {
+        response.statusCode == 401
+    }
+
+    /// Determines whether the `URLRequest` is authenticated with the `Credential`.
+    ///
+    /// - Parameters:
+    ///   - urlRequest: The `URLRequest`.
+    ///   - credential: The `Credential`.
+    ///
+    /// - Returns: `true` if the `URLRequest` is authenticated with the `Credential`, `false` otherwise.
+    func isRequest(_ urlRequest: URLRequest, authenticatedWith credential: Credential) -> Bool {
+        true
+    }
+}
+```

Sources/NetworkLayer/NetworkLayer.docc/Articles/GettingStarted.md

@@ -0,0 +1,76 @@
+# Getting Started with Network Layer
+
+## Defining a Request
+
+Before sending a request to a web server, it is necessary to define a request model. For this, define a new `struct` object that conforms to `IRequest` protocol.
+
+```swift
+import NetworkLayerInterfaces
+
+struct UserRequest: IRequest {
+    // MARK: Properties
+
+    private let id: Int
+
+    // MARK: Initialization
+
+    init(id: Int) {
+        self.id = id
+    }
+
+    // MARK: IRequest
+
+    /// The base `URL` for the resource.
+    var domainName: String { 
+        "https://example.com"
+    }
+
+    /// The endpoint path.
+    var path: String { 
+        "user"
+    }
+
+    /// A dictionary that contains the parameters to be encoded into the request.
+    var parameters: [String: String]? { 
+        ["user_id": id]
+    }
+
+    /// A Boolean value indicating whether authentication is required.
+    var requiresAuthentication: Bool { 
+        true
+    }
+
+    /// The HTTP method.
+    var httpMethod: HTTPMethod { 
+        .get
+    }
+}
+```
+
+## Defining a Response Model
+
+While the `network-layer` returns a `Response<T>` object that expects a decodable object, it is necessary to define a response model.
+
+```swift
+import NetworkLayerInterfaces
+
+struct UserResponse: Decodable {
+    let id: Int
+    let userName: String
+}
+```
+
+## Usage
+
+```swift
+import NetworkLayerInterfaces
+
+let request = UserRequest(id: 1)
+
+do {
+    let user = try await requestProcessor.send(request)
+} catch {
+    // Catch an error here
+}
+
+```

Sources/NetworkLayer/NetworkLayer.docc/Articles/Retry.md

@@ -0,0 +1,31 @@
+# Retry
+
+Learn how to retry failed requests.
+
+## Overview
+
+The `network-layer` is implemented using the `Typhoon` framework to handle the retrying of failed requests. You can read more about `Typhoon` framework [here](https://github.com/space-code/typhoon/).
+
+## Retrying Failed Requests
+
+By default, the `network-layer` attempts to resend a failed request five times. If you wish to customize this behavior, you can pass the desired value to an assembly of the `RequestProcessor`.
+
+```swift
+import NetworkLayer
+import NetworkLayerInterfaces
+
+let requestProcessor = NetworkLayerAssembly.assemble(retryPolicyStrategy: .constant(retry: 10, duration: .seconds(1)))
+```
+
+> Tip: `typhoon` framework provides different strategies for retrying failed request. You can read more [here](https://github.com/space-code/typhoon).
+
+This behavior will be applied to all future requests. 
+
+In case you desire to customize a particular request, you can pass the desired strategy to that specific request:
+
+```swift
+import NetworkLayerInterfaces
+
+let request = UserRequest(id: 1)
+let user: Response<User> = try await requestProcessor.send(request, strategy: .constant(retry: 10, duration: .seconds(1)))
+```

Sources/NetworkLayer/NetworkLayer.docc/NetworkLayer.md

@@ -0,0 +1,60 @@
+# ``NetworkLayer``
+
+The library for network communication.
+
+## Overview
+
+The `network-layer` provides a simple interface for communication, making it very easy to send a request to a web server.
+
+```swift
+import NetworkLayer
+
+let requestProcessor = NetworkLayerAssembly().assemble()
+let user: User = try await requestProcessor.send(request)
+```
+
+The `network-layer` separates into two modules: `NetworkLayer`, which contains core functionality, and `NetworkLayerInterfaces`, which only contains public protocols for this framework.
+
+The library supports authentication, retrying requests, and more.
+
+## License
+
+network-layer is available under the MIT license. See the LICENSE file for more info.
+
+## Topics
+
+### Essentials
+
+- <doc:GettingStarted>
+- <doc:Authentication>
+- <doc:Retry>
+
+<!--### Network Layer Creation-->
+<!---->
+<!--- ``INetworkLayerAssembly``-->
+<!---->
+<!--### Request and Response Models-->
+<!---->
+<!--- ``Configuration``-->
+<!--- ``HTTPMethod``-->
+<!--- ``RequestBody``-->
+<!--- ``IRequest``-->
+<!--- ``Response``-->
+<!---->
+<!--### Errors-->
+<!---->
+<!--- ``NetworkLayerError``-->
+<!--- ``AuthenticatorInterceptorError``-->
+<!---->
+<!--### Authentication-->
+<!---->
+<!--- ``IAuthenticationCredential``-->
+<!--- ``IAuthenticationInterceptor``-->
+<!--- ``IAuthenticator``-->
+<!---->
+<!--### Services-->
+<!---->
+<!--- ``IDataRequestHandler``-->
+<!--- ``IRequestBuilder``-->
+<!--- ``IRequestProcessor``-->
+<!--- ``RequestProcessorDelegate``-->

Sources/NetworkLayerInterfaces/Classes/Core/Authenticator/AuthenticatorInterceptorError.swift

@@ -5,7 +5,7 @@
 
 import Foundation
 
-/// `AuthenticatorInterceptorError` is the error type returned by AuthenticatorInterceptor.
+/// `AuthenticatorInterceptorError` is the error type returned by AuthenticationInterceptor.
 public enum AuthenticatorInterceptorError: Swift.Error {
     /// The credential was not found.
     case missingCredential

…nticator/IAuthenticatorInterceptor.swift …ticator/IAuthenticationInterceptor.swiftSources/NetworkLayerInterfaces/Classes/Core/Authenticator/IAuthenticatorInterceptor.swift renamed to Sources/NetworkLayerInterfaces/Classes/Core/Authenticator/IAuthenticationInterceptor.swift Sources/NetworkLayerInterfaces/Classes/Core/Authenticator/IAuthenticatorInterceptor.swift renamed to Sources/NetworkLayerInterfaces/Classes/Core/Authenticator/IAuthenticationInterceptor.swift

@@ -6,7 +6,7 @@
 import Foundation
 
 /// A type defines the authenticator interceptor interface.
-public protocol IAuthenticatorInterceptor {
+public protocol IAuthenticationInterceptor {
     /// Adapts the request with credentials.
     ///
     /// - Parameters:

Sources/NetworkLayerInterfaces/Classes/DI/INetworkLayerAssembly.swift

@@ -22,7 +22,7 @@ public protocol INetworkLayerAssembly {
         configure: Configuration,
         retryPolicyStrategy: RetryPolicyStrategy?,
         delegate: RequestProcessorDelegate?,
-        interceptor: IAuthenticatorInterceptor?,
+        interceptor: IAuthenticationInterceptor?,
         jsonEncoder: JSONEncoder
     )