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
Reject unread TrueNAS protection histories
pulse-triage[bot]2fb1c2afe3d3
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex 06e5d9a0bb..63394cbbbc 100644--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md@@ -5996,6 +5996,30 @@ with its reader.keys, the result members and the response keys at the type level, and atruntime the three parameters that reach the wire and that a backend response'smeta does not survive the decode.++The points decoder accepts an explicit `data` array only, matching the handler's+allocated empty slice. Missing, null or non-array collections are failed reads,+never evidence of absent snapshots or replication. Each page is validated before+normalization: required row identity/kind/mode/outcome, consumed optional field+types and unique event IDs must be usable. One malformed row rejects the page;+no partial list or duplicate-key replacement can masquerade as a complete read.+Unknown kind/mode/outcome strings, extra fields, legacy subject/provider aliases,+optional nulls and malformed timestamp strings retain existing presentation+fallbacks. Date validity remains the consuming surface's responsibility.++`useRecoveryPoints` reads unknown wire data through that boundary. Initial format+failure reaches the existing TrueNAS Protection error/Refresh state; a failed+refresh keeps the last accepted events with their existing stale-data warning,+filters and details. Only a validated page clears the warning or replaces those+events, including a genuine empty array. Permission failures still withdraw+private rows. Parser errors never include response bodies or source identifiers.+`recoveryPointsResponse.test.ts`, `recoveryTransport.test.ts` and+`TrueNASProtectionTable.refresh.test.tsx` cover admission and the consuming+failure/recovery path. Desktop/narrow browser proof must exercise malformed+HTTP-success responses through the real client and table and inspect pixels.+No backend, pagination, retention, permission, provider or guest-operation+contract changes; this is truthful history inspection, not native recovery.+`useProtectionPostures.ts` holds the same line for `GET /api/recovery/postures`:`ProtectionPosturesResponse` carries the posture rows and the policy that theProxmox Backups tab reads, and nothing else. That endpoint also returns itsdiff --git a/frontend-modern/src/api/__tests__/recoveryTransport.test.ts b/frontend-modern/src/api/__tests__/recoveryTransport.test.tsindex 35eb6c063c..5a47e30731 100644--- a/frontend-modern/src/api/__tests__/recoveryTransport.test.ts+++ b/frontend-modern/src/api/__tests__/recoveryTransport.test.ts@@ -39,6 +39,28 @@ const productionSources = (dir: string): string[] =>});describe('recovery transport', () => {+ it('keeps an unread points page failed until an explicit valid page is received', async () => {+ apiFetchJSONMock.mockResolvedValueOnce({ private: 'private-provider-response' });+ let dispose = () => {};+ const recovery = createRoot((rootDispose) => {+ dispose = rootDispose;+ return useRecoveryPoints(() => ({ platform: 'truenas', page: 1, limit: 200 }));+ });+ try {+ await vi.waitFor(() => expect(recovery.response.error).toBeInstanceOf(Error));+ expect(recovery.points()).toEqual([]);+ expect((recovery.response.error as Error).message).toBe(+ 'The recovery point response format is invalid.',+ );+ apiFetchJSONMock.mockResolvedValueOnce({ data: [] });+ await recovery.refetch();+ expect(recovery.points()).toEqual([]);+ expect(recovery.response.error).toBeNull();+ } finally {+ dispose();+ }+ });+it('normalizes legacy subject recovery fields onto canonical item fields', () => {expect(normalizeRecoveryPointsResponse({diff --git a/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.refresh.test.tsx b/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.refresh.test.tsxindex afc3bc42b7..0f66796fac 100644--- a/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.refresh.test.tsx+++ b/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.refresh.test.tsx@@ -75,6 +75,62 @@ afterEach(() => {});describe('TrueNAS protection refresh evidence', () => {+ it.each([{}, { data: null }, { data: {} }, { data: [point('unexpected'), { id: 'broken' }] }])(+ 'shows an initial read failure for malformed HTTP-success data (%j), not no activity',+ async (payload) => {+ apiFetchJSON.mockResolvedValueOnce(payload);+ mountProtection();+ await vi.waitFor(() =>+ expect(screen.getByText('Could not load TrueNAS protection')).toBeInTheDocument(),+ );+ expect(screen.queryByText('No TrueNAS protection activity')).not.toBeInTheDocument();+ expect(document.querySelector('[data-truenas-protection-row]')).toBeNull();+ expect(screen.getByRole('button', { name: 'Refresh' })).toBeEnabled();+ },+ );++ it('retains labelled evidence through malformed refreshes and replaces it only with a validated page', async () => {+ apiFetchJSON.mockResolvedValueOnce({ data: [point('apps')] });+ const recovery = mountProtection();+ await expectLoaded();+ await fireEvent.click(row('apps')!);+ expect(screen.getByTestId('truenas-protection-detail')).toHaveTextContent('tank/apps');++ for (const payload of [+ { private: 'private-provider-detail' },+ { data: null },+ {+ data: [+ point('unexpected'),+ { ...point('broken'), outcome: { secret: 'private-provider-detail' } },+ ],+ },+ { data: [point('duplicate'), point('duplicate', 'failed')] },+ ]) {+ apiFetchJSON.mockResolvedValueOnce(payload);+ await recovery().refetch({ background: true });+ expect(notice()).toHaveTextContent('Showing previously loaded events.');+ expect(row('apps')).not.toBeNull();+ expect(row('unexpected')).toBeNull();+ expect(row('duplicate')).toBeNull();+ expect(screen.getByTestId('truenas-protection-detail')).toHaveTextContent('tank/apps');+ expect(document.body).not.toHaveTextContent('private-provider-detail');+ expect(screen.queryByText('No TrueNAS protection activity')).not.toBeInTheDocument();+ }++ apiFetchJSON.mockResolvedValueOnce({ data: [point('current', 'warning')] });+ await fireEvent.click(+ within(notice()).getByRole('button', { name: 'Refresh TrueNAS protection' }),+ );+ await vi.waitFor(() => expect(row('current')).not.toBeNull());+ expect(row('apps')).toBeNull();+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ apiFetchJSON.mockResolvedValueOnce({ data: [] });+ await recovery().refetch({ background: true });+ expect(screen.getByText('No TrueNAS protection activity')).toBeInTheDocument();+ expect(document.querySelector('[data-truenas-protection-row]')).toBeNull();+ });+it('labels retained events after a background failure and keeps their filters and details usable', async () => {apiFetchJSON.mockResolvedValueOnce({ data: [point('apps'), point('archive', 'failed')] });const recovery = mountProtection();diff --git a/frontend-modern/src/hooks/useRecoveryPoints.ts b/frontend-modern/src/hooks/useRecoveryPoints.tsindex 001b926b2b..2de290a00d 100644--- a/frontend-modern/src/hooks/useRecoveryPoints.ts+++ b/frontend-modern/src/hooks/useRecoveryPoints.ts@@ -1,10 +1,6 @@import { Accessor, createMemo } from 'solid-js';import { apiFetchJSON } from '@/utils/apiClient';-import type {- RecoveryPoint,- RecoveryPointsResponse,- RecoveryPointsTransportResponse,-} from '@/types/recovery';+import type { RecoveryPoint, RecoveryPointsResponse } from '@/types/recovery';import { normalizeRecoveryPointsResponse } from '@/utils/recoveryPlatformModel';import { createNonSuspendingQuery } from '@/hooks/createNonSuspendingQuery';@@ -69,7 +65,7 @@ async function fetchRecoveryPointsResponse(query: RecoveryPointsQuery | undefined,): Promise<RecoveryPointsResponse> {const url = buildURL(query);- const response = await apiFetchJSON<RecoveryPointsTransportResponse>(url);+ const response = await apiFetchJSON<unknown>(url);return normalizeRecoveryPointsResponse(response);}diff --git a/frontend-modern/src/utils/__tests__/recoveryPlatformModel.branchcov2.test.ts b/frontend-modern/src/utils/__tests__/recoveryPlatformModel.branchcov2.test.tsindex e7c4dba820..1f86401cc1 100644--- a/frontend-modern/src/utils/__tests__/recoveryPlatformModel.branchcov2.test.ts+++ b/frontend-modern/src/utils/__tests__/recoveryPlatformModel.branchcov2.test.ts@@ -198,13 +198,13 @@ describe('recoveryPlatformModel.branchcov2', () => {});describe('normalizeRecoveryPointsResponse', () => {- it('coerces non-array data to [] and carries no response-level meta', () => {- expect(+ it('rejects non-array data rather than inventing an empty response', () => {+ expect(() =>normalizeRecoveryPointsResponse({data: 'not-an-array',meta: { page: NaN, limit: Infinity, total: 'twenty', totalPages: undefined },} as unknown as Parameters<typeof normalizeRecoveryPointsResponse>[0]),- ).toStrictEqual({ data: [] });+ ).toThrow('The recovery point response format is invalid.');});});});diff --git a/frontend-modern/src/utils/__tests__/recoveryPointsResponse.test.ts b/frontend-modern/src/utils/__tests__/recoveryPointsResponse.test.tsnew file mode 100644index 0000000000..2d31c6745c--- /dev/null+++ b/frontend-modern/src/utils/__tests__/recoveryPointsResponse.test.ts@@ -0,0 +1,113 @@+import { describe, expect, it } from 'vitest';++import { normalizeRecoveryPointsResponse } from '@/utils/recoveryPlatformModel';++const point = {+ id: 'snapshot-1',+ provider: 'truenas',+ kind: 'snapshot',+ mode: 'local',+ outcome: 'success',+ display: { subjectLabel: 'tank/apps', subjectType: 'dataset' },+};+const formatError = 'The recovery point response format is invalid.';++describe('recovery point response admission', () => {+ it.each([+ undefined,+ null,+ [],+ 'private-proxy-response',+ 1,+ {},+ { data: null },+ { data: {} },+ { data: 'private-proxy-response' },+ ])('rejects an unread inventory (%j), not a successful empty page', (payload) => {+ expect(() => normalizeRecoveryPointsResponse(payload)).toThrow(formatError);+ });++ it('accepts only an explicit empty array as an empty page and ignores unused pagination', () => {+ expect(normalizeRecoveryPointsResponse({ data: [], meta: { total: 0 } })).toEqual({ data: [] });+ });++ it.each([+ null,+ [],+ 'private-provider-row',+ {},+ { ...point, id: '' },+ { ...point, id: ' ' },+ { ...point, id: 10 },+ { ...point, kind: null },+ { ...point, mode: {} },+ { ...point, outcome: true },+ { ...point, provider: 42 },+ { ...point, platform: [] },+ { ...point, completedAt: {} },+ { ...point, startedAt: 42 },+ { ...point, sizeBytes: '123' },+ { ...point, sizeBytes: -1 },+ { ...point, sizeBytes: Infinity },+ { ...point, verified: 'false' },+ { ...point, encrypted: 1 },+ { ...point, immutable: [] },+ { ...point, display: 'private-provider-label' },+ { ...point, display: { detailsSummary: {} } },+ { ...point, display: { isWorkload: 'false' } },+ { ...point, itemRef: 'private-provider-identity' },+ { ...point, subjectRef: { name: {} } },+ { ...point, repositoryRef: [] },+ { ...point, details: [] },+ ])('rejects the entire page when any consumed row is malformed (%j)', (invalid) => {+ expect(() =>+ normalizeRecoveryPointsResponse({ data: [point, invalid], private: 'do-not-render' }),+ ).toThrow(formatError);+ });++ it('rejects duplicate identities rather than letting one event replace another', () => {+ expect(() =>+ normalizeRecoveryPointsResponse({ data: [point, { ...point, outcome: 'failed' }] }),+ ).toThrow(formatError);+ });++ it('preserves compatibility, unknown strings, optional nulls and unparseable date evidence', () => {+ const payload = {+ data: [+ {+ ...point,+ kind: 'future-kind',+ mode: 'future-mode',+ outcome: 'future-outcome',+ completedAt: '2026-02-30T10:00:00Z',+ startedAt: 'not-an-instant',+ sizeBytes: 0,+ verified: false,+ immutable: null,+ subjectRef: { type: 'truenas-dataset', name: 'tank/apps' },+ repositoryRef: null,+ details: { futureField: ['unknown', 1] },+ futureField: 'preserved',+ },+ ],+ };+ const before = structuredClone(payload);+ const [accepted] = normalizeRecoveryPointsResponse(payload).data;+ expect(accepted).toMatchObject({+ platform: 'truenas',+ kind: 'future-kind',+ mode: 'future-mode',+ outcome: 'future-outcome',+ completedAt: '2026-02-30T10:00:00Z',+ startedAt: 'not-an-instant',+ sizeBytes: 0,+ verified: false,+ immutable: null,+ itemRef: { type: 'truenas-dataset', name: 'tank/apps' },+ display: { itemLabel: 'tank/apps', itemType: 'dataset' },+ details: { futureField: ['unknown', 1] },+ futureField: 'preserved',+ });+ expect(payload).toEqual(before);+ });+});diff --git a/frontend-modern/src/utils/recoveryPlatformModel.ts b/frontend-modern/src/utils/recoveryPlatformModel.tsindex aff3b57374..eedb8f4d97 100644--- a/frontend-modern/src/utils/recoveryPlatformModel.ts+++ b/frontend-modern/src/utils/recoveryPlatformModel.ts@@ -3,7 +3,6 @@ import type {RecoveryPointDisplayTransport,RecoveryPoint,RecoveryPointsResponse,- RecoveryPointsTransportResponse,RecoveryPointTransport,} from '@/types/recovery';@@ -81,8 +80,94 @@ export const normalizeRecoveryPoint = (};};-export const normalizeRecoveryPointsResponse = (- response: RecoveryPointsTransportResponse,-): RecoveryPointsResponse => ({- data: Array.isArray(response?.data) ? response.data.map(normalizeRecoveryPoint) : [],-});+export class RecoveryPointsFormatError extends Error {+ constructor() {+ // Provider/proxy contents may be private. Do not put them in the error.+ super('The recovery point response format is invalid.');+ this.name = 'RecoveryPointsFormatError';+ }+}++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 optional =+ (check: FieldCheck): FieldCheck =>+ (value) =>+ value == null || check(value);+const hasShape = (value: unknown, shape: Readonly<Record<string, FieldCheck>>): boolean =>+ isRecord(value) && Object.entries(shape).every(([field, check]) => check(value[field]));++const displayShape = Object.fromEntries(+ [+ 'itemLabel',+ 'itemType',+ 'subjectLabel',+ 'subjectType',+ 'clusterLabel',+ 'nodeHostLabel',+ 'nodeAgentLabel',+ 'namespaceLabel',+ 'entityIdLabel',+ 'repositoryLabel',+ 'detailsSummary',+ ].map((field) => [field, optional(isString)]),+);+const refShape = Object.fromEntries(+ ['type', 'namespace', 'name', 'uid', 'id', 'class'].map((field) => [field, optional(isString)]),+);+const pointShape = {+ id: (value: unknown) => typeof value === 'string' && value.trim().length > 0,+ kind: isString,+ mode: isString,+ outcome: isString,+ ...Object.fromEntries(+ [+ 'platform',+ 'provider',+ 'entityId',+ 'cluster',+ 'node',+ 'namespace',+ 'startedAt',+ 'completedAt',+ 'itemResourceId',+ 'subjectResourceId',+ 'repositoryResourceId',+ 'providerScope',+ ].map((field) => [field, optional(isString)]),+ ),+ ...Object.fromEntries(+ ['verified', 'encrypted', 'immutable'].map((field) => [+ field,+ optional((value: unknown) => typeof value === 'boolean'),+ ]),+ ),+ sizeBytes: optional((value) => typeof value === 'number' && Number.isFinite(value) && value >= 0),+ display: optional((value) =>+ hasShape(value, {+ ...displayShape,+ isWorkload: optional((value) => typeof value === 'boolean'),+ }),+ ),+ itemRef: optional((value) => hasShape(value, refShape)),+ subjectRef: optional((value) => hasShape(value, refShape)),+ repositoryRef: optional((value) => hasShape(value, refShape)),+ details: optional(isRecord),+};++export const normalizeRecoveryPointsResponse = (response: unknown): RecoveryPointsResponse => {+ // The endpoint explicitly allocates an empty array. Missing/null/wrong-shaped+ // data is an unread inventory, not evidence that there are no restore points.+ // Admit the whole page before normalizing it; never silently drop a bad row.+ if (!isRecord(response) || !Array.isArray(response.data)) throw new RecoveryPointsFormatError();+ const ids = new Set<string>();+ for (const point of response.data) {+ if (!hasShape(point, pointShape) || ids.has(point.id)) throw new RecoveryPointsFormatError();+ ids.add(point.id);+ }+ // Dates remain strings so the consuming table can expose unknown instants;+ // new kind/mode/outcome strings keep their existing fallback presentation.+ return { data: response.data.map(normalizeRecoveryPoint) };+};