improve error handling and enrich contextual information

Enhance error propagation and contextual data in HTTP client operations by introducing a detailed «HttpError» utility. Update test cases to validate enriched error messages, including status text and request details.

Refactor installation steps to incorporate structured error handling using «StepError», providing detailed context and possible causes for failures. Improve diagnostic messaging during installation, including step-specific details and enriched error descriptions.

Add utility functions to extract status codes and derive potential causes for issues, improving debugging capabilities. Update related unit tests to ensure comprehensive coverage of new behaviors.

Author: guidomodarelli

public/dashboard-assistant/modules/common/http/infrastructure/http-error.ts

@@ -0,0 +1,154 @@
+/*
+ * Copyright Wazuh Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const SENSITIVE_KEY_PATTERN = /(key|token|secret|password|authorization)$/i;
+const MAX_BODY_LENGTH = 1000;
+
+export class HttpError extends Error {
+  public response?: Response;
+  public status?: number;
+  public statusText?: string;
+  public request?: { method: string; url: string; body?: string };
+  public responseBodyOmitted?: boolean;
+
+  private constructor(message: string) {
+    super(message);
+    this.name = 'HttpError';
+  }
+
+  public static async create(
+    response: Response,
+    options: RequestInit & { method: string },
+    url: string,
+  ): Promise<HttpError> {
+    const method = options.method.toUpperCase();
+    const sanitizedUrl = this.sanitizeUrl(url);
+    const hasResponseBody = await this.hasMeaningfulBody(response);
+
+    const statusText = response.statusText?.trim();
+    const statusSummary = statusText
+      ? `${response.status} ${statusText}`
+      : `${response.status}`;
+
+    const message = this.buildFailureMessage({
+      method,
+      url: sanitizedUrl,
+      statusSummary,
+      hasResponseBody,
+    });
+
+    const error = new HttpError(message);
+    error.response = response;
+    error.status = response.status;
+    error.statusText = response.statusText;
+    error.request = {
+      method,
+      url: sanitizedUrl,
+      body: this.sanitizeRequestBody(options.body ?? undefined),
+    };
+    if (hasResponseBody) {
+      error.responseBodyOmitted = true;
+    }
+
+    return error;
+  }
+
+  private static buildFailureMessage(params: {
+    method: string;
+    url: string;
+    statusSummary: string;
+    hasResponseBody: boolean;
+  }): string {
+    const { method, url, statusSummary, hasResponseBody } = params;
+
+    const messageParts = [
+      `HTTP ${method} ${url} failed with status ${statusSummary}`,
+      hasResponseBody
+        ? 'Response body omitted due to security policy'
+        : undefined,
+    ].filter(Boolean);
+
+    return messageParts.join('. ');
+  }
+
+  private static sanitizeUrl(url: string): string {
+    try {
+      const base =
+        typeof window !== 'undefined' && window.location?.origin
+          ? window.location.origin
+          : 'http://localhost';
+      const parsed = new URL(url, base);
+      parsed.searchParams.forEach((value, key) => {
+        if (SENSITIVE_KEY_PATTERN.test(key)) {
+          parsed.searchParams.delete(key);
+        }
+      });
+
+      if (!url.startsWith('http')) {
+        return (
+          `${parsed.pathname}${parsed.search}${parsed.hash}` || parsed.pathname
+        );
+      }
+
+      return parsed.toString();
+    } catch (error) {
+      return url;
+    }
+  }
+
+  private static async hasMeaningfulBody(response: Response): Promise<boolean> {
+    try {
+      const body = await response.clone().text();
+      return Boolean(body.trim());
+    } catch (error) {
+      return false;
+    }
+  }
+
+  private static sanitizeStructuredValue(value: unknown): unknown {
+    if (value == null) {
+      return value;
+    }
+
+    if (Array.isArray(value)) {
+      return value.map(item => this.sanitizeStructuredValue(item));
+    }
+
+    if (typeof value === 'object') {
+      return Object.entries(value as Record<string, unknown>).reduce<
+        Record<string, unknown>
+      >((acc, [key, entryValue]) => {
+        if (typeof entryValue !== 'string' || !SENSITIVE_KEY_PATTERN.test(key)) {
+            acc[key] = this.sanitizeStructuredValue(entryValue);
+        }
+        return acc;
+      }, {});
+    }
+
+    return value;
+  }
+
+  private static sanitizeRequestBody(
+    body?: BodyInit | null,
+  ): string | undefined {
+    if (!body) {
+      return undefined;
+    }
+
+    if (typeof body === 'string') {
+      try {
+        const parsed = JSON.parse(body);
+        const sanitized = this.sanitizeStructuredValue(parsed);
+        return JSON.stringify(sanitized);
+      } catch (error) {
+        return body.length > MAX_BODY_LENGTH
+          ? `${body.slice(0, MAX_BODY_LENGTH)}...`
+          : body;
+      }
+    }
+
+    return '';
+  }
+}

public/dashboard-assistant/modules/common/http/infrastructure/window-fetch-http-client.test.ts

@@ -8,7 +8,9 @@ import { WindowFetchHttpClient } from './window-fetch-http-client';
 interface JsonResponse {
   ok: boolean;
   status: number;
+  statusText?: string;
   json: () => Promise<Record<string, unknown>>;
+  clone: () => { text: () => Promise<string> };
 }
 
 describe('WindowFetchHttpClient', () => {
@@ -36,6 +38,9 @@ describe('WindowFetchHttpClient', () => {
       ok: true,
       status: 200,
       json: async () => payload,
+      clone: () => ({
+        text: async () => JSON.stringify(payload),
+      }),
     };
     const fetchSpy = jest.fn().mockResolvedValue(mockResponse);
     // @ts-ignore
@@ -58,6 +63,9 @@ describe('WindowFetchHttpClient', () => {
       ok: true,
       status: 200,
       json: async () => ({}),
+      clone: () => ({
+        text: async () => JSON.stringify({}),
+      }),
     };
     const fetchSpy = jest.fn().mockResolvedValue(mockResponse);
     // @ts-ignore
@@ -93,19 +101,34 @@ describe('WindowFetchHttpClient', () => {
     );
   });
 
-  it('propagates HTTP errors with response attached', async () => {
+  it('propagates HTTP errors with contextual information attached', async () => {
+    expect.assertions(5);
+    const errorPayload = { message: 'boom' };
     const mockResponse: JsonResponse = {
       ok: false,
       status: 500,
-      json: async () => ({ message: 'boom' }),
+      statusText: 'Internal Server Error',
+      json: async () => errorPayload,
+      clone: () => ({
+        text: async () => JSON.stringify(errorPayload),
+      }),
     };
     const fetchSpy = jest.fn().mockResolvedValue(mockResponse);
     // @ts-ignore
     window.fetch = fetchSpy;
     const client = new WindowFetchHttpClient();
-    await expect(client.delete('/x')).rejects.toMatchObject({
-      message: 'HTTP error! status: 500',
-      response: mockResponse,
-    });
+
+    try {
+      await client.delete('/x');
+      throw new Error('Expected HTTP error to be thrown');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toContain(
+        'HTTP DELETE /x failed with status 500 Internal Server Error'
+      );
+      expect((error as Error).message).toContain('Response body: {"message":"boom"}');
+      expect((error as { response?: JsonResponse }).response).toBe(mockResponse);
+      expect((error as { request?: { method: string } }).request?.method).toBe('DELETE');
+    }
   });
 });

public/dashboard-assistant/modules/common/http/infrastructure/window-fetch-http-client.ts

@@ -4,6 +4,7 @@
  */
 
 import type { HttpClient } from '../domain/entities/http-client';
