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.

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.md
index 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 at
runtime the three parameters that reach the wire and that a backend response's
meta 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 the
Proxmox Backups tab reads, and nothing else. That endpoint also returns its
diff --git a/frontend-modern/src/api/__tests__/recoveryTransport.test.ts b/frontend-modern/src/api/__tests__/recoveryTransport.test.ts
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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) };
+};