Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

38.7 KB
Raw Blame
import { readMemoryObservation } from '@/utils/memoryObservation';
import type { MemoryObservation } from '@/types/api';
import { onCleanup, createEffect, createSignal, untrack, type Accessor } from 'solid-js';
import { apiFetchJSON, getOrgID } from '@/utils/apiClient';
import { normalizeOrgScope } from '@/utils/orgScope';
import { eventBus } from '@/stores/events';
import {
  normalizeSourcePlatformScopes,
  resolvePlatformTypeFromSources,
} from '@/utils/sourcePlatforms';
import { canonicalDiscoveryResourceType } from '@/utils/discoveryTarget';
import { normalizeDiskArray } from '@/utils/format';
import { parseBackupTimestampMs } from '@/utils/backupTimestamp';
import { getWorkloadDiskUsagePercent } from '@/utils/workloadDiskUsage';
import {
  getWorkloadCPUFraction,
  isDockerManagedAppContainer,
  resolveWorkloadTypeFromString,
} from '@/utils/workloads';
import { getPreferredResourceKubernetesContext } from '@/utils/resourceIdentity';
import { getExplicitResourceClusterName } from '@/utils/agentResources';
import type { WorkloadGuest } from '@/types/workloads';
import type { HostRAIDArray } from '@/types/api';
import type {
  Resource,
  ResourceActionReadiness,
  ResourceAvailabilityMeta,
  ResourceDiscoveryTarget,
  ResourceMetricsTarget,
  ResourceVMwareTag,
} from '@/types/resource';

const WORKLOADS_URL = '/api/resources?type=vm,system-container,app-container,pod';
const WORKLOADS_PAGE_LIMIT = 500;
const WORKLOADS_PAGE_CONCURRENCY = 4;
// This is a safety valve for malformed pagination metadata, not a truncation
// policy. Estates beyond the guard fail explicitly instead of presenting a
// silently incomplete workload table.
const WORKLOADS_MAX_PAGES = 100;
const WORKLOADS_CACHE_MAX_AGE_MS = 15_000;

type APIMetricValue = {
  observation?: MemoryObservation;
  value?: number;
  used?: number;
  total?: number;
  percent?: number;
  unit?: string;
};

type APINetworkInterface = {
  name?: string;
  mac?: string;
  addresses?: string[];
  rxBytes?: number;
  txBytes?: number;
};

type APIDiskInfo = {
  device?: string;
  mountpoint?: string;
  filesystem?: string;
  total?: number;
  used?: number;
  free?: number;
};

type APIResource = {
  id: string;
  type?: string;
  name?: string;
  status?: string;
  health?: { verdict?: string; reasons?: Array<{ code?: string; detail?: string }> };
  uptime?: number;
  lastSeen?: string;
  sources?: string[];
  platformScopes?: string[];
  metricsTarget?: ResourceMetricsTarget;
  canonicalIdentity?: {
    primaryId?: string;
    aliases?: string[];
    supersededIds?: string[];
  };
  identity?: {
    machineId?: string;
    hostnames?: string[];
    ipAddresses?: string[];
    clusterName?: string;
  };
  metrics?: {
    cpu?: APIMetricValue;
    memory?: APIMetricValue;
    disk?: APIMetricValue;
    netIn?: APIMetricValue;
    netOut?: APIMetricValue;
    diskRead?: APIMetricValue;
    diskWrite?: APIMetricValue;
  };
  parentId?: string;
  parentName?: string;
  tags?: string[];
  vmid?: number;
  node?: string;
  instance?: string;
  proxmox?: {
    sourceId?: string;
    runtimeStatus?: string;
    nodeName?: string;
    clusterName?: string;
    instance?: string;
    vmid?: number;
    cpus?: number;
    uptime?: number;
    template?: boolean;
    lastBackup?: string;
    backupInProgress?: boolean;
    disks?: APIDiskInfo[];
    diskStatusReason?: string;
    guestAgentStatus?: string;
    guestAgentExpected?: boolean;
    networkInterfaces?: APINetworkInterface[];
    lock?: string;
    swapUsed?: number;
    swapTotal?: number;
    balloon?: number;
    memoryCache?: number;
    isOci?: boolean;
    osTemplate?: string;
    osName?: string;
    osVersion?: string;
  };
  virtualMachine?: {
    runtimeState?: string;
    hypervisor?: string;
    vcpus?: number;
  };
  agent?: {
    agentId?: string;
    hostname?: string;
    uptimeSeconds?: number;
    osName?: string;
    osVersion?: string;
    agentVersion?: string;
    networkInterfaces?: APINetworkInterface[];
    disks?: APIDiskInfo[];
    raid?: HostRAIDArray[];
    stale?: boolean;
  };
  docker?: {
    containerId?: string;
    hostname?: string;
    image?: string;
    imageName?: string;
    imageRef?: string;
    uptimeSeconds?: number;
    runtime?: string;
    runtimeVersion?: string;
    dockerVersion?: string;
    collectionMode?: string;
    hostSourceId?: string;
    updateStatus?: WorkloadGuest['updateStatus'];
  };
  kubernetes?: {
    clusterId?: string;
    agentId?: string;
    clusterName?: string;
    namespace?: string;
    context?: string;
    nodeName?: string;
    podUid?: string;
    image?: string;
    uptimeSeconds?: number;
  };
  vmware?: {
    connectionName?: string;
    vcenterHost?: string;
    datacenterName?: string;
    clusterName?: string;
    runtimeHostName?: string;
    managedObjectId?: string;
    powerState?: string;
    guestOsFamily?: string;
    cpuCount?: number;
    tags?: ResourceVMwareTag[];
  };
  discoveryTarget?: {
    resourceType?: string;
    agentId?: string;
    resourceId?: string;
    hostname?: string;
  };
  availability?: ResourceAvailabilityMeta;
  availabilityChecks?: ResourceAvailabilityMeta[];
  actionReadiness?: ResourceActionReadiness[];
};

