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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
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;