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.

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.md
index 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/cancellatio
focus ownership and the established sign-in behaviours. Browser proof exercises
the actual Login/API client/CSS with safe HTTP fixtures at desktop and narrow
widths; 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.json
index 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.md
index 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 access
denial (401 or 403) withdraws the jobs and the tab, and a direct link holds on
the 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 same
platform-table density contract as every other provider surface. Storage and
recovery owns which backup, datastore, workload-type, and VMID facts matter to
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 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 of
running on in the background, and it throws `apiErrorFromResponse` errors that
keep 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 one
track, so their md widths leave the name room for a typical node or service
name at a 768px viewport: Nodes 20 percent (with Capacity at 16 so its
diff --git a/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx b/frontend-modern/src/features/proxmox/ProxmoxReplicationTable.tsx
index 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 the
diff --git a/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx b/frontend-modern/src/features/proxmox/__tests__/ProxmoxPageSurface.contract.test.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.py
index 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) -> d
class 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]