docs(components): reference docs batch 4/4 — ManagementService, CLI, Transport, CentralUI, TraefikProxy, TreeView
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,250 @@
|
||||
# CLI
|
||||
|
||||
The CLI is a standalone command-line tool that provides scripting and automation access to all ScadaBridge administrative operations. It connects to the central cluster's HTTP Management API and dispatches commands to the `ManagementActor` via `POST /management`. Authentication and role resolution happen server-side; the CLI sends LDAP credentials as HTTP Basic Auth on every request.
|
||||
|
||||
## Overview
|
||||
|
||||
The CLI component lives in `src/ZB.MOM.WW.ScadaBridge.CLI/` and builds to a self-contained `scadabridge` executable (or `scadabridge.exe` on Windows). It is not part of the Host binary — it deploys on any machine with HTTP access to a central node.
|
||||
|
||||
The tool is built on `System.CommandLine` and exposes a hierarchical command tree organized by management domain (`template`, `instance`, `site`, `data-connection`, and so on). Every command follows the same pattern: resolve the management URL and credentials, construct a command object whose type maps to a `ManagementCommandRegistry` entry, serialize it into the `{ command, payload }` JSON envelope, and `POST` it to `<managementUrl>/management`. The server response — JSON success body or `{ error, code }` error envelope — is printed to stdout or stderr respectively.
|
||||
|
||||
The CLI is the preferred automation interface. When setting up system state (sites, templates, data connections, deployments, security) without the Central UI, use `scadabridge` commands rather than direct database manipulation.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Connection to the active node
|
||||
|
||||
The CLI connects through Traefik, the reverse proxy fronting the central cluster. Traefik routes each request to the active central node based on the `/health/active` probe, so the CLI does not need to know which node (`central-a` or `central-b`) is currently primary. Pointing `--url` (or `managementUrl`) at the Traefik address (default `http://localhost:9000` in Docker) provides automatic HA failover without any CLI-side configuration change.
|
||||
|
||||
Direct-to-node access (`http://localhost:9001` for `central-a`, `http://localhost:9002` for `central-b`) bypasses Traefik and is useful for diagnostics but not for production automation.
|
||||
|
||||
### Command dispatch
|
||||
|
||||
Most commands serialize to a named management command and reach the `ManagementActor` through the `POST /management` endpoint. The `audit query` and `audit export` commands are the exception — they call plain REST endpoints (`GET /api/audit/query`, `GET /api/audit/export`) introduced by Audit Log (#23) and therefore use `SendGetAsync`/`SendGetStreamAsync` on `ManagementHttpClient` rather than `SendCommandAsync`. The streaming `audit export` path uses `HttpCompletionOption.ResponseHeadersRead` to avoid buffering large payloads in memory.
|
||||
|
||||
### Authentication and roles
|
||||
|
||||
The CLI encodes `--username` and `--password` as an HTTP Basic Auth header on every request. The server performs the LDAP bind, group lookup, and role resolution. The CLI never contacts LDAP directly and never caches credentials between invocations.
|
||||
|
||||
Role enforcement is applied by the `ManagementActor`. Operations require the appropriate role:
|
||||
|
||||
| Role | Covers |
|
||||
|------|--------|
|
||||
| `Admin` | Security settings, site management, SMTP config, audit-config queries |
|
||||
| `Design` | Templates, shared scripts, external systems, DB connections, API methods, notification lists |
|
||||
| `Deployment` | Instance lifecycle (deploy, enable, disable, delete), data connection bindings, bundle import/export |
|
||||
| `OperationalAudit` | Reading the Audit Log (`audit query`) |
|
||||
| `AuditExport` | Exporting the Audit Log (`audit export`) |
|
||||
|
||||
A request lacking the required role exits with code `2` (authorization failure). A bad-credential response (HTTP 401) exits with code `1`.
|
||||
|
||||
### Output formats
|
||||
|
||||
Every command accepts `--format json` (default) or `--format table`. JSON output goes to stdout and is formatted with indented, camelCase JSON. Table output renders a padded plain-text table derived from the response JSON — arrays become rows, single objects become a two-column `Property / Value` table. Errors are always written as `{ "error": "...", "code": "..." }` to stderr, regardless of format.
|
||||
|
||||
## Architecture
|
||||
|
||||
`Program.cs` builds the `RootCommand` tree, attaches the four global options (`--url`, `--username`, `--password`, `--format`), and registers each command group:
|
||||
|
||||
```csharp
|
||||
rootCommand.Add(TemplateCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(InstanceCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(SiteCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(DeployCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(DataConnectionCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(ExternalSystemCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(NotificationCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(SecurityCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(AuditLogCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(AuditCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(HealthCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(DebugCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(SharedScriptCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(DbConnectionCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(ApiMethodCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
rootCommand.Add(BundleCommands.Build(urlOption, formatOption, usernameOption, passwordOption));
|
||||
```
|
||||
|
||||
Every command's action delegates to `CommandHelpers.ExecuteCommandAsync`, which owns the URL/credential resolution, `ManagementHttpClient` lifetime, and exit-code mapping. This consolidation means the authorization-failure exit code (`2`) is enforced uniformly — including for the `bundle` group, which uses `ExecuteCommandAsync` with a longer 5-minute timeout and a per-command `onSuccess` handler rather than a separate HTTP path.
|
||||
|
||||
`CliConfig.Load()` is called at the start of every invocation. It merges `~/.scadabridge/config.json`, environment variables, and any defaults. A malformed or unreadable config file emits a warning to stderr and falls through to the environment variable / command-line precedence chain without crashing.
|
||||
|
||||
## Usage
|
||||
|
||||
### Running the CLI
|
||||
|
||||
```bash
|
||||
# Build
|
||||
dotnet build src/ZB.MOM.WW.ScadaBridge.CLI
|
||||
|
||||
# Minimal invocation (URL and credentials required)
|
||||
scadabridge --url http://localhost:9000 --username multi-role --password password template list
|
||||
|
||||
# Using Traefik (HA; routes to the active node automatically)
|
||||
scadabridge --url http://localhost:9000 --username multi-role --password password site list
|
||||
|
||||
# Table output
|
||||
scadabridge --url http://localhost:9000 --username multi-role --password password \
|
||||
--format table instance list --site-id 1
|
||||
```
|
||||
|
||||
Credentials are safer supplied via environment variables than on the command line, where they appear in process listings and shell history:
|
||||
|
||||
```bash
|
||||
export SCADABRIDGE_MANAGEMENT_URL=http://localhost:9000
|
||||
export SCADABRIDGE_USERNAME=multi-role
|
||||
export SCADABRIDGE_PASSWORD=password
|
||||
|
||||
scadabridge template create --name "PumpStation" --description "Standard pump station"
|
||||
scadabridge template attribute add --template-id 3 --name Speed --data-type Float --default-value 0
|
||||
scadabridge instance create --name "PS-01" --template-id 3 --site-id 1
|
||||
scadabridge instance deploy --id 7
|
||||
```
|
||||
|
||||
### Command groups
|
||||
|
||||
| Group | Subcommands | Role required |
|
||||
|-------|-------------|---------------|
|
||||
| `template` | `list`, `get`, `create`, `update`, `delete`, `validate`; `attribute add/update/delete`; `alarm add/update/delete`; `script add/update/delete`; `composition add/delete`; `native-alarm-source add/list/remove` | `Design` |
|
||||
| `instance` | `list`, `get`, `create`, `deploy`, `enable`, `disable`, `delete`, `set-bindings`; `native-alarm-source set/clear` | `Deployment` |
|
||||
| `site` | `list`, `get`, `create`, `delete`, `deploy-artifacts`; `area list/create/update/delete` | `Admin` |
|
||||
| `deploy` | `instance`, `artifacts`, `status` | `Deployment` |
|
||||
| `data-connection` | `list`, `get`, `create`, `update`, `delete` | `Design` / `Deployment` |
|
||||
| `external-system` | `list`, `get`, `create`, `update`, `delete` | `Design` |
|
||||
| `notification` | `list`, `get`, `create`, `update`, `delete`; `smtp list/update` | `Design` / `Admin` |
|
||||
| `security` | `api-key list/create/update/delete`; `role-mapping list/create/update/delete`; `scope-rule list/add/delete` | `Admin` |
|
||||
| `shared-script` | `list`, `get`, `create`, `update`, `delete` | `Design` |
|
||||
| `db-connection` | `list`, `get`, `create`, `update`, `delete` | `Design` |
|
||||
| `api-method` | `list`, `get`, `create`, `update`, `delete` | `Design` |
|
||||
| `bundle` | `export`, `preview`, `import` | `Deployment` |
|
||||
| `audit` | `query`, `export`, `verify-chain` | `OperationalAudit` / `AuditExport` |
|
||||
| `audit-config` | `query` (config-change audit trail; was `audit-log` pre-M8) | `Admin` |
|
||||
| `health` | `summary`, `site`, `event-log`, `parked-messages` | `Deployment` |
|
||||
| `debug` | `snapshot`, `stream` | `Deployment` |
|
||||
|
||||
### Selected examples
|
||||
|
||||
```bash
|
||||
# Query the operational Audit Log for failed API outbound events in the last 24 hours
|
||||
scadabridge audit query --since 24h --channel ApiOutbound --errors-only --format table
|
||||
|
||||
# Export a full audit window to CSV
|
||||
scadabridge audit export --since 2026-05-01T00:00:00Z --until 2026-06-01T00:00:00Z \
|
||||
--format csv --output /tmp/audit-may-2026.csv
|
||||
|
||||
# Export a Transport bundle for selected templates (with transitive dependencies)
|
||||
scadabridge bundle export --output /tmp/pump-station.scadabundle \
|
||||
--templates "PumpStation,BaseModule" --include-dependencies
|
||||
|
||||
# Preview a bundle diff before importing
|
||||
scadabridge bundle preview --input /tmp/pump-station.scadabundle
|
||||
|
||||
# Import with overwrite conflict policy
|
||||
scadabridge bundle import --input /tmp/pump-station.scadabundle --on-conflict overwrite
|
||||
|
||||
# Stream live attribute and alarm changes for a running instance
|
||||
scadabridge debug stream --id 7
|
||||
|
||||
# Query deployment records for a specific instance
|
||||
scadabridge deploy status --instance-id 7 --page-size 20
|
||||
```
|
||||
|
||||
### Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `0` | Success |
|
||||
| `1` | Command error (connection failure, validation error, server error) |
|
||||
| `2` | Authorization failure (insufficient role; HTTP 403 or `FORBIDDEN`/`UNAUTHORIZED` error code) |
|
||||
|
||||
## Configuration
|
||||
|
||||
`~/.scadabridge/config.json` is loaded on every invocation. A malformed or unreadable file emits a warning to stderr; it does not abort the invocation.
|
||||
|
||||
```json
|
||||
{
|
||||
"managementUrl": "http://localhost:9000",
|
||||
"defaultFormat": "json"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
| `managementUrl` | — | Base URL for the Management API. Overridden by `SCADABRIDGE_MANAGEMENT_URL` env var, then by `--url`. |
|
||||
| `defaultFormat` | `json` | Default output format when `--format` is not supplied. Overridden by `SCADABRIDGE_FORMAT` env var, then by `--format`. |
|
||||
|
||||
Credentials are intentionally never stored in the config file — they are sourced from environment variables or supplied per-invocation on the command line. Storing them in the file would persist them to disk in plaintext.
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Overrides | Description |
|
||||
|----------|-----------|-------------|
|
||||
| `SCADABRIDGE_MANAGEMENT_URL` | `managementUrl` in config file | Management API base URL |
|
||||
| `SCADABRIDGE_FORMAT` | `defaultFormat` in config file | Default output format |
|
||||
| `SCADABRIDGE_USERNAME` | — | LDAP username; overridden by `--username` |
|
||||
| `SCADABRIDGE_PASSWORD` | — | LDAP password; overridden by `--password`. Preferred over `--password` to avoid leaking credentials into process listings and shell history. |
|
||||
|
||||
### URL precedence
|
||||
|
||||
The management URL is resolved in this order: `--url` flag → `SCADABRIDGE_MANAGEMENT_URL` env var → `managementUrl` in config file. If none is set, the command exits with code `1` and a `NO_URL` error.
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- [Management Service (#18)](./ManagementService.md) — the server-side counterpart. Every CLI command (except `audit query`/`audit export`) translates to a named management command dispatched through `POST /management` to the `ManagementActor`. Role enforcement and LDAP authentication are applied there. The `ManagementCommandRegistry` in Commons maps command types to their names; both sides must stay in sync.
|
||||
- [Traefik Proxy (#20)](./TraefikProxy.md) — the recommended connection target. Pointing `--url` at the Traefik address ensures requests reach the active central node without per-command failover logic in the CLI. The `debug stream` command's WebSocket connection (SignalR `/hubs/debug-stream`) also traverses Traefik, which proxies the WebSocket upgrade natively.
|
||||
- [Audit Log (#23)](./AuditLog.md) — the `audit` command group targets the `GET /api/audit/query` and `GET /api/audit/export` REST endpoints exposed by the Audit Log component, bypassing the management command envelope. The `audit-config` group (formerly `audit-log`) targets the configuration-change audit trail (`IAuditService`) via the standard management envelope.
|
||||
- [Security & Auth (#10)](./Security.md) — the server resolves LDAP credentials and maps group memberships to ScadaBridge roles (`Admin`, `Design`, `Deployment`, `OperationalAudit`, `AuditExport`). The CLI does not interact with LDAP directly.
|
||||
- [Commons (#16)](./Commons.md) — owns the management command record types and the `ManagementCommandRegistry` that maps each type to its wire name. The CLI project references Commons for these contracts.
|
||||
- [Transport (#24)](./Transport.md) — the `bundle` command group drives the Transport feature: `bundle export` requests a base64-encoded bundle from the server and streams it to a local `.scadabundle` file; `bundle preview` uploads a file and returns the diff manifest; `bundle import` uploads a file and applies it with a configurable conflict policy.
|
||||
- Design spec: [Component-CLI.md](../requirements/Component-CLI.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No management URL
|
||||
|
||||
```
|
||||
{"error":"No management URL specified. Use --url, set SCADABRIDGE_MANAGEMENT_URL, or add 'managementUrl' to ~/.scadabridge/config.json.","code":"NO_URL"}
|
||||
```
|
||||
|
||||
The URL is not set via `--url`, `SCADABRIDGE_MANAGEMENT_URL`, or the config file. Set one of these before running any command.
|
||||
|
||||
### Connection failed
|
||||
|
||||
```
|
||||
{"error":"Connection failed: Connection refused (localhost:9000)","code":"CONNECTION_FAILED"}
|
||||
```
|
||||
|
||||
The central node or Traefik is not reachable at the configured URL. Verify the cluster is running and the URL matches the Traefik port (default `9000` in Docker) or the node's direct port (`9001`/`9002`).
|
||||
|
||||
### Authorization failure (exit 2)
|
||||
|
||||
The server returned HTTP 403 or an error code of `FORBIDDEN`/`UNAUTHORIZED`. The authenticated user's LDAP groups do not map to a role with permission for the requested operation. Use `security role-mapping list` (requires `Admin`) to inspect role mappings. The `multi-role` test user (`password`) holds `Admin`, `Design`, and `Deployment` roles.
|
||||
|
||||
### Malformed config file warning
|
||||
|
||||
```
|
||||
warning: ignoring malformed or unreadable /home/user/.scadabridge/config.json: ...
|
||||
```
|
||||
|
||||
`CliConfig.Load()` caught a `JsonException`, `IOException`, or `UnauthorizedAccessException` reading the config file. The invocation continues using environment variables and command-line options. Fix or recreate the config file.
|
||||
|
||||
### `audit-log` deprecation warning
|
||||
|
||||
```
|
||||
Warning: 'audit-log' is deprecated and will be removed in a future release. Use 'audit-config' instead.
|
||||
```
|
||||
|
||||
The `audit-log` command group was renamed to `audit-config` in M8 of Audit Log (#23). The old name still works but emits this warning to stderr. Migrate any scripts from `scadabridge audit-log ...` to `scadabridge audit-config ...`.
|
||||
|
||||
### Bundle timeout
|
||||
|
||||
`bundle export` and `bundle import` use a 5-minute per-command timeout (compared to the 30-second default). If a bundle operation times out, the server-side export or import may still be running. Re-try with a smaller selection or check the central node logs.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [CLI design specification](../requirements/Component-CLI.md)
|
||||
- [Management Service](./ManagementService.md)
|
||||
- [Traefik Proxy](./TraefikProxy.md)
|
||||
- [Audit Log](./AuditLog.md)
|
||||
- [Security](./Security.md)
|
||||
- [Commons](./Commons.md)
|
||||
@@ -0,0 +1,223 @@
|
||||
# Central UI
|
||||
|
||||
The Central UI is a Blazor Server web application that hosts every management, configuration, deployment, monitoring, and audit workflow for the ScadaBridge system. It runs on the central cluster only; sites have no user interface.
|
||||
|
||||
## Overview
|
||||
|
||||
Central UI (#9) is built on ASP.NET Core + Blazor Server with Bootstrap CSS. All UI logic executes server-side; updates reach the browser through Blazor's built-in SignalR circuit. No third-party component frameworks are used — tables, grids, forms, and custom controls are implemented directly as Blazor + Bootstrap components.
|
||||
|
||||
The component code lives in `src/ZB.MOM.WW.ScadaBridge.CentralUI/`, split into:
|
||||
|
||||
- `Auth/` — cookie authentication state provider, login/logout/ping Minimal API endpoints, site-scope service.
|
||||
- `Audit/` — CSV export Minimal API endpoint.
|
||||
- `Components/Layout/` — `MainLayout`, `LoginLayout`, and `NavMenu` (the policy-gated rail navigation).
|
||||
- `Components/Pages/` — pages, grouped by nav section: `Admin/`, `Audit/`, `Deployment/`, `Design/`, `Monitoring/`, `Notifications/`, `SiteCalls/`.
|
||||
- `Components/Shared/` — reusable non-page components (`DataTable`, `MonacoEditor`, `ToastNotification`, `SessionExpiry`, dialog infrastructure, and others).
|
||||
- `Components/Health/` — KPI tile components for Notification Outbox, Site Calls, and Audit Log.
|
||||
- `Components/Audit/` — the `AuditFilterBar`, `AuditResultsGrid`, `AuditDrilldownDrawer`, and execution-tree components used by the Audit Log page.
|
||||
- `ScriptAnalysis/` — Roslyn-backed script analysis service and Minimal API endpoint (`/api/centralui/script/analyze`) used by the Monaco editor.
|
||||
- `Services/` — scoped UI services: `AuditLogQueryService`, `AuditLogExportService`, `BrowseService`, `BindingTester`, and `SiteScopeService`.
|
||||
|
||||
The single DI entry point is `ServiceCollectionExtensions.AddCentralUI`, registered only by the central-role Host composition root. `EndpointExtensions.MapCentralUI<TApp>` wires the Minimal API endpoints and the Razor component routes onto the ASP.NET Core pipeline.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Authentication and session model
|
||||
|
||||
Authentication is a standard LDAP bind via `ILdapAuthService` (from Security, #10). On success, `POST /auth/login` maps the user's LDAP groups to ScadaBridge roles via `IGroupRoleMapper<string>`, constructs a `ClaimsIdentity` carrying role claims and site-scope `SiteId` claims, and calls `context.SignInAsync` to write an HttpOnly/Secure ASP.NET Core cookie with `IsPersistent = true` and `SlidingExpiration = true`. No fixed `ExpiresUtc` is stamped — the idle timeout is owned by the cookie middleware configured in the Security component.
|
||||
|
||||
`POST /auth/token` offers the same LDAP flow and returns a JWT bearer token for the CLI.
|
||||
|
||||
Because Blazor Server's `HttpContext` is only valid during the initial HTTP request that establishes the SignalR circuit, `CookieAuthenticationStateProvider` snapshots the authenticated `ClaimsPrincipal` once at construction time and serves that snapshot for the entire circuit lifetime:
|
||||
|
||||
```csharp
|
||||
public CookieAuthenticationStateProvider(IHttpContextAccessor httpContextAccessor)
|
||||
{
|
||||
var user = httpContextAccessor.HttpContext?.User
|
||||
?? new ClaimsPrincipal(new ClaimsIdentity());
|
||||
|
||||
_circuitAuthState = Task.FromResult(new AuthenticationState(user));
|
||||
}
|
||||
|
||||
public override Task<AuthenticationState> GetAuthenticationStateAsync()
|
||||
=> _circuitAuthState;
|
||||
```
|
||||
|
||||
Reading `IHttpContextAccessor` on each `GetAuthenticationStateAsync` call would return `null` (or a stale context) for the lifetime of a long-lived circuit, causing `<AuthorizeView>` re-renders to see an unauthenticated principal.
|
||||
|
||||
### Session expiry detection
|
||||
|
||||
Because `CookieAuthenticationStateProvider` serves a frozen principal, the circuit can never observe a server-side cookie expiry by polling Blazor's auth state. `SessionExpiry` (a headless component rendered in `MainLayout`) polls `GET /auth/ping` via a JavaScript `fetch` call every minute. The ping endpoint returns `200` while the cookie is still valid and `401` once it lapses. A `401` redirects the browser to `/login` with a full-page navigation. The cookie middleware re-validates (and slides) the cookie on every ping, so the poll itself does not artificially extend a genuinely idle session beyond the configured timeout.
|
||||
|
||||
### Site-scoped authorization
|
||||
|
||||
`SiteScopeService` (scoped, registered in `AddCentralUI`) reads `SiteId` claims from the circuit principal. Deployment users whose LDAP mapping carries site-scope rules carry one integer `SiteId` claim per permitted site; Admin and Design users carry none (system-wide). Pages that enumerate sites or issue cross-site commands call `SiteScopeService.FilterSitesAsync` and `IsSiteAllowedAsync` to enforce the grant before any operation.
|
||||
|
||||
### Repository access pattern
|
||||
|
||||
CentralUI pages read and write the configuration database directly through `ICentralUiRepository` and other scoped EF Core repositories — there is no Akka round-trip for design-time CRUD. Operations that must reach site actors (deployment commands, debug stream subscriptions, OPC UA browse, KPI queries) go through `CommunicationService` (from Communication, #5).
|
||||
|
||||
## Architecture
|
||||
|
||||
### Layout and navigation
|
||||
|
||||
`MainLayout` wraps every authenticated page in `ThemeShell` (from the shared `ZB.MOM.WW.Theme` package), which provides the brand bar, responsive hamburger, and side-rail chassis. `NavMenu` fills the rail's `<Nav>` slot with policy-gated navigation groups:
|
||||
|
||||
| Nav group | Policy gate | Key pages |
|
||||
|-----------|-------------|-----------|
|
||||
| Dashboard | Authenticated | `/` |
|
||||
| Admin | `RequireAdmin` | LDAP Mappings, Sites, API Keys, Import Bundle |
|
||||
| Design | `RequireDesign` | Templates, Shared Scripts, Connections, External Systems, Export Bundle |
|
||||
| Deployment | `RequireDeployment` | Topology, Deployments, Debug View |
|
||||
| Notifications | Mixed (per item) | SMTP Configuration (Admin), Notification Lists (Design), Notification Report / KPIs (Deployment) |
|
||||
| Site Calls | `RequireDeployment` | Site Calls |
|
||||
| Monitoring | Health: all; Event Logs + Parked: Deployment | Health Dashboard, Event Logs, Parked Messages |
|
||||
| Audit | `OperationalAudit` | Audit Log, Configuration Audit Log |
|
||||
|
||||
`LoginLayout` is a stripped layout used by `/login`; it also renders `SessionExpiry` so expiry detection is active there without causing a redirect loop (the component no-ops when already on the login page).
|
||||
|
||||
`DialogHost` — a single instance rendered in `MainLayout` — is the rendering target for all modal dialogs raised via the `IDialogService` / `DialogService` scoped service. Pages call `Dialog.ConfirmAsync` or `Dialog.PromptAsync` and await the result without managing modal state themselves.
|
||||
|
||||
### Real-time update channels
|
||||
|
||||
Three distinct mechanisms push live data to the browser:
|
||||
|
||||
**Deployment status (SignalR push):** The `Deployments` page subscribes to `IDeploymentStatusNotifier.StatusChanged` on `OnInitializedAsync`. `DeploymentManager` raises this event on every status write; the handler marshals to the Blazor renderer via `InvokeAsync` and calls `StateHasChanged`, pushing the re-render over the existing SignalR circuit. No polling timer is needed.
|
||||
|
||||
```razor
|
||||
protected override async Task OnInitializedAsync()
|
||||
{
|
||||
await LoadDataAsync();
|
||||
DeploymentStatusNotifier.StatusChanged += OnDeploymentStatusChanged;
|
||||
}
|
||||
```
|
||||
|
||||
**Debug view (gRPC streaming + SignalR relay):** `DebugStreamService` (from Communication, #5) creates a `DebugStreamBridgeActor` per session. The bridge actor opens a gRPC server-streaming subscription to the site's `SiteStreamGrpcServer` for the selected instance, then requests an initial `DebugViewSnapshot` via ClusterClient. Ongoing `AttributeValueChanged` and `AlarmStateChanged` events flow via the gRPC stream to the bridge actor, which delivers them to the `DebugView` page via callbacks that call `InvokeAsync(StateHasChanged)`. A pulsing "Live" badge in the status strip indicates active streaming. Streams are subscribe-on-demand and stop when the page closes.
|
||||
|
||||
**Health dashboard and KPI tiles (10-second polling timer):** The `Health` page initializes a `System.Threading.Timer` at 10-second intervals. Each tick calls `ICentralHealthAggregator.GetAllSiteStates()` for in-memory site state and issues three async KPI queries:
|
||||
|
||||
```csharp
|
||||
private async Task RefreshNow()
|
||||
{
|
||||
_siteStates = HealthAggregator.GetAllSiteStates();
|
||||
await LoadOutboxKpis();
|
||||
await LoadSiteCallKpis();
|
||||
await LoadAuditKpis();
|
||||
}
|
||||
```
|
||||
|
||||
KPI queries go through `CommunicationService` (Notification Outbox and Site Calls KPIs via actor Ask) and `IAuditLogQueryService` (Audit KPIs via `IAuditLogRepository`). A transient fault on any one KPI group degrades only that group's tiles to em dashes — the rest of the dashboard continues to render.
|
||||
|
||||
### Script analysis endpoint
|
||||
|
||||
`ScriptAnalysisService` compiles user script fragments as Roslyn C# Scripting globals against `SandboxScriptHost` (template/shared scripts) or `InboundScriptHost` (Inbound API methods). It surfaces diagnostics and completions in the shape Monaco's provider APIs expect. Diagnostics are cached by code hash via `IMemoryCache` (200-entry limit) to short-circuit repeated requests for the same content. `ScriptAnalysisEndpoints` exposes `POST /api/centralui/script/analyze` and is called by the `MonacoEditor` component's Blazor JS interop module on a 500 ms debounce.
|
||||
|
||||
The sandbox enforces the script trust model: a `SemanticModel` check raises a diagnostic for any use of forbidden APIs (`System.IO`, `Process`, `Thread`, reflection, raw networking).
|
||||
|
||||
### Audit Log query service
|
||||
|
||||
`AuditLogQueryService` (registered with an explicit factory to resolve the `IServiceScopeFactory` constructor) opens a fresh DI scope — and therefore a fresh `ScadaBridgeDbContext` — per operation. This prevents the page's query-string auto-load from racing the filter bar's site enumeration on the shared circuit-scoped context:
|
||||
|
||||
```csharp
|
||||
await using var scope = _scopeFactory!.CreateAsyncScope();
|
||||
var repository = scope.ServiceProvider.GetRequiredService<IAuditLogRepository>();
|
||||
var result = await repository.QueryAsync(filter, effective, ct);
|
||||
return result.Select(AuditEventView.From).ToList();
|
||||
```
|
||||
|
||||
`GetKpiSnapshotAsync` aggregates audit volume and error rate over a trailing one-hour window from the repository, then sums `SiteAuditBacklog.PendingCount` across all site states from `ICentralHealthAggregator` to fill the backlog tile.
|
||||
|
||||
`GetDistinctSourceNodesAsync` caches the result for 60 seconds behind an in-memory lock to keep filter bar rendering cheap during failover events when node membership changes.
|
||||
|
||||
### CSV export endpoint
|
||||
|
||||
`GET /api/centralui/audit/export` is gated on the `AuditExport` policy (a superset of `OperationalAudit`). The endpoint streams directly to `Response.Body` via `IAuditLogExportService.ExportAsync` — no buffering through the Blazor circuit. The default row cap is 100,000; a `maxRows=` query-string override is accepted. The `Content-Disposition: attachment` header and `Cache-Control: no-store` are stamped before the first body write.
|
||||
|
||||
## Usage
|
||||
|
||||
### Registration (Host)
|
||||
|
||||
The central-role Host calls `AddCentralUI` during composition to register all Blazor and UI services, then `MapCentralUI<App>` on the endpoint builder to wire routes:
|
||||
|
||||
```csharp
|
||||
// In Host's central-role composition root:
|
||||
services.AddCentralUI();
|
||||
|
||||
// In the endpoint pipeline:
|
||||
app.MapCentralUI<App>();
|
||||
```
|
||||
|
||||
`MapCentralUI` registers `MapAuthEndpoints`, `MapScriptAnalysisEndpoints`, `MapAuditExportEndpoints`, and `MapRazorComponents<TApp>` with interactive server render mode.
|
||||
|
||||
### Accessing the UI
|
||||
|
||||
The UI is fronted by the Traefik reverse proxy (component #20), which routes to the active central node. In the Docker topology the management port is `9000` (Traefik), with direct access at `9001` (central-a) and `9002` (central-b).
|
||||
|
||||
On central failover the SignalR circuit is interrupted. Blazor's built-in reconnection logic re-establishes the circuit on the new active node. Because authentication state is in the cookie (not server memory), the user's session survives failover without re-login — provided the new node shares the same ASP.NET Data Protection keys (stored in the configuration database).
|
||||
|
||||
Active debug view streams and in-progress deployment status subscriptions are lost on failover and must be re-opened by the user.
|
||||
|
||||
### Audit Log page deep links
|
||||
|
||||
Any page that wants to pre-filter the Audit Log passes query-string parameters to `/audit/log`:
|
||||
|
||||
| Parameter | Example | Effect |
|
||||
|-----------|---------|--------|
|
||||
| `correlationId` | `?correlationId=<guid>` | Pins to a single operation (notification, cached call, inbound request) |
|
||||
| `executionId` | `?executionId=<guid>` | Shows all rows for one script execution |
|
||||
| `channel` | `?channel=ApiOutbound` | Pre-selects channel filter |
|
||||
| `actor` | `?actor=my-key` | Pre-fills actor search |
|
||||
|
||||
The same keys are accepted by `GET /api/centralui/audit/export` for filtered CSV export.
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- [Security (#10)](./Security.md) — `ILdapAuthService` for LDAP bind at login; `IGroupRoleMapper<string>` for LDAP-group → role mapping; `JwtTokenService` for bearer-token generation (`/auth/token`) and claim-type constants; `AuthorizationPolicies` for every `[Authorize(Policy = …)]` attribute. The Security component owns the cookie middleware configuration (sliding window, idle timeout).
|
||||
- [Configuration Database (#17)](./ConfigurationDatabase.md) — all central CRUD (templates, instances, sites, external systems, notifications, audit log, etc.) via scoped EF Core repositories (`ICentralUiRepository`, `IAuditLogRepository`, `ISiteRepository`, `ITemplateEngineRepository`, and others). The Data Protection keys that make sessions portable across failover are also stored here.
|
||||
- [Communication (#5)](./Communication.md) — `CommunicationService` for cross-site commands (deploy, disable, enable, delete, browse OPC UA nodes, read tag values); `DebugStreamService` for gRPC-backed debug stream sessions; KPI request/response messages for Notification Outbox and Site Calls KPIs.
|
||||
- [Deployment Manager (#2)](./DeploymentManager.md) — `IDeploymentStatusNotifier` for real-time deployment status push; deployment command routing.
|
||||
- [Template Engine (#1)](./TemplateEngine.md) — `TemplateService`, `TemplateFolderService`, `TemplateValidationService` for template authoring, on-demand validation, and diff calculation.
|
||||
- [Health Monitoring (#11)](./HealthMonitoring.md) — `ICentralHealthAggregator` for in-memory site health state on the Health Dashboard and audit backlog KPI tile.
|
||||
- [Audit Log (#23)](./AuditLog.md) — `IAuditLogRepository` (via `AuditLogQueryService`) for the Audit Log page query/drilldown/export; `IAuditLogQueryService.GetKpiSnapshotAsync` for the three Audit KPI tiles on the Health Dashboard.
|
||||
- [Notification Outbox (#21)](./NotificationOutbox.md) — Notification Report page queries and Retry/Discard actions; Notification KPI tiles on the Health Dashboard.
|
||||
- [Site Call Audit (#22)](./SiteCallAudit.md) — Site Calls page queries and Retry/Discard relay; Site Call KPI tiles on the Health Dashboard.
|
||||
- [Transport (#24)](./Transport.md) — `IBundleExporter` and `IBundleImporter` for the Export Bundle and Import Bundle multi-step wizards.
|
||||
- [TreeView](./TreeView.md) — the template folder tree sidebar on `/design/templates` uses the shared `TreeView` component; see that document for the reusable tree implementation.
|
||||
- Design spec: [Component-CentralUI.md](../requirements/Component-CentralUI.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Circuit reconnects but user sees "Not Authorized"
|
||||
|
||||
This indicates the shared ASP.NET Data Protection keys are not available to the node that the circuit reconnected to. The keys are stored in the configuration database; verify the central nodes share the same key ring and that the configuration database is reachable on both nodes.
|
||||
|
||||
### Health Dashboard KPI tiles show "—"
|
||||
|
||||
Each KPI group degrades independently. A "—" on the Notification Outbox tiles means `CommunicationService.GetNotificationKpisAsync` threw or the actor returned `Success = false`; the inline error message below the tiles carries the detail. Audit KPI tiles degrade if `IAuditLogRepository.GetKpiSnapshotAsync` fails — check the central SQL connection.
|
||||
|
||||
### Debug view connects but shows no events
|
||||
|
||||
The debug stream bridge actor opens a gRPC subscription to the site's `SiteStreamGrpcServer`. If the gRPC port is unreachable (e.g., `GrpcNodeAAddress` or `GrpcNodeBAddress` misconfigured on the site entity), the bridge actor logs the failure and the stream never starts. Check the site's gRPC address configuration on the Sites admin page and verify port 8083 is accessible from the central nodes.
|
||||
|
||||
### Session expires unexpectedly
|
||||
|
||||
The idle timeout is a sliding window — any authenticated HTTP request (including the `/auth/ping` from `SessionExpiry`) slides the expiry. If sessions lapse before the configured idle timeout, confirm that the Blazor circuit is producing at least one HTTP request per timeout window (the `SessionExpiry` poll interval is one minute). If the cookie middleware's `ExpireTimeSpan` is misconfigured, check the Security component's `AddCookie` call.
|
||||
|
||||
### Script editor shows no diagnostics
|
||||
|
||||
`ScriptAnalysisService` uses Roslyn from in-process `IMemoryCache` (200-entry size limit). If the cache is evicted under memory pressure, the next keystroke re-analyzes. If diagnostics never appear, check that `ScriptAnalysisEndpoints` is registered (it is mapped via `MapCentralUI`), and that the Monaco JS module's network requests to `/api/centralui/script/analyze` are completing successfully.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Central UI design specification](../requirements/Component-CentralUI.md)
|
||||
- [Security](./Security.md)
|
||||
- [Configuration Database](./ConfigurationDatabase.md)
|
||||
- [Communication](./Communication.md)
|
||||
- [Deployment Manager](./DeploymentManager.md)
|
||||
- [Template Engine](./TemplateEngine.md)
|
||||
- [Health Monitoring](./HealthMonitoring.md)
|
||||
- [Audit Log](./AuditLog.md)
|
||||
- [Notification Outbox](./NotificationOutbox.md)
|
||||
- [Site Call Audit](./SiteCallAudit.md)
|
||||
- [Transport](./Transport.md)
|
||||
- [TreeView](./TreeView.md)
|
||||
@@ -0,0 +1,240 @@
|
||||
# Management Service
|
||||
|
||||
The Management Service is the Akka.NET actor that provides programmatic access to every admin operation on the central cluster — the same operations the Central UI exposes, made available over an HTTP API and, optionally, a `ClusterClient` path for cross-cluster callers.
|
||||
|
||||
## Overview
|
||||
|
||||
Management Service (#18) runs on the central cluster only. The component code lives in `src/ZB.MOM.WW.ScadaBridge.ManagementService/`, with four source files:
|
||||
|
||||
- `ManagementActor.cs` — the `ReceiveActor` that owns authorization, dispatch, and error mapping for all commands.
|
||||
- `ManagementEndpoints.cs` — the `POST /management` minimal-API endpoint that authenticates over HTTP Basic Auth and forwards to the actor.
|
||||
- `AuditEndpoints.cs` — dedicated REST endpoints (`GET /api/audit/query`, `GET /api/audit/export`) for the centralized Audit Log (#23); these bypass the actor because the workload is read-only and keyset-paged.
|
||||
- `DebugStreamHub.cs` — a SignalR hub for real-time debug stream subscriptions (attribute and alarm state changes).
|
||||
|
||||
`ServiceCollectionExtensions.AddManagementService` registers `ManagementActorHolder` (a DI singleton that holds the live `IActorRef`) and binds `ManagementServiceOptions` from `ScadaBridge:ManagementService`.
|
||||
|
||||
The `ManagementActor` is not a cluster singleton. Because it is completely stateless — it opens a new DI scope per command and delegates all work to repositories and domain services — every central node runs its own instance. Either node can serve any request independently, so no singleton coordination is needed.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### `ManagementEnvelope` and the wire protocol
|
||||
|
||||
Every command arrives wrapped in a `ManagementEnvelope`:
|
||||
|
||||
```csharp
|
||||
public record AuthenticatedUser(
|
||||
string Username, string DisplayName,
|
||||
string[] Roles, string[] PermittedSiteIds);
|
||||
|
||||
public record ManagementEnvelope(AuthenticatedUser User, object Command, string CorrelationId);
|
||||
```
|
||||
|
||||
The HTTP endpoint constructs the envelope after LDAP authentication and role resolution; the `CorrelationId` (a `Guid` formatted as `"N"`) ties server-log entries to the caller's request. The actor never authenticates a second time — the envelope carries an already-resolved `AuthenticatedUser`.
|
||||
|
||||
### Role enforcement and site scope
|
||||
|
||||
Authorization is a two-level check. `GetRequiredRole` maps each command type to the minimum role required:
|
||||
|
||||
| Role | Commands |
|
||||
|------|----------|
|
||||
| `Administrator` | Site management, role mappings, API key management, scope rules, `QueryAuditLogCommand`, `PreviewBundle`, `ImportBundle` |
|
||||
| `Designer` | Template authoring (members, folders, compositions), external systems, data connections, notification lists, shared scripts, database connections, inbound API methods, `ExportBundle` |
|
||||
| `Deployer` | Instance lifecycle, connection bindings, overrides, deployments, debug snapshot, parked message queries |
|
||||
| _(any authenticated user)_ | Read-only list/get queries, health summary |
|
||||
|
||||
Within `Deployer` commands, `EnforceSiteScope` applies a second check: users whose role mapping carries `PermittedSiteIds` can only touch instances and sites within their permitted set. Administrators and system-wide deployers (empty `PermittedSiteIds`) are unrestricted. A violation throws `SiteScopeViolationException`, which `MapFault` converts to `ManagementUnauthorized`.
|
||||
|
||||
### Command registry
|
||||
|
||||
`ManagementCommandRegistry` (in Commons) maps wire names to CLR types via reflection at startup. It scans the `ZB.MOM.WW.ScadaBridge.Commons.Messages.Management` namespace for non-abstract types whose name ends in `"Command"` and stores them in a `FrozenDictionary`. The HTTP endpoint calls `ManagementCommandRegistry.Resolve(commandName)` to get the target type, then deserializes the `payload` JSON into it.
|
||||
|
||||
### Audit contract
|
||||
|
||||
Mutating handlers that call repositories directly invoke `AuditAsync` (backed by `IAuditService`) after a successful write. Handlers that delegate to domain services — `TemplateService`, `InstanceService`, `DeploymentService`, `ArtifactDeploymentService`, `TemplateFolderService`, `SharedScriptService` — do not call `AuditAsync`; those services audit internally. This avoids double-logging. SMTP configuration and API key responses project out secrets before the audit entry is written.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Actor lifecycle and registration
|
||||
|
||||
`AkkaHostedService` (in the Host) creates the `ManagementActor` under the path `/user/management` and registers it with `ClusterClientReceptionist`:
|
||||
|
||||
```csharp
|
||||
var mgmtActor = _actorSystem!.ActorOf(
|
||||
Props.Create(() => new ManagementActor(_serviceProvider, mgmtLogger)),
|
||||
"management");
|
||||
ClusterClientReceptionist.Get(_actorSystem).RegisterService(mgmtActor);
|
||||
var mgmtHolder = _serviceProvider.GetRequiredService<ManagementActorHolder>();
|
||||
mgmtHolder.ActorRef = mgmtActor;
|
||||
```
|
||||
|
||||
`ClusterClientReceptionist` advertises the actor to `ClusterClient` senders without requiring them to join the Akka cluster. The `ManagementActorHolder.ActorRef` property is then the bridge from the HTTP endpoint (which runs in ASP.NET Core middleware) into the Akka actor world.
|
||||
|
||||
The actor declares an explicit supervisor strategy — one-for-one with Resume and no retry limit — to match the coordinator-actor convention and remain correct if child actors are added later.
|
||||
|
||||
### HTTP Management API (`POST /management`)
|
||||
|
||||
`ManagementEndpoints.MapManagementAPI` registers the endpoint. Each request goes through six steps:
|
||||
|
||||
1. Raise the per-request body size cap to 200 MB (needed for Transport bundle imports).
|
||||
2. Decode `Authorization: Basic <base64>` and split username/password.
|
||||
3. Authenticate via `ILdapAuthService`.
|
||||
4. Resolve roles via `RoleMapper`, building the `AuthenticatedUser` with any site-scope limits.
|
||||
5. Deserialize the JSON body (`command` + `payload`) via `ManagementCommandRegistry`.
|
||||
6. `Ask` the `ManagementActor` with a `ManagementEnvelope` and map the response:
|
||||
|
||||
```csharp
|
||||
return response switch
|
||||
{
|
||||
ManagementSuccess success => Results.Text(success.JsonData, "application/json", statusCode: 200),
|
||||
ManagementError error => Results.Json(new { error = error.Error, code = error.ErrorCode }, statusCode: 400),
|
||||
ManagementUnauthorized u => Results.Json(new { error = u.Message, code = "UNAUTHORIZED" }, statusCode: 403),
|
||||
_ => Results.Json(new { error = "Unexpected response.", code = "INTERNAL_ERROR" }, statusCode: 500)
|
||||
};
|
||||
```
|
||||
|
||||
The `Ask` timeout defaults to 30 seconds and is overridable via `ScadaBridge:ManagementService:CommandTimeout`. An elapsed timeout returns HTTP 504.
|
||||
|
||||
### Actor dispatch and error mapping
|
||||
|
||||
`ManagementActor.HandleEnvelope` checks the required role, then calls `ProcessCommand`, which opens a DI scope, runs `DispatchCommand`, and wraps the result in `ManagementSuccess`. The `PipeTo` pattern keeps the actor's message loop free during async work; the failure continuation maps exceptions to `ManagementError` or `ManagementUnauthorized`:
|
||||
|
||||
```csharp
|
||||
private void HandleEnvelope(ManagementEnvelope envelope)
|
||||
{
|
||||
var sender = Sender;
|
||||
var correlationId = envelope.CorrelationId;
|
||||
var user = envelope.User;
|
||||
|
||||
var requiredRole = GetRequiredRole(envelope.Command);
|
||||
if (requiredRole != null && !user.Roles.Contains(requiredRole, StringComparer.OrdinalIgnoreCase))
|
||||
{
|
||||
sender.Tell(new ManagementUnauthorized(correlationId,
|
||||
$"Role '{requiredRole}' required for {envelope.Command.GetType().Name}"));
|
||||
return;
|
||||
}
|
||||
|
||||
ProcessCommand(envelope, user)
|
||||
.PipeTo(sender,
|
||||
success: result => result,
|
||||
failure: ex => MapFault(ex, correlationId, envelope.Command));
|
||||
}
|
||||
```
|
||||
|
||||
`ManagementCommandException` carries a message safe to surface to callers. Any other exception is an unanticipated fault; only the correlation ID is returned so internal detail (server names, constraint names) is not disclosed.
|
||||
|
||||
### Audit REST API (`/api/audit/*`)
|
||||
|
||||
`AuditEndpoints.MapAuditAPI` registers two GET endpoints that go directly to `IAuditLogRepository`, bypassing the actor:
|
||||
|
||||
- `GET /api/audit/query` — keyset-paged JSON result. Requires `OperationalAudit` permission (Admin / Audit / AuditReadOnly roles). Accepts `channel`, `kind`, `status`, `sourceSiteId`, `correlationId`, `executionId`, `parentExecutionId`, `fromUtc`, `toUtc`, `pageSize`, and cursor params `afterOccurredAtUtc`/`afterEventId`. Returns `{ events, nextCursor }` where `nextCursor` is explicit `null` on the last page.
|
||||
- `GET /api/audit/export` — server-side streaming export (CSV or JSONL) of all matching rows, paging the repository internally at 1 000 rows per batch and flushing after each batch. Requires `AuditExport` permission (Admin / Audit roles). `format=parquet` returns HTTP 501 (deferred).
|
||||
|
||||
Both endpoints apply the same HTTP Basic Auth / LDAP / role flow as `/management`. Site-scoped callers have their `sourceSiteId` filter intersected with their `PermittedSiteIds`; an explicit out-of-scope filter returns HTTP 403 rather than silently empty results.
|
||||
|
||||
### Debug stream (`/debug-stream`)
|
||||
|
||||
`DebugStreamHub` is a SignalR hub registered alongside the management endpoints. It authenticates on `OnConnectedAsync` (same Basic Auth / LDAP / role flow), requires the `Deployer` role, and enforces per-instance site scope on `SubscribeInstance`. Accepted connections receive an initial `DebugViewSnapshot` followed by incremental `AttributeValueChanged` and `AlarmStateChanged` events pushed from `DebugStreamService`.
|
||||
|
||||
## Usage
|
||||
|
||||
### Sending a command from the CLI
|
||||
|
||||
The CLI sends a single `POST /management` with JSON body and Basic Auth; it does not use `ClusterClient` directly. A typical request:
|
||||
|
||||
```
|
||||
POST /management
|
||||
Authorization: Basic base64(username:password)
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"command": "ListSites",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
A successful response is HTTP 200 with the JSON result. An authorization failure is HTTP 403 with `{ "error": "...", "code": "UNAUTHORIZED" }`.
|
||||
|
||||
### Sending a command via ClusterClient
|
||||
|
||||
The `ManagementActor` is also reachable from any `ClusterClient` that has a contact point into the central cluster. The actor is registered under `/system/receptionist` with the path `/user/management`. Callers construct and `Tell` a `ManagementEnvelope` and expect one of `ManagementSuccess`, `ManagementError`, or `ManagementUnauthorized` in reply.
|
||||
|
||||
## Command Groups
|
||||
|
||||
`DispatchCommand` in `ManagementActor.cs` is the canonical enumeration of every supported command. The table below organizes them by domain area.
|
||||
|
||||
| Group | Commands | Minimum role |
|
||||
|-------|----------|--------------|
|
||||
| Templates | `ListTemplates`, `GetTemplate`, `CreateTemplate`, `UpdateTemplate`, `DeleteTemplate`, `ValidateTemplate` | Designer (mutations) |
|
||||
| Template members | `AddTemplateAttribute`, `UpdateTemplateAttribute`, `DeleteTemplateAttribute`, `AddTemplateAlarm`, `UpdateTemplateAlarm`, `DeleteTemplateAlarm`, `AddTemplateNativeAlarmSource`, `UpdateTemplateNativeAlarmSource`, `DeleteTemplateNativeAlarmSource`, `ListTemplateNativeAlarmSources`, `AddTemplateScript`, `UpdateTemplateScript`, `DeleteTemplateScript`, `AddTemplateComposition`, `DeleteTemplateComposition` | Designer (mutations) |
|
||||
| Template folders | `ListTemplateFolders`, `CreateTemplateFolder`, `RenameTemplateFolder`, `MoveTemplateFolder`, `DeleteTemplateFolder`, `MoveTemplateToFolder` | Designer (mutations) |
|
||||
| Instances | `ListInstances`, `GetInstance`, `CreateInstance`, `MgmtDeployInstance`, `MgmtEnableInstance`, `MgmtDisableInstance`, `MgmtDeleteInstance`, `SetConnectionBindings`, `SetInstanceOverrides`, `SetInstanceArea`, `SetInstanceAlarmOverride`, `DeleteInstanceAlarmOverride`, `ListInstanceAlarmOverrides`, `SetInstanceNativeAlarmSourceOverride`, `DeleteInstanceNativeAlarmSourceOverride`, `ListInstanceNativeAlarmSourceOverrides` | Deployer (mutations) |
|
||||
| Sites & areas | `ListSites`, `GetSite`, `CreateSite`, `UpdateSite`, `DeleteSite`, `ListAreas`, `CreateArea`, `UpdateArea`, `DeleteArea` | Administrator (mutations) |
|
||||
| Data connections | `ListDataConnections`, `GetDataConnection`, `CreateDataConnection`, `UpdateDataConnection`, `DeleteDataConnection` | Designer (mutations) |
|
||||
| External systems | `ListExternalSystems`, `GetExternalSystem`, `CreateExternalSystem`, `UpdateExternalSystem`, `DeleteExternalSystem`, `ListExternalSystemMethods`, `GetExternalSystemMethod`, `CreateExternalSystemMethod`, `UpdateExternalSystemMethod`, `DeleteExternalSystemMethod` | Designer (mutations) |
|
||||
| Notification lists / SMTP | `ListNotificationLists`, `GetNotificationList`, `CreateNotificationList`, `UpdateNotificationList`, `DeleteNotificationList`, `ListSmtpConfigs`, `UpdateSmtpConfig` | Designer (mutations) |
|
||||
| Shared scripts | `ListSharedScripts`, `GetSharedScript`, `CreateSharedScript`, `UpdateSharedScript`, `DeleteSharedScript` | Designer (mutations) |
|
||||
| Database connections | `ListDatabaseConnections`, `GetDatabaseConnection`, `CreateDatabaseConnectionDef`, `UpdateDatabaseConnectionDef`, `DeleteDatabaseConnectionDef` | Designer (mutations) |
|
||||
| Inbound API methods | `ListApiMethods`, `GetApiMethod`, `CreateApiMethod`, `UpdateApiMethod`, `DeleteApiMethod` | Designer (mutations) |
|
||||
| Security | `ListRoleMappings`, `CreateRoleMapping`, `UpdateRoleMapping`, `DeleteRoleMapping`, `ListApiKeys`, `CreateApiKey`, `UpdateApiKey`, `DeleteApiKey`, `SetApiKeyMethods`, `ListScopeRules`, `AddScopeRule`, `DeleteScopeRule` | Administrator |
|
||||
| Deployments | `MgmtDeployArtifacts`, `QueryDeployments`, `GetDeploymentDiff` | Deployer |
|
||||
| Health | `GetHealthSummary`, `GetSiteHealth` | Any authenticated user |
|
||||
| Remote queries | `QueryEventLogs`, `QueryParkedMessages`, `RetryParkedMessage`, `DiscardParkedMessage`, `DebugSnapshot` | Deployer |
|
||||
| Audit (legacy) | `QueryAuditLog` | Administrator |
|
||||
| Transport | `ExportBundle` (Designer), `PreviewBundle`, `ImportBundle` (Administrator) | Varies |
|
||||
|
||||
`ValidateTemplate` builds a `FlattenedConfiguration` from the template's attributes, alarms, and scripts, runs the full `ValidationService` pipeline (collision detection, script compilation, trigger reference checks), and merges in naming-collision errors from `TemplateService.DetectCollisionsAsync` — all without a deployment.
|
||||
|
||||
`SetInstanceOverrides` validates every attribute name and lock status against the template before applying any write, making the batch all-or-nothing at the validation layer.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Section | Key | Default | Description |
|
||||
|---------|-----|---------|-------------|
|
||||
| `ScadaBridge:ManagementService` | `CommandTimeout` | `00:00:30` | `Ask` timeout the `ManagementEndpoints` applies when forwarding to the `ManagementActor`. A non-positive value falls back to the 30-second default. |
|
||||
|
||||
The 200 MB per-request body cap (`ManagementEndpoints.MaxManagementRequestBodyBytes`) is hard-coded; it exists to accommodate Transport (#24) Import calls where a 100 MB raw bundle base64-inflates to roughly 140 MB plus the envelope overhead.
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- [Commons (#16)](./Commons.md) — owns the message contracts (`Messages/Management/`), `ManagementEnvelope`, `ManagementCommandRegistry`, `AuthenticatedUser`, and `ManagementSuccess`/`ManagementError`/`ManagementUnauthorized` response types.
|
||||
- [Configuration Database (#17)](./ConfigurationDatabase.md) — every repository (`ITemplateEngineRepository`, `ISiteRepository`, `IExternalSystemRepository`, `INotificationRepository`, `ISecurityRepository`, `IInboundApiRepository`, `IDeploymentManagerRepository`, `ICentralUiRepository`) and `IAuditService` are backed by EF Core against the central MS SQL database. Management Service resolves them per-command through scoped DI.
|
||||
- [Template Engine (#1)](./TemplateEngine.md) — `TemplateService`, `TemplateFolderService`, `SharedScriptService`, and the `ValidationService` handle template authoring and validation. Management Service is the sole entry point for template mutations from outside the Central UI.
|
||||
- [Deployment Manager (#2)](./DeploymentManager.md) — `DeploymentService` and `ArtifactDeploymentService` own the deployment pipeline. `MgmtDeployInstance` and `MgmtDeployArtifacts` delegate here.
|
||||
- [Central–Site Communication (#5)](./Communication.md) — `CommunicationService` routes `QueryEventLogs`, `QueryParkedMessages`, `RetryParkedMessage`, `DiscardParkedMessage`, and `DebugSnapshot` to site actors via `ClusterClient`. Deployment commands also flow through the communication layer.
|
||||
- [Security & Auth (#10)](./Security.md) — `ILdapAuthService` and `RoleMapper` authenticate and map roles on every HTTP request; the `Roles` constants and `IInboundApiKeyAdmin` are also consumed here.
|
||||
- [Health Monitoring (#11)](./HealthMonitoring.md) — `ICentralHealthAggregator` answers `GetHealthSummary` and `GetSiteHealth` queries synchronously from its in-memory state.
|
||||
- [Audit Log (#23)](./AuditLog.md) — `AuditEndpoints` reads the central `AuditLog` table via `IAuditLogRepository` directly (no actor hop). `QueryAuditLogCommand` through `/management` is a legacy path for the configuration-change audit via `ICentralUiRepository`.
|
||||
- [CLI (#19)](./CLI.md) — the primary consumer of `POST /management` and the `/api/audit/*` endpoints. Constructs `ManagementEnvelope`-shaped JSON, sends Basic Auth, and deserializes the response.
|
||||
- [Host (#15)](./Host.md) — `AkkaHostedService` creates the `ManagementActor`, registers it with `ClusterClientReceptionist`, and sets `ManagementActorHolder.ActorRef` so the HTTP endpoint can reach it.
|
||||
- Design spec: [Component-ManagementService.md](../requirements/Component-ManagementService.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Actor not ready (HTTP 503)
|
||||
|
||||
If `POST /management` returns `503 SERVICE_UNAVAILABLE`, `ManagementActorHolder.ActorRef` is null — the actor system has not finished starting. This resolves itself once `AkkaHostedService.StartAsync` completes. The `/health/ready` endpoint is the gating signal; traffic should not reach `/management` before it returns 200.
|
||||
|
||||
### Command timeout (HTTP 504)
|
||||
|
||||
A 504 response means the `Ask` to `ManagementActor` did not return within the configured `CommandTimeout`. The server log entry includes the `CorrelationId` from the response body. Common causes: a long-running deployment waiting on a site that is offline, or a database query against a cold EF Core connection. Increasing `ScadaBridge:ManagementService:CommandTimeout` buys time while the root cause is investigated.
|
||||
|
||||
### Unexpected internal error
|
||||
|
||||
Any exception that is not a `ManagementCommandException` or `SiteScopeViolationException` maps to a generic `COMMAND_FAILED` error with the correlation ID. The server log at `Error` level will contain the full exception, keyed by `CorrelationId`. `ManagementCommandException` messages are intentionally surfaced verbatim; all other exception messages are suppressed on the wire to avoid leaking internal detail.
|
||||
|
||||
### Audit log export stalls mid-stream
|
||||
|
||||
`GET /api/audit/export` streams rows in pages of 1 000 and flushes after each page. If the response body stops arriving, check whether a proxy is buffering the response (the endpoint sets `Cache-Control: no-store` to defeat most buffers). The `pageSize` parameter on `/api/audit/query` caps at 1 000; requests above that are silently clamped.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Management Service design specification](../requirements/Component-ManagementService.md)
|
||||
- [CLI](./CLI.md)
|
||||
- [Central–Site Communication](./Communication.md)
|
||||
- [Commons](./Commons.md)
|
||||
- [Configuration Database](./ConfigurationDatabase.md)
|
||||
- [Template Engine](./TemplateEngine.md)
|
||||
- [Deployment Manager](./DeploymentManager.md)
|
||||
- [Security](./Security.md)
|
||||
- [Audit Log](./AuditLog.md)
|
||||
- [Host](./Host.md)
|
||||
@@ -0,0 +1,192 @@
|
||||
# Traefik Proxy
|
||||
|
||||
The Traefik Proxy is the reverse proxy and load balancer that fronts the central cluster's two web servers. It exposes a single stable entrypoint for all central traffic — Central UI, Management API, Inbound API — and routes exclusively to whichever central node is currently the Akka.NET cluster leader, using a health-check on each node's `/health/active` endpoint to make that determination. When the active node changes, Traefik detects the change on its next poll cycle and redirects traffic automatically, with no operator intervention.
|
||||
|
||||
## Overview
|
||||
|
||||
The proxy runs as the `scadabridge-traefik` Docker container in the main compose stack (`docker/docker-compose.yml`). It is a third-party infrastructure component (Traefik v3.4) — there is no C# project for it. Its entire configuration is two YAML files mounted read-only into the container:
|
||||
|
||||
- `docker/traefik/traefik.yml` — static config: entrypoints, API dashboard, and file provider declaration.
|
||||
- `docker/traefik/dynamic.yml` — routing rules: the router that catches all traffic, the `central` load-balancer service listing both backend nodes, and the `/health/active` health-check settings.
|
||||
|
||||
The proxy sits on the `scadabridge-net` Docker bridge network alongside both central nodes (`scadabridge-central-a`, `scadabridge-central-b`) and all site containers, so it can reach the central backends by container name.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Active-node routing via `/health/active`
|
||||
|
||||
Traefik does not know which central node is the Akka.NET cluster leader — it discovers this by polling `/health/active` on both backends. The Host registers `ActiveNodeHealthCheck` under the `Active` health tag; `app.MapZbHealth()` serves it at `/health/active`. The check returns HTTP 200 on the leader and HTTP 503 on the standby (or when the actor system has not yet reached `MemberStatus.Up`):
|
||||
|
||||
```csharp
|
||||
public bool IsActiveNode
|
||||
{
|
||||
get
|
||||
{
|
||||
var system = _akkaService.ActorSystem;
|
||||
if (system == null)
|
||||
return false;
|
||||
|
||||
var cluster = Cluster.Get(system);
|
||||
var self = cluster.SelfMember;
|
||||
if (self.Status != MemberStatus.Up)
|
||||
return false;
|
||||
|
||||
var leader = cluster.State.Leader;
|
||||
return leader != null && leader == self.Address;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The identical leadership check backs `ActiveNodeGate` — the `IActiveNodeGate` implementation the Inbound API endpoint filter consults before executing method scripts. Both surfaces agree on which node is active because they share the same Akka cluster state.
|
||||
|
||||
### Automatic failover
|
||||
|
||||
When the active central node goes down, the Akka cluster's keep-oldest split-brain resolver promotes the surviving node to leader (roughly 25 seconds: 10-second heartbeat threshold plus a 15-second stable-after period). Once the surviving node's `ActiveNodeHealthCheck` starts returning 200, Traefik's next poll cycle — within the 5-second interval — removes the failed backend from the pool and routes all subsequent requests to the new active node. No config change or restart is required on the Traefik side.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Docker topology
|
||||
|
||||
```
|
||||
Clients (CLI, browser, external API)
|
||||
│
|
||||
host:9000 (HTTP)
|
||||
│
|
||||
┌───────▼──────────────────┐
|
||||
│ scadabridge-traefik │ (Traefik v3.4 container)
|
||||
│ entrypoint :80 │
|
||||
└──────┬──────────┬─────────┘
|
||||
│ /health/active poll (5s)
|
||||
▼ ▼
|
||||
scadabridge- scadabridge-
|
||||
central-a:5000 central-b:5000
|
||||
(ACTIVE → 200) (STANDBY → 503)
|
||||
```
|
||||
|
||||
Clients always connect to `http://localhost:9000`. The two central nodes are also reachable directly — `central-a` on host port 9001, `central-b` on host port 9002 — but these bypass the load balancer and should be used only for direct debugging. The Traefik dashboard is accessible at `http://localhost:8180`.
|
||||
|
||||
### Request flow
|
||||
|
||||
Every incoming request on the `web` entrypoint hits the `central` router, which matches all paths (`PathPrefix("/")`) and forwards to the `central` load-balancer service. The load balancer only includes servers that are currently passing the health check, so in normal operation all traffic goes to the single healthy (active) backend.
|
||||
|
||||
## Usage
|
||||
|
||||
Traefik starts automatically with the cluster compose stack:
|
||||
|
||||
```bash
|
||||
# Start full cluster (includes Traefik)
|
||||
docker compose -f docker/docker-compose.yml up -d
|
||||
|
||||
# Check Traefik dashboard (shows backend health status)
|
||||
open http://localhost:8180
|
||||
|
||||
# Verify routing — reaches the active node
|
||||
curl http://localhost:9000/health/active
|
||||
|
||||
# Direct node access (bypasses Traefik — use for debugging only)
|
||||
curl http://localhost:9001/health/active # central-a
|
||||
curl http://localhost:9002/health/active # central-b
|
||||
```
|
||||
|
||||
The Traefik container's `restart: unless-stopped` policy means it recovers automatically after a Docker host restart.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Static config (`docker/traefik/traefik.yml`)
|
||||
|
||||
```yaml
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
|
||||
api:
|
||||
dashboard: true
|
||||
insecure: true
|
||||
|
||||
providers:
|
||||
file:
|
||||
filename: /etc/traefik/dynamic.yml
|
||||
```
|
||||
|
||||
| Key | Value | Effect |
|
||||
|-----|-------|--------|
|
||||
| `entryPoints.web.address` | `:80` | Listens on container port 80, mapped to host port 9000. |
|
||||
| `api.dashboard` | `true` | Enables the Traefik web dashboard. |
|
||||
| `api.insecure` | `true` | Serves the dashboard on port 8080 without auth (development only). |
|
||||
| `providers.file.filename` | `/etc/traefik/dynamic.yml` | Loads routing rules from the mounted dynamic config; no Docker socket required. |
|
||||
|
||||
### Dynamic config (`docker/traefik/dynamic.yml`)
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
central:
|
||||
rule: "PathPrefix(`/`)"
|
||||
service: central
|
||||
entryPoints:
|
||||
- web
|
||||
|
||||
services:
|
||||
central:
|
||||
loadBalancer:
|
||||
healthCheck:
|
||||
path: /health/active
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
servers:
|
||||
- url: "http://scadabridge-central-a:5000"
|
||||
- url: "http://scadabridge-central-b:5000"
|
||||
```
|
||||
|
||||
| Setting | Value | Effect |
|
||||
|---------|-------|--------|
|
||||
| `routers.central.rule` | `PathPrefix("/")` | Catches every request on the `web` entrypoint. |
|
||||
| `services.central.loadBalancer.healthCheck.path` | `/health/active` | The endpoint Traefik polls on each backend. |
|
||||
| `services.central.loadBalancer.healthCheck.interval` | `5s` | Poll cadence; a backend failing the check is removed within one interval. |
|
||||
| `services.central.loadBalancer.healthCheck.timeout` | `3s` | Per-poll timeout; a non-responding backend counts as unhealthy. |
|
||||
| `servers[0].url` | `http://scadabridge-central-a:5000` | `central-a` backend, reachable by container name on `scadabridge-net`. |
|
||||
| `servers[1].url` | `http://scadabridge-central-b:5000` | `central-b` backend, reachable by container name on `scadabridge-net`. |
|
||||
|
||||
### Port mapping
|
||||
|
||||
| Host port | Container port | Purpose |
|
||||
|-----------|---------------|---------|
|
||||
| `9000` | `80` | Load-balanced entrypoint — all central traffic (Central UI, Management API, Inbound API). |
|
||||
| `8180` | `8080` | Traefik dashboard. |
|
||||
| `9001` | `5000` | Direct access to `central-a` (bypasses Traefik). |
|
||||
| `9002` | `5000` | Direct access to `central-b` (bypasses Traefik). |
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- [Host (#15)](./Host.md) — implements and serves `/health/active` via `ActiveNodeHealthCheck` (tagged `Active`, mounted by `app.MapZbHealth()`). Also implements `ActiveNodeGate`, which enforces the same active-node contract at the Inbound API filter level, providing a defence-in-depth layer if traffic reaches the standby directly.
|
||||
- [Cluster Infrastructure (#13)](./ClusterInfrastructure.md) — the underlying Akka.NET cluster determines which node is the leader. Traefik's routing decision is derived entirely from cluster leadership state via the health-check poll; Traefik has no Akka dependency of its own.
|
||||
- [Central UI (#9)](./CentralUI.md) — Blazor Server (SignalR/WebSocket circuits) is proxied through Traefik. Traefik proxies WebSocket connections natively with no additional config. On failover, active SignalR circuits on the failed node are lost; the browser's reconnection logic re-establishes the circuit on the new active node. Session continuity is preserved because authentication uses a cookie-embedded JWT with Data Protection keys shared across both central nodes.
|
||||
- [Inbound API (#14)](./InboundAPI.md) — external API consumers target `http://localhost:9000/api/{methodName}`. Traefik routes each request to the active node; if a request reaches the standby directly (bypassing Traefik), `ActiveNodeGate` responds with HTTP 503.
|
||||
- [CLI (#19)](./CLI.md) — the CLI connects to the Management API via `http://localhost:9000` (the Traefik entrypoint) by default, so it always reaches the active central node without needing to know which node is active.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Both backends show unhealthy on the dashboard
|
||||
|
||||
If both `central-a` and `central-b` appear red on the Traefik dashboard, neither node's `ActiveNodeHealthCheck` is returning 200. Common causes:
|
||||
|
||||
1. **Akka cluster has not formed yet** — both nodes are still starting. Wait for the cluster to stabilise (typically 10–15 seconds after both containers are up). Check the central node logs for `Cluster is now ready`.
|
||||
2. **Split-brain resolver has downed both nodes** — a network partition followed by a split-brain condition. Restart the cluster via `bash docker/deploy.sh`.
|
||||
3. **Traefik cannot reach the backends** — the `scadabridge-net` Docker network may not exist. Create it: `docker network create scadabridge-net`.
|
||||
|
||||
### Traffic reaches a standby node
|
||||
|
||||
If a client receives HTTP 503 with `X-ScadaBridge-Active: false`, the request reached a standby node — either because Traefik has not yet completed its health-check poll after a failover (up to 5 seconds), or because the client is connecting directly to port 9001/9002 instead of port 9000. Use `http://localhost:9000` for all normal access. The 503 is transient during the Traefik poll window; the client should retry.
|
||||
|
||||
### Health check succeeds but `/health/ready` returns degraded
|
||||
|
||||
`/health/active` and `/health/ready` are independent. A node can pass the active check (it is the leader) but fail the readiness check (database or Akka cluster health probe failed). Traefik only uses `/health/active`; readiness gating is for orchestration and monitoring. Check the node's structured logs for `database` or `akka-cluster` check failures.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Traefik Proxy design specification](../requirements/Component-TraefikProxy.md)
|
||||
- [Host](./Host.md)
|
||||
- [Cluster Infrastructure](./ClusterInfrastructure.md)
|
||||
- [Central UI](./CentralUI.md)
|
||||
- [Inbound API](./InboundAPI.md)
|
||||
- [CLI](./CLI.md)
|
||||
@@ -0,0 +1,257 @@
|
||||
# Transport
|
||||
|
||||
The Transport component provides file-based, encrypted bundle export and import of central configuration artifacts between ScadaBridge environments via the Central UI. It is purely central — no site nodes are touched, no runtime state moves, and no site-scoped artifacts travel in a bundle.
|
||||
|
||||
## Overview
|
||||
|
||||
Transport (#24) is a central-only component that lives in `src/ZB.MOM.WW.ScadaBridge.Transport/`, split into three functional areas:
|
||||
|
||||
- `Export/` — `BundleExporter`, `DependencyResolver`, `ResolvedExport`. The export pipeline resolves artifact dependencies, serializes entities to wire-shaped DTOs, optionally encrypts the content, and produces a ZIP-formatted `.scadabundle` stream.
|
||||
- `Import/` — `BundleImporter`, `BundleSessionStore`, `BundleSessionEvictionService`, `ArtifactDiff`, `BundleUnlockRateLimiter`. The import pipeline validates the bundle envelope, decrypts it, diffs against the target environment, and applies operator-chosen conflict resolutions in a single EF transaction.
|
||||
- `Serialization/` and `Encryption/` — `BundleSerializer`, `EntitySerializer`, `ManifestBuilder`, `ManifestValidator`, `BundleSecretEncryptor`, `BundleManifestAad`. Stateless helpers that handle ZIP packing/unpacking, DTO projection, SHA-256 hashing, and AES-256-GCM authenticated encryption.
|
||||
|
||||
The single DI entry point is `ServiceCollectionExtensions.AddTransport`, registered by `Host` for central roles only. Stateless helpers are singletons; the exporter and importer are scoped because they reach into per-request EF Core scopes and audited repositories.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Bundle format
|
||||
|
||||
A `.scadabundle` file is a ZIP archive with exactly two entries:
|
||||
|
||||
```
|
||||
bundle.scadabundle
|
||||
├── manifest.json # always plaintext; never encrypted
|
||||
└── content.json # plaintext artifact data (no passphrase)
|
||||
OR content.enc # AES-256-GCM ciphertext (passphrase supplied)
|
||||
```
|
||||
|
||||
`manifest.json` is always plaintext so the import wizard can display source provenance and artifact counts before the operator supplies a passphrase. `BundleManifest` carries: `BundleFormatVersion`, `SchemaVersion`, `CreatedAtUtc`, `SourceEnvironment`, `ExportedBy`, `ScadaBridgeVersion`, `ContentHash` (`sha256:<hex>` of the raw content bytes), optional `Encryption` metadata, a `Summary` (artifact counts by type), and a `Contents` list (one `ManifestContentEntry` per artifact with its `dependsOn` edges).
|
||||
|
||||
`BundleFormatVersion` is an integer gate: the importer hard-refuses any value higher than `TransportOptions.SchemaVersionMajor` (default `1`). Unknown entity types in `Contents` produce a preview-row classification of "unsupported" rather than aborting the whole import.
|
||||
|
||||
### Encrypted vs plaintext bundles
|
||||
|
||||
When a passphrase is supplied, `BundleSecretEncryptor` derives a 256-bit key via PBKDF2-SHA256 (default 600,000 iterations, configurable) from a fresh 16-byte random salt, then encrypts the UTF-8 JSON content using AES-256-GCM with a fresh 12-byte nonce. Output format is `ciphertext ‖ GCM-tag` (16-byte tag appended). The salt and nonce are stored in `manifest.json`; the passphrase is never persisted. An unencrypted export is permitted but produces an `UnencryptedBundleExport` audit event rather than `BundleExported`.
|
||||
|
||||
### AAD binding (T-005)
|
||||
|
||||
`BundleManifestAad.Compute` produces AES-GCM Associated Authenticated Data by SHA-256-hashing a canonicalized form of the manifest with `ContentHash` zeroed and `Encryption` nulled. This binds `SourceEnvironment`, `ExportedBy`, `Summary`, and `Contents` to the GCM authentication tag. Tampering with any of those fields on a stolen bundle yields an `AuthenticationTagMismatchException` on decryption, making the Step-4 "type the source environment to confirm" gate tamper-evident.
|
||||
|
||||
### BundleSession and session lifecycle
|
||||
|
||||
After `LoadAsync` validates and decrypts a bundle, the plaintext content is stored in a `BundleSession` held by the singleton `BundleSessionStore` (a `ConcurrentDictionary<Guid, BundleSession>`). Sessions have a 30-minute TTL (`BundleSessionTtlMinutes`). `BundleSessionEvictionService` sweeps the store every minute so abandoned sessions — and the secrets they carry — are released without waiting for the next `Get` call. `ApplyAsync` explicitly zeros and removes the session on both success and failure (T-007).
|
||||
|
||||
### Conflict resolution and `BundleImportId` correlation
|
||||
|
||||
`PreviewAsync` compares each bundle artifact against the target environment using `ArtifactDiff`, classifying items as `Identical`, `Modified`, `New`, or `Blocker`. The operator assigns a `ResolutionAction` (`Add`, `Overwrite`, `Skip`, `Rename`) per item. `ApplyAsync` honours those resolutions in a single EF transaction and threads a new `BundleImportId` GUID through every per-entity audit row via the scoped `IAuditCorrelationContext`. This makes every configuration row written by a bundle import queryable as a group from the audit log.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Export pipeline
|
||||
|
||||
`BundleExporter.ExportAsync` orchestrates these steps in sequence:
|
||||
|
||||
1. `DependencyResolver.ResolveAsync` — expands the operator's `ExportSelection` to the full transitive closure, then topologically sorts templates (base-before-derived via Kahn's algorithm).
|
||||
2. `EntitySerializer.ToBundleContent` — projects EF entity POCOs to wire-shaped DTOs (`BundleContentDto`), carving secret fields (connection strings, credentials, OAuth tokens) into per-entity `SecretsBlock` records.
|
||||
3. `ManifestBuilder.Build` — stamps `BundleFormatVersion`, `SchemaVersion`, SHA-256 `ContentHash`, `Summary`, and `Contents` into a `BundleManifest`.
|
||||
4. `BundleSerializer.Pack` — serializes the manifest and content into a ZIP stream. When a passphrase is present, `BundleSecretEncryptor.Encrypt` runs with a fresh salt and nonce; `Pack` re-stamps `ContentHash` and `Encryption` in the manifest against the ciphertext it actually writes.
|
||||
5. Audit — `IAuditService.LogAsync` writes one `BundleExported` (or `UnencryptedBundleExport`) row with the SHA-256 of the full ZIP stream as `EntityId`.
|
||||
|
||||
```csharp
|
||||
public sealed class BundleExporter : IBundleExporter
|
||||
{
|
||||
public async Task<Stream> ExportAsync(
|
||||
ExportSelection selection,
|
||||
string user,
|
||||
string sourceEnvironment,
|
||||
string? passphrase,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
var resolved = await _resolver.ResolveAsync(selection, cancellationToken);
|
||||
var aggregate = new EntityAggregate(/* resolved collections */);
|
||||
var contentDto = _entitySerializer.ToBundleContent(aggregate);
|
||||
var summary = new BundleSummary(/* counts from resolved */);
|
||||
EncryptionMetadata? encryptionSeed = passphrase is null ? null
|
||||
: new EncryptionMetadata("AES-256-GCM", "PBKDF2-SHA256",
|
||||
_options.Value.Pbkdf2Iterations, string.Empty, string.Empty);
|
||||
var manifest = _manifestBuilder.Build(sourceEnvironment, user, assemblyVersion,
|
||||
encryptionSeed, summary, resolved.ContentManifest,
|
||||
_bundleSerializer.SerializeContentBytes(contentDto));
|
||||
var zipStream = _bundleSerializer.Pack(contentDto, manifest, passphrase, _encryptor);
|
||||
var bundleHash = ComputeStreamSha256(zipStream);
|
||||
await _auditService.LogAsync(user,
|
||||
passphrase is null ? "UnencryptedBundleExport" : "BundleExported",
|
||||
"Bundle", bundleHash, sourceEnvironment, /* afterState */, cancellationToken);
|
||||
zipStream.Position = 0;
|
||||
return zipStream;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dependency expansion
|
||||
|
||||
`DependencyResolver` walks five dependency edge types when `ExportSelection.IncludeDependencies` is true:
|
||||
|
||||
| Edge | Mechanism |
|
||||
|------|-----------|
|
||||
| Template composes Template | `TemplateComposition.ComposedTemplateId` (BFS over composition graph) |
|
||||
| Template references SharedScript | Name-scan of `TemplateScript.Code` and `TemplateAttribute.Value` |
|
||||
| Template references ExternalSystem | Name-scan of `TemplateScript.Code` and `TemplateAttribute.DataSourceReference` |
|
||||
| ApiMethod references SharedScript | Name-scan of `ApiMethod.Script` |
|
||||
| Template folder ancestor chain | Always included regardless of `IncludeDependencies` |
|
||||
|
||||
`ExternalSystemMethod` records always travel with their parent `ExternalSystemDefinition`. Templates are emitted in topological order (base-before-derived) so the importer can `Apply*` them in sequence without forward-reference gaps.
|
||||
|
||||
Inbound API keys are explicitly excluded — per re-architecture C4, keys are environment-specific and must be re-issued on the target cluster. `ApiMethod` definitions travel without key bindings.
|
||||
|
||||
### Import pipeline
|
||||
|
||||
`BundleImporter` is a three-phase service:
|
||||
|
||||
**Phase 1 — `LoadAsync`**: copies the upload stream to a seekable `MemoryStream`, enforces the bundle size cap (`MaxBundleSizeMb`), validates the ZIP envelope (entry count, per-entry decompressed size, compression ratio — all before decompression), reads and validates `manifest.json` (format version, SHA-256 content hash), and decrypts `content.enc` when `Encryption` is present. The decrypted bytes are stored in a new `BundleSession`.
|
||||
|
||||
Passphrase lockout operates at two levels: per-bundle (3-strike counter in `BundleSessionStore`, keyed by `ContentHash` so a second browser tab sharing the same bundle bytes cannot reset the counter) and per-IP-per-hour (`BundleUnlockRateLimiter`, default 10 attempts). A successful decrypt clears the per-bundle counter.
|
||||
|
||||
```csharp
|
||||
// From BundleImporter.LoadAsync — decrypt path (simplified)
|
||||
var aad = Encryption.BundleManifestAad.Compute(manifest);
|
||||
try
|
||||
{
|
||||
decryptedContent = _encryptor.Decrypt(contentBytes, manifest.Encryption, passphrase, aad);
|
||||
}
|
||||
catch (CryptographicException)
|
||||
{
|
||||
var newCount = _sessionStore.IncrementUnlockFailureCount(manifest.ContentHash);
|
||||
if (newCount >= maxAttempts)
|
||||
throw new BundleLockedException(manifest.ContentHash, newCount);
|
||||
throw;
|
||||
}
|
||||
_sessionStore.ClearUnlockFailures(manifest.ContentHash);
|
||||
```
|
||||
|
||||
**Phase 2 — `PreviewAsync`**: deserializes the session's plaintext bytes to `BundleContentDto` and calls `ArtifactDiff.Compare*` methods for each entity type. Diff results use `ConflictKind` (`Identical`, `Modified`, `New`, `Blocker`). `Modified` items carry a `FieldDiffJson` payload with changed-field names and old/new values; script bodies record a line-count delta rather than full text to keep the diff compact. `DetectBlockersAsync` scans script bodies for unresolvable `SharedScript` or `ExternalSystem` name references.
|
||||
|
||||
**Phase 3 — `ApplyAsync`**: runs semantic validation first (a name-resolution scan plus the full `SemanticValidator` from `TemplateEngine`), then applies all resolutions inside one EF transaction. The correlation GUID is set on `IAuditCorrelationContext.BundleImportId` before any writes so that every `IAuditService.LogAsync` call during the apply picks it up automatically. A two-pass flush handles forward references: the first `SaveChangesAsync` materializes identity values for new rows; `ResolveAlarmScriptLinksAsync` and `ResolveCompositionEdgesAsync` run afterward inside the same transaction. On failure, the transaction rolls back, `BundleImportId` is cleared, and a `BundleImportFailed` row is written outside the rolled-back transaction before the exception propagates.
|
||||
|
||||
```csharp
|
||||
// From BundleImporter.ApplyAsync — correlation + transaction pattern
|
||||
_correlationContext.BundleImportId = bundleImportId;
|
||||
await using var tx = await _dbContext.Database.BeginTransactionAsync(ct);
|
||||
try
|
||||
{
|
||||
var errors = await RunSemanticValidationAsync(content, resolutionMap, ct);
|
||||
if (errors.Count > 0) throw new SemanticValidationException(errors);
|
||||
|
||||
await ApplyTemplateFoldersAsync(/* ... */);
|
||||
await ApplyTemplatesAsync(/* ... */);
|
||||
// ... other entity types ...
|
||||
await _dbContext.SaveChangesAsync(ct); // flush for FK resolution
|
||||
await ResolveAlarmScriptLinksAsync(/* ... */);
|
||||
await ResolveCompositionEdgesAsync(/* ... */);
|
||||
|
||||
await _auditService.LogAsync(user, "BundleImported", "Bundle",
|
||||
bundleImportId.ToString(), session.Manifest.SourceEnvironment, /* afterState */, ct);
|
||||
await _dbContext.SaveChangesAsync(ct);
|
||||
await tx.CommitAsync(ct);
|
||||
ZeroDecryptedContent(session);
|
||||
_sessionStore.Remove(sessionId);
|
||||
return new ImportResult(BundleImportId: bundleImportId, /* counts */);
|
||||
}
|
||||
catch
|
||||
{
|
||||
await tx.RollbackAsync(ct);
|
||||
_correlationContext.BundleImportId = null;
|
||||
await _auditService.LogAsync(user, "BundleImportFailed", /* ... */);
|
||||
ZeroDecryptedContent(session);
|
||||
_sessionStore.Remove(sessionId);
|
||||
throw;
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The Central UI surfaces Transport through two wizard pages (see [Central UI](./CentralUI.md)):
|
||||
|
||||
- **Export** (`/design/transport/export`, Design role): a 4-step wizard — select artifacts, review resolved dependencies, set a passphrase, download the `.scadabundle` file.
|
||||
- **Import** (`/design/transport/import`, Admin role): a 5-step wizard — upload bundle, enter passphrase, review the diff and set per-artifact resolutions, confirm (operator types the source environment name), view the result and navigate to the Deployments page for any newly stale instances.
|
||||
|
||||
The same operations are available via the CLI:
|
||||
|
||||
```bash
|
||||
scadabridge bundle export --output FILE --passphrase X [--templates A,B] \
|
||||
[--include-dependencies] [--source-environment NAME]
|
||||
|
||||
scadabridge bundle preview --input FILE --passphrase X
|
||||
|
||||
scadabridge bundle import --input FILE --passphrase X [--on-conflict skip|overwrite|rename]
|
||||
```
|
||||
|
||||
CLI commands route through `ManagementActor` handlers (`ExportBundleCommand`, `PreviewBundleCommand`, `ImportBundleCommand`), which delegate to the same `IBundleExporter` / `IBundleImporter` scoped services. Bundle bytes ride the existing `/management` JSON envelope as base64.
|
||||
|
||||
After import, template changes propagate to deployed instances through revision-hash drift detection in `DeploymentService.CompareAsync`. Transport does not write a stale marker — the existing Deployments page surfaces affected instances automatically.
|
||||
|
||||
## Configuration
|
||||
|
||||
`TransportOptions` is bound from the `ScadaBridge:Transport` section.
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
| `SourceEnvironment` | `"scadabridge"` | Environment label stamped in `manifest.json` and used in export filenames. |
|
||||
| `SchemaVersionMajor` | `1` | Maximum `bundleFormatVersion` this node accepts at import. |
|
||||
| `BundleSessionTtlMinutes` | `30` | TTL for an in-progress import session. |
|
||||
| `MaxBundleSizeMb` | `100` | Upload size cap; enforced before any decompression. |
|
||||
| `MaxBundleEntryCount` | `4` | Maximum ZIP entries (a valid bundle has exactly 2). |
|
||||
| `MaxBundleEntryDecompressedMb` | `200` | Per-entry decompressed size cap (ZIP-bomb defence). |
|
||||
| `MaxBundleEntryCompressionRatio` | `50` | Per-entry compression ratio cap (ZIP-bomb defence). |
|
||||
| `MaxUnlockAttemptsPerSession` | `3` | Per-bundle passphrase strike limit. |
|
||||
| `MaxUnlockAttemptsPerIpPerHour` | `10` | Per-IP trailing-hour unlock attempts. |
|
||||
| `Pbkdf2Iterations` | `600000` | PBKDF2-SHA256 iteration count for key derivation. |
|
||||
|
||||
`SourceEnvironment` should be set per environment (e.g., `dev-cluster`, `prod-cluster`) so the import wizard's confirmation gate works correctly.
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- [Commons (#16)](./Commons.md) — owns `BundleManifest`, `ExportSelection`, `ImportPreview`, `ImportResolution`, `ImportResult`, `BundleSession`, `EncryptionMetadata`, `BundleSummary`, `ManifestContentEntry`, `ConflictKind`, and the `IBundleExporter`, `IBundleImporter`, `IBundleSessionStore`, `IAuditCorrelationContext` interfaces. Transport implementations bind to these contracts; Commons defines nothing Transport-specific beyond the DTOs and interfaces.
|
||||
- [Configuration Database (#17)](./ConfigurationDatabase.md) — supplies all repository implementations (`ITemplateEngineRepository`, `IExternalSystemRepository`, `INotificationRepository`, `IInboundApiRepository`), `IAuditService` for per-entity audit rows, the `IAuditCorrelationContext` implementation (`AuditCorrelationContext`) registered as scoped, the `ScadaBridgeDbContext` used for the import transaction, and the EF migration that adds `BundleImportId uniqueidentifier NULL` (with index `IX_AuditLogEntries_BundleImportId`) to `AuditLogEntries`.
|
||||
- [Template Engine (#1)](./TemplateEngine.md) — provides `SemanticValidator`, invoked inside `ApplyAsync` before the transaction commits. The importer feeds each imported `TemplateDto` through the validator alongside the combined in-bundle + pre-existing `SharedScript` catalog; validation errors surface as `SemanticValidationException` and roll back the entire import.
|
||||
- [Audit Log / Configuration Audit](./AuditLog.md) — every export produces a `BundleExported` or `UnencryptedBundleExport` row; every import produces a `BundleImported` summary row (or `BundleImportFailed` on rollback). Per-entity rows written by `Apply*` helpers carry `BundleImportId` so operators can query all configuration changes from a single import as a group. `BundleImportUnlockFailed` rows are written on passphrase failures. Warning rows `BundleImportAlarmScriptUnresolved` and `BundleImportCompositionUnresolved` are written when second-pass FK rewire cannot resolve a name.
|
||||
- [Central UI](./CentralUI.md) — hosts the Export Bundle page under the Design nav group and the Import Bundle page under the Admin nav group; the import result page links to the Deployments page and to the filtered Configuration Audit Log Viewer pre-populated with the completed `BundleImportId`.
|
||||
- [Security & Auth (#10)](./Security.md) — enforces `RequireDesign` on export and `RequireAdmin` on import, both at the Razor page layer and inside the `IBundleExporter` / `IBundleImporter` service entrypoints (defense in depth).
|
||||
- [Deployment Manager (#2)](./DeploymentManager.md) — not directly called by Transport; template overwrites naturally change the flattened-config hash that `DeploymentService.CompareAsync` reads, causing affected instances to surface as stale on the Deployments page.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bundle upload rejected at format version check
|
||||
|
||||
`LoadAsync` throws `NotSupportedException` when `manifest.json` carries a `bundleFormatVersion` higher than `TransportOptions.SchemaVersionMajor`. The bundle was exported from a newer ScadaBridge version. Upgrade the target cluster or re-export from a compatible version.
|
||||
|
||||
### Content hash mismatch on upload
|
||||
|
||||
`LoadAsync` throws `InvalidDataException("Bundle content hash does not match manifest — file may be corrupt.")`. The ZIP was corrupted in transit. Compare the SHA-256 shown in the export wizard's Step 4 against the downloaded file and re-export if they differ.
|
||||
|
||||
### Session expired between diff and apply
|
||||
|
||||
`PreviewAsync` or `ApplyAsync` throws when the `BundleSession` is not found. The 30-minute TTL elapsed while the operator was reviewing the diff. Re-upload the bundle to start a new session.
|
||||
|
||||
### Apply rolls back with SemanticValidationException
|
||||
|
||||
A template's scripts reference a `SharedScript` or `ExternalSystem` that exists neither in the bundle nor in the target environment, or a type mismatch exists in a call argument. The exception lists per-template errors. Either re-export with the missing dependency included, or pre-create the missing artifact in the target environment before importing.
|
||||
|
||||
### Passphrase lockout
|
||||
|
||||
After 3 wrong passphrase attempts against the same bundle (keyed by `ContentHash`), `BundleImporter.LoadAsync` throws `BundleLockedException`. The session is unusable. Re-upload the bundle file to get a new session with a fresh counter. A `BundleImportUnlockFailed` audit row is written on each failed attempt.
|
||||
|
||||
### BundleImportAlarmScriptUnresolved / BundleImportCompositionUnresolved warnings
|
||||
|
||||
These audit rows appear when the second-pass rewire (`ResolveAlarmScriptLinksAsync` / `ResolveCompositionEdgesAsync`) cannot match a name to a persisted row. The import commits — the FK is left null / the composition row is skipped — but the warning signals an incomplete import. Re-examine the bundle's dependency graph and re-export with the missing artifacts included.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Transport design specification](../requirements/Component-Transport.md)
|
||||
- [Central UI](./CentralUI.md)
|
||||
- [Audit Log](./AuditLog.md)
|
||||
- [Template Engine](./TemplateEngine.md)
|
||||
- [Configuration Database](./ConfigurationDatabase.md)
|
||||
- [Commons](./Commons.md)
|
||||
- [Security](./Security.md)
|
||||
- [Deployment Manager](./DeploymentManager.md)
|
||||
@@ -0,0 +1,190 @@
|
||||
# Tree View
|
||||
|
||||
`TreeView<TItem>` is a generic, reusable Blazor Server component that renders any tree-shaped data as an expandable/collapsible hierarchy with ARIA roles, optional guide lines, single or checkbox selection, and session-persistent expansion state.
|
||||
|
||||
## Overview
|
||||
|
||||
The component lives at `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Shared/TreeView.razor` alongside its scoped stylesheet `TreeView.razor.css`. It is data-agnostic: the caller supplies the data source, a children accessor, a key function, and a `RenderFragment<TItem>` for node content — the component owns only the structural chrome (indentation, toggle, guide lines, ARIA attributes, selection highlight, context menu positioning).
|
||||
|
||||
Active uses within the Central UI:
|
||||
|
||||
- **Data Connections page** (`DataConnections.razor`) — two-level Site → Connection tree with a kebab action menu per node and search-based dimming.
|
||||
- **Topology page** (`Topology.razor`) — three-level Site → Area → Instance tree with inline rename, context menus, and `StorageKey = "topology-tree"` expansion persistence.
|
||||
- **`TemplateFolderTree`** (`TemplateFolderTree.razor`) — a domain-specific wrapper that projects `TemplateFolder` / `Template` entities into `TemplateTreeNode` items and delegates to `TreeView<TemplateTreeNode>`. Consumed by the Templates browser page (Single mode, click-to-navigate) and the Transport Export wizard (Checkbox mode, bulk template selection).
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Generic node typing
|
||||
|
||||
`@typeparam TItem` means the component imposes no node base class. The consumer brings its own model — a record, a class, an interface — and wires four `[EditorRequired]` delegates that teach the component how to navigate it. The `TemplateTreeNode` class in `Components/Shared/TemplateTreeNode.cs` is the shared adapter type for template/folder hierarchies; the Data Connections and Topology pages use local `record` types.
|
||||
|
||||
### Expansion state
|
||||
|
||||
Expanded-node keys are stored in `_expandedKeys` (`HashSet<string>`). Keys are stringified via `KeyStr(object) => key.ToString()!` for consistency with `sessionStorage`, which stores them as a JSON array when `StorageKey` is set. On first render the component reads `sessionStorage` via `treeviewStorage.load`; on every toggle it writes back via `treeviewStorage.save`. `InitiallyExpanded` applies only when no persisted state exists (or `StorageKey` is null). The two sources are always unioned — a `RevealNode` call before the async storage read completes is not clobbered.
|
||||
|
||||
### Selection modes
|
||||
|
||||
`TreeViewSelectionMode` (defined in `TreeViewSelectionMode.cs`) controls how nodes are selected:
|
||||
|
||||
```csharp
|
||||
public enum TreeViewSelectionMode
|
||||
{
|
||||
Single, // Default. Clicking node content fires SelectedKeyChanged with the node key.
|
||||
Checkbox, // Renders a tri-state checkbox per node. Folder check state is aggregated
|
||||
// from descendant leaves; only leaf keys enter SelectedKeys.
|
||||
}
|
||||
```
|
||||
|
||||
In `Single` mode the component uses `SelectedKey` / `SelectedKeyChanged` (two-way binding on a single `object?`). In `Checkbox` mode it uses `SelectedKeys` / `SelectedKeysChanged` (`HashSet<object>`). Checking a folder selects or deselects all of its descendant leaf keys. The `indeterminate` checkbox property is set via JS interop (`treeviewStorage.setIndeterminate`) after every render because Blazor does not bind `input.indeterminate` natively.
|
||||
|
||||
### Context menu
|
||||
|
||||
When `ContextMenu` is non-null, right-clicking any row suppresses the browser default and positions a Bootstrap `dropdown-menu show` div at the cursor coordinates using `position: fixed`. An invisible overlay behind the menu dismisses it on click-outside; Escape also dismisses it. The menu receives the `TItem` of the right-clicked node, so the consumer's fragment can branch on node type.
|
||||
|
||||
## Architecture
|
||||
|
||||
The component is a single `@typeparam` `.razor` file with a private `void RenderNode(TItem item, int depth)` local function that recurses the tree at render time — no intermediate view model is built inside the component. Every `<li>` carries `@key="key"` so Blazor can diff the list efficiently.
|
||||
|
||||
`IJSRuntime` is injected for two purposes: reading/writing `sessionStorage` for expansion persistence, and setting `input.indeterminate` for tri-state checkboxes. Both call sites guard `JSDisconnectedException` so a disconnected circuit never throws out of the lifecycle methods.
|
||||
|
||||
The public surface the caller can invoke via `@ref`:
|
||||
|
||||
```csharp
|
||||
public bool IsExpanded(object key); // Whether the given key is currently expanded.
|
||||
public void ExpandAll(); // Expand every branch node; persists if StorageKey set.
|
||||
public void CollapseAll(); // Collapse every node; clears persisted state.
|
||||
public async Task RevealNode(object key, bool select = false);
|
||||
// Expands all ancestors of the given key. Optionally selects the node.
|
||||
// No-op if the key does not exist in the current tree.
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The Data Connections page binds a two-level Site → Connection tree with `StorageKey`, single selection, and a context menu for Edit and Delete actions on connection nodes:
|
||||
|
||||
```razor
|
||||
<TreeView @ref="_tree" TItem="DcTreeNode" Items="_treeRoots"
|
||||
ChildrenSelector="n => n.Children"
|
||||
HasChildrenSelector="n => n.Children.Count > 0"
|
||||
KeySelector="n => (object)n.Key"
|
||||
StorageKey="data-connections-tree"
|
||||
Selectable="true"
|
||||
SelectedKey="_selectedKey"
|
||||
SelectedKeyChanged="OnTreeNodeSelected">
|
||||
<NodeContent Context="node">
|
||||
@if (node.Kind == DcNodeKind.Site)
|
||||
{
|
||||
<span class="tv-label fw-semibold">@node.Label</span>
|
||||
<span class="badge bg-secondary ms-1">@node.Children.Count</span>
|
||||
}
|
||||
else
|
||||
{
|
||||
<span class="tv-label">@node.Label</span>
|
||||
<span class="badge bg-info ms-2">@node.Connection!.Protocol</span>
|
||||
}
|
||||
</NodeContent>
|
||||
<ContextMenu Context="node">
|
||||
@if (node.Kind == DcNodeKind.DataConnection)
|
||||
{
|
||||
<button class="dropdown-item"
|
||||
@onclick='() => NavigationManager.NavigateTo($"/design/connections/{node.Connection!.Id}/edit")'>
|
||||
Edit
|
||||
</button>
|
||||
<div class="dropdown-divider"></div>
|
||||
<button class="dropdown-item text-danger"
|
||||
@onclick="() => DeleteConnection(node.Connection!)">
|
||||
Delete
|
||||
</button>
|
||||
}
|
||||
</ContextMenu>
|
||||
<EmptyContent>
|
||||
<span class="text-muted fst-italic">No sites configured.</span>
|
||||
</EmptyContent>
|
||||
</TreeView>
|
||||
|
||||
@code {
|
||||
record DcTreeNode(string Key, string Label, DcNodeKind Kind, List<DcTreeNode> Children,
|
||||
int? SiteId = null, DataConnection? Connection = null);
|
||||
enum DcNodeKind { Site, DataConnection }
|
||||
|
||||
private TreeView<DcTreeNode>? _tree;
|
||||
private object? _selectedKey;
|
||||
|
||||
private void OnTreeNodeSelected(object? key) => _selectedKey = key;
|
||||
}
|
||||
```
|
||||
|
||||
The `TemplateFolderTree` wrapper demonstrates `Checkbox` mode, where `SelectedKeys` / `SelectedKeysChanged` drive bulk template selection in the Transport Export wizard:
|
||||
|
||||
```razor
|
||||
<TreeView @ref="_tree" TItem="TemplateTreeNode"
|
||||
Items="_visibleRoots"
|
||||
ChildrenSelector="n => n.Children"
|
||||
HasChildrenSelector="n => n.Children.Count > 0"
|
||||
KeySelector="n => (object)n.Key"
|
||||
Selectable="@(SelectionMode == TreeViewSelectionMode.Single)"
|
||||
SelectionMode="SelectionMode"
|
||||
SelectedKeys="SelectedKeys"
|
||||
SelectedKeysChanged="SelectedKeysChanged"
|
||||
InitiallyExpanded="@(_initiallyExpanded)"
|
||||
StorageKey="@StorageKey">
|
||||
<NodeContent Context="node">
|
||||
<span class="tv-glyph"><i class="bi @(NodeGlyph(node))"></i></span>
|
||||
<span class="tv-label @(node.Children.Count > 0 ? "fw-semibold" : "")"
|
||||
title="@node.Name">@node.Name</span>
|
||||
</NodeContent>
|
||||
</TreeView>
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
All `[Parameter]` properties on `TreeView<TItem>`. Parameters marked **required** carry `[EditorRequired]` and must be supplied; omitting them produces a build warning.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `Items` | `IReadOnlyList<TItem>` | — | **Required.** Root-level nodes to render. |
|
||||
| `ChildrenSelector` | `Func<TItem, IReadOnlyList<TItem>>` | — | **Required.** Returns the ordered children of a node. |
|
||||
| `HasChildrenSelector` | `Func<TItem, bool>` | — | **Required.** Returns `true` for branch nodes. Determines whether the expand toggle is rendered. |
|
||||
| `KeySelector` | `Func<TItem, object>` | — | **Required.** Unique stable key per node. Used for expansion tracking, selection, and `@key` diffing. |
|
||||
| `NodeContent` | `RenderFragment<TItem>` | — | **Required.** Render fragment for node label content. Receives the `TItem`; responsible for all domain-specific markup (glyphs, labels, badges). |
|
||||
| `EmptyContent` | `RenderFragment?` | `null` | Shown when `Items` is empty or null. |
|
||||
| `ContextMenu` | `RenderFragment<TItem>?` | `null` | Right-click menu content. Receives the right-clicked node. If null, right-click is not intercepted. If the fragment renders nothing for a node type, the browser default is used. |
|
||||
| `IndentPx` | `int` | `24` | Pixels of left padding added per depth level via inline `style`. |
|
||||
| `ShowGuideLines` | `bool` | `true` | Adds `tv-guides` CSS class to the root `<ul>`, enabling the depth guide lines drawn by a `linear-gradient` pseudo-element in `TreeView.razor.css`. |
|
||||
| `InitiallyExpanded` | `Func<TItem, bool>?` | `null` | Predicate applied on first load (before storage is read) to expand matching nodes. Overridden by persisted state when `StorageKey` is set and storage contains prior data. |
|
||||
| `StorageKey` | `string?` | `null` | Browser `sessionStorage` key for expansion persistence (`treeview:{StorageKey}`). When null, expansion is in-memory only. |
|
||||
| `Selectable` | `bool` | `false` | Enables click-to-select on node content. Clicking the expand toggle never changes selection. |
|
||||
| `SelectedKey` | `object?` | `null` | Currently selected node key for `Single` mode. Supports two-way binding (`@bind-SelectedKey`). |
|
||||
| `SelectedKeyChanged` | `EventCallback<object?>` | — | Fires when selection changes in `Single` mode. Also fires on `RevealNode(..., select: true)`. Fires with `null` when the selected key disappears from the tree. |
|
||||
| `SelectedCssClass` | `string` | `"bg-primary bg-opacity-10"` | CSS class(es) applied to the selected node's row div in addition to `tv-selected`. |
|
||||
| `SelectionMode` | `TreeViewSelectionMode` | `Single` | Switches between single-key selection and tri-state checkbox selection. |
|
||||
| `SelectedKeys` | `HashSet<object>?` | `null` | Set of currently selected leaf keys for `Checkbox` mode. |
|
||||
| `SelectedKeysChanged` | `EventCallback<HashSet<object>>` | — | Fires with the updated set when any checkbox is toggled in `Checkbox` mode. Always fires with a fresh `HashSet` reference. |
|
||||
|
||||
### CSS utility classes in `NodeContent`
|
||||
|
||||
The scoped stylesheet defines layout slots that `NodeContent` fragments should use for consistent alignment:
|
||||
|
||||
| Class | Purpose |
|
||||
|---|---|
|
||||
| `tv-glyph` | 20 px flex slot for a Bootstrap Icon (`<i class="bi bi-…">`). |
|
||||
| `tv-label` | `flex: 1 1 auto; min-width: 0` — primary text with ellipsis overflow. |
|
||||
| `tv-meta` | `margin-left: auto` — right-aligned badges or trailing controls. |
|
||||
| `tv-kebab` | Opt-in hidden-by-default "more actions" slot; revealed on row hover. |
|
||||
|
||||
## Dependencies & Interactions
|
||||
|
||||
- **Bootstrap 5** — all state visuals use Bootstrap utility classes and CSS variables (`--bs-tertiary-bg`, `--bs-border-color`, `--bs-primary-rgb`). No third-party Blazor component frameworks.
|
||||
- **Bootstrap Icons** — static files served from `wwwroot/lib/bootstrap-icons/`; referenced once in `MainLayout.razor`. `NodeContent` fragments use `<i class="bi bi-…">` inside the `tv-glyph` slot.
|
||||
- **`IJSRuntime`** — injected for `treeviewStorage.load` / `treeviewStorage.save` (expansion persistence) and `treeviewStorage.setIndeterminate` (checkbox tri-state). The JS helpers live in the CentralUI's shared JS bundle.
|
||||
- **`TemplateFolderTree`** (`Components/Shared/TemplateFolderTree.razor`) — a domain-specific wrapper around `TreeView<TemplateTreeNode>` that handles folder/template tree construction, text filtering, and `ExtraTemplateChildren` injection. Consumers that need the template hierarchy use `TemplateFolderTree`; they do not wire `TreeView<TemplateTreeNode>` directly.
|
||||
- **`TemplateTreeNode` / `TemplateTreeNodeKind`** (`Components/Shared/TemplateTreeNode.cs`) — the shared node model used by `TemplateFolderTree` and its callers. Folder keys are prefixed `f:`, template keys `t:`, composition keys `c:`.
|
||||
- **Data Connections page** (`Components/Pages/Design/DataConnections.razor`) — binds `TreeView<DcTreeNode>` directly with a local two-level record type.
|
||||
- **Topology page** (`Components/Pages/Deployment/Topology.razor`) — binds `TreeView` for the Site → Area → Instance hierarchy; calls `ExpandAll`, `CollapseAll`, and `RevealNode` via `@ref`.
|
||||
- **Central UI component** — see [./CentralUI.md](./CentralUI.md) for the broader Blazor Server application context.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Tree View design specification](../requirements/Component-TreeView.md)
|
||||
- [Central UI](./CentralUI.md)
|
||||
- [Template Engine](./TemplateEngine.md)
|
||||
Reference in New Issue
Block a user