feat: Add health check endpoint (#776)

Signed-off-by: Oleg Kopysov <o.kopysov@samsung.com>

Author: o-kopysov

doc/docs/user-guide/service/health.md

@@ -0,0 +1,52 @@
+# Health Check API
+
+The License Pre-Validation Service (LPVS) provides a health check endpoint to monitor the status of the service, specifically to check the current load on the processing queue.
+
+## Endpoint
+
+- **URL:** `/health`
+- **Method:** `GET`
+
+## Description
+
+This endpoint allows you to check the health of the LPVS service by retrieving the current number of items in the processing queue. This can be used for monitoring purposes to ensure the service is running and to gauge its current workload.
+
+A high or continuously growing queue length might indicate that the service is under heavy load or that there are issues with processing items.
+
+## Response
+
+The endpoint returns a JSON object with a single key, `queueLength`, which represents the total number of items currently in the processing queue (persisted in the database).
+
+### Success Response
+
+- **Code:** `200 OK`
+- **Content:**
+  ```json
+  {
+    "queueLength": 5
+  }
+  ```
+
+### Response Schema
+
+| Key         | Type   | Description                                      |
+|-------------|--------|--------------------------------------------------|
+| `queueLength` | integer| The current number of items in the processing queue. |
+
+## Example Usage
+
+You can check the service health using a tool like `curl`:
+
+```bash
+curl -X GET http://localhost:8080/health
+```
+
+**Example Output:**
+
+```json
+{
+  "queueLength": 0
+}
+```
+
+This output indicates that the service is running and there are currently no items in the processing queue.

doc/lpvs-api.yaml

@@ -115,6 +115,20 @@ paths:
               schema:
                 $ref: '#/components/schemas/WebhookResponseForbidden'
 
+  /health:
+    get:
+      tags:
+        - Health Check API
+      summary: Service Health Check
+      description: Endpoint for checking the health of the service. Returns the current number of items in the processing queue.
+      responses:
+        '200':
+          description: 200 OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+
 components:
   schemas:
     WebhookRequest:
@@ -182,3 +196,12 @@ components:
           type: string
           format: uuid
           example: Error
+
+    HealthResponse:
+      type: object
+      properties:
+        queueLength:
+          type: integer
+          format: int64
+          description: The current number of items in the processing queue.
+          example: 5

doc/mkdocs.yml

@@ -36,6 +36,7 @@ nav:
       - Service mode:
           - GitHub webhook configuration: user-guide/service/webhook.md
           - Run service using pre-built Docker image: user-guide/service/docker.md
+          - Health check: user-guide/service/health.md
           - Build and run service from the source code:
             - Prerequisites:
               - Scanner installation: user-guide/service/scanner.md

src/main/java/com/lpvs/controller/HealthController.java

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2025, Samsung Electronics Co., Ltd. All rights reserved.
+ *
+ * Use of this source code is governed by a MIT license that can be
+ * found in the LICENSE file.
+ */
+package com.lpvs.controller;
+
+import com.lpvs.repository.LPVSQueueRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Controller for handling health check requests.
+ * This class provides an endpoint to check the health of the service,
+ * specifically returning the current length of the processing queue.
+ */
+@RestController
+@RequestMapping("/health")
+@Slf4j
+public class HealthController {
+
+    /**
+     * Repository for accessing LPVSQueue entities to determine queue size.
+     */
+    private final LPVSQueueRepository queueRepository;
+
+    /**
+     * Constructor for HealthController.
+     *
+     * @param queueRepository Repository for accessing LPVSQueue entities.
+     */
+    @Autowired
+    public HealthController(LPVSQueueRepository queueRepository) {
+        this.queueRepository = queueRepository;
+    }
+
+    /**
+     * Endpoint for checking the health of the service.
+     * Returns the current number of items in the processing queue.
+     *
+     * @return A ResponseEntity containing a map with the queue length.
+     */
+    @GetMapping
+    public ResponseEntity<Map<String, Long>> getHealthStatus() {
+        long queueLength = queueRepository.count();
+        Map<String, Long> response = new HashMap<>();
+        response.put("queueLength", queueLength);
+        log.info("Current queue length: {}", queueLength);
+        return ResponseEntity.ok(response);
+    }
+}

src/main/java/com/lpvs/controller/package-info.java

@@ -7,12 +7,14 @@
 
 /**
  * This package contains the controller classes for handling various aspects of the License Pre-Validation Service (LPVS).
- * Controllers in this package manage interactions related to GitHub webhooks.
+ * Controllers in this package manage interactions related to GitHub webhooks and service health checks.
  * <p>
  * - {@link com.lpvs.controller.GitHubController}: Manages GitHub webhook events, processes payloads, and interacts
  *   with LPVS services for queue handling and GitHub operations.
+ * - {@link com.lpvs.controller.HealthController}: Provides a health check endpoint to monitor the service,
+ *   specifically returning the current length of the processing queue.
  * </p>
  * These controllers play a crucial role in integrating LPVS functionalities into different parts of the application,
- * such as handling external events.
+ * such as handling external events and providing service status information.
  */
 package com.lpvs.controller;

src/test/java/com/lpvs/controller/HealthControllerTest.java

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025, Samsung Electronics Co., Ltd. All rights reserved.
+ *
+ * Use of this source code is governed by a MIT license that can be
+ * found in the LICENSE file.
+ */
+package com.lpvs.controller;
+
+import com.lpvs.repository.LPVSQueueRepository;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+public class HealthControllerTest {
+
+    @Mock private LPVSQueueRepository queueRepository;
+
+    @InjectMocks private HealthController healthController;
+
+    @Test
+    public void testGetHealthStatus_Success_EmptyQueue() {
+        when(queueRepository.count()).thenReturn(0L);
+
+        ResponseEntity<Map<String, Long>> response = healthController.getHealthStatus();
+
+        assertEquals(HttpStatus.OK, response.getStatusCode());
+        Map<String, Long> responseBody = response.getBody();
+        assertEquals(0L, responseBody.get("queueLength"));
+    }
+
+    @Test
+    public void testGetHealthStatus_Success_WithItems() {
+        long expectedQueueLength = 5L;
+        when(queueRepository.count()).thenReturn(expectedQueueLength);
+
+        ResponseEntity<Map<String, Long>> response = healthController.getHealthStatus();
+
+        assertEquals(HttpStatus.OK, response.getStatusCode());
+        Map<String, Long> responseBody = response.getBody();
+        assertEquals(expectedQueueLength, responseBody.get("queueLength"));
+    }
+}