const buildAlertResourceIds = (resource: APIResource): string[] => {
  const candidates = [
    resource.metricsTarget?.resourceId,
    resource.proxmox?.sourceId,
    resource.canonicalIdentity?.primaryId,
    ...(resource.canonicalIdentity?.aliases ?? []),
    ...(resource.canonicalIdentity?.supersededIds ?? []),
    resource.id,
  ];
  return [...new Set(candidates.map((value) => value?.trim()).filter(Boolean) as string[])];
};

type APIListResponse = {
  data?: APIResource[];
  resources?: APIResource[];
  meta?: {
    page?: number;
    limit?: number;
    total?: number;
    totalPages?: number;
  };
};

type WorkloadsCacheEntry = {
  workloads: WorkloadGuest[];
  cachedAt: number;
  sharedFetch: Promise<WorkloadGuest[]> | null;
};

const workloadsCaches = new Map<string, WorkloadsCacheEntry>();

const getWorkloadsCacheEntry = (orgScope: string): WorkloadsCacheEntry => {
  const existing = workloadsCaches.get(orgScope);
  if (existing) {
    return existing;
  }
  const created: WorkloadsCacheEntry = {
    workloads: [],
    cachedAt: 0,
    sharedFetch: null,
  };
  workloadsCaches.set(orgScope, created);
  return created;
};

// Workload objects are produced by one canonical mapper and never mutated
// after construction, so their property order is stable and one serialization
// per row object is a valid immutable signature. The WeakMap keeps reused row
// objects from being re-serialized on every refresh.
const workloadRowSignatures = new WeakMap<WorkloadGuest, string>();

const workloadSignature = (guest: WorkloadGuest): string => {
  const cached = workloadRowSignatures.get(guest);
  if (cached !== undefined) return cached;
  const signature = JSON.stringify(guest);
  workloadRowSignatures.set(guest, signature);
  return signature;
};

// Rebuilding every row object on each refresh made row identity churn even
// for guests whose data did not change, forcing keyed table rows to re-render
// estate-wide on every metrics tick. Reusing the previous row object whenever
// its serialized form is unchanged keeps referential identity stable, and
// returning the previous array itself when nothing changed lets those
// refreshes skip downstream work entirely.
const reconcileWorkloadRowIdentity = (
  previous: WorkloadGuest[],
  next: WorkloadGuest[],
): WorkloadGuest[] => {
  if (previous === next || previous.length === 0 || next.length === 0) return next;
  const previousById = new Map(previous.map((row) => [row.id, row] as const));
  let reusedCount = 0;
  const reconciled = next.map((row) => {
    const previousRow = previousById.get(row.id);
    if (previousRow === row) {
      reusedCount += 1;
      return row;
    }
    if (previousRow && workloadSignature(previousRow) === workloadSignature(row)) {
      reusedCount += 1;
      return previousRow;
    }
    return row;
  });
  if (reusedCount === next.length && next.length === previous.length) {
    let sameOrder = true;
    for (let index = 0; index < reconciled.length; index += 1) {
      if (reconciled[index] !== previous[index]) {
        sameOrder = false;
        break;
      }
    }
    if (sameOrder) return previous;
  }
  return reconciled;
};

const normalizeWorkloadStatus = (status?: string | null): string => {
  const normalized = (status || '').trim().toLowerCase();
  if (!normalized) return 'unknown';
  if (normalized === 'online' || normalized === 'healthy') return 'running';
  if (normalized === 'poweredon' || normalized === 'powered_on' || normalized === 'powered-on') {
    return 'running';
  }
  if (normalized === 'offline') return 'stopped';
  if (normalized === 'poweredoff' || normalized === 'powered_off' || normalized === 'powered-off') {
    return 'stopped';
  }
  return normalized;
};

const resolveWorkloadType = resolveWorkloadTypeFromString;

const finiteMetricNumber = (value: unknown): number | undefined =>
  typeof value === 'number' && Number.isFinite(value) ? value : undefined;

const firstFiniteMetricNumber = (...values: unknown[]): number | undefined => {
  for (const value of values) {
    const finite = finiteMetricNumber(value);
    if (finite !== undefined) return finite;
  }
  return undefined;
};

const hasMetricValue = (metric?: APIMetricValue): boolean =>
  firstFiniteMetricNumber(metric?.percent, metric?.value, metric?.used, metric?.total) !==
  undefined;

