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 { describe, expect, it } from 'vitest';
import type { Resource } from '@/types/resource';
import {
getAgentLikeMetadataIds,
getPreferredConfiguredNodeLabel,
getPreferredNamedEntityLabel,
getPreferredNormalizedPlatformId,
getInfrastructureDiscoveryHostname,
getInfrastructureMetadataId,
getPreferredResourceClusterName,
getPreferredResourceKubernetesContext,
getPreferredResourceDisplayName,
getPreferredInfrastructureDisplayName,
getPreferredResourceHostname,
getPreferredResourceIP,
getPreferredWorkloadsAgentHint,
getPrimaryResourceIdentity,
getPrimaryResourceIdentityRows,
getResourceIdentityAliases,
resolveGuestUrlWithIdentity,
shouldShowResourcePlatformId,
} from '@/utils/resourceIdentity';
import type { Agent, Node } from '@/types/api';
const makeResource = (overrides: Partial<Resource> = {}): Resource =>
({
id: 'resource-1',
type: 'agent',
name: 'resource-1',
displayName: 'resource-1',
platformId: 'resource-1',
platformType: 'agent',
sourceType: 'agent',
status: 'online',
lastSeen: Date.now(),
...overrides,
}) as Resource;
describe('resourceIdentity', () => {
it('prefers metrics and discovery targets for primary identity', () => {
expect(
getPrimaryResourceIdentity(
makeResource({
metricsTarget: { resourceType: 'docker-host', resourceId: 'docker-host-1' },
}),
),
).toBe('docker-host:docker-host-1');
expect(
getPrimaryResourceIdentity(
makeResource({
discoveryTarget: {
resourceType: 'agent',
agentId: 'agent-1',
resourceId: 'agent-1',
},
}),
),
).toBe('agent:agent-1');
});
it('prefers backend canonical identity when present', () => {
const resource = makeResource({
displayName: '',
canonicalIdentity: {
primaryId: 'node:instance-pve1',
hostname: 'tower.local',
aliases: ['node:instance-pve1', 'instance-pve1', 'tower.local'],
},
identity: {
hostname: 'legacy-host.local',
},
});
expect(getPrimaryResourceIdentity(resource)).toBe('node:instance-pve1');
expect(getResourceIdentityAliases(resource)).toEqual([
'node:instance-pve1',
'instance-pve1',
'tower.local',
'legacy-host.local',
]);
expect(getPreferredResourceHostname(resource)).toBe('tower.local');
expect(getPrimaryResourceIdentityRows(resource)).toEqual([
{ label: 'Hostname', value: 'tower.local' },
{ label: 'Primary ID', value: 'node:instance-pve1' },
]);
});
it('resolves superseded canonical ids even though broadcast aliases no longer carry them', () => {
// Slimmed broadcast payloads stop duplicating supersededIds into the
// alias list, so the identity resolver has to consult them explicitly for
// alert overrides and lookups keyed by a retired spelling.
const aliases = getResourceIdentityAliases(
makeResource({
canonicalIdentity: {
primaryId: 'agent:core2026',
aliases: ['agent:core2026', 'core2026'],
supersededIds: ['agent-core2026-a1b2c3', 'agent-core2026-d4e5f6'],
},
}),
);
expect(aliases).toContain('agent-core2026-a1b2c3');
expect(aliases).toContain('agent-core2026-d4e5f6');
expect(aliases).toContain('agent:core2026');
});
it('uses actionable linked identities before falling back to unified ids', () => {
expect(
getPrimaryResourceIdentity(
makeResource({
platformData: {
linkedAgentId: 'agent-linked',
},
}),
),
).toBe('agent:agent-linked');
expect(
getPrimaryResourceIdentity(
makeResource({
type: 'docker-host',
platformData: {
docker: { hostSourceId: 'docker-host-2' },
},
}),
),
).toBe('docker-host:docker-host-2');
});
it('deduplicates aliases and includes linked agent identities', () => {
expect(
getResourceIdentityAliases(
makeResource({
metricsTarget: { resourceType: 'docker-host', resourceId: 'docker-host-1' },
discoveryTarget: {
resourceType: 'agent',
agentId: 'agent-linked',
resourceId: 'agent-linked',
},
platformData: {
linkedAgentId: 'agent-linked',
agent: {
agentId: 'agent-linked',
hostname: 'tower.local',
},
docker: {
hostSourceId: 'docker-host-1',
},
},
identity: {
hostname: 'tower.local',
machineId: 'machine-1',
},
}),
),
).toEqual(['docker-host-1', 'agent-linked', 'tower.local', 'machine-1']);
});
it('builds primary identity rows from enriched targets', () => {
expect(
getPrimaryResourceIdentityRows(
makeResource({
identity: {
hostname: 'tower.local',
machineId: 'machine-1',
},
clusterId: 'cluster-a',
parentId: 'parent-1',
discoveryTarget: {
resourceType: 'agent',
agentId: 'agent-1',
resourceId: 'agent-1',
},
metricsTarget: {
resourceType: 'docker-host',
resourceId: 'docker-host-1',
},
}),
),
).toEqual([
{ label: 'Hostname', value: 'tower.local' },
{ label: 'Primary ID', value: 'docker-host:docker-host-1' },
{ label: 'Machine ID', value: 'machine-1' },
{ label: 'Cluster', value: 'cluster-a' },
{ label: 'Parent', value: 'parent-1' },
{ label: 'Discovery', value: 'agent:agent-1' },
// The metrics target is the Primary ID shown above, so it is not repeated.
]);
});
it('keeps a discovery target that matches only a name the drawer never shows', () => {
const rows = getPrimaryResourceIdentityRows(
makeResource({
displayName: 'Friendly host',
canonicalIdentity: { displayName: 'agent:other' },
discoveryTarget: { resourceType: 'agent', agentId: 'other', resourceId: 'other' },
metricsTarget: { resourceType: 'node', resourceId: 'self' },
} as Parameters<typeof makeResource>[0]),
);
expect(rows.find((row) => row.label === 'Discovery')?.value).toBe('agent:other');
});
it('shows an identity once when discovery and metrics targets name the resource itself', () => {
const rows = getPrimaryResourceIdentityRows(
makeResource({
identity: { hostname: 'tower.local' },
discoveryTarget: { resourceType: 'agent', agentId: 'agent-1', resourceId: 'agent-1' },
metricsTarget: { resourceType: 'agent', resourceId: 'agent-1' },
}),
);
expect(rows.filter((row) => row.value === 'agent:agent-1').map((row) => row.label)).toEqual([
'Primary ID',
]);
});
it('prefers the canonical Kubernetes cluster name over display labels', () => {
const resource = makeResource({
type: 'k8s-cluster',
name: 'secret-cluster',
displayName: 'Governed Cluster',
clusterId: 'cluster-override',
kubernetes: {
clusterName: 'cluster-a',
context: 'cluster-context',
clusterId: 'cluster-a-id',
},
});
expect(getPreferredResourceClusterName(resource)).toBe('cluster-a');
});
it('prefers proxmox cluster names when kubernetes context is unavailable', () => {
const resource = makeResource({
type: 'vm',
name: 'proxmox-node',
displayName: 'Governed Node',
proxmox: {
clusterName: 'proxmox-cluster',
},
});
expect(getPreferredResourceClusterName(resource)).toBe('proxmox-cluster');
});
it('prefers the canonical Kubernetes context prefix without display fallbacks', () => {
const resource = makeResource({
type: 'k8s-node',
name: 'secret-node',
displayName: 'Governed Node',
clusterId: 'cluster-override',
kubernetes: {
clusterName: 'cluster-a',
context: 'cluster-context',
clusterId: 'cluster-a-id',
},
});
expect(getPreferredResourceKubernetesContext(resource)).toBe('cluster-a');
});
it('hides platform ids that duplicate canonical identity labels', () => {
expect(
shouldShowResourcePlatformId(
makeResource({
name: 'delly',
displayName: 'delly',
platformId: 'delly',
canonicalIdentity: {
displayName: 'delly',
hostname: 'delly',
},
}),
),
).toBe(false);
});
it('keeps platform ids when they add distinct identity context', () => {
expect(
shouldShowResourcePlatformId(
makeResource({
name: 'pbs-main',
displayName: 'PBS Main',
platformId: '192.168.0.8',
canonicalIdentity: {
displayName: 'pbs-main',
hostname: 'pbs-main',
},
}),
),
).toBe(true);
});
it('builds agent-like metadata ids without hostnames', () => {
const agent = {
id: 'agent-explicit',
hostname: 'tower.local',
status: 'online',
lastSeen: Date.now(),
platformData: {
linkedAgentId: 'agent-linked',
agent: {
agentId: 'agent-platform',
hostname: 'tower.internal',
},
},
discoveryTarget: {
resourceType: 'agent',
resourceId: 'agent-discovery',
agentId: 'agent-discovery',
},
} as unknown as Agent;
expect(getAgentLikeMetadataIds(agent)).toEqual([
'agent-discovery',
'agent-platform',
'agent-linked',
'agent-explicit',
]);
});
it('resolves infrastructure metadata ids and discovery hostnames', () => {
const node = {
id: 'node-1',
name: 'pve1',
linkedAgentId: 'agent-linked',
} as Pick<Node, 'id' | 'name' | 'linkedAgentId'>;
const agent = {
id: 'agent-explicit',
hostname: 'pve1.local',
status: 'online',
lastSeen: Date.now(),
} as Agent;
expect(getInfrastructureMetadataId(node, agent)).toBe('agent-explicit');
expect(getInfrastructureMetadataId(node)).toBe('agent-linked');
expect(getInfrastructureDiscoveryHostname({ name: 'pve1' }, agent)).toBe('pve1.local');
expect(getInfrastructureDiscoveryHostname({ name: 'pve1' })).toBe('pve1');
});
it('prefers canonical discovery metadata over raw agent ids for infrastructure helpers', () => {
const node = {
id: 'node-1',
name: 'pve1',
linkedAgentId: 'agent-linked',
} as Pick<Node, 'id' | 'name' | 'linkedAgentId'>;
const agent = {
id: 'agent-unified-id',
hostname: 'legacy-host.local',
status: 'online',
lastSeen: Date.now(),
canonicalIdentity: {
hostname: 'canonical-host.local',
},
discoveryTarget: {
resourceType: 'agent',
resourceId: 'agent-discovery',
agentId: 'agent-discovery',
hostname: 'discovery-host.local',
},
platformData: {
linkedAgentId: 'agent-linked',
agent: {
agentId: 'agent-platform',
hostname: 'platform-host.local',
},
},
} as unknown as Agent;
expect(getInfrastructureMetadataId(node, agent)).toBe('agent-discovery');
expect(getInfrastructureDiscoveryHostname({ name: 'pve1' }, agent)).toBe(
'canonical-host.local',
);
});
it('resolves configured node labels with display-first precedence', () => {
expect(
getPreferredConfiguredNodeLabel({
id: 'node-1',
displayName: 'Cluster Node',
name: 'pve1',
host: 'pve1.local',
} as never),
).toBe('Cluster Node');
expect(
getPreferredConfiguredNodeLabel({
id: 'node-2',
displayName: '',
name: '',
host: 'pbs.local',
} as never),
).toBe('pbs.local');
});
it('resolves named entity labels across runtime and cluster-like shapes', () => {
expect(
getPreferredNamedEntityLabel({
id: 'runtime-1',
displayName: '',
hostname: 'tower.local',
}),
).toBe('tower.local');
expect(
getPreferredNamedEntityLabel({
id: 'cluster-1',
name: 'cluster-a',
}),
).toBe('cluster-a');
});
it('resolves normalized platform ids with source-aware precedence', () => {
expect(
getPreferredNormalizedPlatformId({
id: 'resource-1',
name: 'fallback-name',
proxmox: { nodeName: 'pve-node-1' },
agent: { hostname: 'agent-host.local' },
docker: { hostname: 'docker-host.local' },
}),
).toBe('pve-node-1');
expect(
getPreferredNormalizedPlatformId({
id: 'resource-2',
name: 'fallback-name',
agent: { hostname: 'agent-host.local' },
docker: { hostname: 'docker-host.local' },
}),
).toBe('agent-host.local');
});
it('resolves shared resource hostnames and display names', () => {
const resource = makeResource({
name: 'fallback-name',
displayName: '',
platformId: 'platform-name',
platformData: {
agent: {
hostname: 'platform-host.local',
},
},
});
expect(getPreferredResourceHostname(resource)).toBe('platform-host.local');
expect(getPreferredResourceDisplayName(resource)).toBe('platform-host.local');
expect(
getPreferredResourceDisplayName(
makeResource({
name: 'sensitive-host',
displayName: 'Sensitive Host',
policy: {
sensitivity: 'restricted',
routing: {
scope: 'local-only',
redact: ['hostname', 'alias'],
},
},
aiSafeSummary: 'restricted host summary safe for remote AI consumption',
}),
),
).toBe('restricted host summary safe for remote AI consumption');
expect(
getPreferredResourceDisplayName(
makeResource({
name: 'pbs-secret',
displayName: 'PBS Secret',
type: 'pbs',
policy: {
sensitivity: 'sensitive',
routing: {
scope: 'local-first',
redact: ['hostname', 'platform-id'],
},
},
aiSafeSummary:
'backup server resource; status online; sources pbs; 1 child resources; redacted for cloud summary',
}),
),
).toBe('backup server (online)');
expect(
getPreferredInfrastructureDisplayName(
makeResource({
name: 'pbs-main',
displayName: 'PBS Main',
type: 'pbs',
policy: {
sensitivity: 'sensitive',
routing: {
scope: 'local-first',
redact: ['hostname', 'platform-id'],
},
},
aiSafeSummary:
'backup server resource; status online; sources pbs; 1 child resources; redacted for cloud summary',
}),
),
).toBe('PBS Main');
expect(
getPreferredResourceDisplayName(
makeResource({
displayName: 'Display Label',
platformData: {
agent: {
hostname: 'platform-host.local',
},
},
}),
),
).toBe('Display Label');
});
it('resolves workloads agent hints with source-specific precedence', () => {
expect(
getPreferredWorkloadsAgentHint(
makeResource({
type: 'docker-host',
identity: { hostname: 'identity-host' },
platformData: {
docker: { hostname: 'docker-host-1' },
},
}),
),
).toBe('docker-host-1');
expect(
getPreferredWorkloadsAgentHint(
makeResource({
type: 'agent',
identity: { hostname: 'identity-host' },
platformData: {
proxmox: { nodeName: 'pve1' },
},
}),
),
).toBe('pve1');
expect(
getPreferredWorkloadsAgentHint(
makeResource({
type: 'agent',
platformType: 'truenas',
id: 'truenas-id',
identity: { hostname: 'identity-host' },
platformData: {
truenas: { hostname: 'truenas-main' },
},
}),
),
).toBe('truenas-main');
});
it('resolves canonical cluster names for Kubernetes RBAC inventory rows', () => {
for (const type of [
'k8s-role',
'k8s-cluster-role',
'k8s-role-binding',
'k8s-cluster-role-binding',
] as const) {
expect(
getPreferredResourceClusterName(
makeResource({
type,
name:
type === 'k8s-role' || type === 'k8s-role-binding'
? 'api-runtime'
: 'platform-monitoring',
kubernetes: { clusterName: 'prod-eu', context: 'prod-eu-context' },
}),
),
).toBe('prod-eu');
}
});
describe('getPreferredResourceIP', () => {
it('returns undefined when no identity IPs', () => {
expect(getPreferredResourceIP(makeResource())).toBeUndefined();
});
it('prefers RFC 1918 private IPv4 over Tailscale and IPv6', () => {
const resource = makeResource({
identity: {
ips: [
'100.109.215.65',
'fd7a:115c:a1e0::f35:d741',
'fe80::1bf2:7ef4:cd4b:8d71',
'192.168.0.2',
],
},
});
expect(getPreferredResourceIP(resource)).toBe('192.168.0.2');
});
it('falls back to any IPv4 when no RFC 1918 address', () => {
const resource = makeResource({
identity: { ips: ['100.64.0.1', 'fe80::1'] },
});
expect(getPreferredResourceIP(resource)).toBe('100.64.0.1');
});
it('prefers a host interface over Docker bridges, tunnels, and link-local addresses', () => {
const resource = makeResource({
identity: { ips: ['fe80::1', '172.18.0.1', '192.168.0.113'] },
agent: {
networkInterfaces: [
{ name: 'docker0', addresses: ['172.18.0.1/16'] },
{ name: 'tailscale0', addresses: ['100.109.215.65/32'] },
{ name: 'eth0', addresses: ['fe80::1/64', '192.168.0.113/24'] },
],
},
});
expect(getPreferredResourceIP(resource)).toBe('192.168.0.113');
});
});
describe('resolveGuestUrlWithIdentity', () => {
it('replaces bare hostname with LAN IP', () => {
const resource = makeResource({
identity: { ips: ['100.109.215.65', '192.168.0.2'] },
});
expect(resolveGuestUrlWithIdentity('https://pi:8006', resource)).toBe(
'https://192.168.0.2:8006',
);
});
it('keeps URL that already uses an IP', () => {
const resource = makeResource({ identity: { ips: ['192.168.0.2'] } });
expect(resolveGuestUrlWithIdentity('https://192.168.0.5:8006', resource)).toBe(
'https://192.168.0.5:8006',
);
});
it('keeps URL with FQDN hostname', () => {
const resource = makeResource({ identity: { ips: ['192.168.0.2'] } });
expect(resolveGuestUrlWithIdentity('https://delly.local:8006', resource)).toBe(
'https://delly.local:8006',
);
});
it('returns original URL when no identity IPs available', () => {
expect(resolveGuestUrlWithIdentity('https://pi:8006', makeResource())).toBe(
'https://pi:8006',
);
});
it('handles empty URL', () => {
expect(resolveGuestUrlWithIdentity('', makeResource())).toBe('');
});
});
});