lukas.pupkalipinski/BanGUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Stage 11: polish, cross-cutting concerns & hardening

Browse Source 
- 11.1 MainLayout health indicator: warning MessageBar when fail2ban offline
- 11.2 formatDate utility + TimezoneProvider + GET /api/setup/timezone
- 11.3 Responsive sidebar: auto-collapse <640px, media query listener
- 11.4 PageFeedback (PageLoading/PageError/PageEmpty), BanTable updated
- 11.5 prefers-reduced-motion: disable sidebar transition
- 11.6 WorldMap ARIA: role/tabIndex/aria-label/onKeyDown for countries
- 11.7 Health transition logging (fail2ban_came_online/went_offline)
- 11.8 Global handlers: Fail2BanConnectionError/ProtocolError -> 502
- 11.9 379 tests pass, 82% coverage, ruff+mypy+tsc+eslint clean
- Timezone endpoint: setup_service.get_timezone, 5 new tests
This commit is contained in:
Lukas
2026-03-01 15:59:06 +01:00
parent 1efa0e973b
commit 1cdc97a729
19 changed files with 649 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
frontend/src/App.tsx
View File

@@ -23,6 +23,7 @@ import { FluentProvider } from "@fluentui/react-components";
import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";
import { lightTheme } from "./theme/customTheme";
import { AuthProvider } from "./providers/AuthProvider";
import { TimezoneProvider } from "./providers/TimezoneProvider";
import { RequireAuth } from "./components/RequireAuth";
import { MainLayout } from "./layouts/MainLayout";
import { SetupPage } from "./pages/SetupPage";
@@ -52,7 +53,9 @@ function App(): React.JSX.Element {
<Route
element={
<RequireAuth>
<MainLayout />
<TimezoneProvider>
<MainLayout />
</TimezoneProvider>
</RequireAuth>
}
>

1
frontend/src/api/endpoints.ts
View File

@@ -16,6 +16,7 @@ export const ENDPOINTS = {
// Setup wizard
// -------------------------------------------------------------------------
setup: "/setup",
setupTimezone: "/setup/timezone",
// -------------------------------------------------------------------------
// Authentication

13
frontend/src/api/setup.ts
View File

@@ -10,6 +10,7 @@ import type {
SetupRequest,
SetupResponse,
SetupStatusResponse,
SetupTimezoneResponse,
} from "../types/setup";
/**
@@ -30,3 +31,15 @@ export async function getSetupStatus(): Promise<SetupStatusResponse> {
export async function submitSetup(data: SetupRequest): Promise<SetupResponse> {
return api.post<SetupResponse>(ENDPOINTS.setup, data);
}
/**
* Fetch the IANA timezone configured during setup.
*
* Used by the frontend to convert UTC timestamps to the local timezone
* chosen by the administrator.
*
* @returns The configured timezone identifier (e.g. `"Europe/Berlin"`).
*/
export async function fetchTimezone(): Promise<SetupTimezoneResponse> {
return api.get<SetupTimezoneResponse>(ENDPOINTS.setupTimezone);
}

28
frontend/src/components/BanTable.tsx
View File

@@ -19,9 +19,6 @@ import {
DataGridHeader,
DataGridHeaderCell,
DataGridRow,
MessageBar,
MessageBarBody,
Spinner,
Text,
Tooltip,
makeStyles,
@@ -29,6 +26,7 @@ import {
type TableColumnDefinition,
createTableColumn,
} from "@fluentui/react-components";
import { PageEmpty, PageError, PageLoading } from "./PageFeedback";
import { ChevronLeftRegular, ChevronRightRegular } from "@fluentui/react-icons";
import { useBans, type BanTableMode } from "../hooks/useBans";
import type { AccessListItem, DashboardBanItem, TimeRange } from "../types/ban";
@@ -236,7 +234,7 @@ function buildAccessColumns(styles: ReturnType<typeof useStyles>): TableColumnDe
*/
export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element {
const styles = useStyles();
const { banItems, accessItems, total, page, setPage, loading, error } = useBans(
const { banItems, accessItems, total, page, setPage, loading, error, refresh } = useBans(
mode,
timeRange,
);
@@ -248,22 +246,14 @@ export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element
// Loading state
// --------------------------------------------------------------------------
if (loading) {
return (
<div className={styles.centred}>
<Spinner label="Loading…" />
</div>
);
return <PageLoading label="Loading…" />;
}
// --------------------------------------------------------------------------
// Error state
// --------------------------------------------------------------------------
if (error) {
return (
<MessageBar intent="error">
<MessageBarBody>{error}</MessageBarBody>
</MessageBar>
);
return <PageError message={error} onRetry={refresh} />;
}
// --------------------------------------------------------------------------
@@ -272,11 +262,11 @@ export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element
const isEmpty = mode === "bans" ? banItems.length === 0 : accessItems.length === 0;
if (isEmpty) {
return (
<div className={styles.centred}>
<Text size={300} style={{ color: tokens.colorNeutralForeground3 }}>
No {mode === "bans" ? "bans" : "accesses"} recorded in the selected time window.
</Text>
</div>
<PageEmpty
message={`No ${
mode === "bans" ? "bans" : "accesses"
} recorded in the selected time window.`}
/>
);
}

139
frontend/src/components/PageFeedback.tsx Normal file
View File

@@ -0,0 +1,139 @@
/**
* Reusable page-level feedback components.
*
* Three shared building blocks for consistent data-loading UI across all pages:
*
* - {@link PageLoading} — Centred `Spinner` for full-region loading states.
* - {@link PageError} — `MessageBar` with an error message and a retry button.
* - {@link PageEmpty} — Centred neutral message for zero-result states.
*/
import {
Button,
MessageBar,
MessageBarActions,
MessageBarBody,
MessageBarTitle,
Spinner,
Text,
makeStyles,
tokens,
} from "@fluentui/react-components";
import { ArrowClockwiseRegular } from "@fluentui/react-icons";
// ---------------------------------------------------------------------------
// Styles
// ---------------------------------------------------------------------------
const useStyles = makeStyles({
centred: {
display: "flex",
flexDirection: "column",
alignItems: "center",
justifyContent: "center",
minHeight: "120px",
gap: tokens.spacingVerticalM,
padding: tokens.spacingVerticalL,
},
emptyText: {
color: tokens.colorNeutralForeground3,
textAlign: "center",
},
});
// ---------------------------------------------------------------------------
// PageLoading
// ---------------------------------------------------------------------------
export interface PageLoadingProps {
/** Short description shown next to the spinner. */
label?: string;
}
/**
* Full-region loading indicator using a Fluent UI `Spinner`.
*
* @example
* ```tsx
* if (loading) return <PageLoading label="Loading jails…" />;
* ```
*/
export function PageLoading({ label = "Loading…" }: PageLoadingProps): React.JSX.Element {
const styles = useStyles();
return (
<div className={styles.centred} aria-live="polite" aria-label={label}>
<Spinner label={label} />
</div>
);
}
// ---------------------------------------------------------------------------
// PageError
// ---------------------------------------------------------------------------
export interface PageErrorProps {
/** Error message shown in the `MessageBar`. */
message: string;
/** Optional callback invoked when the user clicks "Retry". */
onRetry?: () => void;
}
/**
* Error state `MessageBar` with an optional retry button.
*
* @example
* ```tsx
* if (error) return <PageError message={error} onRetry={refresh} />;
* ```
*/
export function PageError({ message, onRetry }: PageErrorProps): React.JSX.Element {
return (
<MessageBar intent="error" role="alert">
<MessageBarBody>
<MessageBarTitle>Error</MessageBarTitle>
{message}
</MessageBarBody>
{onRetry != null && (
<MessageBarActions>
<Button
appearance="transparent"
size="small"
icon={<ArrowClockwiseRegular />}
onClick={onRetry}
aria-label="Retry"
>
Retry
</Button>
</MessageBarActions>
)}
</MessageBar>
);
}
// ---------------------------------------------------------------------------
// PageEmpty
// ---------------------------------------------------------------------------
export interface PageEmptyProps {
/** Message displayed to the user, e.g. "No bans found." */
message: string;
}
/**
* Centred empty-state message for tables or lists with zero results.
*
* @example
* ```tsx
* if (items.length === 0) return <PageEmpty message="No bans in this period." />;
* ```
*/
export function PageEmpty({ message }: PageEmptyProps): React.JSX.Element {
const styles = useStyles();
return (
<div className={styles.centred} role="status" aria-label={message}>
<Text size={200} className={styles.emptyText}>
{message}
</Text>
</div>
);
}

20
frontend/src/components/WorldMap.tsx
View File

@@ -102,9 +102,23 @@ function GeoLayer({
<g
key={geo.rsmKey}
style={{ cursor: cc ? "pointer" : "default" }}
role={cc ? "button" : undefined}
tabIndex={cc ? 0 : undefined}
aria-label={cc
? `${cc}: ${String(count)} ban${count !== 1 ? "s" : ""}${
isSelected ? " (selected)" : ""
}`
: undefined}
aria-pressed={isSelected || undefined}
onClick={(): void => {
if (cc) handleClick(cc);
}}
onKeyDown={(e): void => {
if (cc && (e.key === "Enter" || e.key === " ")) {
e.preventDefault();
handleClick(cc);
}
}}
>
<Geography
geography={geo}
@@ -170,7 +184,11 @@ export function WorldMap({
const maxCount = Math.max(0, ...Object.values(countries));
return (
<div className={styles.mapWrapper}>
<div
className={styles.mapWrapper}
role="img"
aria-label="World map showing banned IP counts by country. Click a country to filter the table below."
>
<ComposableMap
projection="geoMercator"
projectionConfig={{ scale: 130, center: [10, 20] }}

47
frontend/src/layouts/MainLayout.tsx
View File

@@ -6,11 +6,14 @@
* icon-only (48 px) on small screens.
*/
import { useCallback, useState } from "react";
import { useCallback, useEffect, useState } from "react";
import {
Button,
makeStyles,
mergeClasses,
MessageBar,
MessageBarBody,
MessageBarTitle,
Text,
tokens,
Tooltip,
@@ -27,6 +30,7 @@ import {
} from "@fluentui/react-icons";
import { NavLink, Outlet, useNavigate } from "react-router-dom";
import { useAuth } from "../providers/AuthProvider";
import { useServerStatus } from "../hooks/useServerStatus";
// ---------------------------------------------------------------------------
// Styles
@@ -56,6 +60,10 @@ const useStyles = makeStyles({
transition: "width 200ms ease",
overflow: "hidden",
flexShrink: 0,
// Honour the OS/browser reduced-motion preference.
"@media (prefers-reduced-motion: reduce)": {
transition: "none",
},
},
sidebarCollapsed: {
width: SIDEBAR_COLLAPSED,
@@ -137,6 +145,13 @@ const useStyles = makeStyles({
flexGrow: 1,
overflow: "auto",
},
warningBar: {
flexShrink: 0,
paddingLeft: tokens.spacingHorizontalM,
paddingRight: tokens.spacingHorizontalM,
paddingTop: tokens.spacingVerticalXS,
paddingBottom: tokens.spacingVerticalXS,
},
content: {
flexGrow: 1,
maxWidth: "1440px",
@@ -180,7 +195,23 @@ export function MainLayout(): React.JSX.Element {
const styles = useStyles();
const { logout } = useAuth();
const navigate = useNavigate();
const [collapsed, setCollapsed] = useState(false);
// Initialise collapsed based on screen width so narrow viewports start
// with the icon-only sidebar rather than the full-width one.
const [collapsed, setCollapsed] = useState(() => window.innerWidth < 640);
const { status } = useServerStatus();
/** True only after the first successful poll and fail2ban is unreachable. */
const serverOffline = status !== null && !status.online;
// Auto-collapse / auto-expand when the viewport crosses the 640 px breakpoint.
useEffect(() => {
const mq = window.matchMedia("(max-width: 639px)");
const handler = (e: MediaQueryListEvent): void => {
setCollapsed(e.matches);
};
mq.addEventListener("change", handler);
return (): void => { mq.removeEventListener("change", handler); };
}, []);
const toggleCollapse = useCallback(() => {
setCollapsed((prev) => !prev);
@@ -270,6 +301,18 @@ export function MainLayout(): React.JSX.Element {
{/* Main content */}
{/* ---------------------------------------------------------------- */}
<main className={styles.main}>
{/* Connection health warning — shown when fail2ban is unreachable */}
{serverOffline && (
<div className={styles.warningBar} role="alert">
<MessageBar intent="warning">
<MessageBarBody>
<MessageBarTitle>fail2ban Unreachable</MessageBarTitle>
The connection to the fail2ban server has been lost. Some
features may be temporarily unavailable.
</MessageBarBody>
</MessageBar>
</div>
)}
<div className={styles.content}>
<Outlet />
</div>

95
frontend/src/providers/TimezoneProvider.tsx Normal file
View File

@@ -0,0 +1,95 @@
/**
* TimezoneProvider.
*
* Fetches the IANA timezone configured during the BanGUI setup wizard and
* makes it available throughout the component tree via React Context.
*
* The timezone is fetched once at mount. On error or before the initial
* fetch resolves, the value defaults to ``"UTC"`` so date-formatting callers
* always receive a safe fallback.
*/
import {
createContext,
useCallback,
useContext,
useEffect,
useMemo,
useState,
} from "react";
import { fetchTimezone } from "../api/setup";
// ---------------------------------------------------------------------------
// Context definition
// ---------------------------------------------------------------------------
interface TimezoneContextValue {
/** IANA timezone string, e.g. ``"Europe/Berlin"`` or ``"UTC"``. */
timezone: string;
}
const TimezoneContext = createContext<TimezoneContextValue>({ timezone: "UTC" });
// ---------------------------------------------------------------------------
// Provider
// ---------------------------------------------------------------------------
export interface TimezoneProviderProps {
children: React.ReactNode;
}
/**
* Wrap the application (or authenticated shell) with this provider to make the
* configured timezone available via {@link useTimezone}.
*
* @example
* ```tsx
* <TimezoneProvider>
* <App />
* </TimezoneProvider>
* ```
*/
export function TimezoneProvider({
children,
}: TimezoneProviderProps): React.JSX.Element {
const [timezone, setTimezone] = useState<string>("UTC");
const load = useCallback((): void => {
fetchTimezone()
.then((resp) => { setTimezone(resp.timezone); })
.catch(() => {
// Silently fall back to UTC; the backend may not be reachable yet.
});
}, []);
useEffect(() => {
load();
}, [load]);
const value = useMemo<TimezoneContextValue>(() => ({ timezone }), [timezone]);
return (
<TimezoneContext.Provider value={value}>{children}</TimezoneContext.Provider>
);
}
// ---------------------------------------------------------------------------
// Hook
// ---------------------------------------------------------------------------
/**
* Return the IANA timezone string configured during setup.
*
* Must be used inside a {@link TimezoneProvider}.
*
* @returns The configured timezone, e.g. ``"Europe/Berlin"``.
*
* @example
* ```tsx
* const { timezone } = useTimezone();
* const label = formatDate(item.created_at, timezone);
* ```
*/
export function useTimezone(): string {
return useContext(TimezoneContext).timezone;
}

5
frontend/src/types/setup.ts
View File

@@ -20,3 +20,8 @@ export interface SetupResponse {
export interface SetupStatusResponse {
completed: boolean;
}
/** Response from GET /api/setup/timezone. */
export interface SetupTimezoneResponse {
timezone: string;
}

132
frontend/src/utils/formatDate.ts Normal file
View File

@@ -0,0 +1,132 @@
/**
* Date formatting utility.
*
* All timestamps stored and transmitted by the backend are in UTC (ISO 8601
* strings). This module provides helper functions that convert them to the
* IANA timezone configured during the BanGUI setup wizard and format them
* for display.
*
* Usage:
* ```ts
* import { formatDate, formatDateShort } from "../utils/formatDate";
*
* // Full date + time
* formatDate("2024-06-15T13:45:00Z", "Europe/Berlin");
* // → "15/06/2024, 15:45:00"
*
* // Date only
* formatDateShort("2024-06-15T13:45:00Z", "Europe/Berlin");
* // → "15/06/2024"
* ```
*/
/** Fallback timezone used when no timezone is provided. */
const DEFAULT_TIMEZONE = "UTC";
/**
* Validate that *tz* is a recognised IANA timezone identifier.
*
* Returns the validated string or ``DEFAULT_TIMEZONE`` on failure so that
* callers always receive a safe value rather than an exception.
*
* @param tz - IANA timezone string to validate.
* @returns The original *tz* if valid, otherwise ``"UTC"``.
*/
function safeTimezone(tz: string | undefined | null): string {
if (!tz) return DEFAULT_TIMEZONE;
try {
// Intl.DateTimeFormat throws a RangeError for unknown timezone identifiers.
Intl.DateTimeFormat(undefined, { timeZone: tz });
return tz;
} catch {
return DEFAULT_TIMEZONE;
}
}
/**
* Format an ISO 8601 UTC timestamp as a localised date-and-time string.
*
* The exact format depends on the user's browser locale in combination with
* the provided timezone (e.g. ``"15/06/2024, 15:45:00"`` for ``en-GB``).
*
* @param isoUtc - UTC timestamp string, e.g. ``"2024-06-15T13:45:00Z"``.
* @param timezone - IANA timezone identifier, e.g. ``"Europe/Berlin"``.
* Defaults to ``"UTC"``.
* @returns A human-readable date-time string in the specified timezone.
*/
export function formatDate(
isoUtc: string | null | undefined,
timezone: string | null | undefined = DEFAULT_TIMEZONE,
): string {
if (!isoUtc) return "—";
try {
return new Intl.DateTimeFormat(undefined, {
timeZone: safeTimezone(timezone),
year: "numeric",
month: "2-digit",
day: "2-digit",
hour: "2-digit",
minute: "2-digit",
second: "2-digit",
}).format(new Date(isoUtc));
} catch {
return isoUtc;
}
}
/**
* Format an ISO 8601 UTC timestamp as a localised date-only string.
*
* @param isoUtc - UTC timestamp string.
* @param timezone - IANA timezone identifier. Defaults to ``"UTC"``.
* @returns A date-only string, e.g. ``"15/06/2024"``.
*/
export function formatDateShort(
isoUtc: string | null | undefined,
timezone: string | null | undefined = DEFAULT_TIMEZONE,
): string {
if (!isoUtc) return "—";
try {
return new Intl.DateTimeFormat(undefined, {
timeZone: safeTimezone(timezone),
year: "numeric",
month: "2-digit",
day: "2-digit",
}).format(new Date(isoUtc));
} catch {
return isoUtc;
}
}
/**
* Format an ISO 8601 UTC timestamp as a relative time string (e.g. "3 minutes
* ago") using the browser's `Intl.RelativeTimeFormat`.
*
* Falls back to {@link formatDate} when the difference cannot be computed.
*
* @param isoUtc - UTC timestamp string.
* @param timezone - IANA timezone identifier used for the fallback format.
* @returns A relative time string or a full date-time string as fallback.
*/
export function formatRelative(
isoUtc: string | null | undefined,
timezone: string | null | undefined = DEFAULT_TIMEZONE,
): string {
if (!isoUtc) return "—";
try {
const then = new Date(isoUtc).getTime();
const now = Date.now();
const diffSeconds = Math.round((then - now) / 1000);
const absDiff = Math.abs(diffSeconds);
const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
if (absDiff < 60) return rtf.format(diffSeconds, "second");
if (absDiff < 3600) return rtf.format(Math.round(diffSeconds / 60), "minute");
if (absDiff < 86400) return rtf.format(Math.round(diffSeconds / 3600), "hour");
if (absDiff < 86400 * 30) return rtf.format(Math.round(diffSeconds / 86400), "day");
return formatDate(isoUtc, timezone);
} catch {
return formatDate(isoUtc, timezone);
}
}