const buildMetric = (metric?: APIMetricValue) => {
  const total = finiteMetricNumber(metric?.total) ?? 0;
  const used = finiteMetricNumber(metric?.used) ?? 0;
  const free =
    metric?.total !== undefined && metric?.used !== undefined ? Math.max(0, total - used) : 0;
  const usage =
    firstFiniteMetricNumber(metric?.percent, metric?.value) ??
    (total > 0 ? (used / total) * 100 : 0);
  return { total, used, free, usage };
};

const buildDiskMetric = (metric?: APIMetricValue): WorkloadGuest['disk'] => {
  const disk = {
    total: metric?.total,
    used: metric?.used,
    // Byte metrics always serialize a generic value, including default zero.
    // Only an explicit percentage or measured byte pair establishes usage.
    usage:
      metric?.percent ?? (!metric?.unit || metric.unit === 'percent' ? metric?.value : undefined),
  };
  return {
    ...disk,
    // Preserve missing/invalid evidence. Capacity-only metrics must not turn
    // into current 0%, but explicitly reported zero and byte-only reads work.
    usage: getWorkloadDiskUsagePercent(disk) ?? disk.usage,
    free:
      typeof disk.total === 'number' &&
      Number.isFinite(disk.total) &&
      typeof disk.used === 'number' &&
      Number.isFinite(disk.used)
        ? Math.max(0, disk.total - disk.used)
        : undefined,
  };
};

const mapNetworkInterfaces = (interfaces?: APINetworkInterface[]) =>
  interfaces?.map((iface) => ({
    name: iface.name,
    mac: iface.mac,
    addresses: iface.addresses,
    rxBytes: iface.rxBytes,
    txBytes: iface.txBytes,
  }));

const toIsoString = (value?: string): string => {
  if (!value) return '';
  const parsed = Date.parse(value);
  if (Number.isNaN(parsed)) return '';
  return new Date(parsed).toISOString();
};

const resolveWorkloadsPayload = (payload: unknown): { data: APIResource[]; totalPages: number } => {
  if (Array.isArray(payload)) {
    return { data: payload as APIResource[], totalPages: 1 };
  }
  if (!payload || typeof payload !== 'object') {
    return { data: [], totalPages: 1 };
  }
  const record = payload as APIListResponse;
  const data = Array.isArray(record.data)
    ? record.data
    : Array.isArray(record.resources)
      ? record.resources
      : [];
  const totalPages = Number.isFinite(record.meta?.totalPages)
    ? Math.max(1, Number(record.meta?.totalPages))
    : 1;
  return { data, totalPages };
};

const buildWorkloadsUrl = (page: number) =>
  `${WORKLOADS_URL}&page=${page}&limit=${WORKLOADS_PAGE_LIMIT}`;

const resolveWorkloadDiscoveryTarget = (
  resource: APIResource,
): ResourceDiscoveryTarget | undefined => {
  const explicit = resource.discoveryTarget;
  if (!explicit) return undefined;
  const resourceType = canonicalDiscoveryResourceType(explicit.resourceType);
  const agentId = (explicit.agentId || '').trim();
  const resourceId = (explicit.resourceId || '').trim();
  if (!resourceType || !agentId || !resourceId) return undefined;
  switch (resourceType) {
    case 'agent':
    case 'vm':
    case 'system-container':
    case 'app-container':
    case 'pod':
    case 'disk':
    case 'ceph':
      return {
        resourceType,
        agentId,
        resourceId,
        hostname: explicit.hostname,
      };
    default:
      return undefined;
  }
};

/**
 * vCenter tag labels for one resource, or undefined when the resource is not
 * a vSphere workload at all.
 *
 * A vSphere workload the operator never tagged returns an empty array on
 * purpose. Falling through to the flat `resource.tags` there would put the
 * adapter's provenance strings back in the cell, which is the whole reason the
 * column was worth nothing before.
 */
const vmwareRowTags = (resource: APIResource): string[] | undefined => {
  if (!resource.vmware) return undefined;
  const tags = resource.vmware.tags;
  if (!Array.isArray(tags)) return [];
  return tags
    .map((tag) => (tag?.label || tag?.name || '').trim())
    .filter((label) => label.length > 0);
};

