1689901c0e
Four new docs at docs/v2/ giving a single-page tour of each v2 piece: - Architecture-v2.md: top-level mental model (fused Host + roles + cluster + live-edit) - Cluster.md: AkkaClusterOptions + IClusterRoleInfo + WithOtOpcUaClusterBootstrap - ControlPlane.md: 5 admin singletons + DPS topics + deploy flow + failover recovery - Runtime.md: per-node actor tree + state machines + engine-wiring follow-up map Each links back to the design doc for depth. Architecture-v2 cross-references the other three + ServiceHosting + Redundancy + security.
127 lines
6.6 KiB
Markdown
127 lines
6.6 KiB
Markdown
# OtOpcUa.Runtime
|
|
|
|
Driver-role actor tree — one set per node. Path: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/`.
|
|
|
|
## Actor tree
|
|
|
|
```
|
|
DriverHostActor (per node)
|
|
│ state machine: Steady ⇄ Applying ⇄ Stale
|
|
│
|
|
├──▶ DriverInstanceActor (per configured DriverInstance row)
|
|
│ state: Connecting → Connected → Reconnecting (or Stubbed)
|
|
│
|
|
├──▶ VirtualTagActor (per VirtualTag row)
|
|
│ compiles + evaluates expression, publishes derived value
|
|
│
|
|
├──▶ ScriptedAlarmActor (per ScriptedAlarm row)
|
|
│ state: Inactive ⇄ Active ⇄ Acknowledged
|
|
│
|
|
├──▶ OpcUaPublishActor (per node, pinned dispatcher)
|
|
│ marshalled OPC UA SDK writes + RebuildAddressSpace
|
|
│
|
|
├──▶ HistorianAdapterActor (per node)
|
|
│ pipe IPC to Wonderware historian sidecar
|
|
│
|
|
├──▶ PeerOpcUaProbeActor (per peer node)
|
|
│ opc.tcp ping → redundancy-state DPS topic
|
|
│
|
|
└──▶ DbHealthProbeActor (per node)
|
|
cached SELECT 1; consumed by /health/ready + redundancy calc
|
|
```
|
|
|
|
## Public surface
|
|
|
|
| Type | File |
|
|
|---|---|
|
|
| `WithOtOpcUaRuntimeActors()` | `ServiceCollectionExtensions.cs` — extension on `AkkaConfigurationBuilder`. Spawns `DriverHostActor` + `DbHealthProbeActor` on the host's ActorSystem. |
|
|
| `DriverHostActor` | `Drivers/DriverHostActor.cs` |
|
|
| `DriverInstanceActor` | `Drivers/DriverInstanceActor.cs` |
|
|
| `VirtualTagActor` | `VirtualTags/VirtualTagActor.cs` |
|
|
| `ScriptedAlarmActor` | `ScriptedAlarms/ScriptedAlarmActor.cs` |
|
|
| `OpcUaPublishActor` | `OpcUa/OpcUaPublishActor.cs` |
|
|
| `HistorianAdapterActor` | `Historian/HistorianAdapterActor.cs` |
|
|
| `PeerOpcUaProbeActor` | `Health/PeerOpcUaProbeActor.cs` |
|
|
| `DbHealthProbeActor` | `Health/DbHealthProbeActor.cs` |
|
|
|
|
Marker keys for registry lookup: `DriverHostActorKey`, `DbHealthProbeActorKey`.
|
|
|
|
## DriverHostActor
|
|
|
|
Per-node supervisor with three Become states:
|
|
|
|
| State | Meaning |
|
|
|---|---|
|
|
| `Steady(rev)` | Caught up. `DispatchDeployment` with `msg.rev == currentRev` → immediate `ApplyAck(Applied)` (idempotent). New rev → `Become(Applying)`. |
|
|
| `Applying(id)` | Apply in progress. Further `DispatchDeployment` for in-flight ID → debug-log + ignore. For new ID → defer via `Self.Forward`. |
|
|
| `Stale` | ConfigDb unreachable on bootstrap. Periodic `RetryConfigDbConnection` tries to advance to `Steady`. |
|
|
|
|
`PreStart`:
|
|
|
|
1. Subscribe to `deployments` DPS topic.
|
|
2. Read most-recent `NodeDeploymentState` for this node from ConfigDb.
|
|
3. If `Applied` → restore `_currentRevision`, `Become(Steady)`.
|
|
4. If `Applying` (orphan from crash) → replay apply (idempotent).
|
|
5. If `Failed` → `Become(Steady)` at last known rev.
|
|
6. DB unreachable → `Become(Stale)`, start retry timer.
|
|
|
|
ACK publishing: when no `_coordinatorOverride` is set (production), `SendAck` publishes on the dedicated `deployment-acks` DPS topic which the coordinator subscribes to (commit `5cfbe8b`).
|
|
|
|
## DriverInstanceActor
|
|
|
|
Per-driver-instance child. State machine:
|
|
|
|
- `Connecting` → first attempt to reach the underlying driver
|
|
- `Connected` → subscriptions active, reads/writes flow
|
|
- `Reconnecting` → temporary disconnect; backoff retry
|
|
- `Stubbed` → DEV-STUB mode for Windows-only drivers (Galaxy, Wonderware Historian) on non-Windows or when `roles` contains `dev`
|
|
|
|
`ShouldStub(driverType, roles)` returns `true` for `"Galaxy" | "Historian.Wonderware"` on non-Windows; the actor goes straight to `Stubbed` and returns deterministic success without touching real hardware. Wiring this into the DriverHost child-spawn path is follow-up F20 (folds into F7).
|
|
|
|
Engine wiring (subscription publishing, ApplyDelta diff, bad-quality-on-disconnect, write path, supervisor backoff) is stubbed — tracked as F7. Tests exercise message contracts, not engine behaviour.
|
|
|
|
## VirtualTagActor / ScriptedAlarmActor
|
|
|
|
Skeleton state machines + message handlers. Engine work:
|
|
|
|
- `VirtualTagEngine.Evaluate()` not yet called from `VirtualTagActor.DependencyValueChanged` (F8).
|
|
- `AlarmConditionService` not yet called from `ScriptedAlarmActor` (F9).
|
|
- `ScriptedAlarmState` DB persistence on `PreRestart` not wired (F9).
|
|
|
|
## OpcUaPublishActor
|
|
|
|
The only actor on the **pinned dispatcher** (`opcua-synchronized-dispatcher` from `akka.conf`). All OPC UA SDK address-space writes go through it so the SDK's threading model isn't violated.
|
|
|
|
Message contracts are defined; actual SDK calls are stubbed (counters only). Real address-space writes + `ServiceLevel` Variable updates + `RebuildAddressSpace` after a deploy land in F10 (gated on F13 — full `OpcUaApplicationHost` extraction).
|
|
|
|
## HistorianAdapterActor, PeerOpcUaProbeActor
|
|
|
|
Both have message contracts wired. Engine integration deferred:
|
|
|
|
- `HistorianAdapterActor` — named-pipe IPC to the Wonderware historian sidecar + `SqliteStoreAndForwardSink` (F11).
|
|
- `PeerOpcUaProbeActor` — real `opc.tcp://peer:4840` ping (F12). Current stub always returns `Ok=true`.
|
|
|
|
## DbHealthProbeActor
|
|
|
|
`Ask<DbHealthStatus>` returns cached state (refreshed every 5 s by an internal `SELECT 1`). Consumed by `/health/ready` and `RedundancyStateActor`.
|
|
|
|
## Lifecycle wiring
|
|
|
|
```csharp
|
|
// Program.cs (driver role only)
|
|
builder.Services.AddAkka("otopcua", (ab, sp) =>
|
|
{
|
|
ab.WithOtOpcUaClusterBootstrap(sp);
|
|
if (hasAdmin) ab.WithOtOpcUaControlPlaneSingletons();
|
|
if (hasDriver) ab.WithOtOpcUaRuntimeActors();
|
|
});
|
|
```
|
|
|
|
`WithOtOpcUaRuntimeActors` resolves `IDbContextFactory<OtOpcUaConfigDbContext>` + `IClusterRoleInfo` from DI, then spawns `DbHealthProbeActor` and `DriverHostActor` as top-level `/user/` actors. Both register marker keys in `ActorRegistry` so the registry lookup works from anywhere.
|
|
|
|
## Tests
|
|
|
|
`tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/` — 16 tests covering DriverHostActor (Steady ack, Applying transitions, Stale recovery), DriverInstanceActor (state machine, stub mode), VirtualTagActor + ScriptedAlarmActor (message contracts), OpcUaPublishActor (props + message acceptance), DbHealthProbe + PeerOpcUaProbe (probe loop), and the `WithOtOpcUaRuntimeActors` registration round-trip.
|
|
|
|
End-to-end deploy from admin → driver via the cluster is in `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/DeployHappyPathTests.cs`.
|