docs: update Features and Architecture for config list/detail redesign

- Features.md §6: describe list/detail layout with active/inactive badges,
  active-first sort, and per-item collapsible raw config editing
- Architekture.md routers: add file_config.py router entry
- Architekture.md services: add file_config_service.py and conffile_parser.py
- Architekture.md components: add ConfigListDetail, RawConfigSection,
  AutoSaveIndicator
- Architekture.md hooks: add useConfigActiveStatus, useFilterConfig,
  useActionConfig, useJailFileConfig, useAutoSave
- Architekture.md API layer: expand config.ts entry with full function list
This commit is contained in:
2026-03-13 14:44:29 +01:00
parent c250439326
commit a344f1035b
2 changed files with 29 additions and 6 deletions

View File

@@ -152,7 +152,8 @@ The HTTP interface layer. Each router maps URL paths to handler functions. Route
| `dashboard.py` | `/api/dashboard` | Server status bar data, recent bans for the dashboard |
| `jails.py` | `/api/jails` | List jails, jail detail, start/stop/reload/idle controls |
| `bans.py` | `/api/bans` | Ban an IP, unban an IP, unban all, list currently banned IPs |
| `config.py` | `/api/config` | Read and write fail2ban jail/filter/server configuration |
| `config.py` | `/api/config` | Read and write fail2ban jail/filter/server configuration via the socket |
| `file_config.py` | `/api/config` | Read and write fail2ban config files on disk (jail.d/, filter.d/, action.d/) — list, get, and overwrite raw file contents, toggle jail enabled/disabled |
| `history.py` | `/api/history` | Query historical bans, per-IP timeline |
| `blocklist.py` | `/api/blocklists` | CRUD blocklist sources, trigger import, view import logs |
| `geo.py` | `/api/geo` | IP geolocation lookup, ASN and RIR data |
@@ -169,6 +170,8 @@ The business logic layer. Services orchestrate operations, enforce rules, and co
| `jail_service.py` | Retrieves jail list and details from fail2ban, aggregates metrics (banned count, failure count), sends start/stop/reload/idle commands |
| `ban_service.py` | Executes ban and unban commands via the fail2ban socket, queries the currently banned IP list, validates IPs before banning |
| `config_service.py` | Reads active jail and filter configuration from fail2ban, writes configuration changes, validates regex patterns, triggers reload |
| `file_config_service.py` | Reads and writes raw fail2ban config files on disk (jail.d/, filter.d/, action.d/); lists files, reads content, overwrites files, toggles enabled/disabled |
| `conffile_parser.py` | Parses fail2ban `.conf` files into structured Python types (jail config, filter config, action config); also serialises back to text |
| `history_service.py` | Queries the fail2ban database for historical ban records, builds per-IP timelines, computes ban counts and repeat-offender flags |
| `blocklist_service.py` | Downloads blocklists via aiohttp, validates IPs/CIDRs, applies bans through fail2ban or iptables, logs import results |
| `geo_service.py` | Resolves IP addresses to country, ASN, and RIR using external APIs or a local database, caches results |
@@ -373,6 +376,9 @@ Reusable UI building blocks. Components receive data via props, emit changes via
| `ConfirmDialog` | Reusable Fluent UI Dialog for destructive action confirmations |
| `RequireAuth` | Route guard: renders children only when authenticated; otherwise redirects to `/login?next=<path>` |
| `SetupGuard` | Route guard: checks `GET /api/setup` on mount and redirects to `/setup` if not complete; shows a spinner while loading |
| `config/ConfigListDetail` | Reusable two-pane master/detail layout used by the Jails, Filters, and Actions config tabs. Left pane lists items with active/inactive badges (active sorted first, keyboard navigable); right pane renders the selected item's detail content. Collapses to a dropdown on narrow screens. |
| `config/RawConfigSection` | Collapsible section that lazily loads the raw text of a config file into a monospace textarea. Provides a Save button backed by a configurable save callback; shows idle/saving/saved/error feedback. Used by all three config tabs. |
| `config/AutoSaveIndicator` | Small inline indicator showing the current save state (idle, saving, saved, error) for form fields that auto-save on change. |
#### Hooks (`src/hooks/`)
@@ -383,7 +389,12 @@ Encapsulate all stateful logic, side effects, and API calls. Components and page
| `useAuth` | Manages login state, provides `login()`, `logout()`, and `isAuthenticated` |
| `useBans` | Fetches ban list for a given time range, returns `{ bans, loading, error }` |
| `useJails` | Fetches jail list and individual jail detail |
| `useConfig` | Reads and writes fail2ban configuration |
| `useConfig` | Reads and writes fail2ban jail configuration via the socket-based API |
| `useFilterConfig` | Fetches and manages a single filter file's parsed configuration |
| `useActionConfig` | Fetches and manages a single action file's parsed configuration |
| `useJailFileConfig` | Fetches and manages a single jail.d config file |
| `useConfigActiveStatus` | Derives active status sets for jails, filters, and actions by correlating the live jail list with the config file lists; returns `{ activeJails, activeFilters, activeActions, loading, error, refresh }` |
| `useAutoSave` | Debounced auto-save hook: invokes a save callback after the user stops typing, tracks saving/saved/error state |
| `useHistory` | Queries historical ban data with filters |
| `useBlocklists` | Manages blocklist sources and import triggers |
| `useServerStatus` | Polls the server status endpoint at an interval |
@@ -401,7 +412,7 @@ A thin typed wrapper around `fetch`. All HTTP communication is centralised here
| `dashboard.ts` | `fetchStatus()`, `fetchRecentBans()` |
| `jails.ts` | `fetchJails()`, `fetchJailDetail()`, `startJail()`, `stopJail()`, `reloadJail()` |
| `bans.ts` | `banIp()`, `unbanIp()`, `unbanAll()`, `fetchBannedIps()` |
| `config.ts` | `fetchConfig()`, `updateConfig()`, `testRegex()` |
| `config.ts` | Socket-based config: `fetchJailConfigs()`, `updateJailConfig()`, `testRegex()`. File-based config: `fetchJailFiles()`, `fetchJailFile()`, `writeJailFile()`, `setJailFileEnabled()`, `fetchFilterFiles()`, `fetchFilterFile()`, `writeFilterFile()`, `fetchActionFiles()`, `fetchActionFile()`, `writeActionFile()`, `reloadConfig()` |
| `history.ts` | `fetchHistory()`, `fetchIpTimeline()` |
| `blocklist.ts` | `fetchSources()`, `addSource()`, `removeSource()`, `triggerImport()`, `fetchImportLog()` |
| `geo.ts` | `lookupIp()` |