const mapResourceToWorkload = (resource: APIResource): WorkloadGuest | null => {
  const workloadType = resolveWorkloadType(resource.type);
  if (!workloadType) return null;
  const platformType = resolvePlatformTypeFromSources(resource.sources);
  const platformScopes = normalizeSourcePlatformScopes(resource.platformScopes, platformType);
  const dockerManagedAppContainer = isDockerManagedAppContainer({
    workloadType,
    type: resource.type ?? '',
    platformType,
    containerRuntime: resource.docker?.runtime,
  });

  const name = (resource.name || resource.id || '').toString().trim();
  const vmwareNode =
    platformType === 'vmware-vsphere'
      ? (resource.vmware?.runtimeHostName ?? resource.parentName)
      : undefined;
  const vmwareInstance =
    platformType === 'vmware-vsphere'
      ? (resource.vmware?.clusterName ??
        resource.vmware?.datacenterName ??
        resource.vmware?.connectionName)
      : undefined;
  const node =
    vmwareNode ??
    resource.node ??
    resource.proxmox?.nodeName ??
    resource.kubernetes?.nodeName ??
    resource.parentName ??
    '';
  const kubernetesContext = getPreferredResourceKubernetesContext(resource);
  // The preferred helper falls back to the resource's own name, which is the
  // right label for a cluster resource but not for a workload: a vSphere VM
  // or a standalone Proxmox guest would otherwise be labelled as its own
  // cluster. Only an explicit cluster may become the workload's cluster.
  const workloadClusterName =
    (platformType === 'vmware-vsphere'
      ? resource.vmware?.clusterName?.trim() || undefined
      : undefined) ?? getExplicitResourceClusterName(resource);
  const instance =
    vmwareInstance ??
    resource.instance ??
    resource.proxmox?.instance ??
    kubernetesContext ??
    workloadClusterName ??
    '';
  const vmid =
    typeof resource.vmid === 'number'
      ? resource.vmid
      : typeof resource.proxmox?.vmid === 'number'
        ? resource.proxmox.vmid
        : 0;
  const rawDisplayId = resource.id;
  // vCenter identifies VMs by managed object reference (e.g. `vm-206`),
  // not a numeric vmid. When the resource has no Proxmox-shaped numeric
  // vmid, fall back to the vSphere MoRef so the workload table's ID
  // column shows the identifier operators recognize from vCenter rather
  // than rendering blank.
  const vsphereDisplayId =
    workloadType === 'vm' && vmid <= 0
      ? (resource.vmware?.managedObjectId ?? '').trim() || undefined
      : undefined;
  const displayId =
    workloadType === 'vm' || workloadType === 'system-container'
      ? vmid > 0
        ? String(vmid)
        : vsphereDisplayId
      : rawDisplayId
        ? rawDisplayId.length > 12
          ? rawDisplayId.slice(0, 12)
          : rawDisplayId
        : undefined;

  const cpuPercent =
    firstFiniteMetricNumber(resource.metrics?.cpu?.percent, resource.metrics?.cpu?.value) ?? 0;
  const cpuAvailable = hasMetricValue(resource.metrics?.cpu);
  const memoryAvailable = hasMetricValue(resource.metrics?.memory);
  const disk = buildDiskMetric(resource.metrics?.disk);
  const diskAvailable = getWorkloadDiskUsagePercent(disk) !== null;
  const networkIOAvailable =
    hasMetricValue(resource.metrics?.netIn) || hasMetricValue(resource.metrics?.netOut);
  const diskIOAvailable =
    hasMetricValue(resource.metrics?.diskRead) || hasMetricValue(resource.metrics?.diskWrite);
  const uptime = firstFiniteMetricNumber(
    resource.proxmox?.uptime,
    resource.agent?.uptimeSeconds,
    resource.docker?.uptimeSeconds,
    resource.kubernetes?.uptimeSeconds,
    resource.uptime,
  );
  const cpuCount = firstFiniteMetricNumber(
    resource.proxmox?.cpus,
    resource.virtualMachine?.vcpus,
    resource.vmware?.cpuCount,
  );

  const appContainerRuntimeId =
    workloadType === 'app-container' ? (resource.docker?.containerId || '').trim() : '';
  const discoveryTarget = resolveWorkloadDiscoveryTarget(resource);

  // Keep workload identity on the canonical unified resource id. Platform-native
  // runtime ids such as Docker container ids must stay separate so workload
  // routing, discovery, anomalies, and drawer selection align with the shared
  // resource model.
  const guestId = resource.id;

  return {
    id: guestId,
    canonicalResourceId: resource.id,
    parentResourceId: resource.parentId?.trim() || undefined,
    alertResourceIds: buildAlertResourceIds(resource),
    metricsTarget: resource.metricsTarget,
    vmid: Number.isFinite(vmid) ? vmid : 0,
    name: name || resource.id,
    node,
    instance,
    status: normalizeWorkloadStatus(
      resource.proxmox?.runtimeStatus ||
        resource.virtualMachine?.runtimeState ||
        resource.status ||
        (platformType === 'vmware-vsphere' ? resource.vmware?.powerState : null),
    ),
    resourceStatus: (resource.status || '').trim().toLowerCase() || undefined,
    hasOpenAlert: (resource.health?.reasons ?? []).some(
      (reason) => reason.code === 'warning_alert' || reason.code === 'critical_alert',
    ),
    type:
      workloadType === 'vm'
        ? 'vm'
        : workloadType === 'system-container'
          ? 'system-container'
          : workloadType === 'pod'
            ? 'pod'
            : 'app-container',
    cpu: getWorkloadCPUFraction(cpuPercent),
    cpus: cpuCount !== undefined && cpuCount > 0 ? cpuCount : 0,
    memory: (() => {
      const base = buildMetric(resource.metrics?.memory);
      const cache = resource.proxmox?.memoryCache ?? 0;
      const observation = readMemoryObservation(resource.metrics?.memory?.observation);
      return {
        ...base,
        ...(observation ? { observation } : {}),
        usageUnavailable: !memoryAvailable,
        // buildMetric derives free as total-used (available); carve the
        // reclaimable cache back out so free means truly-free pages.
        free: Math.max(0, base.free - cache),
        cache,
        swapUsed: resource.proxmox?.swapUsed ?? 0,
        swapTotal: resource.proxmox?.swapTotal ?? 0,
        balloon: resource.proxmox?.balloon ?? 0,
      };
    })(),
    disk,
    disks: normalizeDiskArray(resource.proxmox?.disks ?? resource.agent?.disks),
    disksFromAgent: (resource.proxmox?.disks == null && resource.agent?.disks != null) || undefined,
    // Both the API and owning platform snapshot pass through this mapper.
    // A retained numeric metric must not lose the provider's read deferral.
    diskStatusReason: resource.proxmox?.diskStatusReason,
    guestAgentStatus: resource.proxmox?.guestAgentStatus,
    guestAgentExpected: resource.proxmox?.guestAgentExpected,
    ipAddresses: resource.identity?.ipAddresses ?? [],
    // Guest OS info: agent.osName/osVersion is the universal fallback the
    // workload table reads. Proxmox writes to resource.proxmox.osName /
    // osVersion (qemu-guest-agent os-info); vSphere surfaces a coarse
    // family on resource.vmware.guestOsFamily (e.g. "LINUX", "WINDOWS"
    // — there's no analogous "OS version" carve-out). Falling back here
    // lights up the OS column for both platforms without changing what
    // already-populated agent-driven rows render.
    osName: resource.agent?.osName ?? resource.proxmox?.osName ?? resource.vmware?.guestOsFamily,
    osVersion: resource.agent?.osVersion ?? resource.proxmox?.osVersion,
    agentVersion: resource.agent?.agentVersion,
    agentKind: resource.agent?.agentVersion ? 'pulse' : undefined,
    agentId: resource.agent?.agentId,
    agentRaid: resource.agent?.raid,
    // Agent reports retain precedence, including an explicitly empty list.
    // Agentless PVE guests already supply named interfaces on their platform
    // facet; both the REST and owning-snapshot paths must preserve them.
    networkInterfaces: mapNetworkInterfaces(
      resource.agent?.networkInterfaces ?? resource.proxmox?.networkInterfaces,
    ),
    networkInterfacesFromAgent:
      resource.agent?.networkInterfaces != null
        ? true
        : resource.proxmox?.networkInterfaces != null
          ? false
          : undefined,
    // A linked agent past its reporting lease keeps its last report on the
    // resource, so its RAID, network and filesystem rows are not current.
    agentStale: resource.agent?.stale === true || undefined,
    networkIn: finiteMetricNumber(resource.metrics?.netIn?.value) ?? 0,
    networkOut: finiteMetricNumber(resource.metrics?.netOut?.value) ?? 0,
    diskRead: finiteMetricNumber(resource.metrics?.diskRead?.value) ?? 0,
    diskWrite: finiteMetricNumber(resource.metrics?.diskWrite?.value) ?? 0,
    // Zero can be a real API value for a newly started workload. The
    // availability facet below distinguishes that from no uptime observation.
    uptime: uptime ?? 0,
    template: resource.proxmox?.template ?? false,
    lastBackup: (() => {
      const timestamp = resource.proxmox?.lastBackup?.trim();
      // Go zero time is an explicit absence sentinel. Keep other invalid
      // readings (NaN included) distinct so the UI can report uncertainty.
      if (!timestamp || /^0001-01-01T00:00:00(?:\.0+)?Z$/.test(timestamp)) return 0;
      return parseBackupTimestampMs(timestamp) ?? NaN;
    })(),
    backupInProgress: resource.proxmox?.backupInProgress ?? false,
    // vSphere's flat `resource.tags` is a mixed keyword set: the adapter keeps
    // provenance strings there (`vmware`, `vsphere`, `source:vcenter`, ...) so
    // resource search and the `?tags=` filter keep matching, and appends the
    // operator's real vCenter tags. Only the latter belong in a per-row Tags
    // cell, so the vSphere facet wins for every vSphere workload — including
    // the untagged ones, which must render empty rather than fall back.
    tags: vmwareRowTags(resource) ?? resource.tags ?? [],
    lock: resource.proxmox?.lock ?? '',
    lastSeen: toIsoString(resource.lastSeen),
    isOci: workloadType === 'system-container' ? (resource.proxmox?.isOci ?? false) : false,
    osTemplate: workloadType === 'system-container' ? resource.proxmox?.osTemplate : undefined,
    workloadType,
    displayId,
    containerId: appContainerRuntimeId || undefined,
    image:
      workloadType === 'app-container'
        ? resource.docker?.image || resource.docker?.imageName || resource.docker?.imageRef
        : workloadType === 'pod'
          ? resource.kubernetes?.image
          : undefined,
    namespace: workloadType === 'pod' ? resource.kubernetes?.namespace : undefined,
    contextLabel:
      workloadType === 'vm' || workloadType === 'system-container'
        ? node
          ? (() => {
              const cluster = workloadClusterName || '';
              if (cluster && cluster !== node) return `${node} (${cluster})`;
              if (instance && instance !== node) return `${node} (${instance})`;
              return node;
            })()
          : undefined
        : workloadType === 'app-container'
          ? resource.parentName || resource.docker?.hostname
          : workloadType === 'pod'
            ? workloadClusterName
            : undefined,
    clusterName: workloadClusterName || undefined,
    containerRuntime:
      workloadType === 'app-container'
        ? (resource.docker?.runtime || '').trim() || undefined
        : undefined,
    updateStatus: resource.docker?.updateStatus as WorkloadGuest['updateStatus'] | undefined,
    actionReadiness: resource.actionReadiness,
    dockerHostId: dockerManagedAppContainer ? resource.docker?.hostSourceId : undefined,
    dockerHostName:
      workloadType === 'app-container'
        ? (resource.docker?.hostname || '').trim() || undefined
        : undefined,
    kubernetesAgentId: workloadType === 'pod' ? resource.kubernetes?.agentId : undefined,
    kubernetesClusterId: workloadType === 'pod' ? resource.kubernetes?.clusterId : undefined,
    platformType,
    platformScopes,
    telemetryAvailability: {
      cpu: cpuAvailable,
      memory: memoryAvailable,
      disk: diskAvailable,
      networkIO: networkIOAvailable,
      diskIO: diskIOAvailable,
      uptime: uptime !== undefined,
    },
    discoveryTarget,
    vmware:
      platformType === 'vmware-vsphere' && resource.vmware
        ? {
            connectionName: resource.vmware.connectionName,
            vcenterHost: resource.vmware.vcenterHost,
            datacenterName: resource.vmware.datacenterName,
            clusterName: resource.vmware.clusterName,
          }
        : undefined,
    availability: resource.availability as ResourceAvailabilityMeta | undefined,
    availabilityChecks: resource.availabilityChecks as ResourceAvailabilityMeta[] | undefined,
  };
};

