homarr/packages/integrations/src/unraid/unraid-integration.ts

import dayjs from "dayjs";
import type { fetch as undiciFetch } from "undici/types/fetch";

import { ResponseError } from "@homarr/common/server";
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import { createLogger } from "@homarr/core/infrastructure/logs";

import { HandleIntegrationErrors } from "../base/errors/decorator";
import type { IntegrationTestingInput } from "../base/integration";
import { Integration } from "../base/integration";
import type { TestingResult } from "../base/test-connection/test-connection-service";
import type { ISystemHealthMonitoringIntegration } from "../interfaces/health-monitoring/health-monitoring-integration";
import type { SystemHealthMonitoring } from "../interfaces/health-monitoring/health-monitoring-types";
import type { UnraidSystemInfo } from "./unraid-types";
import { unraidSystemInfoSchema } from "./unraid-types";

const logger = createLogger({ module: "UnraidIntegration" });

@HandleIntegrationErrors([])
export class UnraidIntegration extends Integration implements ISystemHealthMonitoringIntegration {
  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    await this.queryGraphQLAsync<{ info: UnraidSystemInfo }>(
      `
      query {
        info {
          os { platform }
        }
      }
      `,
      input.fetchAsync,
    );

    return { success: true };
  }

  public async getSystemInfoAsync(): Promise<SystemHealthMonitoring> {
    const systemInfo = await this.getSystemInformationAsync();

    const cpuUtilization = systemInfo.metrics.cpu.cpus.reduce((acc, val) => acc + val.percentTotal, 0);
    const cpuCount = systemInfo.metrics.cpu.cpus.length;
    let cpuUtilizationNormalized = 0;
    if (cpuCount > 0) {
      cpuUtilizationNormalized = cpuUtilization / cpuCount;
    }

    const totalMemory = systemInfo.metrics.memory.total;
    const usedMemory = Math.max(totalMemory - systemInfo.metrics.memory.available, 0);
    const uptime = dayjs(systemInfo.info.os.uptime);

    return {
      version: systemInfo.info.os.release,
      cpuModelName: systemInfo.info.cpu.brand,
      cpuUtilization: cpuUtilizationNormalized,
      memUsedInBytes: usedMemory,
      memAvailableInBytes: totalMemory - usedMemory,
      uptime: dayjs().diff(uptime, "seconds"),
      network: null, // Not implemented, see https://github.com/unraid/api/issues/1602
      loadAverage: null,
      rebootRequired: false,
      availablePkgUpdates: 0,
      cpuTemp: undefined, // Not implemented, see https://github.com/unraid/api/issues/1597
      fileSystem: systemInfo.array.disks.map((disk) => ({
        deviceName: disk.name,
        used: `${disk.fsUsed * 1024}`, // API is in KiB (kibibytes), convert to bytes
        available: `${(disk.size - disk.fsUsed) * 1024}`, // free space left on the disk, API is in KiB (kibibytes)
        percentage: (disk.fsUsed / disk.size) * 100, // The units are the same, therefore the actual unit is irrelevant
      })),
      smart: systemInfo.array.disks.map((disk) => ({
        deviceName: disk.name,
        temperature: disk.temp ?? null,
        overallStatus: disk.status,
        // See ArrayDiskStatus from https://studio.apollographql.com/public/Unraid-API/variant/current/explorer
        healthy: disk.status === "DISK_OK",
      })),
      gpu: [],
    };
  }

  private async getSystemInformationAsync(): Promise<UnraidSystemInfo> {
    logger.debug("Retrieving system information", {
      url: this.url("/graphql"),
    });

    const query = `
      query {
        metrics {
          cpu {
            percentTotal
            cpus {
              percentTotal
            }
          },
          memory {
            available
            used
            free
            total
            swapFree
            swapTotal
            swapUsed
            percentTotal
          }
        }
        array {
          state
          capacity {
            disks {
              free
              total
              used
            }
          }
          disks {
            name
            size
            fsFree
            fsUsed
            status
            temp
          }
        }
        info {
          devices {
            network {
              speed
              dhcp
              model
              model
            }
          }
          os {
            platform,
            distro,
            release,
            uptime
          },
          cpu {
            manufacturer,
            brand,
            cores,
            threads
          }
        }
      }
    `;

    const response = await this.queryGraphQLAsync<UnraidSystemInfo>(query);
    const result = await unraidSystemInfoSchema.parseAsync(response);

    logger.debug("Retrieved system information", {
      url: this.url("/graphql"),
    });

    return result;
  }

  private async queryGraphQLAsync<T>(
    query: string,
    fetchAsync: typeof undiciFetch = fetchWithTrustedCertificatesAsync,
  ): Promise<T> {
    const url = this.url("/graphql");
    const apiKey = this.getSecretValue("apiKey");

    logger.debug("Sending GraphQL query", {
      url: url.toString(),
    });

    const response = await fetchAsync(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey,
      },
      body: JSON.stringify({ query }),
    });

    if (!response.ok) {
      throw new ResponseError(response);
    }

    const json = (await response.json()) as { data: T; errors?: { message: string }[] };

    if (json.errors) {
      throw new Error(`GraphQL errors: ${json.errors.map((error) => error.message).join(", ")}`);
    }

    return json.data;
  }
}