Joseph Doherty
1a6108c402
A graceful stop of a site node whose peer holds an open LocalDb sync stream left the Akka cluster ~30 s late (the ScadaBridge half of lmxopcua#906, scadaproj#57). WebApplication stops the web server before AkkaHostedService, whose StopAsync ran CoordinatedShutdown, and Kestrel's graceful drain waited the whole ShutdownTimeout for /localdb_sync.v1.LocalDbSync/Sync: LocalDb 0.3.7 observes only the call token, which Kestrel cancels at the END of the drain. CancelAllStreams only covered SiteStreamGrpcServer's own streams. - AkkaHostedService is now an IHostedLifecycleService. StoppingAsync runs before any hosted service's StopAsync (Kestrel's included): marks the stop intentional, raises ApplicationStopping (so CancelAllStreams still precedes actor teardown), then runs and awaits CoordinatedShutdown(ClrExitReason), bounded by the host shutdown token. StopAsync returns the same completed shutdown. Exit codes unchanged: planned stop exits 0; only a termination outside host shutdown (self-down / #132 shut-out) exits 75. No Akka.Hosting here, so no ClusterLeavingReason/-1 exit-code path is involved. - ShutdownStreamCancellationInterceptor, innermost on both the central and the site AddGrpc pipelines: every streaming call's token is linked with ApplicationStopping; new streams are refused Unavailable while stopping. Covers the LocalDb sync stream until LocalDb 0.3.8 is pinned. Evidence (IntegrationTests/GracefulStopWithOpenSyncStreamTests: real WebApplication + Kestrel h2c + MapZbLocalDbSync behind LocalDbSyncAuthInterceptor + a real LocalDb SyncBackgroundService peer + the production AkkaHostedService forming a single-member cluster, 8 s drain budget, IServer wrapped to timestamp the drain): before 8859 ms stop, member removed at 8834 ms, drain began at 0 ms; after 960 ms stop, member removed at 950 ms, drain began at 959 ms. Mutations (all killed): StoppingAsync skips CoordinatedShutdown; interceptor passes the original context (stop 8003 ms); no Unavailable refusal; StoppingAsync does not raise ApplicationStopping; lifecycle interface dropped; site pipeline loses the interceptor. Release build of the solution: 0 warnings. Host.Tests 733/733, IntegrationTests 133/133, Communication.Tests 843/843. Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
Component Reference Documentation
Developer-reference docs for each ScadaBridge component, describing how the shipped
code in src/ actually works — with real code examples. These complement the
design specs in docs/requirements/: the specs say what a
component should do and why; these docs say how the code does it.
Reference docs exist for all 27 components (plus the shared TreeView, listed below).
| # | Component | Description |
|---|---|---|
| 1 | Template Engine | Template modeling, inheritance, composition, flattening, diffs, and semantic validation as implemented by the engine's services. |
| 2 | Deployment Manager | The central deployment pipeline: deployment identity and idempotency, per-instance operation locks, state transitions, all-or-nothing site apply, and artifact deployment. |
| 3 | Site Runtime | The site actor hierarchy (Deployment Manager singleton, Instance, Script, and Alarm actors), script compilation and execution, the site-wide stream, native alarms, and supervision. |
| 4 | Data Connection Layer | Protocol adapters (OPC UA, MxGateway), the Become/Stash connection state machine, reconnect and re-subscribe, and the native-alarm subscription seam. |
| 5 | Central–Site Communication | ClusterClient command and control plus gRPC server-streaming, the central and site communication actors, receptionist registration, and per-site contact points. |
| 6 | Store-and-Forward Engine | Site-only buffering, fixed-interval retry, parking, SQLite persistence, standby replication, and the operation-tracking store. |
| 7 | External System Gateway | Script-facing HTTP/REST and database access, the Call and CachedCall modes, and transient versus permanent error classification. |
| 8 | Notification Service | Central notification-list and SMTP definitions, the per-type delivery adapters, and OAuth2 or Basic SMTP delivery. |
| 9 | Central UI | The Blazor Server app structure, authentication, real-time updates (SignalR and gRPC), and the management pages. |
| 10 | Security & Auth | LDAP bind authentication, cookie and JWT sessions, role-based and site-scoped authorization, and shared Data Protection keys. |
| 11 | Health Monitoring | Site metric collection and central aggregation, report and heartbeat intervals, offline detection, and dead-letter monitoring. |
| 12 | Site Event Logging | The site-local SQLite event log, retention and storage cap, daily purge, and paginated central query access. |
| 13 | Cluster Infrastructure | The ClusterOptions model and validation for active/standby clustering, split-brain resolution, and failover. |
| 14 | Inbound API | POST /api/{method} script invocation, API-key authentication, the extended type system, and inbound-request auditing. |
| 15 | Host | The deployable binary: role-based component registration, Akka bootstrap, ASP.NET Core hosting, and the readiness and active-node health endpoints. |
| 16 | Commons | Shared POCO entities, repository and service interfaces, message contracts, and the Types/Interfaces/Entities/Messages namespace layout. |
| 17 | Configuration Database | The EF Core DbContext, repository implementations, the audit service, secret encryption, and migration and partition maintenance. |
| 18 | Management Service | The ManagementActor admin command surface, its HTTP endpoints, and ClusterClientReceptionist registration. |
| 19 | CLI | The System.CommandLine tool over the HTTP Management API — its command groups, config file, and output formats. |
| 20 | Traefik Proxy | The reverse proxy fronting the central cluster, active-node routing via /health/active, and the Docker topology configuration. |
| 21 | Notification Outbox | The central NotificationOutboxActor, the Notifications table, the dispatcher loop, retry and parking, and KPIs. |
| 22 | Site Call Audit | The central SiteCallAuditActor, the SiteCalls mirror table, telemetry ingest, and the parked-call Retry/Discard relay. |
| 23 | Audit Log | The append-only audit store: site SQLite hot-path, gRPC telemetry, central ingest and reconciliation, redaction, retention, and KPIs. |
| 24 | Transport | Encrypted bundle export and import, dependency resolution, conflict detection, and BundleImportId-correlated audit. |
| 25 | Script Analysis | The script trust model and validator, the diagnostics-only compile gate, the blocking-wait advisory, and the static flow-shape predictor. |
| 26 | KPI History | The central KpiHistoryRecorderActor singleton: KPI sampling, hourly rollups and backfill, and retention purge. |
| 27 | Delmia Notifier | The WWNotifier console client DELMIA shells out to, its YES/NO contract, and pre-execution-only failover. |
| 28 | Tree View | The reusable Blazor tree component — parameters, selection modes, and usage in the Central UI. |
Related Documentation
- Component design specs — the spec each component implements.
- Documentation Style Guide — the writing conventions these docs follow.
- README — the repository master index.