const metricToAPI = (metric?: Resource['cpu']): APIMetricValue | undefined =>
  metric
    ? {
        percent: metric.current,
        ...(metric.observation ? { observation: metric.observation } : {}),
        used: metric.used,
        total: metric.total,
      }
    : undefined;

/**
 * The Proxmox overview already owns a canonical unified-resource snapshot.
 * Adapt that snapshot into the legacy WorkloadGuest boundary so the overview
 * does not fetch and parse the same VM/LXC rows a second time.
 */
const mapCanonicalResourceToWorkload = (resource: Resource): WorkloadGuest | null =>
  mapResourceToWorkload({
    id: resource.id,
    type: resource.type,
    name: resource.name,
    status: resource.status,
    health: resource.health,
    uptime: resource.uptime,
    lastSeen: resource.lastSeen ? new Date(resource.lastSeen).toISOString() : undefined,
    sources: resource.sources,
    platformScopes: resource.platformScopes,
    metricsTarget: resource.metricsTarget,
    canonicalIdentity: resource.canonicalIdentity,
    identity: resource.identity
      ? {
          machineId: resource.identity.machineId,
          hostnames: resource.identity.hostname ? [resource.identity.hostname] : undefined,
          ipAddresses: resource.identity.ips,
          clusterName: resource.identity.clusterName,
        }
      : undefined,
    metrics: {
      cpu: metricToAPI(resource.cpu),
      memory: metricToAPI(resource.memory),
      disk: metricToAPI(resource.disk),
      netIn: resource.network ? { value: resource.network.rxBytes } : undefined,
      netOut: resource.network ? { value: resource.network.txBytes } : undefined,
      diskRead: resource.diskIO ? { value: resource.diskIO.readRate } : undefined,
      diskWrite: resource.diskIO ? { value: resource.diskIO.writeRate } : undefined,
    },
    parentId: resource.parentId,
    parentName: resource.parentName,
    tags: resource.tags,
    vmid: resource.proxmox?.vmid,
    node: resource.proxmox?.nodeName || resource.proxmox?.node,
    instance: resource.proxmox?.instance,
    proxmox: resource.proxmox ? (resource.proxmox as unknown as APIResource['proxmox']) : undefined,
    virtualMachine: resource.virtualMachine
      ? (resource.virtualMachine as unknown as APIResource['virtualMachine'])
      : undefined,
    agent: resource.agent ? (resource.agent as unknown as APIResource['agent']) : undefined,
    docker: resource.docker ? (resource.docker as unknown as APIResource['docker']) : undefined,
    kubernetes: resource.kubernetes
      ? (resource.kubernetes as unknown as APIResource['kubernetes'])
      : undefined,
    vmware: resource.vmware ? (resource.vmware as unknown as APIResource['vmware']) : undefined,
    discoveryTarget: resource.discoveryTarget,
    availability: resource.availability,
    availabilityChecks: resource.availabilityChecks,
    actionReadiness: resource.actionReadiness,
  });

