docs: improve documentation

LLCFreedom-Space · Feb 23, 2024 · f782da4 · f782da4
1 parent a256c60
commit f782da4
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 31 deletions.
diff --git a/Sources/HealthChecks/ChecksProtocol.swift b/Sources/HealthChecks/ChecksProtocol.swift
@@ -24,10 +24,13 @@
 
 import Vapor
 
-/// Groups func for get health check
+/// The protocol defines a basic interface for performing health checks against different systems or services.
 public protocol ChecksProtocol {
-    /// Check with setup options
-    /// - Parameter options: array of `MeasurementType`
-    /// - Returns: dictionary `[String: HealthCheckItem]`
+    /// Performs health checks against Consul, returning a dictionary
+    /// of `HealthCheckItem`s for the specified components.
+    ///
+    /// - Parameters:
+    ///   - options: An array of `MeasurementType`s indicating which checks to perform.
+    /// - Returns: A dictionary of `HealthCheckItem`s, keyed by  component ID and measurement type.
     func check(for options: [MeasurementType]) async -> [String: HealthCheckItem]
 }
diff --git a/Sources/HealthChecks/ConsulHealthChecks/ConsulConfig.swift b/Sources/HealthChecks/ConsulHealthChecks/ConsulConfig.swift
@@ -24,21 +24,41 @@
 
 import Vapor
 
-/// A generic `ConsulConfig` data that can be save in storage.
+/// Represents configuration details for connecting to a Consul server.
 public struct ConsulConfig {
-    /// Is a unique identifier of the consul, in the application scope
-    /// Example: `43119325-63f5-4e14-9175-84e0e296c527`
+    /// A unique identifier for this Consul configuration within your application.
+    /// This ID is not related to Consul itself and can be used for internal reference.
+    /// Example: "43119325-63f5-4e14-9175-84e0e296c527"
     public let id: String
-
-    /// Consul url
-    /// Example: `http://127.0.0.1:8500`, `https://xmpl-consul.example.com`
+    
+    /// The URL of the Consul server to connect to.
+    /// Example: "http://127.0.0.1:8500", "https://xmpl-consul.example.com"
     public let url: String
-
-    /// Consul username
-    /// Example: `username`
+    
+    /// The username for authenticating with Consul (optional).
+    /// Example: "username"
     public let username: String?
-
-    /// Consul password
-    /// Example: `password`
+    
+    /// The password for authenticating with Consul (optional).
+    /// Example: "password"
     public let password: String?
+
+    /// Initializes a `ConsulConfig` with the specified details.
+    ///
+    /// - Parameters:
+    ///   - id: The unique identifier for this configuration.
+    ///   - url: The URL of the Consul server.
+    ///   - username: The username for authentication (optional).
+    ///   - password: The password for authentication (optional).
+    public init(
+        id: String,
+        url: String,
+        username: String? = nil,
+        password: String? = nil
+    ) {
+        self.id = id
+        self.url = url
+        self.username = username
+        self.password = password
+    }
 }
diff --git a/Sources/HealthChecks/ConsulHealthChecks/ConsulHealthChecks.swift b/Sources/HealthChecks/ConsulHealthChecks/ConsulHealthChecks.swift
@@ -24,9 +24,9 @@
 
 import Vapor
 
