feat: test integration connection (#669)

* feat: add test integration for pi-hole

* refactor: test integration for pi-hole

* fix: multiple secrets of same type could be used for integration creation

* fix: remove integration test connection test and add mock for test-connection function

* fix: add missing onUpdateFn to mysql integration secrets

* fix: format issues

* feat: add home assistant test connection

* fix: deepsource issues

* test: add system integration tests for test connection

* fix: add before all for pulling home assistant image

* test: add unit tests for handleTestConnectionResponseAsync

* test: add unit test for testConnectionAsync

* test: add mroe tests to integration-test-connection

* fix: deepsource issues

* fix: deepsource issue

* chore: address pull request feedback

packages/integrations/src/base/creator.ts

@@ -0,0 +1,16 @@
+import type { IntegrationKind } from "@homarr/definitions";
+
+import { HomeAssistantIntegration } from "../homeassistant/homeassistant-integration";
+import { PiHoleIntegration } from "../pi-hole/pi-hole-integration";
+import type { IntegrationInput } from "./integration";
+
+export const integrationCreatorByKind = (kind: IntegrationKind, integration: IntegrationInput) => {
+  switch (kind) {
+    case "piHole":
+      return new PiHoleIntegration(integration);
+    case "homeAssistant":
+      return new HomeAssistantIntegration(integration);
+    default:
+      throw new Error(`Unknown integration kind ${kind}`);
+  }
+};

packages/integrations/src/base/integration.ts

@@ -1,16 +1,25 @@
+import { extractErrorMessage } from "@homarr/common";
 import type { IntegrationSecretKind } from "@homarr/definitions";
+import { logger } from "@homarr/log";
+import type { TranslationObject } from "@homarr/translation";
+import { z } from "@homarr/validation";
 
+import { IntegrationTestConnectionError } from "./test-connection-error";
 import type { IntegrationSecret } from "./types";
 
+const causeSchema = z.object({
+  code: z.string(),
+});
+
+export interface IntegrationInput {
+  id: string;
+  name: string;
+  url: string;
+  decryptedSecrets: IntegrationSecret[];
+}
+
 export abstract class Integration {
-  constructor(
-    protected integration: {
-      id: string;
-      name: string;
-      url: string;
-      decryptedSecrets: IntegrationSecret[];
-    },
-  ) {}
+  constructor(protected integration: IntegrationInput) {}
 
   protected getSecretValue(kind: IntegrationSecretKind) {
     const secret = this.integration.decryptedSecrets.find((secret) => secret.kind === kind);
@@ -19,4 +28,87 @@ export abstract class Integration {
     }
     return secret.value;
   }
+
+  /**
+   * Test the connection to the integration
+   * @throws {IntegrationTestConnectionError} if the connection fails
+   */
+  public abstract testConnectionAsync(): Promise<void>;
+
+  protected async handleTestConnectionResponseAsync({
+    queryFunctionAsync,
+    handleResponseAsync,
+  }: {
+    queryFunctionAsync: () => Promise<Response>;
+    handleResponseAsync?: (response: Response) => Promise<void>;
+  }): Promise<void> {
+    const response = await queryFunctionAsync().catch((error) => {
+      if (error instanceof Error) {
+        const cause = causeSchema.safeParse(error.cause);
+        if (!cause.success) {
+          logger.error("Failed to test connection", error);
+          throw new IntegrationTestConnectionError("commonError", extractErrorMessage(error));
+        }
+
+        if (cause.data.code === "ENOTFOUND") {
+          logger.error("Failed to test connection: Domain not found");
+          throw new IntegrationTestConnectionError("domainNotFound");
+        }
+
+        if (cause.data.code === "ECONNREFUSED") {
+          logger.error("Failed to test connection: Connection refused");
+          throw new IntegrationTestConnectionError("connectionRefused");
+        }
+
+        if (cause.data.code === "ECONNABORTED") {
+          logger.error("Failed to test connection: Connection aborted");
+          throw new IntegrationTestConnectionError("connectionAborted");
+        }
+      }
+
+      logger.error("Failed to test connection", error);
+
+      throw new IntegrationTestConnectionError("commonError", extractErrorMessage(error));
+    });
+
+    if (response.status >= 400) {
+      logger.error(`Failed to test connection with status code ${response.status}`);
+
+      throwErrorByStatusCode(response.status);
+    }
+
+    await handleResponseAsync?.(response);
+  }
 }
+
+export interface TestConnectionError {
+  key: Exclude<keyof TranslationObject["integration"]["testConnection"]["notification"], "success">;
+  message?: string;
+}
+export type TestConnectionResult =
+  | {
+      success: false;
+      error: TestConnectionError;
+    }
+  | {
+      success: true;
+    };
+
+const throwErrorByStatusCode = (statusCode: number) => {
+  switch (statusCode) {
+    case 400:
+      throw new IntegrationTestConnectionError("badRequest");
+    case 401:
+      throw new IntegrationTestConnectionError("unauthorized");
+    case 403:
+      throw new IntegrationTestConnectionError("forbidden");
+    case 404:
+      throw new IntegrationTestConnectionError("notFound");
+    case 500:
+      throw new IntegrationTestConnectionError("internalServerError");
+    case 503:
+      throw new IntegrationTestConnectionError("serviceUnavailable");
+    default:
+      throw new IntegrationTestConnectionError("commonError");
+  }
+};

packages/integrations/src/base/test-connection-error.ts

@@ -0,0 +1,26 @@
+import { FlattenError } from "@homarr/common";
+import { z } from "@homarr/validation";
+
+import type { TestConnectionError } from "./integration";
+
+export class IntegrationTestConnectionError extends FlattenError {
+  constructor(
+    public key: TestConnectionError["key"],
+    public detailMessage?: string,
+  ) {
+    super("Checking integration connection failed", { key, message: detailMessage });
+  }
+}
+
+const schema = z.object({
+  key: z.custom<TestConnectionError["key"]>((value) => z.string().parse(value)),
+  message: z.string().optional(),
+});
+export const convertIntegrationTestConnectionError = (error: unknown) => {
+  const result = schema.safeParse(error);
+  if (!result.success) {
+    return;
+  }
+
+  return result.data;
+};