async function fetchWorkloads(): Promise<WorkloadGuest[]> {
  const firstResponse = await apiFetchJSON<unknown>(buildWorkloadsUrl(1), { cache: 'no-store' });
  const firstPage = resolveWorkloadsPayload(firstResponse);
  const allResources: APIResource[] = [...firstPage.data];

  const totalPages = firstPage.totalPages;
  if (totalPages > WORKLOADS_MAX_PAGES) {
    throw new Error(
      `Workload inventory has ${totalPages * WORKLOADS_PAGE_LIMIT}+ rows, refusing an unsafe browser payload`,
    );
  }
  for (
    let firstPageNumber = 2;
    firstPageNumber <= totalPages;
    firstPageNumber += WORKLOADS_PAGE_CONCURRENCY
  ) {
    const pageNumbers = Array.from(
      { length: Math.min(WORKLOADS_PAGE_CONCURRENCY, totalPages - firstPageNumber + 1) },
      (_, offset) => firstPageNumber + offset,
    );
    const responses = await Promise.all(
      pageNumbers.map((page) =>
        apiFetchJSON<unknown>(buildWorkloadsUrl(page), { cache: 'no-store' }),
      ),
    );
    for (const response of responses) {
      const pageData = resolveWorkloadsPayload(response);
      allResources.push(...pageData.data);
    }
  }

  const dedupedResources = Array.from(
    new Map(allResources.map((resource) => [resource.id, resource])).values(),
  );

  return dedupedResources
    .map((resource) => mapResourceToWorkload(resource))
    .filter((resource): resource is WorkloadGuest => !!resource);
}

