[OGUI-1840 & OGUI-1841] Refactor the response object of retrieveRunStatus (#3229)

* The method `retrieveRunStatus` is renamed to `retrieveRunInformation`
* The method now returns an object with established run information:
  * `runStatus`: this is the field created right now by QCG and should be kept to ensure front-end compatibility
  * time at which the run has started - `startTime`
  * time at which the run has run ended - `endTime`
  * the run belongs to a partition also known as environment: `environmentId`
  * the run also is defined by multiple properties. Depending on which oneas are used the run has a definition: `definition`
  * the run has a quality that decides if it should be stored or not for long time: `runQuality`
  * run normally runs only during an LHC beam mode: `lhcBeamMode`
  * A run has multiple detectors taking data, thus we should also get the list of detectors and qualityies: `detectorQualities`
* All methods making use of this have been updated accordingly:
  * Methods in `FilterService`
  * Methods in `FilterController`

Author: hehoon

QualityControl/lib/api.js

@@ -109,7 +109,7 @@ export const setup = async (http, ws, eventEmitter) => {
   http.get(
     '/filter/run-status/:runNumber',
     runStatusFilterMiddleware,
-    filterController.getRunStatusHandler.bind(filterController),
+    filterController.getRunInformationHandler.bind(filterController),
   );
   http.get(
     '/filter/ongoingRuns',

QualityControl/lib/controllers/FilterController.js

@@ -46,12 +46,10 @@ export class FilterController {
    * @param {Request} req - HTTP request
    * @param {Response} res - HTTP response to provide run status information
    */
-  async getRunStatusHandler(req, res) {
+  async getRunInformationHandler(req, res) {
     try {
-      const runStatus = await this._filterService.getRunStatus(req.params.runNumber);
-      res.status(200).json({
-        runStatus,
-      });
+      const runInformation = await this._filterService.getRunInformation(req.params.runNumber);
+      res.status(200).json(runInformation);
     } catch (error) {
       this._logger.errorMessage('Error getting run status:', error);
       updateAndSendExpressResponseFromNativeError(res, error);

QualityControl/lib/dtos/BookkeepingDto.js

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+/**
+ * Quality information for a single detector participating in the run.
+ * @typedef {object} DetectorQuality
+ * @property {number} id - Unique detector identifier.
+ * @property {string} name - The name (abbreviation) of the detector.
+ * @property {string} quality - Quality flag or classification for the detector.
+ */
+
+/**
+ * Bookkeeping run information.
+ * @typedef {object} RunInformation
+ * @property {RunStatus} runStatus - Custom status for front-end consumption:
+ *   - ONGOING: run is currently ongoing
+ *   - ENDED: run has completed (timeO2End is present)
+ *   - NOT_FOUND: run data does not exist
+ *   - UNKNOWN: error occurred or data unavailable
+ * @property {number} startTime - Time (epoch) at which the run started.
+ * @property {number|undefined} endTime - Time (epoch) at which the run ended. If `undefined`, the run hasn't ended yet.
+ * @property {number|undefined} environmentId - Partition/environment the run belongs to.
+ * @property {string|undefined} definition - The definition of the run.
+ * @property {string} runQuality - Overall run quality.
+ * @property {string|undefined} lhcBeamMode - LHC beam mode during which the run was taken, if any.
+ * @property {DetectorQuality[]} detectorsQualities - Per-detector quality information.
+ */
+
+/**
+ * Wrapped Run Status object
+ * @typedef {object} WrappedRunStatus
+ * @property {RunStatus} runStatus - The Run Status
+ */
+
+/**
+ * Wraps a given run status value into a standardized result object.
+ * Use this helper when you need to return only a `runStatus` field without any
+ * additional payload. This ensures that all callers receive a consistent
+ * object shape, matching the structure returned by `retrieveRunInformation`.
+ * @param {RunStatus} runStatus The run status to wrap. Must be a valid `RunStatus` enum value.
+ * @returns {WrappedRunStatus} A simple object containing only the provided `runStatus`.
+ */
+export function wrapRunStatus(runStatus) {
+  return { runStatus };
+}

QualityControl/lib/services/BookkeepingService.js

@@ -15,6 +15,7 @@
 import { RunStatus } from '../../common/library/runStatus.enum.js';
 import { httpGetJson } from '../utils/httpRequests.js';
 import { LogManager } from '@aliceo2/web-ui';
+import { wrapRunStatus } from '../dtos/BookkeepingDto.js';
 
 const GET_BKP_DATABASE_STATUS_PATH = '/api/status/database';
 const GET_RUN_TYPES_PATH = '/api/runTypes';
@@ -127,17 +128,14 @@ export class BookkeepingService {
   }
 
   /**
-   * Retrieves the status of a specific run from the Bookkeeping service
+   * Retrieves the information of a specific run from the Bookkeeping service
    * @param {number} runNumber - The run number to check the status for
-   * @returns {Promise<RunStatus>} - Returns a promise that resolves to the run status:
-   *                                 - RunStatus.ONGOING if the run is ongoing
-   *                                 - RunStatus.ENDED if the run has completed (has timeO2End)
-   *                                 - RunStatus.NOT_FOUND if there was an error or data is not available
+   * @returns {Promise<RunInformation|WrappedRunStatus>} - Returns a promise that resolves to the run information
    */
-  async retrieveRunStatus(runNumber) {
+  async retrieveRunInformation(runNumber) {
     if (!this.active) {
       this._logger.warnMessage('Could not connect to bookkeeping');
-      return RunStatus.BOOKKEEPING_UNAVAILABLE;
+      return wrapRunStatus(RunStatus.BOOKKEEPING_UNAVAILABLE);
     }
 
     try {
@@ -150,15 +148,36 @@ export class BookkeepingService {
         throw new Error('No data available');
       }
 
-      return data.timeO2End ? RunStatus.ENDED : RunStatus.ONGOING;
+      const {
+        startTime,
+        endTime,
+        environmentId,
+        definition,
+        runQuality,
+        lhcBeamMode,
+        detectorsQualities = [],
+        timeO2End,
+      } = data;
+      const runStatus = timeO2End ? RunStatus.ENDED : RunStatus.ONGOING;
+
+      return {
+        startTime,
+        endTime,
+        environmentId,
+        definition,
+        runQuality,
+        lhcBeamMode,
+        detectorsQualities,
+        ...wrapRunStatus(runStatus),
+      };
     } catch (error) {
       const msg = error?.message ?? String(error);
       if (msg.includes('404')) {
         this._logger.warnMessage(`Run number ${runNumber} not found in bookkeeping`);
-        return RunStatus.NOT_FOUND;
+        return wrapRunStatus(RunStatus.NOT_FOUND);
       }
       this._logger.errorMessage(`Error fetching run status: ${error.message || error}`);
-      return RunStatus.UNKNOWN;
+      return wrapRunStatus(RunStatus.UNKNOWN);
     }
   }
 

QualityControl/lib/services/FilterService.js

@@ -14,6 +14,7 @@
 
 import { LogManager } from '@aliceo2/web-ui';
 import { RunStatus } from '../../common/library/runStatus.enum.js';
+import { wrapRunStatus } from '../dtos/BookkeepingDto.js';
 
 const LOG_FACILITY = `${process.env.npm_config_log_label ?? 'qcg'}/filter-service`;
 
@@ -87,18 +88,17 @@ export class FilterService {
   }
 
   /**
-   * This method is used to retrieve the run status from the bookkeeping service
-   * @param {number} runNumber - run number to retrieve the status for
-   * @returns {Promise<string>} - resolves with the run status
+   * This method is used to retrieve the run information from the bookkeeping service
+   * @param {number} runNumber - run number to retrieve the information for
+   * @returns {Promise<object>} - resolves with the run information
    */
-  async getRunStatus(runNumber) {
+  async getRunInformation(runNumber) {
     try {
-      const runStatus = await this._bookkeepingService.retrieveRunStatus(runNumber);
-      return runStatus;
+      return await this._bookkeepingService.retrieveRunInformation(runNumber);
     } catch (error) {
       const message = `Error while retrieving run status for run ${runNumber}: ${error.message || error}`;
       this._logger.errorMessage(message);
-      return RunStatus.UNKNOWN;
+      return wrapRunStatus(RunStatus.UNKNOWN);
     }
   }
 }

QualityControl/lib/services/RunModeService.js

@@ -63,7 +63,7 @@ export class RunModeService {
       return { paths: cachedPaths };
     }
 
-    const runStatus = await this._bookkeepingService.retrieveRunStatus(runNumber);
+    const { runStatus } = await this._bookkeepingService.retrieveRunInformation(runNumber);
     const rawPaths = await this._dataService.getObjectsLatestVersionList({
       filters: { RunNumber: runNumber },
     });
@@ -88,7 +88,7 @@ export class RunModeService {
   async refreshRunsCache() {
     for (const [runNumber] of this._ongoingRuns.entries()) {
       try {
-        const runStatus = await this._bookkeepingService.retrieveRunStatus(runNumber);
+        const { runStatus } = await this._bookkeepingService.retrieveRunInformation(runNumber);
         if (runStatus === RunStatus.ONGOING) {
           const updatedPaths = await this._dataService.getObjectsLatestVersionList({
             filters: { RunNumber: runNumber },

QualityControl/test/lib/controllers/FiltersController.test.js

@@ -73,7 +73,9 @@ export const filtersControllerTestSuite = async () => {
   suite('getRunStatusHandler', async () => {
     test('should successfully retrieve run status from FilterService', async () => {
       const filterService = sinon.createStubInstance(FilterService);
-      filterService.getRunStatus.resolves(RunStatus.ONGOING);
+      filterService.getRunInformation.resolves({
+        runStatus: RunStatus.ONGOING,
+      });
 
       const req = {
         params: {
@@ -86,9 +88,12 @@ export const filtersControllerTestSuite = async () => {
       };
 
       const filterController = new FilterController(filterService);
-      await filterController.getRunStatusHandler(req, res);
+      await filterController.getRunInformationHandler(req, res);
 
-      ok(filterService.getRunStatus.calledWith(123456), 'FilterService.getRunStatus should be called with run number');
+      ok(
+        filterService.getRunInformation.calledWith(123456),
+        'FilterService.getRunInformation should be called with run number',
+      );
       ok(res.status.calledWith(200), 'Response status should be 200');
       ok(res.json.calledWith({
         runStatus: RunStatus.ONGOING,
@@ -98,7 +103,7 @@ export const filtersControllerTestSuite = async () => {
     test('should handle errors from FilterService and send error response', async () => {
       const filterService = sinon.createStubInstance(FilterService);
       const testError = new Error('Bookkeeping service unavailable');
-      filterService.getRunStatus.rejects(testError);
+      filterService.getRunInformation.rejects(testError);
 
       const req = {
         params: {
@@ -111,9 +116,12 @@ export const filtersControllerTestSuite = async () => {
       };
 
       const filterController = new FilterController(filterService);
-      await filterController.getRunStatusHandler(req, res);
+      await filterController.getRunInformationHandler(req, res);
 
-      ok(filterService.getRunStatus.calledWith(123456), 'FilterService.getRunStatus should be called with run number');
+      ok(
+        filterService.getRunInformation.calledWith(123456),
+        'FilterService.getRunStatus should be called with run number',
+      );
       ok(res.status.calledWith(500), 'Response status should be 500 for service errors');
       ok(res.json.calledWithMatch({
         message: 'Bookkeeping service unavailable',
@@ -124,7 +132,9 @@ export const filtersControllerTestSuite = async () => {
 
     test('should return UNKNOWN status when FilterService returns invalid status', async () => {
       const filterService = sinon.createStubInstance(FilterService);
-      filterService.getRunStatus.resolves('UNKNOWN');
+      filterService.getRunInformation.resolves({
+        runStatus: RunStatus.UNKNOWN,
+      });
 
       const req = {
         params: {
@@ -137,9 +147,12 @@ export const filtersControllerTestSuite = async () => {
       };
 
       const filterController = new FilterController(filterService);
-      await filterController.getRunStatusHandler(req, res);
+      await filterController.getRunInformationHandler(req, res);
 
-      ok(filterService.getRunStatus.calledWith(999999), 'FilterService.getRunStatus should be called with run number');
+      ok(
+        filterService.getRunInformation.calledWith(999999),
+        'FilterService.getRunStatus should be called with run number',
+      );
       ok(res.status.calledWith(200), 'Response status should be 200');
       ok(res.json.calledWith({
         runStatus: RunStatus.UNKNOWN,

QualityControl/test/lib/services/BookkeepingService.test.js

@@ -256,31 +256,59 @@ export const bookkeepingServiceTestSuite = async () => {
         };
 
         nock(VALID_CONFIG.bookkeeping.url).get(runsPathPattern).reply(200, mockResponse);
-        const result = await bkpService.retrieveRunStatus(123);
-        strictEqual(result, RunStatus.ENDED);
+        const { runStatus } = await bkpService.retrieveRunInformation(123);
+        strictEqual(runStatus, RunStatus.ENDED);
+      });
+
+      test('should return run information when data is present', async () => {
+        const mockResponse = {
+          data: {
+            startTime: 1,
+            endTime: 2,
+            definition: null,
+            runQuality: 'good',
+            lhcBeamMode: 'PHYSICS',
+            detectorsQualities: [],
+          },
+        };
+
+        nock(VALID_CONFIG.bookkeeping.url).get(runsPathPattern).reply(200, mockResponse);
+        const {
+          startTime,
+          endTime,
+          definition,
+          runQuality,
+          lhcBeamMode,
+          detectorsQualities,
+          runStatus,
+        } = await bkpService.retrieveRunInformation(123);
+        const data = { startTime, endTime, definition, runQuality, lhcBeamMode, detectorsQualities };
+
+        deepStrictEqual(data, mockResponse.data);
+        ok(Object.values(RunStatus).includes(runStatus));
       });
 
       test('should return ONGOING status when timeO2End is not present', async () => {
         const mockResponse = { data: { timeO2End: undefined } };
 
         nock(VALID_CONFIG.bookkeeping.url).get(runsPathPattern).reply(200, mockResponse);
 
-        const result = await bkpService.retrieveRunStatus(456);
-        strictEqual(result, RunStatus.ONGOING);
+        const { runStatus } = await bkpService.retrieveRunInformation(456);
+        strictEqual(runStatus, RunStatus.ONGOING);
       });
 
       test('should return UNKNOWN status when no data is returned', async () => {
         nock(VALID_CONFIG.bookkeeping.url).get(runsPathPattern).reply(200, {});
 
-        const result = await bkpService.retrieveRunStatus(789);
-        strictEqual(result, RunStatus.UNKNOWN);
+        const { runStatus } = await bkpService.retrieveRunInformation(789);
+        strictEqual(runStatus, RunStatus.UNKNOWN);
       });
 
       test('should return UNKNOWN status when request fails', async () => {
         nock(VALID_CONFIG.bookkeeping.url).get(runsPathPattern).reply(500);
 
-        const result = await bkpService.retrieveRunStatus(1010);
-        strictEqual(result, RunStatus.UNKNOWN);
+        const { runStatus } = await bkpService.retrieveRunInformation(1010);
+        strictEqual(runStatus, RunStatus.UNKNOWN);
       });
 
       test('should return NOT_FOUND status when request fails', async () => {
@@ -293,15 +321,15 @@ export const bookkeepingServiceTestSuite = async () => {
           ],
         });
 
-        const result = await bkpService.retrieveRunStatus(1010);
-        strictEqual(result, RunStatus.NOT_FOUND);
+        const { runStatus } = await bkpService.retrieveRunInformation(1010);
+        strictEqual(runStatus, RunStatus.NOT_FOUND);
       });
 
       test('should return BOOKKEEPING_UNAVAILABLE status when service is not active', async () => {
         bkpService.active = false;
 
-        const result = await bkpService.retrieveRunStatus(123);
-        strictEqual(result, RunStatus.BOOKKEEPING_UNAVAILABLE);
+        const { runStatus } = await bkpService.retrieveRunInformation(123);
+        strictEqual(runStatus, RunStatus.BOOKKEEPING_UNAVAILABLE);
       });
     });
   });