+import { HttpError } from './http-error';
 
 export class WindowFetchHttpClient implements HttpClient {
   private defaultHeaders = { 'osd-xsrf': 'kibana' };
@@ -28,8 +29,7 @@ export class WindowFetchHttpClient implements HttpClient {
 
     return window.fetch(url, options).then(async (response) => {
       if (!response.ok) {
-        const error = new Error(`HTTP error! status: ${response.status}`);
-        (error as any).response = response;
+        const error = await HttpError.create(response, options as RequestInit & { method: string }, url);
         throw error;
       }
       return response.json();

public/dashboard-assistant/modules/installation-manager/domain/entities/installation-progress-manager.test.ts

@@ -65,7 +65,7 @@ describe('InstallationProgressManager', () => {
 
     const p = mgr.getProgress();
     expect(p.getSteps()[0].state).toBe(ExecutionState.FAILED);
-    expect(p.getSteps()[0].message).toBe('boom-msg');
+    expect(p.getSteps()[0].message).toBe('boom-msg Additional details: boom');
     expect(p.getSteps()[0].error).toBeInstanceOf(Error);
     expect(p.hasFailedSteps()).toBe(true);
     expect(p.getFailedSteps().length).toBe(1);

public/dashboard-assistant/modules/installation-manager/infrastructure/installation-manager.ts

@@ -48,9 +48,13 @@ export class InstallationManager implements IInstallationManager {
     } catch (error) {
       const progress = progressManager.getProgress();
       const failedSteps = progress.getFailedSteps();
+      const firstFailedStep = failedSteps[0];
+      const stepContext = firstFailedStep ? `during step "${firstFailedStep.stepName}"` : 'at an unknown step';
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
       return {
         success: false,
-        message: `Installation failed: ${error}`,
+        message: `Installation failed ${stepContext}: ${errorMessage}`,
         progress,
         data: context.toObject(),
         errors: failedSteps.map((step) => ({

public/dashboard-assistant/modules/installation-manager/infrastructure/steps/create-agent-step.ts

@@ -13,6 +13,7 @@ import {
   InstallationAIAssistantStep,
   InstallAIDashboardAssistantDto,
 } from '../../domain';
+import { StepError } from '../utils/step-error';
 
 export class CreateAgentStep extends InstallationAIAssistantStep {
   constructor() {
@@ -62,10 +63,28 @@ export class CreateAgentStep extends InstallationAIAssistantStep {
     request: InstallAIDashboardAssistantDto,
     context: InstallationContext
   ): Promise<void> {
-    const agent = await getUseCases().createAgent(
-      this.createAgentDto(request, context.get('modelId'))
-    );
-    context.set('agentId', agent.id);
+    const details: Record<string, unknown> = {
+      provider: request.selected_provider,
+    };
+
+    if (context.has('modelId')) {
+      details.modelId = context.get('modelId');
+    }
+
+    try {
+      const dto = this.createAgentDto(request, context.get('modelId'));
+      details.agentName = dto.name;
+      const agent = await getUseCases().createAgent(dto);
+      details.agentId = agent?.id;
+      context.set('agentId', agent.id);
+    } catch (error) {
+      throw StepError.create({
+        stepName: this.getName(),
+        action: 'creating the assistant agent',
+        cause: error,
+        details,
+      });
+    }
   }
 
   public getSuccessMessage(): string {

public/dashboard-assistant/modules/installation-manager/infrastructure/steps/create-connector-step.ts

@@ -11,6 +11,7 @@ import {
   InstallAIDashboardAssistantDto,
 } from '../../domain';
 import { getUseCases } from '../../../../services/ml-use-cases.service';
+import { StepError } from '../utils/step-error';
 
 export class CreateConnectorStep extends InstallationAIAssistantStep {
   constructor() {
@@ -41,8 +42,26 @@ export class CreateConnectorStep extends InstallationAIAssistantStep {
     request: InstallAIDashboardAssistantDto,
     context: InstallationContext
   ): Promise<void> {
-    const connector = await getUseCases().createConnector(this.buildDto(request));
-    context.set('connectorId', connector.id);
+    const details: Record<string, unknown> = {
+      provider: request.selected_provider,
+      endpoint: request.api_url,
+      modelId: request.model_id,
+    };
+
+    try {
+      const dto = this.buildDto(request);
+      details.connectorName = dto.name;
+      const connector = await getUseCases().createConnector(dto);
+      details.connectorId = connector?.id;
+      context.set('connectorId', connector.id);
+    } catch (error) {
+      throw StepError.create({
+        stepName: this.getName(),
+        action: 'creating the ML Commons connector',
+        cause: error,
+        details,
+      });
+    }
   }
 
   getSuccessMessage(): string {

public/dashboard-assistant/modules/installation-manager/infrastructure/steps/create-model-step.ts

@@ -10,6 +10,7 @@ import {
   InstallationAIAssistantStep,
   InstallAIDashboardAssistantDto,
 } from '../../domain';
+import { StepError } from '../utils/step-error';
 
 export class CreateModelStep extends InstallationAIAssistantStep {
   constructor() {
@@ -31,8 +32,27 @@ export class CreateModelStep extends InstallationAIAssistantStep {
     request: InstallAIDashboardAssistantDto,
     context: InstallationContext
   ): Promise<void> {
-    const model = await getUseCases().createModel(this.buildDto(request, context));
-    context.set('modelId', model.id);
+    const details: Record<string, unknown> = {
+      provider: request.selected_provider,
+    };
+
+    if (context.has('connectorId')) {
+      details.connectorId = context.get('connectorId');
+    }
+
+    try {
+      const dto = this.buildDto(request, context);
+      const model = await getUseCases().createModel(dto);
+      details.modelId = model?.id;
+      context.set('modelId', model.id);
+    } catch (error) {
+      throw StepError.create({
+        stepName: this.getName(),
+        action: 'creating the ML Commons model',
+        cause: error,
+        details,
+      });
+    }
   }
 
   getSuccessMessage(): string {