chore: add availability status to the overviews (#3556)

* chore: add availability status to the overviews

fixes RHIDP-14338

assisted by cursor

* squash: re-gen api

* squash: add a changeset

* squash: tsc error fix

* squash: api-reports

Author: lholmquist

workspaces/orchestrator/.changeset/fresh-swans-complain.md

@@ -0,0 +1,6 @@
+---
+'@red-hat-developer-hub/backstage-plugin-orchestrator-backend': patch
+'@red-hat-developer-hub/backstage-plugin-orchestrator-common': patch
+---
+
+The updated overview of a workflow will have the availability property if the isAvailable prop is false

workspaces/orchestrator/plugins/orchestrator-backend/src/service/OrchestratorService.test.ts

@@ -63,7 +63,6 @@ const createInstancesMock = (size: number): ProcessInstance[] => {
 const instanceId = createInstanceIdMock(1);
 const definitionId = createDefinitionIdMock(1);
 const workflowInfo = createWorkflowInfoMock(1);
-const workflowOverview = createWorkflowOverviewMock(1);
 const workflowOverviews = createWorkflowOverviewsMock(3);
 const instance = createInstanceMock(1);
 const instances = createInstancesMock(3);
@@ -135,8 +134,21 @@ describe('OrchestratorService', () => {
   });
 
   describe('fetchWorkflowOverviews', () => {
+    const availabilityResponse = {
+      isAvailable: false,
+      statusCode: 503,
+      urlToFetch: `${serviceUrl}/management/processes/${definitionId}`,
+      reason: 'Service Unavailable',
+    };
+
     beforeEach(() => {
       jest.clearAllMocks();
+      sonataFlowServiceMock.pingWorkflowService = jest
+        .fn()
+        .mockResolvedValue(availabilityResponse);
+      dataIndexServiceMock.fetchWorkflowServiceUrls = jest
+        .fn()
+        .mockResolvedValue({ [definitionId]: serviceUrl });
     });
 
     it('should throw error when data index returns error', async () => {
@@ -161,6 +173,27 @@ describe('OrchestratorService', () => {
 
       expect(result).toHaveLength(workflowOverviews.length);
       expect(sonataFlowServiceMock.fetchWorkflowOverviews).toHaveBeenCalled();
+      expect(sonataFlowServiceMock.pingWorkflowService).not.toHaveBeenCalled();
+    });
+
+    it('pings unavailable workflows and sets availability on each overview', async () => {
+      sonataFlowServiceMock.fetchWorkflowOverviews = jest
+        .fn()
+        .mockResolvedValue([createWorkflowOverviewMock(1)]);
+      workflowCacheServiceMock.isAvailable = jest.fn().mockReturnValue(false);
+
+      const result = await orchestratorService.fetchWorkflowOverviews({});
+
+      expect(result).toHaveLength(1);
+      expect(result?.[0].isAvailable).toBe(false);
+      expect(result?.[0].availability).toEqual(availabilityResponse);
+      expect(
+        dataIndexServiceMock.fetchWorkflowServiceUrls,
+      ).toHaveBeenCalledTimes(1);
+      expect(sonataFlowServiceMock.pingWorkflowService).toHaveBeenCalledWith({
+        definitionId,
+        serviceUrl,
+      });
     });
   });
 
@@ -286,21 +319,111 @@ describe('OrchestratorService', () => {
   });
 
   describe('fetchWorkflowOverview', () => {
+    const availabilityResponse = {
+      isAvailable: false,
+      statusCode: 503,
+      urlToFetch: `${serviceUrl}/management/processes/${definitionId}`,
+      reason: 'Service Unavailable',
+    };
+
     beforeEach(() => {
       jest.clearAllMocks();
+      sonataFlowServiceMock.fetchWorkflowOverview = jest
+        .fn()
+        .mockResolvedValue(createWorkflowOverviewMock(1));
+      sonataFlowServiceMock.pingWorkflowService = jest
+        .fn()
+        .mockResolvedValue(availabilityResponse);
+      dataIndexServiceMock.fetchWorkflowServiceUrls = jest
+        .fn()
+        .mockResolvedValue({ [definitionId]: serviceUrl });
     });
 
-    it('should execute the operation', async () => {
+    it('sets isAvailable from cache when workflow is available', async () => {
       workflowCacheServiceMock.isAvailable = jest.fn().mockReturnValue(true);
+
+      const result = await orchestratorService.fetchWorkflowOverview({
+        definitionId,
+      });
+
+      expect(workflowCacheServiceMock.isAvailable).toHaveBeenCalledWith(
+        definitionId,
+      );
+      expect(result?.isAvailable).toBe(true);
+      expect(result?.availability).toBeUndefined();
+      expect(sonataFlowServiceMock.pingWorkflowService).not.toHaveBeenCalled();
+    });
+
+    it('pings workflow service and sets availability when workflow is unavailable', async () => {
+      workflowCacheServiceMock.isAvailable = jest.fn().mockReturnValue(false);
+
+      const result = await orchestratorService.fetchWorkflowOverview({
+        definitionId,
+      });
+
+      expect(result?.isAvailable).toBe(false);
+      expect(result?.availability).toEqual(availabilityResponse);
+      expect(dataIndexServiceMock.fetchWorkflowServiceUrls).toHaveBeenCalled();
+      expect(sonataFlowServiceMock.pingWorkflowService).toHaveBeenCalledWith({
+        definitionId,
+        serviceUrl,
+      });
+    });
+
+    it('returns undefined without setting availability when overview is not found', async () => {
+      workflowCacheServiceMock.isAvailable = jest.fn().mockReturnValue(false);
       sonataFlowServiceMock.fetchWorkflowOverview = jest
         .fn()
-        .mockResolvedValue(workflowOverview);
+        .mockResolvedValue(undefined);
 
       const result = await orchestratorService.fetchWorkflowOverview({
         definitionId,
       });
 
-      expect(result).toBeDefined();
+      expect(result).toBeUndefined();
+      expect(sonataFlowServiceMock.pingWorkflowService).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('pingWorkflowService', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('returns true when the workflow service is available', async () => {
+      sonataFlowServiceMock.pingWorkflowService = jest.fn().mockResolvedValue({
+        isAvailable: true,
+        statusCode: 200,
+        urlToFetch: `${serviceUrl}/management/processes/${definitionId}`,
+        reason: 'OK',
+      });
+
+      const result = await orchestratorService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(result).toBe(true);
+      expect(sonataFlowServiceMock.pingWorkflowService).toHaveBeenCalledWith({
+        definitionId,
+        serviceUrl,
+      });
+    });
+
+    it('returns false when the workflow service is unavailable', async () => {
+      sonataFlowServiceMock.pingWorkflowService = jest.fn().mockResolvedValue({
+        isAvailable: false,
+        statusCode: 503,
+        urlToFetch: `${serviceUrl}/management/processes/${definitionId}`,
+        reason: 'Service Unavailable',
+      });
+
+      const result = await orchestratorService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(result).toBe(false);
     });
   });
 

workspaces/orchestrator/plugins/orchestrator-backend/src/service/OrchestratorService.ts

@@ -134,13 +134,28 @@ export class OrchestratorService {
       targetEntity: args.targetEntity,
     });
 
-    return overviews?.map(overview => {
-      const updatedOverview = overview;
-      updatedOverview.isAvailable = this.workflowCacheService.isAvailable(
-        updatedOverview.workflowId,
-      );
-      return updatedOverview;
-    });
+    if (!overviews?.length) {
+      return overviews;
+    }
+
+    const serviceUrls = await this.dataIndexService.fetchWorkflowServiceUrls();
+
+    return Promise.all(
+      overviews.map(async overview => {
+        const updatedOverview = overview;
+        updatedOverview.isAvailable = this.workflowCacheService.isAvailable(
+          updatedOverview.workflowId,
+        );
+        if (!updatedOverview.isAvailable) {
+          updatedOverview.availability =
+            await this.sonataFlowService.pingWorkflowService({
+              definitionId: updatedOverview.workflowId,
+              serviceUrl: serviceUrls[updatedOverview.workflowId],
+            });
+        }
+        return updatedOverview;
+      }),
+    );
   }
 
   public async executeWorkflowAsCloudEvent(args: {
@@ -183,7 +198,18 @@ export class OrchestratorService {
       this.workflowCacheService.isAvailable(definitionId);
     const overview =
       await this.sonataFlowService.fetchWorkflowOverview(definitionId);
-    if (overview) overview.isAvailable = isWorkflowAvailable; // workflow overview is avaiable but the workflow itself is not
+    if (overview) {
+      overview.isAvailable = isWorkflowAvailable; // workflow overview is avaiable but the workflow itself is not
+      if (!isWorkflowAvailable) {
+        overview.availability =
+          await this.sonataFlowService.pingWorkflowService({
+            definitionId,
+            serviceUrl: (
+              await this.dataIndexService.fetchWorkflowServiceUrls()
+            )[definitionId],
+          });
+      }
+    }
     return overview;
   }
 
@@ -211,6 +237,6 @@ export class OrchestratorService {
       definitionId,
       serviceUrl,
     });
-    return isServiceUp;
+    return isServiceUp.isAvailable;
   }
 }

workspaces/orchestrator/plugins/orchestrator-backend/src/service/SonataFlowService.test.ts

@@ -667,6 +667,97 @@ describe('SonataFlowService', () => {
     });
   });
 
+  describe('pingWorkflowService', () => {
+    const urlToFetch = `${serviceUrl}/management/processes/${definitionId}`;
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('returns available when the management endpoint responds ok', async () => {
+      setupTest({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: {},
+      });
+
+      const result = await sonataFlowService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(fetch).toHaveBeenCalledWith(urlToFetch);
+      expect(result).toEqual({
+        isAvailable: true,
+        statusCode: 200,
+        urlToFetch,
+        reason: 'OK',
+      });
+    });
+
+    it('returns unavailable with status details when the management endpoint fails', async () => {
+      setupTest({
+        ok: false,
+        status: 503,
+        statusText: 'Service Unavailable',
+        json: {},
+      });
+
+      const result = await sonataFlowService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(result).toEqual({
+        isAvailable: false,
+        statusCode: 503,
+        urlToFetch,
+        reason: 'Service Unavailable',
+      });
+    });
+
+    it('returns unavailable with a default reason when status text is missing', async () => {
+      setupTest({
+        ok: false,
+        status: 500,
+        json: {},
+      });
+
+      const result = await sonataFlowService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(result).toEqual({
+        isAvailable: false,
+        statusCode: 500,
+        urlToFetch,
+        reason: 'Unknown reason',
+      });
+    });
+
+    it('returns unavailable when fetch throws an error', async () => {
+      const errorMessage = 'Network Error';
+      global.fetch = jest.fn().mockRejectedValue(new Error(errorMessage));
+
+      const result = await sonataFlowService.pingWorkflowService({
+        definitionId,
+        serviceUrl,
+      });
+
+      expect(result).toEqual({
+        isAvailable: false,
+        statusCode: 500,
+        urlToFetch,
+        reason: `Failed to fetch from ${urlToFetch}: ${errorMessage}`,
+      });
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        `Failed to fetch from ${urlToFetch}: ${errorMessage}`,
+      );
+    });
+  });
+
   describe('fetchWorkflowOverviews', () => {
     const NOW = new Date('2024-06-01T12:00:00Z');
     const WITHIN_30_DAYS = '2024-05-15T12:00:00Z';

workspaces/orchestrator/plugins/orchestrator-backend/src/service/SonataFlowService.ts

@@ -27,6 +27,7 @@ import {
   fromWorkflowSource,
   ProcessInstanceStateValues,
   ProcessInstanceVariables,
+  WorkflowAvailabilityResponse,
   WorkflowDefinition,
   WorkflowExecutionResponse,
   WorkflowInfo,
@@ -511,7 +512,7 @@ export class SonataFlowService {
   public async pingWorkflowService(args: {
     definitionId: string;
     serviceUrl: string;
-  }): Promise<boolean> {
+  }): Promise<WorkflowAvailabilityResponse> {
     const urlToFetch = `${args.serviceUrl}/management/processes/${args.definitionId}`;
     let response: Response | undefined;
     try {
@@ -520,9 +521,19 @@ export class SonataFlowService {
       this.logger.error(
         `Failed to fetch from ${urlToFetch}: ${(error as Error).message}`,
       );
-      return false;
+      return {
+        isAvailable: false,
+        statusCode: 500,
+        urlToFetch,
+        reason: `Failed to fetch from ${urlToFetch}: ${(error as Error).message}`,
+      };
     }
-    return response.ok;
+    return {
+      isAvailable: response.ok,
+      statusCode: response.status || 500,
+      urlToFetch,
+      reason: response.statusText || 'Unknown reason',
+    };
   }
 
   private async handleWorkflowServiceResponse(