const DEFAULT_POLL_INTERVAL_MS = 5_000;

const hasFreshWorkloadsCache = (entry: WorkloadsCacheEntry) =>
  entry.workloads.length > 0 && Date.now() - entry.cachedAt <= WORKLOADS_CACHE_MAX_AGE_MS;

const setWorkloadsCache = (
  entry: WorkloadsCacheEntry,
  workloads: WorkloadGuest[],
  at = Date.now(),
) => {
  entry.workloads = workloads;
  entry.cachedAt = at;
};

const fetchWorkloadsShared = async (
  entry: WorkloadsCacheEntry,
  force = false,
): Promise<WorkloadGuest[]> => {
  if (!force && hasFreshWorkloadsCache(entry)) {
    return entry.workloads;
  }

  if (entry.sharedFetch) {
    return entry.sharedFetch;
  }

  const request = (async () => {
    const previous = entry.workloads;
    const fetched = await fetchWorkloads();
    const reconciled = reconcileWorkloadRowIdentity(previous, fetched);
    if (reconciled === previous) {
      entry.cachedAt = Date.now();
      return previous;
    }
    setWorkloadsCache(entry, reconciled, Date.now());
    return reconciled;
  })();

  entry.sharedFetch = request;

  try {
    return await request;
  } finally {
    if (entry.sharedFetch === request) {
      entry.sharedFetch = null;
    }
  }
};

export const __resetWorkloadsCacheForTests = () => {
  workloadsCaches.clear();
};

export interface UseWorkloadsOptions {
  /** Optional canonical snapshot owned by a platform page. */
  resourceSnapshot?: Accessor<Resource[] | undefined>;
  /** Changed IDs from the same committed snapshot, or null for a full refresh. */
  resourceSnapshotChange?: Accessor<{
    version: number;
    changedIds: ReadonlySet<string> | null;
  }>;
  /** Refetch the owner snapshot when the surface explicitly reconnects. */
  refetchSnapshot?: () => Promise<unknown>;
}

