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
Keep unread replication inventory distinct from absent jobs
pulse-triage[bot]240b8fadab13
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.mdindex 84b04b3316..b26fb8853c 100644--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md@@ -10786,3 +10786,13 @@ reads, recovery to SSO/local login or confirmed setup, single-flight/cancellatiofocus ownership and the established sign-in behaviours. Browser proof exercisesthe actual Login/API client/CSS with safe HTTP fixtures at desktop and narrowwidths; it is not installed SSO or original private/access recovery.++### Replication inventory failure presentation (30 October 2026)++The Proxmox Replication table consumes the validated full inventory owned by+unified-resources. Malformed successful HTTP responses use the existing+`PlatformErrorState` and Refresh interaction with a fixed safe explanation:+missing jobs do not establish that none are configured. Neither raw provider+body nor JSON parser details enter the rendered error. This is a failed read,+not an empty-state or a new error surface; full retry, normal status filters,+phone columns and disclosure interactions retain their existing owners.diff --git a/docs/release-control/v6/internal/subsystems/registry.json b/docs/release-control/v6/internal/subsystems/registry.jsonindex 260e235249..501e903cb2 100644--- a/docs/release-control/v6/internal/subsystems/registry.json+++ b/docs/release-control/v6/internal/subsystems/registry.json@@ -8631,6 +8631,7 @@"frontend-modern/src/features/proxmox/proxmoxPageModel.ts","frontend-modern/src/features/proxmox/ProxmoxRecoverableTable.tsx","frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx",+ "frontend-modern/src/features/proxmox/proxmoxReplicationInventory.ts","frontend-modern/src/features/standalone/AgentsMachinesTable.tsx","frontend-modern/src/features/standalone/AvailabilityChecksTable.tsx","frontend-modern/src/features/standalone/standalonePageModel.ts",@@ -8685,6 +8686,22 @@"exact_files": [],"require_explicit_path_policy_coverage": true,"path_policies": [+ {+ "id": "replication-inventory",+ "label": "complete typed replication inventory read proof",+ "match_prefixes": [],+ "match_files": [+ "frontend-modern/src/features/proxmox/proxmoxReplicationInventory.ts",+ "frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx"+ ],+ "allow_same_subsystem_tests": false,+ "test_prefixes": [],+ "exact_files": [+ "frontend-modern/src/features/proxmox/__tests__/proxmoxReplicationInventory.test.ts",+ "frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsx",+ "frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx"+ ]+ },{"id": "proxmox-update-evidence-json","label": "authoritative Proxmox update JSON clearing proof",diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex 6bb5fdb7ba..5c21facf86 100644--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md@@ -2262,6 +2262,12 @@ fallback for an empty answer) rather than reopening the route. An accessdenial (401 or 403) withdraws the jobs and the tab, and a direct link holds onthe denial so the operator sees why. The poll re-reads the existing read-only`/api/replication/jobs` snapshot and opens no new storage or recovery path.+A successful replication observation requires the unified-resources-owned+inventory parser to accept the complete typed snapshot and matching total.+Missing, null, malformed or ambiguous job lists are unavailable, not evidence+that replication is unconfigured; they follow the same failed-read navigation+and retry rules above. This validation neither changes PVE job status nor+establishes a completed copy, guest thaw or native recovery.Proxmox backup-health and recoverable-artifact summary rows follow the sameplatform-table density contract as every other provider surface. Storage andrecovery owns which backup, datastore, workload-type, and VMID facts matter todiff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.mdindex c39719c515..1863972dff 100644--- a/docs/release-control/v6/internal/subsystems/unified-resources.md+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md@@ -1843,6 +1843,18 @@ once at mount would age a job that keeps syncing and count it overdue.`apiFetch`, so a replaced or unmounted replication read stops instead ofrunning on in the background, and it throws `apiErrorFromResponse` errors thatkeep the HTTP status, so a 401 or 403 withdraws the jobs as an access failure.+The same read validates the complete replication snapshot through+`proxmoxReplicationInventory.ts`: an explicit array and matching nonnegative+integer `meta.total`, typed consumed job fields, boolean `enabled`, nonempty+connection/native/projected identity and no repeated projected ID or native job+within one connection. A malformed envelope, row, count or JSON document fails+the whole read with a fixed safe format error; it is never a successful empty+inventory, a partially filtered list or a truthy health flag. Additional fields+and unfamiliar status strings remain readable. Native job IDs may repeat across+independent connections. The parser changes no status or timestamp semantics.+First-read failure keeps a direct Replication link on the existing error/Refresh;+a failed poll keeps prior presence for navigation but the table displays the+error, not old job health. Only a validated full retry replaces the observation.Kubernetes name columns hold the chevron, status dot and name inside onetrack, so their md widths leave the name room for a typical node or servicename at a 768px viewport: Nodes 20 percent (with Capacity at 16 so itsdiff --git a/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx b/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsxindex 5c60625308..f663e71733 100644--- a/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx+++ b/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx@@ -40,7 +40,11 @@ import {} from '@/features/platformPage/PlatformResourceDetailTableRow';import { RecordOwnerLink } from '@/features/platformPage/RecordOwnerLink';import { useObservedElementWidth } from '@/hooks/useObservedElementWidth';-import type { ReplicationJob, ReplicationJobsResponse } from '@/types/api';+import type { ReplicationJob } from '@/types/api';+import {+ parseReplicationInventory,+ readReplicationInventoryJSON,+} from './proxmoxReplicationInventory';import { buildPlatformSearchSuggestions } from '@/features/platformPage/platformSearchSuggestions';import { matchesSearchTermSplit, splitSearchExclusions } from '@/utils/searchQuery';import { buildProxmoxGuestNativeId } from '@/utils/workloads';@@ -430,8 +434,7 @@ export async function fetchReplicationJobs(signal?: AbortSignal): Promise<Replic`Failed to load replication jobs (${response.status})`,);}- const payload = (await response.json()) as ReplicationJobsResponse;- return Array.isArray(payload?.data) ? payload.data : [];+ return parseReplicationInventory(await readReplicationInventoryJSON(response));}// The jobs resource lives in ProxmoxPageSurface (it also gates thediff --git a/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx b/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsxindex 3c993a601e..615e15c094 100644--- a/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx+++ b/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import type { UnifiedResourceFacets } from '@/hooks/useUnifiedResources';import type { Resource } from '@/types/resource';import { ProxmoxPageSurface } from '../ProxmoxPageSurface';+import { ReplicationInventoryFormatError } from '../proxmoxReplicationInventory';import proxmoxPageSurfaceSource from '../ProxmoxPageSurface.tsx?raw';import proxmoxBackupServersTableSource from '../ProxmoxBackupServersTable.tsx?raw';import proxmoxBackupsTableSource from '../ProxmoxBackupsTable.tsx?raw';@@ -802,7 +803,7 @@ describe('ProxmoxPageSurface contract', () => {);// A failed read reports the error but keeps the tab and the user on it.- mockFetchReplicationJobs.mockRejectedValueOnce(new Error('replication read failed'));+ mockFetchReplicationJobs.mockRejectedValueOnce(new ReplicationInventoryFormatError());vi.advanceTimersByTime(30_000);await waitFor(() =>expect(screen.getByTestId('replication-table')).toHaveAttribute('data-error', 'yes'),@@ -835,7 +836,7 @@ describe('ProxmoxPageSurface contract', () => {refetch: vi.fn(async () => []),});mockFetchReplicationJobs.mockReset();- mockFetchReplicationJobs.mockRejectedValueOnce(new Error('replication read failed'));+ mockFetchReplicationJobs.mockRejectedValueOnce(new ReplicationInventoryFormatError());mockFetchReplicationJobs.mockResolvedValueOnce([{ id: 'job-1' }]);try {diff --git a/frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsx b/frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsxindex ad1d642acd..76836031c1 100644--- a/frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsx+++ b/frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsx@@ -13,6 +13,7 @@ import {formatMobileReplicationGuestLabel,} from '../ProxmoxReplicationTable';import replicationTableSource from '../ProxmoxReplicationTable.tsx?raw';+import { ReplicationInventoryFormatError } from '../proxmoxReplicationInventory';// Record drawers link to the object they are about, which needs a router.const renderInRouter = (component: () => JSX.Element) =>@@ -210,6 +211,31 @@ describe('ProxmoxReplicationTable', () => {});describe('fetchReplicationJobs', () => {+ it.each([+ '{}',+ '{"data":null,"meta":{"total":0}}',+ '{"data":[null],"meta":{"total":1}}',+ '{"data":[],"meta":{"total":1}}',+ '{"data":[{"id":"private-invalid-row"}',+ ])('rejects a malformed HTTP 200 response without leaking its body (%#)', async (body) => {+ vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(body));+ await expect(fetchReplicationJobs()).rejects.toMatchObject({+ name: 'ReplicationInventoryFormatError',+ message: new ReplicationInventoryFormatError().message,+ });+ });++ it('returns the complete typed HTTP inventory without changing job state', async () => {+ const data = [+ replicationJob(),+ replicationJob({ id: 'site-b-100', instance: 'site-b', enabled: false }),+ ];+ vi.spyOn(globalThis, 'fetch').mockResolvedValue(+ new Response(JSON.stringify({ data, meta: { total: 2 } })),+ );+ await expect(fetchReplicationJobs()).resolves.toEqual(data);+ });+it('passes the caller abort signal to the network request', async () => {const fetchSpy = vi.spyOn(globalThis, 'fetch')diff --git a/frontend-modern/src/features/proxmox/__tests__/proxmoxReplicationInventory.test.ts b/frontend-modern/src/features/proxmox/__tests__/proxmoxReplicationInventory.test.tsnew file mode 100644index 0000000000..00576fddf4--- /dev/null+++ b/frontend-modern/src/features/proxmox/__tests__/proxmoxReplicationInventory.test.ts@@ -0,0 +1,152 @@+import { describe, expect, it } from 'vitest';+import {+ ReplicationInventoryFormatError,+ parseReplicationInventory,+} from '../proxmoxReplicationInventory';++const job = () => ({+ id: 'site-a-100-0',+ instance: 'site-a',+ jobId: '100-0',+ enabled: true,+});+const payload = (data: unknown[]) => ({ data, meta: { total: data.length } });++describe('replication inventory wire boundary', () => {+ it('accepts only an explicit complete empty observation as absence', () => {+ expect(parseReplicationInventory(payload([]))).toEqual([]);+ });++ it('keeps current Go wire fields, optional omissions and future fields without mutation', () => {+ const current = Object.freeze({+ ...job(),+ guestId: 100,+ guestName: 'database',+ guestType: 'qemu',+ guestNode: 'pve-a',+ sourceNode: 'pve-a',+ targetNode: 'pve-b',+ lastSyncStatus: 'ok',+ lastSyncTime: '2026-10-30T01:00:00Z',+ lastSyncUnix: 1793322000,+ nextSyncTime: '2026-10-30T01:15:00Z',+ nextSyncUnix: 1793322900,+ lastSyncDurationSeconds: 0,+ failCount: 0,+ rateLimitMbps: 0,+ lastPolled: '2026-10-30T01:01:00Z',+ futureField: { present: true },+ });+ const data = [current, { ...job(), id: 'site-b-100-0', instance: 'site-b', enabled: false }];+ const response = payload(data);+ expect(parseReplicationInventory(response)).toBe(data);+ expect(data[0]).toBe(current);+ });++ it('does not invent a health classification or chronology for unfamiliar strings', () => {+ const data = [{ ...job(), lastSyncStatus: 'new-provider-state', lastSyncTime: '' }];+ expect(parseReplicationInventory(payload(data))).toEqual(data);+ });++ it.each([+ null,+ [],+ '',+ {},+ { meta: { total: 0 } },+ { data: null, meta: { total: 0 } },+ { data: {}, meta: { total: 0 } },+ { data: [] },+ { data: [], meta: null },+ { data: [], meta: [] },+ { data: [], meta: {} },+ { data: [], meta: { total: '0' } },+ { data: [], meta: { total: -1 } },+ { data: [], meta: { total: 0.5 } },+ { data: [], meta: { total: 1 } },+ { data: [job()], meta: { total: 0 } },+ ])('rejects an unread or inconsistent envelope %# instead of returning no jobs', (response) => {+ expect(() => parseReplicationInventory(response)).toThrow(ReplicationInventoryFormatError);+ });++ it.each([null, [], true, 'job', {}, { ...job(), enabled: 'false' }])(+ 'rejects a malformed row %# without dropping just that job',+ (row) => {+ expect(() => parseReplicationInventory(payload([job(), row]))).toThrow(+ ReplicationInventoryFormatError,+ );+ },+ );++ it.each(['id', 'instance', 'jobId', 'enabled'])('requires %s from the producer', (field) => {+ const row: Record<string, unknown> = job();+ delete row[field];+ expect(() => parseReplicationInventory(payload([row]))).toThrow(+ ReplicationInventoryFormatError,+ );+ });++ it.each([+ ['id', ' '],+ ['instance', ''],+ ['jobId', null],+ ['enabled', 1],+ ['guestId', '100'],+ ['guestId', -1],+ ['guestId', 1.5],+ ['guestName', {}],+ ['guestType', true],+ ['guest', []],+ ['guestNode', null],+ ['sourceNode', []],+ ['targetNode', {}],+ ['sourceStorage', 1],+ ['targetStorage', null],+ ['schedule', []],+ ['lastSyncStatus', {}],+ ['lastSyncTime', {}],+ ['nextSyncTime', true],+ ['lastSyncUnix', '1793322000'],+ ['nextSyncUnix', Infinity],+ ['lastSyncDurationSeconds', -1],+ ['lastSyncDurationHuman', []],+ ['failCount', '0'],+ ['failCount', 0.5],+ ['failCount', NaN],+ ['failCount', -1],+ ['rateLimitMbps', -1],+ ['error', {}],+ ['comment', false],+ ])('rejects wrongly typed %s (%#) before classification, search or links', (field, value) => {+ expect(() =>+ parseReplicationInventory(payload([{ ...job(), [field as string]: value }])),+ ).toThrow(ReplicationInventoryFormatError);+ });++ it('rejects identical and conflicting duplicate disclosure IDs', () => {+ for (const duplicate of [job(), { ...job(), instance: 'site-b', enabled: false }]) {+ expect(() => parseReplicationInventory(payload([job(), duplicate]))).toThrow(+ ReplicationInventoryFormatError,+ );+ }+ });++ it('rejects duplicate native jobs even when the projected IDs differ', () => {+ expect(() => parseReplicationInventory(payload([job(), { ...job(), id: 'other' }]))).toThrow(+ ReplicationInventoryFormatError,+ );+ });++ it('never includes response data in the error', () => {+ const marker = 'private-provider-response';+ let error: unknown;+ try {+ parseReplicationInventory({ error: marker });+ } catch (caught) {+ error = caught;+ }+ expect(error).toBeInstanceOf(ReplicationInventoryFormatError);+ expect((error as Error).message).toContain('Missing jobs do not mean none are configured.');+ expect(String(error)).not.toContain(marker);+ });+});diff --git a/frontend-modern/src/features/proxmox/proxmoxReplicationInventory.ts b/frontend-modern/src/features/proxmox/proxmoxReplicationInventory.tsnew file mode 100644index 0000000000..5221273aef--- /dev/null+++ b/frontend-modern/src/features/proxmox/proxmoxReplicationInventory.ts@@ -0,0 +1,99 @@+import type { ReplicationJob } from '@/types/api';++export class ReplicationInventoryFormatError extends Error {+ constructor() {+ // Provider response bodies, identifiers and JSON parser text stay private.+ super(+ 'The replication response format is invalid. Missing jobs do not mean none are configured.',+ );+ this.name = 'ReplicationInventoryFormatError';+ }+}++type FieldCheck = (value: unknown) => boolean;+const isRecord = (value: unknown): value is Record<string, unknown> =>+ value !== null && typeof value === 'object' && !Array.isArray(value);+const isString: FieldCheck = (value) => typeof value === 'string';+const isID: FieldCheck = (value) => isString(value) && (value as string).trim().length > 0;+const isNumber: FieldCheck = (value) => typeof value === 'number' && Number.isFinite(value);+const isNonnegativeNumber: FieldCheck = (value) => isNumber(value) && (value as number) >= 0;+const isCount: FieldCheck = (value) => isNonnegativeNumber(value) && Number.isSafeInteger(value);+const isTime: FieldCheck = (value) => isString(value) || isNumber(value);+const optional =+ (check: FieldCheck): FieldCheck =>+ (value) =>+ value === undefined || check(value);++// Validate the fields the table consumes before it classifies, searches or+// links a job. Do not coerce truthy flags, drop malformed rows or guess identity.+// Unknown fields and status strings remain forward-compatible. Time strings+// keep the existing presentation rules; this is not a chronology assessment.+const jobShape: Readonly<Record<string, FieldCheck>> = {+ id: isID,+ instance: isID,+ jobId: isID,+ enabled: (value) => typeof value === 'boolean',+ guestId: optional(isCount),+ ...Object.fromEntries(+ [+ 'guest',+ 'guestName',+ 'guestType',+ 'guestNode',+ 'sourceNode',+ 'sourceStorage',+ 'targetNode',+ 'targetStorage',+ 'schedule',+ 'lastSyncStatus',+ 'lastSyncDurationHuman',+ 'error',+ 'comment',+ ].map((field) => [field, optional(isString)]),+ ),+ lastSyncTime: optional(isTime),+ nextSyncTime: optional(isTime),+ lastSyncUnix: optional(isNumber),+ nextSyncUnix: optional(isNumber),+ lastSyncDurationSeconds: optional(isNonnegativeNumber),+ failCount: optional(isCount),+ rateLimitMbps: optional(isNonnegativeNumber),+};++export function parseReplicationInventory(payload: unknown): ReplicationJob[] {+ // This endpoint returns one complete, unpaginated snapshot. Only an explicit+ // empty array with a matching total establishes absence, never a missing list.+ if (+ !isRecord(payload) ||+ !Array.isArray(payload.data) ||+ !isRecord(payload.meta) ||+ !isCount(payload.meta.total) ||+ payload.meta.total !== payload.data.length+ ) {+ throw new ReplicationInventoryFormatError();+ }+ const fields = Object.entries(jobShape);+ const ids = new Set<string>();+ const subjects = new Set<string>();+ for (const row of payload.data) {+ if (!isRecord(row) || !fields.every(([field, check]) => check(row[field]))) {+ throw new ReplicationInventoryFormatError();+ }+ const id = row.id as string;+ const subject = JSON.stringify([row.instance, row.jobId]);+ // Disclosure and counts require one unambiguous row per native job. Native+ // job IDs can repeat across independent connections, not within one.+ if (ids.has(id) || subjects.has(subject)) throw new ReplicationInventoryFormatError();+ ids.add(id);+ subjects.add(subject);+ }+ return payload.data as ReplicationJob[];+}++export async function readReplicationInventoryJSON(response: Response): Promise<unknown> {+ try {+ return await response.json();+ } catch {+ throw new ReplicationInventoryFormatError();+ }+}diff --git a/scripts/release_control/subsystem_lookup_test.py b/scripts/release_control/subsystem_lookup_test.pyindex a54f44a46f..43caf5b25a 100644--- a/scripts/release_control/subsystem_lookup_test.py+++ b/scripts/release_control/subsystem_lookup_test.py@@ -97,6 +97,24 @@ def _contract_reference(contract_path: str, needle: str, runtime_path: str) -> dclass SubsystemLookupTest(unittest.TestCase):+ def test_replication_inventory_uses_complete_wire_and_consumer_proof(self):+ paths = [+ "frontend-modern/src/features/proxmox/proxmoxReplicationInventory.ts",+ "frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx",+ ]+ result = lookup_paths(paths)+ self.assertEqual(result["unowned_runtime_files"], [])+ for entry in result["files"]:+ match = next(item for item in entry["matches"] if item["subsystem"] == "unified-resources")+ proof = match["verification_requirement"]+ self.assertEqual(proof["id"], "replication-inventory")+ self.assertFalse(proof["allow_same_subsystem_tests"])+ self.assertEqual(proof["test_prefixes"], [])+ self.assertIn("frontend-modern/src/features/proxmox/__tests__/proxmoxReplicationInventory.test.ts", proof["exact_files"])+ self.assertIn("frontend-modern/src/features/proxmox/__tests__/ProxmoxReplicationTable.test.tsx", proof["exact_files"])+ self.assertIn("frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx", proof["exact_files"])++def test_sso_provider_management_uses_label_and_runtime_proof(self) -> None:result = lookup_paths(["internal/api/identity_sso_handlers.go"])file_result = result["files"][0]