-/// Service that provides consul health check functionality
+/// Service that provides Consul health check functionality
 public struct ConsulHealthChecks: ConsulHealthChecksProtocol {
-    /// Instance of app as `Application`
+    /// Instance of the application as `Application`
     public let app: Application
 
     /// Check with setup options
@@ -55,7 +55,10 @@ public struct ConsulHealthChecks: ConsulHealthChecksProtocol {
     /// Get response for consul
     /// - Returns: `ClientResponse`
     func getStatus() async -> ClientResponse {
-        let url = app.consulConfig?.url ?? Constants.consulUrl
+        guard let url = app.consulConfig?.url else {
+            app.logger.error("ERROR: Consul URL is not configured.")
+            return ClientResponse()
+        }
         let path = Constants.consulStatusPath
         let uri = URI(string: url + path)
         var headers = HTTPHeaders()
@@ -77,7 +80,14 @@ public struct ConsulHealthChecks: ConsulHealthChecksProtocol {
     /// - Parameter response: `ClientResponse`
     /// - Returns: `HealthCheckItem`
     func status(_ response: ClientResponse) -> HealthCheckItem {
-        let url = app.consulConfig?.url ?? Constants.consulUrl
+        guard let url = app.consulConfig?.url else {
+            return HealthCheckItem(
+                componentId: app.consulConfig?.id,
+                componentType: .component,
+                status: .fail,
+                output: "Consul URL is not configured."
+            )
+        }
         let path = Constants.consulStatusPath
         return HealthCheckItem(
             componentId: app.consulConfig?.id,
@@ -96,7 +106,14 @@ public struct ConsulHealthChecks: ConsulHealthChecksProtocol {
     ///   - start: `TimeInterval`
     /// - Returns: `HealthCheckItem`
     func responseTime(from response: ClientResponse, _ start: TimeInterval) -> HealthCheckItem {
-        let url = app.consulConfig?.url ?? Constants.consulUrl
+        guard let url = app.consulConfig?.url else {
+            return HealthCheckItem(
+                componentId: app.consulConfig?.id,
+                componentType: .component,
+                status: .fail,
+                output: "Consul URL is not configured."
+            )
+        }
         let path = Constants.consulStatusPath
         return HealthCheckItem(
             componentId: app.consulConfig?.id,

diff --git a/Sources/HealthChecks/ConsulHealthChecks/ConsulHealthChecksProtocol.swift b/Sources/HealthChecks/ConsulHealthChecks/ConsulHealthChecksProtocol.swift
@@ -24,5 +24,5 @@
 
 import Vapor
 
-/// Groups func for get consul health check
+/// Protocol defining an interface for performing Consul health checks.
 public protocol ConsulHealthChecksProtocol: ChecksProtocol {}
diff --git a/Tests/HealthChecksTests/ConsulHealthChecksTests.swift b/Tests/HealthChecksTests/ConsulHealthChecksTests.swift
@@ -33,9 +33,7 @@ final class ConsulHealthChecksTests: XCTestCase {
         app.consulHealthChecks = ConsulHealthChecksMock()
         let consulConfig = ConsulConfig(
             id: UUID().uuidString,
-            url: Constants.consulUrl,
-            username: "username",
-            password: "password"
+            url: Constants.consulUrl
         )
         app.consulConfig = consulConfig
         let result = await app.consulHealthChecks?.check(for: [MeasurementType.responseTime, MeasurementType.connections])
@@ -50,6 +48,10 @@ final class ConsulHealthChecksTests: XCTestCase {
     func testCheckForBothSuccess() async {
         let app = Application(.testing)
         defer { app.shutdown() }
+        app.consulConfig = ConsulConfig(
+            id: String(UUID()),
+            url: "consul-url"
+        )
         let clientResponse = ClientResponse(status: .ok)
         app.clients.use { app in
             MockClient(eventLoop: app.eventLoopGroup.next(), clientResponse: clientResponse)
@@ -77,6 +79,10 @@ final class ConsulHealthChecksTests: XCTestCase {
     func testCheckStatusSuccess() async {
         let app = Application(.testing)
         defer { app.shutdown() }
+        app.consulConfig = ConsulConfig(
+            id: String(UUID()),
+            url: "consul-url"
+        )
         let clientResponse = ClientResponse(status: .ok)
         app.clients.use { app in
             MockClient(eventLoop: app.eventLoopGroup.next(), clientResponse: clientResponse)
@@ -109,6 +115,10 @@ final class ConsulHealthChecksTests: XCTestCase {
     func testCheckResponseTimeSuccess() async {
         let app = Application(.testing)
         defer { app.shutdown() }
+        app.consulConfig = ConsulConfig(
+            id: String(UUID()),
+            url: "consul-url"
+        )
         let clientResponse = ClientResponse(status: .ok)
         app.clients.use { app in
             MockClient(eventLoop: app.eventLoopGroup.next(), clientResponse: clientResponse)
@@ -128,6 +138,10 @@ final class ConsulHealthChecksTests: XCTestCase {
     func testCheckResponseTimeFail() async {
         let app = Application(.testing)
         defer { app.shutdown() }
+        app.consulConfig = ConsulConfig(
+            id: String(UUID()),
+            url: "consul-url"
+        )
         let clientResponse = ClientResponse(status: .badRequest)
         app.clients.use { app in
             MockClient(eventLoop: app.eventLoopGroup.next(), clientResponse: clientResponse)
@@ -145,16 +159,13 @@ final class ConsulHealthChecksTests: XCTestCase {
     }
 
     func testGetStatusSuccessWithAuth() async {
-        let expectedUrl = "https://example.com/status"
-        let expectedUsername = "user"
-        let expectedPassword = "password"
         let app = Application(.testing)
         defer { app.shutdown() }
         app.consulConfig = ConsulConfig(
             id: String(UUID()),
-            url: expectedUrl,
-            username: expectedUsername,
-            password: expectedPassword
+            url: "https://example.com/status",
+            username: "user",
+            password: "password"
         )
         let clientResponse = ClientResponse(status: .ok)
         app.clients.use { app in