Joseph Doherty
cbb882293b
The tier system was documented, operator-authorable, and inert. Deleted rather than activated,
because its premise is gone rather than merely unused.
"Tier C" meant a driver running out-of-process behind an IDriverSupervisor that could restart its
Host without tearing down the OPC UA session. No such process exists anywhere: Galaxy reaches
MXAccess over gRPC to the external mxaccessgw sidecar (PR 7.2 retired the in-process
Galaxy.Host/Proxy/Shared projects) and FOCAS has run in-process since its managed wire client
landed 2026-04-24. Consistently, IDriverSupervisor had ZERO implementations and there was nothing
for one to implement against.
The issue understated the inertness. It says the Tier-C-only protections never engaged, implying
the Tier A/B parts did. They did not: nothing constructs MemoryTracking, MemoryRecycle or
ScheduledRecycleScheduler outside their own unit tests, so the whole Core/Stability recycle layer
was dead — meaning option (a), "pass real tiers", was never a flag flip. It would have meant
writing the wiring that never existed AND arming it.
Deleted: MemoryTracking, MemoryRecycle, ScheduledRecycleScheduler, IDriverSupervisor, the
vestigial DriverTypeRegistry (referenced only by its own tests), and the RecycleIntervalSeconds
knob — which the AdminUI let an operator author and the parser validated while it configured
nothing.
DriverTier itself SURVIVES and is load-bearing: DriverResilienceOptions.GetTierDefaults supplies
the real per-capability timeout/retry/breaker policies via DriverFactoryRegistry.GetTier and
DriverCapabilityInvokerFactory. Only the isolation-and-recycle layer above it is gone.
Deliberately NOT deleted:
- WedgeDetector came along in the same directory and is equally dead in production, but it is
tier-agnostic and is not recycle machinery — it only shares the folder. Restored rather than
swept up in a decision that was not about it.
- IDriver.GetMemoryFootprint() and FlushOptionalCachesAsync() lose their only consumer here.
Removing them touches all 12 drivers and every test stub, so they are documented as
consumerless and filed as #525 instead of buried in this diff.
Compatibility: a deployed ResilienceConfig blob still carrying "recycleIntervalSeconds" parses
cleanly (unknown keys are ignored — guarded by a new test, because a blob that suddenly failed to
parse would fall back to tier defaults and silently discard the operator's real overrides), and
the AdminUI's preserve-unknown-keys bag keeps the key rather than rewriting stored config on an
unrelated edit.
The 01/U-6 knob-inertness guard carried an explicit carve-out admitting RecycleIntervalSeconds was
dormant and out of scope; that carve-out is now gone, so the expected set is literally what the
test's name claims.
Note: Host.IntegrationTests has 2 failures (DriverProbeRegistrationTests.is_idempotent,
PrimaryGateFailoverTests) — verified pre-existing by reproducing both on clean master dc9d947b.
Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
13 KiB
OPC UA Server
⚠️ Correction (2026-07-28):
GenericDriverNodeManageris NOT a production dispatch path. It is test scaffolding — its own source says so (Core/OpcUa/GenericDriverNodeManager.cs:71, "verified 07/#10: zero production references"). The production chain isOpcUaPublishActor→IOpcUaAddressSpaceSink(SdkAddressSpaceSink) →OtOpcUaNodeManager, materialising the two v3 namespaces (.../rawand.../uns). Sections below that describe per-node dispatch, rediscovery re-walks, or alarm-sink capture through that class describe a design, not the running server. The same correction is already carried byAddressSpace.mdandIncrementalSync.md; this file was missed in that pass.
The OPC UA server component (src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/) hosts the OPC UA stack and exposes a browsable address space built from the registered drivers. The server itself is driver-agnostic — Galaxy/MXAccess, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client are all plugged in as IDriver implementations via the capability interfaces in src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/.
In v2 the Server and Admin processes were fused into a single role-gated ZB.MOM.WW.OtOpcUa.Host binary. Which subsystems start (OPC UA endpoint, Admin UI, control plane, driver runtime) is decided by the OTOPCUA_ROLES gate, not by running separate executables. See docs/ServiceHosting.md for the role model.
Composition
OtOpcUaSdkServer (src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs) subclasses the OPC Foundation StandardServer and wires a single custom node manager:
CreateMasterNodeManagerconstructs oneOtOpcUaNodeManager(src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs) — aCustomNodeManager2subclass that owns the writable address space under the namespacehttps://zb.com/otopcua/nsand a singleOtOpcUaroot folder organized under the standardObjectsfolder. It is wrapped in aMasterNodeManagerwith no additional core managers.OtOpcUaSdkServer.NodeManagerexposes the live node manager afterStartAsync, so the hosting layer can wrap it in aSdkAddressSpaceSink(src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkAddressSpaceSink.cs) and hand it toOpcUaPublishActor.
Address-space population is push-driven: drivers stream discovery and data-change events through the Akka actor system (DriverInstanceActor → OpcUaPublishActor), and OpcUaPublishActor writes them into the node manager through the IOpcUaAddressSpaceSink seam. OtOpcUaNodeManager.EnsureFolder / EnsureVariable materialize the UNS folder + variable hierarchy; WriteValue / WriteAlarmCondition push runtime values and fire ClearChangeMasks so subscribed clients see updates.
The driver-agnostic walk that turns a driver's discovery into folder/variable calls lives in GenericDriverNodeManager (src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs): it walks ITagDiscovery.DiscoverAsync into an IAddressSpaceBuilder, captures alarm-condition sinks for variables flagged via IVariableHandle.MarkAsAlarmCondition, subscribes to IAlarmSource.OnAlarmEvent, and routes each alarm transition to the sink registered for its SourceNodeId.
The lifecycle facade OpcUaApplicationHost (src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs) owns the ApplicationInstance + ApplicationConfiguration lifetime, starts the StandardServer, and attaches the ImpersonateUser hook (see Session impersonation).
Resilience and capability dispatch
Driver-capability calls (IReadable.ReadAsync, IWritable.WriteAsync, ITagDiscovery.DiscoverAsync, ISubscribable.SubscribeAsync/UnsubscribeAsync, the IHostConnectivityProbe probe loop, IAlarmSource surfaces, and the four IHistoryProvider reads) are routed through a CapabilityInvoker (src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs) so the Polly resilience pipeline (retry / timeout / breaker) applies. There is one invoker per (DriverInstance, IDriver) pair; all invokers share the process-singleton DriverResiliencePipelineBuilder, which keys pipelines on (DriverInstanceId, hostName, DriverCapability). Per-instance resilience options come from the driver's tier — the DriverTier passed at factory registration, resolved via DriverFactoryRegistry.GetTier (every driver is Tier A today, since no factory passes one) — plus per-instance JSON overrides parsed from DriverInstance.ResilienceConfig by DriverResilienceOptionsParser. (It was never DriverTypeRegistry; that class was vestigial and was deleted in Gitea #522.)
The OTOPCUA0001 Roslyn analyzer (src/Tooling/ZB.MOM.WW.OtOpcUa.Analyzers/UnwrappedCapabilityCallAnalyzer.cs, category OtOpcUa.Resilience, severity Warning) flags direct driver-capability calls that bypass the invoker.
| Capability | Surface | Invoker entry point |
|---|---|---|
| Read | IReadable.ReadAsync |
ExecuteAsync(DriverCapability.Read, host, …) |
| Write | IWritable.WriteAsync |
ExecuteWriteAsync(host, isIdempotent, …) — disables retries for non-idempotent writes per WriteIdempotentAttribute / decisions #44-45, #143 |
| Discovery | ITagDiscovery.DiscoverAsync |
ExecuteAsync(DriverCapability.Discover, host, …) |
| Subscribe / Unsubscribe | ISubscribable.SubscribeAsync/UnsubscribeAsync |
ExecuteAsync(DriverCapability.Subscribe, host, …) |
| HistoryRead (raw / processed / at-time / events) | IHistoryProvider.*Async |
ExecuteAsync(DriverCapability.HistoryRead, host, …) |
| Alarm subscribe / unsubscribe / acknowledge | IAlarmSource.SubscribeAlarmsAsync/UnsubscribeAlarmsAsync/AcknowledgeAsync |
via AlarmSurfaceInvoker (src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/AlarmSurfaceInvoker.cs), which fans out per host |
The host name fed to the invoker comes from IPerCallHostResolver.ResolveHost(fullReference) when the driver implements it (multi-host drivers: AB CIP, Modbus, FOCAS, TwinCAT, AB Legacy resolve per device). Single-host drivers fall back to DriverInstanceId, preserving the per-instance pipeline-key semantics (decision #144).
Configuration
Tenant-scoped server wiring flows from the SQL Server Config DB, not from appsettings.json: ServerInstance + DriverInstance + Tag + NodeAcl rows are published as a generation by sp_PublishGeneration and loaded into the running process by the generation applier. The Admin UI (Blazor Server, docs/v2/admin-ui.md) is the operator surface — drafts accumulate edits and sp_ComputeGenerationDiff drives the DiffViewer preview before publish. Optimistic concurrency uses each entity's RowVersion; a stale edit fails the publish/save rather than silently overwriting. See docs/v2/config-db-schema.md for the schema.
Environmental knobs that aren't per-tenant — bind address, port, PKI store root, security profiles — are supplied to OpcUaApplicationHostOptions and resolved from appsettings.json on the Host project.
Transport
The server binds a TCP endpoint at opc.tcp://{PublicHostname}:{OpcUaPort}/OtOpcUa (defaults 0.0.0.0:4840). The ApplicationConfiguration is built programmatically in OpcUaApplicationHost.BuildConfigurationAsync — there are no UA XML files unless ApplicationConfigPath is set. Security profiles are listed in OpcUaApplicationHostOptions.EnabledSecurityProfiles; by default all three baseline profiles are exposed (None, Basic256Sha256 + Sign, Basic256Sha256 + SignAndEncrypt) and the SDK publishes one endpoint descriptor per profile. Production deployments typically drop None. User token policies (Anonymous, UserName) are always attached; the UserName policy is SDK-encrypted with the server certificate so it works on None endpoints too. See docs/security.md for hardening.
Session impersonation
OpcUaApplicationHost subscribes to SessionManager.ImpersonateUser after ApplicationInstance.Start. The handler (HandleImpersonation) deals with the token types as follows:
UserNameIdentityToken→ the password is decrypted, thenIOpcUaUserAuthenticator.AuthenticateUserNameAsyncvalidates the credential (LdapOpcUaUserAuthenticatorin production, a stub in tests). On success aUserIdentitycarrying the token is attached and the LDAP-derived roles are logged; on failureImpersonateEventArgs.IdentityValidationErroris set toBadIdentityTokenRejected.AnonymousIdentityTokenand X.509 tokens → the handler returns without intervening, so the SDK's default validation stands.
Decryption failures and authenticator exceptions also map to BadIdentityTokenRejected.
Authorization
Node-level authorization is backed by a permission trie under src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/ (PermissionTrie, PermissionTrieBuilder, PermissionTrieCache, TriePermissionEvaluator, NodeScope, UserAuthorizationState, AuthorizationDecision). The trie is built from NodeAcl rows and a session's UserAuthorizationState, and an IPermissionEvaluator can return a per-tag AuthorizationDecision for Read / HistoryRead / Write / Browse independently. See docs/v2/acl-design.md.
Redundancy
Redundancy.Enabled = true on the ServerInstance activates the RedundancyStateActor + ServiceLevelCalculator (src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/Redundancy/). The OPC UA Server/ServiceLevel node (VariableIds.Server_ServiceLevel) is recomputed and republished via SdkServiceLevelPublisher (src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkServiceLevelPublisher.cs, wired as IServiceLevelPublisher) whenever role or driver-health changes; ServiceLevelCalculator produces a 0–255 value where higher means more authoritative, so the primary advertises a higher ServiceLevel than the secondary. Clients also read the standard Server/ServerRedundancy/RedundancySupport and Server/ServerRedundancy/ServerUriArray properties the SDK exposes on the ServerObject. An apply-lease prevents two instances from concurrently applying a generation. See docs/Redundancy.md.
Peer endpoints are advertised through the standard Server.ServerArray property: OpcUaApplicationHost appends OpcUaApplicationHostOptions.PeerApplicationUris to IServerInternal.ServerUris after start so warm-redundancy clients can discover the partner.
Server class hierarchy
OtOpcUaSdkServer extends StandardServer
CreateMasterNodeManager— Constructs the singleOtOpcUaNodeManagerand wraps it in aMasterNodeManagerwith no extra core managers.NodeManager— Public accessor exposing the liveOtOpcUaNodeManageronce the SDK has bootstrapped (null untilCreateMasterNodeManagerruns).
ApplicationName, ApplicationUri (urn:OtOpcUa), and ProductUri (https://zb.com/otopcua) come from OpcUaApplicationHostOptions, which the ApplicationConfiguration is built from in OpcUaApplicationHost.
Certificate handling
Certificate stores are directory-based under OpcUaApplicationHostOptions.PkiStoreRoot (default pki, relative to the host's working directory):
| Store | Path suffix |
|---|---|
| Own (application certificate) | pki/own |
| Trusted issuers | pki/issuer |
| Trusted peers | pki/trusted |
| Rejected | pki/rejected |
OpcUaApplicationHostOptions.AutoAcceptUntrustedClientCertificates (default false) controls whether unknown client certificates are auto-trusted on first connection; production deployments leave it off and operators promote peers via the Admin UI. The application instance certificate is auto-created (SDK defaults: 2048-bit, 12-month lifetime) on first start against a fresh PKI tree, and the server certificate is always created — even for None-only deployments — because UserName token encryption needs it.
Key source files
src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs—StandardServersubclass wiring the single node managersrc/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs— programmaticApplicationConfiguration+ lifecycle +ImpersonateUserhook + ServerArray populationsrc/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs—CustomNodeManager2owning the writable address spacesrc/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkAddressSpaceSink.cs—IOpcUaAddressSpaceSinkadapter the actor system pushes intosrc/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkServiceLevelPublisher.cs— publishes the redundancyServiceLevelnodesrc/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs— driver-agnostic discovery walk + alarm routingsrc/Core/ZB.MOM.WW.OtOpcUa.Core/Hosting/DriverHost.cs— process-local driver registration + lifecyclesrc/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs— Polly pipeline entry point for capability callssrc/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/AlarmSurfaceInvoker.cs— per-host fan-out wrapper forIAlarmSourcesrc/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/— permission trie + evaluator (PermissionTrie,PermissionTrieCache,TriePermissionEvaluator)