export function useWorkloads(
  enabled: Accessor<boolean> = () => true,
  options: UseWorkloadsOptions = {},
) {
  const [orgScope, setOrgScope] = createSignal(normalizeOrgScope(getOrgID()));
  const resolveActiveOrgScope = () => orgScope();
  const resolveActiveCacheEntry = () => getWorkloadsCacheEntry(resolveActiveOrgScope());
  const [workloads, setWorkloads] = createSignal<WorkloadGuest[]>(
    resolveActiveCacheEntry().workloads,
  );
  const [loading, setLoading] = createSignal(
    enabled() && !options.resourceSnapshot && !hasFreshWorkloadsCache(resolveActiveCacheEntry()),
  );
  const [error, setError] = createSignal<unknown>(undefined);
  let requestVersion = 0;
  let lastSnapshotVersion = 0;
  let lastSnapshotOrgScope = resolveActiveOrgScope();
  let lastSnapshotRowsByResourceID = new Map<string, WorkloadGuest | null>();

  const mutate = (value: WorkloadGuest[] | ((prev: WorkloadGuest[]) => WorkloadGuest[])) =>
    setWorkloads((previous) => {
      const current = previous ?? [];
      const next = typeof value === 'function' ? value(current) : value;
      const normalized = next ?? [];
      const cacheEntry = resolveActiveCacheEntry();
      const reconciled = reconcileWorkloadRowIdentity(current, normalized);
      if (reconciled === current) {
        setWorkloadsCache(cacheEntry, current);
        return current;
      }
      setWorkloadsCache(cacheEntry, reconciled, Date.now());
      return reconciled;
    });

  const applyWorkloads = (next: WorkloadGuest[], targetOrgScope = resolveActiveOrgScope()) => {
    const cacheEntry = getWorkloadsCacheEntry(targetOrgScope);
    const current =
      targetOrgScope === resolveActiveOrgScope() ? untrack(workloads) : cacheEntry.workloads;
    const reconciled = reconcileWorkloadRowIdentity(current, next);
    if (reconciled === current) {
      setWorkloadsCache(cacheEntry, current, Date.now());
      if (targetOrgScope === resolveActiveOrgScope()) {
        setWorkloads(() => current);
      }
      return current;
    }
    setWorkloadsCache(cacheEntry, reconciled, Date.now());
    if (targetOrgScope === resolveActiveOrgScope()) {
      setWorkloads(() => reconciled);
    }
    return reconciled;
  };

  const loadWorkloads = async (
    scope: string,
    options: { force?: boolean; showLoading?: boolean } = {},
  ) => {
    const version = ++requestVersion;
    const cacheEntry = getWorkloadsCacheEntry(scope);
    const shouldShowLoading =
      options.showLoading === true && enabled() && scope === resolveActiveOrgScope();
    if (shouldShowLoading) {
      setLoading(true);
    }

    try {
      const data = await fetchWorkloadsShared(cacheEntry, options.force === true);
      if (version !== requestVersion || scope !== resolveActiveOrgScope() || !enabled()) {
        return data;
      }
      applyWorkloads(data, scope);
      setError(undefined);
      return data;
    } catch (err) {
      if (version === requestVersion && scope === resolveActiveOrgScope() && enabled()) {
        setError(err);
      }
      throw err;
    } finally {
      if (version === requestVersion && scope === resolveActiveOrgScope() && shouldShowLoading) {
        setLoading(false);
      }
    }
  };

  const refetch = async () => {
    if (options.resourceSnapshot) {
      if (options.refetchSnapshot) {
        await options.refetchSnapshot();
      }
      return workloads();
    }
    const scope = resolveActiveOrgScope();
    const cacheEntry = getWorkloadsCacheEntry(scope);
    return loadWorkloads(scope, { force: true, showLoading: cacheEntry.workloads.length === 0 });
  };

  createEffect(() => {
    if (!enabled()) {
      requestVersion += 1;
      lastSnapshotVersion = 0;
      lastSnapshotRowsByResourceID.clear();
      setLoading(false);
      return;
    }
    const resourceSnapshot = options.resourceSnapshot?.();
    if (options.resourceSnapshot) {
      if (resourceSnapshot === undefined) {
        if (workloads().length === 0) setLoading(true);
        return;
      }

      const change = options.resourceSnapshotChange?.();
      const currentOrgScope = resolveActiveOrgScope();
      const canReuseStableRows =
        change?.changedIds !== null &&
        change?.changedIds !== undefined &&
        change.version === lastSnapshotVersion + 1 &&
        currentOrgScope === lastSnapshotOrgScope;
      const nextRowsByResourceID = new Map<string, WorkloadGuest | null>();
      const next = resourceSnapshot.flatMap((resource) => {
        const mapped =
          canReuseStableRows &&
          !change!.changedIds!.has(resource.id) &&
          lastSnapshotRowsByResourceID.has(resource.id)
            ? lastSnapshotRowsByResourceID.get(resource.id)!
            : mapCanonicalResourceToWorkload(resource);
        nextRowsByResourceID.set(resource.id, mapped);
        return mapped ? [mapped] : [];
      });
      lastSnapshotVersion = change?.version ?? 0;
      lastSnapshotOrgScope = currentOrgScope;
      lastSnapshotRowsByResourceID = nextRowsByResourceID;
      applyWorkloads(next);
      setLoading(false);
      setError(undefined);
      return;
    }

    const scope = resolveActiveOrgScope();
    const cacheEntry = getWorkloadsCacheEntry(scope);
    if (cacheEntry.workloads !== workloads()) {
      setWorkloads(() => cacheEntry.workloads);
    }
    if (hasFreshWorkloadsCache(cacheEntry)) {
      setLoading(false);
      setError(undefined);
      return;
    }
    void loadWorkloads(scope, {
      showLoading: cacheEntry.workloads.length === 0,
    }).catch(() => undefined);
  });

  // Poll for fresh metrics while enabled.
  // Apply the result directly to retained signal state so polling never trips
  // the app-level <Suspense> boundary or replaces the last good table with an
  // empty loading surface.
  createEffect(() => {
    if (!enabled() || options.resourceSnapshot) return;
    const scope = resolveActiveOrgScope();
    const id = setInterval(async () => {
      try {
        const data = await fetchWorkloadsShared(getWorkloadsCacheEntry(scope), true);
        if (scope !== resolveActiveOrgScope()) {
          return;
        }
        applyWorkloads(data, scope);
        setError(undefined);
      } catch (err) {
        // Keep the last coherent snapshot while making the failed refresh
        // observable to the surface.
        if (scope === resolveActiveOrgScope()) {
          setError(err);
        }
      }
    }, DEFAULT_POLL_INTERVAL_MS);
    onCleanup(() => clearInterval(id));
  });

  const unsubscribeOrgSwitch = eventBus.on('org_switched', (nextOrgID) => {
    const nextOrgScope = normalizeOrgScope(nextOrgID);
    if (nextOrgScope === resolveActiveOrgScope()) {
      return;
    }

    const nextCacheEntry = getWorkloadsCacheEntry(nextOrgScope);
    requestVersion += 1;
    setWorkloads(() => nextCacheEntry.workloads);
    setError(undefined);
    setLoading(enabled() && nextCacheEntry.workloads.length === 0);
    setOrgScope(nextOrgScope);

    if (options.resourceSnapshot) {
      return;
    }

    if (!hasFreshWorkloadsCache(nextCacheEntry)) {
      void loadWorkloads(nextOrgScope, {
        force: true,
        showLoading: nextCacheEntry.workloads.length === 0,
      }).catch(() => undefined);
    }
  });
  onCleanup(unsubscribeOrgSwitch);

  return {
    workloads,
    refetch,
    mutate,
    loading,
    error,
  };
}

export default useWorkloads;