View File

@@ -150,9 +150,13 @@ A page to inspect and modify the fail2ban configuration without leaving the web
### View Configuration
- Display all active fail2ban jails and their current settings.
- For each jail, show the associated filter and its regex patterns in a readable format.
- Show global fail2ban settings (ban time, find time, max retries, etc.).
- The **Jails**, **Filters**, and **Actions** tabs each use a **master/detail list layout**:
- A scrollable left pane lists all items (jail names, filter filenames, action filenames).
- Each item displays an **Active** or **Inactive** badge. Active items are sorted to the top; items within each group are sorted alphabetically.
- A jail is "active" if fail2ban reports it as enabled at runtime. A filter or action is "active" if it is referenced by at least one enabled jail.
- Clicking an item loads its structured configuration form in the right detail pane.
- On narrow screens (< 900 px) the list pane collapses into a dropdown above the detail pane.
- Show global fail2ban settings (ban time, find time, max retries, etc.) on the Global Settings tab.
### Edit Configuration
@@ -166,6 +170,14 @@ A page to inspect and modify the fail2ban configuration without leaving the web
- Save changes and optionally reload fail2ban to apply them immediately.
- Validation feedback if a regex pattern or setting value is invalid before saving.
### Raw Configuration Editing
- Every jail, filter, and action detail pane includes a collapsible **Raw Configuration** section at the bottom.
- The section shows the complete raw text of the config file (`.conf`) in an editable monospace textarea.
- The user can edit the raw text directly and click **Save Raw** to overwrite the file on disk.
- The textarea loads lazily — the raw file content is only fetched when the section is first expanded.
- A save-state indicator shows idle / saving / saved / error feedback after each save attempt.
### Add Log Observation
- Option to register additional log files that fail2ban should monitor.