Improve error boundary granularity with page and section level boundaries

Implement three-level error boundary strategy:
- Top-level (app shell): catches critical failures
- Page-level: preserves navigation when page crashes
- Section-level: graceful degradation for charts/tables

Create new components:
- PageErrorBoundary: wraps page routes
- SectionErrorBoundary: wraps data-heavy sections

Enhance ErrorBoundary with customizable titles, messages, and reload behavior.

Apply page boundaries to all route handlers in App.tsx.

Apply section boundaries to:
- DashboardPage: server status, ban trend, country charts, ban list
- JailsPage: jail overview, ban/unban form, IP lookup
- MapPage: world map, ban table
- ConfigPage: configuration editor
- HistoryPage: history table, IP detail view
- BlocklistsPage: sources, schedule, import log

Update Web-Development.md with error boundary strategy documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-04-28 08:33:39 +02:00
parent 42beb9cf3b
commit da6433b2cf
12 changed files with 453 additions and 143 deletions

View File

@@ -17,6 +17,11 @@
* - `/history` — event history (protected)
* - `/blocklists` — blocklist management (protected)
* All unmatched paths redirect to `/`.
*
* Error Boundaries:
* - Top-level ErrorBoundary wraps the entire app shell (rare full-page reload).
* - Each page route wrapped in PageErrorBoundary (page fails but nav persists).
* - Risky sections within pages wrapped in SectionErrorBoundary (graceful degradation).
*/
import { lazy, Suspense } from "react";
@@ -29,6 +34,7 @@ import { TimezoneProvider } from "./providers/TimezoneProvider";
import { RequireAuth } from "./components/RequireAuth";
import { SetupGuard } from "./components/SetupGuard";
import { ErrorBoundary } from "./components/ErrorBoundary";
import { PageErrorBoundary } from "./components/PageErrorBoundary";
import { MainLayout } from "./layouts/MainLayout";
const SetupPage = lazy(() => import("./pages/SetupPage").then((m) => ({ default: m.SetupPage })));
@@ -50,21 +56,34 @@ function AppContents(): React.JSX.Element {
return (
<FluentProvider theme={theme}>
<ErrorBoundary>
<ErrorBoundary
title="Application Error"
message="The application encountered a critical error. Reloading may help."
isFullPage={true}
>
<BrowserRouter future={{ v7_startTransition: true, v7_relativeSplatPath: true }}>
<Suspense fallback={<Spinner size="large" label="Loading…" />}>
<AuthProvider>
<Routes>
{/* Setup wizard — always accessible; redirects to /login if already done */}
<Route path="/setup" element={<SetupPage />} />
<Route
path="/setup"
element={
<PageErrorBoundary pageName="Setup">
<SetupPage />
</PageErrorBoundary>
}
/>
{/* Login — requires setup to be complete */}
<Route
path="/login"
element={
<SetupGuard>
<LoginPage />
</SetupGuard>
<PageErrorBoundary pageName="Login">
<SetupGuard>
<LoginPage />
</SetupGuard>
</PageErrorBoundary>
}
/>
@@ -80,13 +99,62 @@ function AppContents(): React.JSX.Element {
</SetupGuard>
}
>
<Route index element={<DashboardPage />} />
<Route path="/map" element={<MapPage />} />
<Route path="/jails" element={<JailsPage />} />
<Route path="/jails/:name" element={<JailDetailPage />} />
<Route path="/config" element={<ConfigPage />} />
<Route path="/history" element={<HistoryPage />} />
<Route path="/blocklists" element={<BlocklistsPage />} />
<Route
index
element={
<PageErrorBoundary pageName="Dashboard">
<DashboardPage />
</PageErrorBoundary>
}
/>
<Route
path="/map"
element={
<PageErrorBoundary pageName="Map">
<MapPage />
</PageErrorBoundary>
}
/>
<Route
path="/jails"
element={
<PageErrorBoundary pageName="Jails">
<JailsPage />
</PageErrorBoundary>
}
/>
<Route
path="/jails/:name"
element={
<PageErrorBoundary pageName="Jail Details">
<JailDetailPage />
</PageErrorBoundary>
}
/>
<Route
path="/config"
element={
<PageErrorBoundary pageName="Configuration">
<ConfigPage />
</PageErrorBoundary>
}
/>
<Route
path="/history"
element={
<PageErrorBoundary pageName="History">
<HistoryPage />
</PageErrorBoundary>
}
/>
<Route
path="/blocklists"
element={
<PageErrorBoundary pageName="Blocklists">
<BlocklistsPage />
</PageErrorBoundary>
}
/>
</Route>
{/* Fallback — redirect unknown paths to dashboard */}

View File

@@ -2,6 +2,8 @@
* React error boundary component.
*
* Catches render-time exceptions in child components and shows a fallback UI.
* This is the base component; use PageErrorBoundary or SectionErrorBoundary
* for page and section-level boundaries.
*/
import React from "react";
import { Button, makeStyles, Text, tokens } from "@fluentui/react-components";
@@ -13,14 +15,22 @@ interface ErrorBoundaryState {
interface ErrorBoundaryProps {
children: React.ReactNode;
title?: string;
message?: string;
showReloadButton?: boolean;
isFullPage?: boolean;
onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
}
interface ErrorBoundaryFallbackProps {
title: string;
message: string;
showReloadButton: boolean;
isFullPage: boolean;
onReload: () => void;
}
const useFallbackStyles = makeStyles({
const useFullPageStyles = makeStyles({
root: {
display: "flex",
flexDirection: "column",
@@ -36,20 +46,46 @@ const useFallbackStyles = makeStyles({
},
});
function ErrorBoundaryFallback({ message, onReload }: ErrorBoundaryFallbackProps): React.ReactElement {
const styles = useFallbackStyles();
const useSectionStyles = makeStyles({
root: {
display: "flex",
flexDirection: "column",
alignItems: "flex-start",
padding: tokens.spacingVerticalM,
backgroundColor: tokens.colorNeutralBackground3,
borderRadius: tokens.borderRadiusMedium,
border: `1px solid ${tokens.colorStatusWarningForeground1}`,
gap: tokens.spacingVerticalM,
},
message: {
color: tokens.colorNeutralForeground1,
},
});
function ErrorBoundaryFallback({
title,
message,
showReloadButton,
isFullPage,
onReload,
}: ErrorBoundaryFallbackProps): React.ReactElement {
const fullPageStyles = useFullPageStyles();
const sectionStyles = useSectionStyles();
const styles = isFullPage ? fullPageStyles : sectionStyles;
return (
<div className={styles.root} role="alert">
<Text as="h1" size={700} weight="semibold">
Something went wrong
<Text as={isFullPage ? "h1" : "h2"} size={isFullPage ? 700 : 500} weight="semibold">
{title}
</Text>
<Text size={300} className={styles.message}>
<Text size={isFullPage ? 300 : 200} className={isFullPage ? fullPageStyles.message : sectionStyles.message}>
{message}
</Text>
<Button appearance="primary" onClick={onReload}>
Reload
</Button>
{showReloadButton && (
<Button appearance="primary" onClick={onReload}>
{isFullPage ? "Reload Page" : "Retry"}
</Button>
)}
</div>
);
}
@@ -65,18 +101,37 @@ export class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoun
}
componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
console.error("ErrorBoundary caught an error", { error, errorInfo });
const { onError } = this.props;
if (onError) {
onError(error, errorInfo);
} else {
console.error("ErrorBoundary caught an error", { error, errorInfo });
}
}
handleReload = (): void => {
window.location.reload();
if (this.props.isFullPage) {
window.location.reload();
} else {
this.setState({ hasError: false, errorMessage: null });
}
};
render(): React.ReactNode {
if (this.state.hasError) {
const {
title = "Something went wrong",
message = "Please try again or contact support if the problem persists.",
showReloadButton = true,
isFullPage = true,
} = this.props;
return (
<ErrorBoundaryFallback
message={this.state.errorMessage ?? "Please try reloading the page."}
title={title}
message={message}
showReloadButton={showReloadButton}
isFullPage={isFullPage}
onReload={this.handleReload}
/>
);

View File

@@ -0,0 +1,42 @@
/**
* Page-level error boundary.
*
* Wraps entire page components to catch rendering errors while preserving
* the app shell (navigation, theme, auth). When an error occurs, shows a
* full-page fallback but the user can still navigate away via the sidebar.
*
* Use this for wrapping page components in App.tsx routes.
*/
import React from "react";
import { ErrorBoundary } from "./ErrorBoundary";
interface PageErrorBoundaryProps {
children: React.ReactNode;
pageName?: string;
onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
}
/**
* Wraps a page component with error boundary protection.
*
* @param children - Page component to wrap
* @param pageName - Name of page for error message (default: "Page")
* @param onError - Optional callback for error logging
*/
export function PageErrorBoundary({
children,
pageName = "Page",
onError,
}: PageErrorBoundaryProps): React.JSX.Element {
return (
<ErrorBoundary
title={`${pageName} Error`}
message={`The ${pageName.toLowerCase()} encountered an error and could not load. Please try navigating to another page or reloading.`}
showReloadButton={true}
isFullPage={false}
onError={onError}
>
{children}
</ErrorBoundary>
);
}

View File

@@ -0,0 +1,46 @@
/**
* Section-level error boundary.
*
* Wraps individual data-heavy sections (charts, tables, forms) within a page
* to provide graceful degradation. When an error occurs, only that section
* fails to render; the rest of the page remains functional.
*
* Use this to wrap:
* - Charts (BanTrendChart, TopCountriesBarChart, etc.)
* - Data tables (BanTable, JailOverviewSection, etc.)
* - Forms with complex logic
* - Any component that fetches data or has risky side effects
*/
import React from "react";
import { ErrorBoundary } from "./ErrorBoundary";
interface SectionErrorBoundaryProps {
children: React.ReactNode;
sectionName?: string;
onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
}
/**
* Wraps a section component with error boundary protection.
*
* @param children - Section component to wrap
* @param sectionName - Name of section for error message (default: "Section")
* @param onError - Optional callback for error logging
*/
export function SectionErrorBoundary({
children,
sectionName = "Section",
onError,
}: SectionErrorBoundaryProps): React.JSX.Element {
return (
<ErrorBoundary
title={`${sectionName} Unavailable`}
message={`Could not load ${sectionName.toLowerCase()}. The rest of the page is still functional.`}
showReloadButton={true}
isFullPage={false}
onError={onError}
>
{children}
</ErrorBoundary>
);
}

View File

@@ -2,10 +2,12 @@
* BlocklistsPage — external IP blocklist source management.
*
* Responsible for composition of sources, schedule, and import log sections.
* Sections are wrapped with SectionErrorBoundary for independent resilience.
*/
import { useCallback, useState } from "react";
import { MessageBar, MessageBarBody, Text } from "@fluentui/react-components";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { useBlocklistStyles } from "../components/blocklist/blocklistStyles";
import { BlocklistSourcesSection } from "../components/blocklist/BlocklistSourcesSection";
import { BlocklistScheduleSection } from "../components/blocklist/BlocklistScheduleSection";
@@ -36,9 +38,17 @@ export function BlocklistsPage(): React.JSX.Element {
</MessageBar>
)}
<BlocklistSourcesSection onRunImport={handleRunImport} runImportRunning={running} />
<BlocklistScheduleSection onRunImport={handleRunImport} runImportRunning={running} importLastResult={lastResult} />
<BlocklistImportLogSection />
<SectionErrorBoundary sectionName="Blocklist Sources">
<BlocklistSourcesSection onRunImport={handleRunImport} runImportRunning={running} />
</SectionErrorBoundary>
<SectionErrorBoundary sectionName="Blocklist Schedule">
<BlocklistScheduleSection onRunImport={handleRunImport} runImportRunning={running} importLastResult={lastResult} />
</SectionErrorBoundary>
<SectionErrorBoundary sectionName="Blocklist Import Log">
<BlocklistImportLogSection />
</SectionErrorBoundary>
<ImportResultDialog
open={importResultOpen}

View File

@@ -10,9 +10,13 @@
* Actions — structured action.d form editor
* Server — server-level settings, map thresholds, service health + log viewer
* Regex Tester — live pattern tester
*
* Configuration content is wrapped with SectionErrorBoundary to prevent
* one tab or editor from crashing the entire page.
*/
import { Text, makeStyles, tokens } from "@fluentui/react-components";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { ConfigPageContainer } from "../components/config/ConfigPageContainer";
const useStyles = makeStyles({
@@ -44,7 +48,9 @@ export function ConfigPage(): React.JSX.Element {
</Text>
</div>
<ConfigPageContainer />
<SectionErrorBoundary sectionName="Configuration Editor">
<ConfigPageContainer />
</SectionErrorBoundary>
</div>
);
}

View File

@@ -4,6 +4,9 @@
* Composes the fail2ban server status bar at the top, a shared time-range
* selector, and the ban list showing aggregate bans from the fail2ban
* database. The time-range selection controls how far back to look.
*
* Sections are wrapped with SectionErrorBoundary to provide graceful
* degradation if individual charts or tables fail to render.
*/
import { Text, makeStyles, tokens } from "@fluentui/react-components";
@@ -14,6 +17,7 @@ import { DashboardFilterBar } from "../components/DashboardFilterBar";
import { ServerStatusBar } from "../components/ServerStatusBar";
import { TopCountriesBarChart } from "../components/TopCountriesBarChart";
import { TopCountriesPieChart } from "../components/TopCountriesPieChart";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { useCommonSectionStyles } from "../components/commonStyles";
import { useDashboardCountryData } from "../hooks/useDashboardCountryData";
import { DashboardFilterProvider, useDashboardFilters } from "./DashboardFilterProvider";
@@ -69,7 +73,8 @@ const useStyles = makeStyles({
* Main dashboard landing page.
*
* Displays the fail2ban server status, a time-range selector, and the
* ban list table.
* ban list table. Each section is protected with a SectionErrorBoundary
* so that a failure in one section does not crash the entire page.
*/
function DashboardPageContent(): React.JSX.Element {
const styles = useStyles();
@@ -85,7 +90,9 @@ function DashboardPageContent(): React.JSX.Element {
{/* ------------------------------------------------------------------ */}
{/* Server status bar */}
{/* ------------------------------------------------------------------ */}
<ServerStatusBar />
<SectionErrorBoundary sectionName="Server Status">
<ServerStatusBar />
</SectionErrorBoundary>
{/* ------------------------------------------------------------------ */}
{/* Global filter bar */}
@@ -109,11 +116,13 @@ function DashboardPageContent(): React.JSX.Element {
</Text>
</div>
<div className={styles.tabContent}>
<BanTrendChart
timeRange={timeRange}
origin={originFilter}
source={source}
/>
<SectionErrorBoundary sectionName="Ban Trend Chart">
<BanTrendChart
timeRange={timeRange}
origin={originFilter}
source={source}
/>
</SectionErrorBoundary>
</div>
</div>
@@ -127,28 +136,30 @@ function DashboardPageContent(): React.JSX.Element {
</Text>
</div>
<div className={styles.tabContent}>
<ChartStateWrapper
isLoading={countryLoading}
error={countryError}
onRetry={reloadCountry}
isEmpty={!countryLoading && Object.keys(countries).length === 0}
emptyMessage="No ban data for the selected period."
>
<div className={styles.chartsRow}>
<div className={styles.chartCard}>
<TopCountriesPieChart
countries={countries}
countryNames={countryNames}
/>
<SectionErrorBoundary sectionName="Country Charts">
<ChartStateWrapper
isLoading={countryLoading}
error={countryError}
onRetry={reloadCountry}
isEmpty={!countryLoading && Object.keys(countries).length === 0}
emptyMessage="No ban data for the selected period."
>
<div className={styles.chartsRow}>
<div className={styles.chartCard}>
<TopCountriesPieChart
countries={countries}
countryNames={countryNames}
/>
</div>
<div className={styles.chartCard}>
<TopCountriesBarChart
countries={countries}
countryNames={countryNames}
/>
</div>
</div>
<div className={styles.chartCard}>
<TopCountriesBarChart
countries={countries}
countryNames={countryNames}
/>
</div>
</div>
</ChartStateWrapper>
</ChartStateWrapper>
</SectionErrorBoundary>
</div>
</div>
@@ -164,11 +175,13 @@ function DashboardPageContent(): React.JSX.Element {
{/* Ban table */}
<div className={styles.tabContent}>
<BanTable
timeRange={timeRange}
origin={originFilter}
source={source}
/>
<SectionErrorBoundary sectionName="Ban List">
<BanTable
timeRange={timeRange}
origin={originFilter}
source={source}
/>
</SectionErrorBoundary>
</div>
</div>
</div>
@@ -183,3 +196,4 @@ export function DashboardPage(): React.JSX.Element {
);
}

View File

@@ -4,6 +4,8 @@
* Shows a paginated, filterable table of every ban ever recorded in the
* fail2ban database. Clicking an IP address opens a per-IP timeline view.
* Rows with repeatedly-banned IPs are highlighted in amber.
*
* The history table is wrapped with SectionErrorBoundary for resilience.
*/
import { useCallback, useEffect, useMemo, useState } from "react";
@@ -30,6 +32,7 @@ import {
ChevronRightRegular,
} from "@fluentui/react-icons";
import { DashboardFilterBar } from "../components/DashboardFilterBar";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { useHistory } from "../hooks/useHistory";
import { IpDetailView } from "./history/IpDetailView";
import { HISTORY_PAGE_SIZE } from "../utils/constants";
@@ -236,12 +239,14 @@ export function HistoryPage(): React.JSX.Element {
if (selectedIp !== null) {
return (
<div className={styles.root}>
<IpDetailView
ip={selectedIp}
onBack={(): void => {
setSelectedIp(null);
}}
/>
<SectionErrorBoundary sectionName="IP Detail View">
<IpDetailView
ip={selectedIp}
onBack={(): void => {
setSelectedIp(null);
}}
/>
</SectionErrorBoundary>
</div>
);
}
@@ -306,38 +311,40 @@ export function HistoryPage(): React.JSX.Element {
{/* DataGrid table */}
{/* ---------------------------------------------------------------- */}
{!loading && !error && (
<div className={styles.tableWrapper}>
<DataGrid
items={items}
columns={columns}
getRowId={(item: HistoryBanItem) => `${item.ip}-${item.banned_at}`}
focusMode="composite"
>
<DataGridHeader>
<DataGridRow>
{({ renderHeaderCell }) => (
<DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>
)}
</DataGridRow>
</DataGridHeader>
<DataGridBody<HistoryBanItem>>
{({ item }) => (
<DataGridRow<HistoryBanItem>
key={`${item.ip}-${item.banned_at}`}
className={
item.ban_count >= HIGH_BAN_THRESHOLD
? styles.highBanRow
: undefined
}
>
{({ renderCell }) => (
<DataGridCell>{renderCell(item)}</DataGridCell>
<SectionErrorBoundary sectionName="History Table">
<div className={styles.tableWrapper}>
<DataGrid
items={items}
columns={columns}
getRowId={(item: HistoryBanItem) => `${item.ip}-${item.banned_at}`}
focusMode="composite"
>
<DataGridHeader>
<DataGridRow>
{({ renderHeaderCell }) => (
<DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>
)}
</DataGridRow>
)}
</DataGridBody>
</DataGrid>
</div>
</DataGridHeader>
<DataGridBody<HistoryBanItem>>
{({ item }) => (
<DataGridRow<HistoryBanItem>
key={`${item.ip}-${item.banned_at}`}
className={
item.ban_count >= HIGH_BAN_THRESHOLD
? styles.highBanRow
: undefined
}
>
{({ renderCell }) => (
<DataGridCell>{renderCell(item)}</DataGridCell>
)}
</DataGridRow>
)}
</DataGridBody>
</DataGrid>
</div>
</SectionErrorBoundary>
)}
{/* ---------------------------------------------------------------- */}

View File

@@ -1,4 +1,5 @@
import { Text } from "@fluentui/react-components";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { useJailsPageStyles } from "./jails/jailsPageStyles";
import { JailOverviewSection } from "./jails/JailOverviewSection";
import { BanUnbanForm } from "./jails/BanUnbanForm";
@@ -19,11 +20,17 @@ function JailsPageContent(): React.JSX.Element {
Jails
</Text>
<JailOverviewSection />
<SectionErrorBoundary sectionName="Jail Overview">
<JailOverviewSection />
</SectionErrorBoundary>
<BanUnbanForm jailNames={jailNames} onBan={banIp} onUnban={unbanIp} />
<SectionErrorBoundary sectionName="Ban/Unban Form">
<BanUnbanForm jailNames={jailNames} onBan={banIp} onUnban={unbanIp} />
</SectionErrorBoundary>
<IpLookupSection />
<SectionErrorBoundary sectionName="IP Lookup">
<IpLookupSection />
</SectionErrorBoundary>
</div>
);
}

View File

@@ -4,6 +4,8 @@
* Shows a clickable SVG world map coloured by ban density, a time-range
* selector, and a companion table filtered by the selected country (or all
* bans when no country is selected).
*
* Critical sections wrapped with SectionErrorBoundary for resilience.
*/
import { useState, useMemo, useEffect } from "react";
@@ -23,6 +25,7 @@ import {
DismissRegular,
} from "@fluentui/react-icons";
import { DashboardFilterBar } from "../components/DashboardFilterBar";
import { SectionErrorBoundary } from "../components/SectionErrorBoundary";
import { WorldMap } from "../components/WorldMap";
import { useMapData } from "../hooks/useMapData";
import { useMapColorThresholds } from "../hooks/useMapColorThresholds";
@@ -250,15 +253,17 @@ export function MapPage(): React.JSX.Element {
{/* immediate visual feedback before the filtered data arrives. */}
{/* ---------------------------------------------------------------- */}
{!error && hasLoadedOnce && (
<WorldMap
countries={countries}
countryNames={countryNames}
selectedCountry={selectedCountry}
onSelectCountry={setSelectedCountry}
thresholdLow={thresholdLow}
thresholdMedium={thresholdMedium}
thresholdHigh={thresholdHigh}
/>
<SectionErrorBoundary sectionName="World Map">
<WorldMap
countries={countries}
countryNames={countryNames}
selectedCountry={selectedCountry}
onSelectCountry={setSelectedCountry}
thresholdLow={thresholdLow}
thresholdMedium={thresholdMedium}
thresholdHigh={thresholdHigh}
/>
</SectionErrorBoundary>
)}
{/* ---------------------------------------------------------------- */}
@@ -302,19 +307,21 @@ export function MapPage(): React.JSX.Element {
{/* Companion bans table */}
{/* ---------------------------------------------------------------- */}
{!error && hasLoadedOnce && (
<div className={mergeClasses(styles.tableWrapper, loading && styles.tableWrapperLoading)}>
<MapBansTable
pageBans={pageBans}
visibleCount={visibleBans.length}
page={page}
pageSize={pageSize}
totalPages={totalPages}
hasPrev={hasPrev}
hasNext={hasNext}
onPageChange={setPage}
onPageSizeChange={setPageSize}
/>
</div>
<SectionErrorBoundary sectionName="Map Ban Table">
<div className={mergeClasses(styles.tableWrapper, loading && styles.tableWrapperLoading)}>
<MapBansTable
pageBans={pageBans}
visibleCount={visibleBans.length}
page={page}
pageSize={pageSize}
totalPages={totalPages}
hasPrev={hasPrev}
hasNext={hasNext}
onPageChange={setPage}
onPageSizeChange={setPageSize}
/>
</div>
</SectionErrorBoundary>
)}
</div>
);