chore: organize solution into module folders (Core/Server/Drivers/Client/Tooling)
Group all 69 projects into category subfolders under src/ and tests/ so the Rider Solution Explorer mirrors the module structure. Folders: Core, Server, Drivers (with a nested Driver CLIs subfolder), Client, Tooling. - Move every project folder on disk with git mv (history preserved as renames). - Recompute relative paths in 57 .csproj files: cross-category ProjectReferences, the lib/ HintPath+None refs in Driver.Historian.Wonderware, and the external mxaccessgw refs in Driver.Galaxy and its test project. - Rebuild ZB.MOM.WW.OtOpcUa.slnx with nested solution folders. - Re-prefix project paths in functional scripts (e2e, compliance, smoke SQL, integration, install). Build green (0 errors); unit tests pass. Docs left for a separate pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,84 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Persistent per-alarm state tracked by the Part 9 state machine. Every field
|
||||
/// carried here either participates in the state machine or contributes to the
|
||||
/// audit trail required by Phase 7 plan decision #14 (GxP / 21 CFR Part 11).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <see cref="Active"/> is re-derived from the predicate at startup per Phase 7
|
||||
/// decision #14 — the engine runs every alarm's predicate against current tag
|
||||
/// values at <c>Load</c>, overriding whatever Active state is in the store.
|
||||
/// Every other state field persists verbatim across server restarts so
|
||||
/// operators don't re-ack active alarms after an outage + shelved alarms stay
|
||||
/// shelved + audit history survives.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <see cref="Comments"/> is append-only; comments + ack/confirm user identities
|
||||
/// are the audit surface regulators consume. The engine never rewrites past
|
||||
/// entries.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed record AlarmConditionState(
|
||||
string AlarmId,
|
||||
AlarmEnabledState Enabled,
|
||||
AlarmActiveState Active,
|
||||
AlarmAckedState Acked,
|
||||
AlarmConfirmedState Confirmed,
|
||||
ShelvingState Shelving,
|
||||
DateTime LastTransitionUtc,
|
||||
DateTime? LastActiveUtc,
|
||||
DateTime? LastClearedUtc,
|
||||
DateTime? LastAckUtc,
|
||||
string? LastAckUser,
|
||||
string? LastAckComment,
|
||||
DateTime? LastConfirmUtc,
|
||||
string? LastConfirmUser,
|
||||
string? LastConfirmComment,
|
||||
IReadOnlyList<AlarmComment> Comments)
|
||||
{
|
||||
/// <summary>Initial-load state for a newly registered alarm — everything in the "no-event" position.</summary>
|
||||
public static AlarmConditionState Fresh(string alarmId, DateTime nowUtc) => new(
|
||||
AlarmId: alarmId,
|
||||
Enabled: AlarmEnabledState.Enabled,
|
||||
Active: AlarmActiveState.Inactive,
|
||||
Acked: AlarmAckedState.Acknowledged,
|
||||
Confirmed: AlarmConfirmedState.Confirmed,
|
||||
Shelving: ShelvingState.Unshelved,
|
||||
LastTransitionUtc: nowUtc,
|
||||
LastActiveUtc: null,
|
||||
LastClearedUtc: null,
|
||||
LastAckUtc: null,
|
||||
LastAckUser: null,
|
||||
LastAckComment: null,
|
||||
LastConfirmUtc: null,
|
||||
LastConfirmUser: null,
|
||||
LastConfirmComment: null,
|
||||
Comments: []);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Shelving state — kind plus, for <see cref="ShelvingKind.Timed"/>, the UTC
|
||||
/// timestamp at which the shelving auto-expires. The engine polls the timer on its
|
||||
/// evaluation cadence; callers should not rely on millisecond-precision expiry.
|
||||
/// </summary>
|
||||
public sealed record ShelvingState(ShelvingKind Kind, DateTime? UnshelveAtUtc)
|
||||
{
|
||||
public static readonly ShelvingState Unshelved = new(ShelvingKind.Unshelved, null);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A single append-only audit record — acknowledgement / confirmation / explicit
|
||||
/// comment / shelving action. Every entry carries a monotonic UTC timestamp plus the
|
||||
/// user identity Phase 6.2 authenticated.
|
||||
/// </summary>
|
||||
/// <param name="TimestampUtc">When the action happened.</param>
|
||||
/// <param name="User">OS / LDAP identity of the actor. For engine-internal events (shelving expiry, startup recovery) this is <c>"system"</c>.</param>
|
||||
/// <param name="Kind">Human-readable classification — "Acknowledge", "Confirm", "ShelveOneShot", "ShelveTimed", "Unshelve", "AddComment", "Enable", "Disable", "AutoUnshelve".</param>
|
||||
/// <param name="Text">Operator-supplied comment or engine-generated message.</param>
|
||||
public sealed record AlarmComment(
|
||||
DateTime TimestampUtc,
|
||||
string User,
|
||||
string Kind,
|
||||
string Text);
|
||||
@@ -0,0 +1,55 @@
|
||||
using Serilog;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Scripting;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// <see cref="ScriptContext"/> subclass for alarm predicate evaluation. Reads from
|
||||
/// the engine's shared tag cache (driver + virtual tags), writes are rejected —
|
||||
/// predicates must be side-effect free so their output doesn't depend on evaluation
|
||||
/// order or drive cascade behavior.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Per Phase 7 plan Shape A decision, alarm scripts are one-script-per-alarm
|
||||
/// returning <c>bool</c>. They read any tag they want but should not write
|
||||
/// anything (the owning alarm's state is tracked by the engine, not the script).
|
||||
/// </remarks>
|
||||
public sealed class AlarmPredicateContext : ScriptContext
|
||||
{
|
||||
private readonly IReadOnlyDictionary<string, DataValueSnapshot> _readCache;
|
||||
private readonly Func<DateTime> _clock;
|
||||
|
||||
public AlarmPredicateContext(
|
||||
IReadOnlyDictionary<string, DataValueSnapshot> readCache,
|
||||
ILogger logger,
|
||||
Func<DateTime>? clock = null)
|
||||
{
|
||||
_readCache = readCache ?? throw new ArgumentNullException(nameof(readCache));
|
||||
Logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
_clock = clock ?? (() => DateTime.UtcNow);
|
||||
}
|
||||
|
||||
public override DataValueSnapshot GetTag(string path)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(path))
|
||||
return new DataValueSnapshot(null, 0x80340000u, null, _clock());
|
||||
return _readCache.TryGetValue(path, out var v)
|
||||
? v
|
||||
: new DataValueSnapshot(null, 0x80340000u, null, _clock());
|
||||
}
|
||||
|
||||
public override void SetVirtualTag(string path, object? value)
|
||||
{
|
||||
// Predicates must be pure — writing from an alarm script couples alarm state to
|
||||
// virtual-tag state in a way that's near-impossible to reason about. Rejected
|
||||
// at runtime with a clear message; operators see it in the scripts-*.log.
|
||||
throw new InvalidOperationException(
|
||||
"Alarm predicate scripts cannot write to virtual tags. Move the write logic " +
|
||||
"into a virtual tag whose value the alarm predicate then reads.");
|
||||
}
|
||||
|
||||
public override DateTime Now => _clock();
|
||||
|
||||
public override ILogger Logger { get; }
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// The concrete OPC UA Part 9 alarm subtype a scripted alarm materializes as. The
|
||||
/// engine's internal state machine is identical regardless of kind — the
|
||||
/// <c>AlarmKind</c> only affects how the alarm node appears to OPC UA clients
|
||||
/// (which ObjectType it maps to) and what diagnostic fields are populated.
|
||||
/// </summary>
|
||||
public enum AlarmKind
|
||||
{
|
||||
/// <summary>Base AlarmConditionType — no numeric or discrete interpretation.</summary>
|
||||
AlarmCondition,
|
||||
/// <summary>LimitAlarmType — the condition reflects a numeric setpoint / threshold breach.</summary>
|
||||
LimitAlarm,
|
||||
/// <summary>DiscreteAlarmType — the condition reflects a specific discrete value match.</summary>
|
||||
DiscreteAlarm,
|
||||
/// <summary>OffNormalAlarmType — the condition reflects deviation from a configured "normal" state.</summary>
|
||||
OffNormalAlarm,
|
||||
}
|
||||
|
||||
/// <summary>OPC UA Part 9 EnabledState — operator-controlled alarm enable/disable.</summary>
|
||||
public enum AlarmEnabledState { Enabled, Disabled }
|
||||
|
||||
/// <summary>OPC UA Part 9 ActiveState — reflects the current predicate truth.</summary>
|
||||
public enum AlarmActiveState { Inactive, Active }
|
||||
|
||||
/// <summary>OPC UA Part 9 AckedState — operator has acknowledged the active transition.</summary>
|
||||
public enum AlarmAckedState { Unacknowledged, Acknowledged }
|
||||
|
||||
/// <summary>OPC UA Part 9 ConfirmedState — operator has confirmed the clear transition.</summary>
|
||||
public enum AlarmConfirmedState { Unconfirmed, Confirmed }
|
||||
|
||||
/// <summary>
|
||||
/// OPC UA Part 9 shelving mode.
|
||||
/// <see cref="OneShot"/> suppresses the next active transition; once cleared
|
||||
/// the shelving expires and the alarm returns to normal behavior.
|
||||
/// <see cref="Timed"/> suppresses until a configured expiry timestamp passes.
|
||||
/// <see cref="Unshelved"/> is the default state — no suppression.
|
||||
/// </summary>
|
||||
public enum ShelvingKind { Unshelved, OneShot, Timed }
|
||||
@@ -0,0 +1,47 @@
|
||||
using System.Collections.Concurrent;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Persistence for <see cref="AlarmConditionState"/> across server restarts. Phase 7
|
||||
/// plan decision #14: operator-supplied state (EnabledState / AckedState /
|
||||
/// ConfirmedState / ShelvingState + audit trail) persists; ActiveState is
|
||||
/// recomputed from the live predicate on startup so operators never re-ack.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Stream E wires this to a SQL-backed store against the <c>ScriptedAlarmState</c>
|
||||
/// table with audit logging through <see cref="Core.Abstractions"/> IAuditLogger.
|
||||
/// Tests + local dev use <see cref="InMemoryAlarmStateStore"/>.
|
||||
/// </remarks>
|
||||
public interface IAlarmStateStore
|
||||
{
|
||||
Task<AlarmConditionState?> LoadAsync(string alarmId, CancellationToken ct);
|
||||
Task<IReadOnlyList<AlarmConditionState>> LoadAllAsync(CancellationToken ct);
|
||||
Task SaveAsync(AlarmConditionState state, CancellationToken ct);
|
||||
Task RemoveAsync(string alarmId, CancellationToken ct);
|
||||
}
|
||||
|
||||
/// <summary>In-memory default — used by tests + by dev deployments without a SQL backend.</summary>
|
||||
public sealed class InMemoryAlarmStateStore : IAlarmStateStore
|
||||
{
|
||||
private readonly ConcurrentDictionary<string, AlarmConditionState> _map
|
||||
= new(StringComparer.Ordinal);
|
||||
|
||||
public Task<AlarmConditionState?> LoadAsync(string alarmId, CancellationToken ct)
|
||||
=> Task.FromResult(_map.TryGetValue(alarmId, out var v) ? v : null);
|
||||
|
||||
public Task<IReadOnlyList<AlarmConditionState>> LoadAllAsync(CancellationToken ct)
|
||||
=> Task.FromResult<IReadOnlyList<AlarmConditionState>>(_map.Values.ToArray());
|
||||
|
||||
public Task SaveAsync(AlarmConditionState state, CancellationToken ct)
|
||||
{
|
||||
_map[state.AlarmId] = state;
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
|
||||
public Task RemoveAsync(string alarmId, CancellationToken ct)
|
||||
{
|
||||
_map.TryRemove(alarmId, out _);
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
using System.Text.RegularExpressions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Per Phase 7 plan decision #13, alarm messages are static-with-substitution
|
||||
/// templates. The engine resolves <c>{TagPath}</c> tokens at event emission time
|
||||
/// against current tag values; unresolvable tokens become <c>{?}</c> so the event
|
||||
/// still fires but the operator sees where the reference broke.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Token syntax: <c>{path/with/slashes}</c>. Brace-stripped the contents must
|
||||
/// match a path the caller's resolver function can look up. No escaping
|
||||
/// currently — if you need literal braces in the message, reach for a feature
|
||||
/// request.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Pure function. Same inputs always produce the same string. Tests verify the
|
||||
/// edge cases (no tokens / one token / many / nested / unresolvable / bad
|
||||
/// quality / null value).
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class MessageTemplate
|
||||
{
|
||||
private static readonly Regex TokenRegex = new(@"\{([^{}]+)\}",
|
||||
RegexOptions.Compiled | RegexOptions.CultureInvariant);
|
||||
|
||||
/// <summary>
|
||||
/// Resolve every <c>{path}</c> token in <paramref name="template"/> using
|
||||
/// <paramref name="resolveTag"/>. Tokens whose returned <see cref="DataValueSnapshot"/>
|
||||
/// has a non-Good <see cref="DataValueSnapshot.StatusCode"/> or a null
|
||||
/// <see cref="DataValueSnapshot.Value"/> resolve to <c>{?}</c>.
|
||||
/// </summary>
|
||||
public static string Resolve(string template, Func<string, DataValueSnapshot?> resolveTag)
|
||||
{
|
||||
if (string.IsNullOrEmpty(template)) return template ?? string.Empty;
|
||||
if (resolveTag is null) throw new ArgumentNullException(nameof(resolveTag));
|
||||
|
||||
return TokenRegex.Replace(template, match =>
|
||||
{
|
||||
var path = match.Groups[1].Value.Trim();
|
||||
if (path.Length == 0) return "{?}";
|
||||
var snap = resolveTag(path);
|
||||
if (snap is null) return "{?}";
|
||||
if (snap.StatusCode != 0u) return "{?}";
|
||||
return snap.Value?.ToString() ?? "{?}";
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>Enumerate the token paths the template references. Used at publish time to validate references exist.</summary>
|
||||
public static IReadOnlyList<string> ExtractTokenPaths(string? template)
|
||||
{
|
||||
if (string.IsNullOrEmpty(template)) return Array.Empty<string>();
|
||||
var tokens = new List<string>();
|
||||
foreach (Match m in TokenRegex.Matches(template))
|
||||
{
|
||||
var path = m.Groups[1].Value.Trim();
|
||||
if (path.Length > 0) tokens.Add(path);
|
||||
}
|
||||
return tokens;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,294 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Pure functions for OPC UA Part 9 alarm-condition state transitions. Input = the
|
||||
/// current <see cref="AlarmConditionState"/> + the event; output = the new state +
|
||||
/// optional emission hint. The engine calls these; persistence happens around them.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// No instance state, no I/O, no mutation of the input record. Every transition
|
||||
/// returns a fresh record. Makes the state machine trivially unit-testable —
|
||||
/// tests assert on (input, event) -> (output) without standing anything else up.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Two invariants the machine enforces:
|
||||
/// (1) Disabled alarms never transition ActiveState / AckedState / ConfirmedState
|
||||
/// — all predicate evaluations while disabled produce a no-op result and a
|
||||
/// diagnostic log line. Re-enable restores normal flow with ActiveState
|
||||
/// re-derived from the next predicate evaluation.
|
||||
/// (2) Shelved alarms (OneShot / Timed) don't fire active transitions to
|
||||
/// subscribers, but the state record still advances so that when shelving
|
||||
/// expires the ActiveState reflects current reality. OneShot expires on the
|
||||
/// next clear; Timed expires at <see cref="ShelvingState.UnshelveAtUtc"/>.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class Part9StateMachine
|
||||
{
|
||||
/// <summary>
|
||||
/// Apply a predicate re-evaluation result. Handles activation, clearing,
|
||||
/// branch-stack increment when a new active arrives while prior active is
|
||||
/// still un-acked, and shelving suppression.
|
||||
/// </summary>
|
||||
public static TransitionResult ApplyPredicate(
|
||||
AlarmConditionState current,
|
||||
bool predicateTrue,
|
||||
DateTime nowUtc)
|
||||
{
|
||||
if (current.Enabled == AlarmEnabledState.Disabled)
|
||||
return TransitionResult.NoOp(current, "disabled — predicate result ignored");
|
||||
|
||||
// Expire timed shelving if the configured clock has passed.
|
||||
var shelving = MaybeExpireShelving(current.Shelving, nowUtc);
|
||||
var stateWithShelving = current with { Shelving = shelving };
|
||||
|
||||
// Shelved alarms still update state but skip event emission.
|
||||
var shelved = shelving.Kind != ShelvingKind.Unshelved;
|
||||
|
||||
if (predicateTrue && current.Active == AlarmActiveState.Inactive)
|
||||
{
|
||||
// Inactive -> Active transition.
|
||||
// OneShotShelving is consumed on the NEXT clear, not activation — so we
|
||||
// still suppress this transition's emission.
|
||||
var next = stateWithShelving with
|
||||
{
|
||||
Active = AlarmActiveState.Active,
|
||||
Acked = AlarmAckedState.Unacknowledged,
|
||||
Confirmed = AlarmConfirmedState.Unconfirmed,
|
||||
LastActiveUtc = nowUtc,
|
||||
LastTransitionUtc = nowUtc,
|
||||
};
|
||||
return new TransitionResult(next, shelved ? EmissionKind.Suppressed : EmissionKind.Activated);
|
||||
}
|
||||
|
||||
if (!predicateTrue && current.Active == AlarmActiveState.Active)
|
||||
{
|
||||
// Active -> Inactive transition.
|
||||
var next = stateWithShelving with
|
||||
{
|
||||
Active = AlarmActiveState.Inactive,
|
||||
LastClearedUtc = nowUtc,
|
||||
LastTransitionUtc = nowUtc,
|
||||
// OneShotShelving expires on clear — resetting here so the next
|
||||
// activation fires normally.
|
||||
Shelving = shelving.Kind == ShelvingKind.OneShot
|
||||
? ShelvingState.Unshelved
|
||||
: shelving,
|
||||
};
|
||||
return new TransitionResult(next, shelved ? EmissionKind.Suppressed : EmissionKind.Cleared);
|
||||
}
|
||||
|
||||
// Predicate matches current Active — no state change beyond possible shelving
|
||||
// expiry.
|
||||
return new TransitionResult(stateWithShelving, EmissionKind.None);
|
||||
}
|
||||
|
||||
/// <summary>Operator acknowledges the currently-active transition.</summary>
|
||||
public static TransitionResult ApplyAcknowledge(
|
||||
AlarmConditionState current,
|
||||
string user,
|
||||
string? comment,
|
||||
DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user))
|
||||
throw new ArgumentException("User identity required for audit.", nameof(user));
|
||||
|
||||
if (current.Acked == AlarmAckedState.Acknowledged)
|
||||
return TransitionResult.NoOp(current, "already acknowledged");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "Acknowledge", comment);
|
||||
var next = current with
|
||||
{
|
||||
Acked = AlarmAckedState.Acknowledged,
|
||||
LastAckUtc = nowUtc,
|
||||
LastAckUser = user,
|
||||
LastAckComment = comment,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Acknowledged);
|
||||
}
|
||||
|
||||
/// <summary>Operator confirms the cleared transition. Part 9 requires confirm after clear for retain-flag alarms.</summary>
|
||||
public static TransitionResult ApplyConfirm(
|
||||
AlarmConditionState current,
|
||||
string user,
|
||||
string? comment,
|
||||
DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user))
|
||||
throw new ArgumentException("User identity required for audit.", nameof(user));
|
||||
|
||||
if (current.Confirmed == AlarmConfirmedState.Confirmed)
|
||||
return TransitionResult.NoOp(current, "already confirmed");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "Confirm", comment);
|
||||
var next = current with
|
||||
{
|
||||
Confirmed = AlarmConfirmedState.Confirmed,
|
||||
LastConfirmUtc = nowUtc,
|
||||
LastConfirmUser = user,
|
||||
LastConfirmComment = comment,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Confirmed);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyOneShotShelve(
|
||||
AlarmConditionState current, string user, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (current.Shelving.Kind == ShelvingKind.OneShot)
|
||||
return TransitionResult.NoOp(current, "already one-shot shelved");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "ShelveOneShot", null);
|
||||
var next = current with
|
||||
{
|
||||
Shelving = new ShelvingState(ShelvingKind.OneShot, null),
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Shelved);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyTimedShelve(
|
||||
AlarmConditionState current, string user, DateTime unshelveAtUtc, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (unshelveAtUtc <= nowUtc)
|
||||
throw new ArgumentOutOfRangeException(nameof(unshelveAtUtc), "Unshelve time must be in the future.");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "ShelveTimed",
|
||||
$"UnshelveAtUtc={unshelveAtUtc:O}");
|
||||
var next = current with
|
||||
{
|
||||
Shelving = new ShelvingState(ShelvingKind.Timed, unshelveAtUtc),
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Shelved);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyUnshelve(AlarmConditionState current, string user, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (current.Shelving.Kind == ShelvingKind.Unshelved)
|
||||
return TransitionResult.NoOp(current, "not shelved");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "Unshelve", null);
|
||||
var next = current with
|
||||
{
|
||||
Shelving = ShelvingState.Unshelved,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Unshelved);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyEnable(AlarmConditionState current, string user, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (current.Enabled == AlarmEnabledState.Enabled)
|
||||
return TransitionResult.NoOp(current, "already enabled");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "Enable", null);
|
||||
var next = current with
|
||||
{
|
||||
Enabled = AlarmEnabledState.Enabled,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Enabled);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyDisable(AlarmConditionState current, string user, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (current.Enabled == AlarmEnabledState.Disabled)
|
||||
return TransitionResult.NoOp(current, "already disabled");
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "Disable", null);
|
||||
var next = current with
|
||||
{
|
||||
Enabled = AlarmEnabledState.Disabled,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Disabled);
|
||||
}
|
||||
|
||||
public static TransitionResult ApplyAddComment(
|
||||
AlarmConditionState current, string user, string text, DateTime nowUtc)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(user)) throw new ArgumentException("User required.", nameof(user));
|
||||
if (string.IsNullOrWhiteSpace(text)) throw new ArgumentException("Comment text required.", nameof(text));
|
||||
|
||||
var audit = AppendComment(current.Comments, nowUtc, user, "AddComment", text);
|
||||
var next = current with { Comments = audit };
|
||||
return new TransitionResult(next, EmissionKind.CommentAdded);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Re-evaluate whether a currently timed-shelved alarm has expired. Returns
|
||||
/// the (possibly unshelved) state + emission hint so the engine knows to
|
||||
/// publish an Unshelved event at the right moment.
|
||||
/// </summary>
|
||||
public static TransitionResult ApplyShelvingCheck(AlarmConditionState current, DateTime nowUtc)
|
||||
{
|
||||
if (current.Shelving.Kind != ShelvingKind.Timed) return TransitionResult.None(current);
|
||||
if (current.Shelving.UnshelveAtUtc is DateTime t && nowUtc >= t)
|
||||
{
|
||||
var audit = AppendComment(current.Comments, nowUtc, "system", "AutoUnshelve",
|
||||
$"Timed shelving expired at {nowUtc:O}");
|
||||
var next = current with
|
||||
{
|
||||
Shelving = ShelvingState.Unshelved,
|
||||
LastTransitionUtc = nowUtc,
|
||||
Comments = audit,
|
||||
};
|
||||
return new TransitionResult(next, EmissionKind.Unshelved);
|
||||
}
|
||||
return TransitionResult.None(current);
|
||||
}
|
||||
|
||||
private static ShelvingState MaybeExpireShelving(ShelvingState s, DateTime nowUtc)
|
||||
{
|
||||
if (s.Kind != ShelvingKind.Timed) return s;
|
||||
return s.UnshelveAtUtc is DateTime t && nowUtc >= t ? ShelvingState.Unshelved : s;
|
||||
}
|
||||
|
||||
private static IReadOnlyList<AlarmComment> AppendComment(
|
||||
IReadOnlyList<AlarmComment> existing, DateTime ts, string user, string kind, string? text)
|
||||
{
|
||||
var list = new List<AlarmComment>(existing.Count + 1);
|
||||
list.AddRange(existing);
|
||||
list.Add(new AlarmComment(ts, user, kind, text ?? string.Empty));
|
||||
return list;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Result of a state-machine operation — new state + what to emit (if anything).</summary>
|
||||
public sealed record TransitionResult(AlarmConditionState State, EmissionKind Emission)
|
||||
{
|
||||
public static TransitionResult None(AlarmConditionState state) => new(state, EmissionKind.None);
|
||||
public static TransitionResult NoOp(AlarmConditionState state, string reason) => new(state, EmissionKind.None);
|
||||
}
|
||||
|
||||
/// <summary>What kind of event, if any, the engine should emit after a transition.</summary>
|
||||
public enum EmissionKind
|
||||
{
|
||||
/// <summary>State did not change meaningfully — no event to emit.</summary>
|
||||
None,
|
||||
/// <summary>Predicate transitioned to true while shelving was suppressing events.</summary>
|
||||
Suppressed,
|
||||
Activated,
|
||||
Cleared,
|
||||
Acknowledged,
|
||||
Confirmed,
|
||||
Shelved,
|
||||
Unshelved,
|
||||
Enabled,
|
||||
Disabled,
|
||||
CommentAdded,
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Operator-authored scripted-alarm configuration. Phase 7 Stream E (config DB schema)
|
||||
/// materializes these from the <c>ScriptedAlarm</c> + <c>Script</c> tables on publish.
|
||||
/// </summary>
|
||||
/// <param name="AlarmId">
|
||||
/// Stable identity for the alarm — used as the OPC UA ConditionId + the key in the
|
||||
/// state store. Should be globally unique within the cluster; convention is
|
||||
/// <c>{EquipmentPath}::{AlarmName}</c>.
|
||||
/// </param>
|
||||
/// <param name="EquipmentPath">
|
||||
/// UNS path of the Equipment node the alarm hangs under. Alarm browse lives here;
|
||||
/// ACL binding inherits this equipment's scope per Phase 6.2.
|
||||
/// </param>
|
||||
/// <param name="AlarmName">Human-readable alarm name — used in the browse tree + Admin UI.</param>
|
||||
/// <param name="Kind">Concrete OPC UA Part 9 subtype the alarm materializes as.</param>
|
||||
/// <param name="Severity">Static severity per Phase 7 plan decision #13; not currently computed by the predicate.</param>
|
||||
/// <param name="MessageTemplate">
|
||||
/// Message text with <c>{TagPath}</c> tokens resolved at event-emission time per
|
||||
/// Phase 7 plan decision #13. Unresolvable tokens emit <c>{?}</c> + a structured
|
||||
/// error so operators can spot stale references.
|
||||
/// </param>
|
||||
/// <param name="PredicateScriptSource">
|
||||
/// Roslyn C# script returning <c>bool</c>. <c>true</c> = alarm condition currently holds (active);
|
||||
/// <c>false</c> = condition has cleared. Same sandbox rules as virtual tags per Phase 7 decision #6.
|
||||
/// </param>
|
||||
/// <param name="HistorizeToAveva">
|
||||
/// When true, every transition emission of this alarm flows to the Historian alarm
|
||||
/// sink (Stream D). Defaults to true — plant alarm history is usually the
|
||||
/// operator's primary diagnostic. Galaxy-native alarms default false since Galaxy
|
||||
/// historises them directly.
|
||||
/// </param>
|
||||
/// <param name="Retain">
|
||||
/// Part 9 retain flag — when true, the condition node remains visible after the
|
||||
/// predicate clears as long as it has un-acknowledged or un-confirmed transitions.
|
||||
/// Default true.
|
||||
/// </param>
|
||||
public sealed record ScriptedAlarmDefinition(
|
||||
string AlarmId,
|
||||
string EquipmentPath,
|
||||
string AlarmName,
|
||||
AlarmKind Kind,
|
||||
AlarmSeverity Severity,
|
||||
string MessageTemplate,
|
||||
string PredicateScriptSource,
|
||||
bool HistorizeToAveva = true,
|
||||
bool Retain = true);
|
||||
@@ -0,0 +1,459 @@
|
||||
using System.Collections.Concurrent;
|
||||
using Serilog;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Scripting;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Phase 7 scripted-alarm orchestrator. Compiles every configured alarm's predicate
|
||||
/// against the Stream A sandbox, subscribes to the referenced upstream tags,
|
||||
/// re-evaluates the predicate on every input change + on a shelving-check timer,
|
||||
/// applies the resulting transition through <see cref="Part9StateMachine"/>,
|
||||
/// persists state via <see cref="IAlarmStateStore"/>, and emits the resulting events
|
||||
/// through <see cref="ScriptedAlarmSource"/> (which wires into the existing
|
||||
/// <c>IAlarmSource</c> fan-out).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Scripted alarms are leaves in the evaluation DAG — no alarm's state drives
|
||||
/// another alarm's predicate. The engine maintains only an inverse index from
|
||||
/// upstream tag path → alarms referencing it; no topological sort needed
|
||||
/// (unlike the virtual-tag engine).
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Evaluation errors (script throws, timeout, coercion fail) surface as
|
||||
/// structured errors in the dedicated scripts-*.log sink plus a WARN companion
|
||||
/// in the main log. The alarm's ActiveState stays at its prior value — the
|
||||
/// engine does NOT invent a clear transition just because the predicate broke.
|
||||
/// Operators investigating a broken predicate shouldn't see a phantom
|
||||
/// clear-event preceding the failure.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class ScriptedAlarmEngine : IDisposable
|
||||
{
|
||||
private readonly ITagUpstreamSource _upstream;
|
||||
private readonly IAlarmStateStore _store;
|
||||
private readonly ScriptLoggerFactory _loggerFactory;
|
||||
private readonly ILogger _engineLogger;
|
||||
private readonly Func<DateTime> _clock;
|
||||
private readonly TimeSpan _scriptTimeout;
|
||||
|
||||
private readonly Dictionary<string, AlarmState> _alarms = new(StringComparer.Ordinal);
|
||||
private readonly ConcurrentDictionary<string, DataValueSnapshot> _valueCache
|
||||
= new(StringComparer.Ordinal);
|
||||
private readonly Dictionary<string, HashSet<string>> _alarmsReferencing
|
||||
= new(StringComparer.Ordinal); // tag path -> alarm ids
|
||||
|
||||
private readonly List<IDisposable> _upstreamSubscriptions = [];
|
||||
private readonly SemaphoreSlim _evalGate = new(1, 1);
|
||||
private Timer? _shelvingTimer;
|
||||
private bool _loaded;
|
||||
private bool _disposed;
|
||||
|
||||
public ScriptedAlarmEngine(
|
||||
ITagUpstreamSource upstream,
|
||||
IAlarmStateStore store,
|
||||
ScriptLoggerFactory loggerFactory,
|
||||
ILogger engineLogger,
|
||||
Func<DateTime>? clock = null,
|
||||
TimeSpan? scriptTimeout = null)
|
||||
{
|
||||
_upstream = upstream ?? throw new ArgumentNullException(nameof(upstream));
|
||||
_store = store ?? throw new ArgumentNullException(nameof(store));
|
||||
_loggerFactory = loggerFactory ?? throw new ArgumentNullException(nameof(loggerFactory));
|
||||
_engineLogger = engineLogger ?? throw new ArgumentNullException(nameof(engineLogger));
|
||||
_clock = clock ?? (() => DateTime.UtcNow);
|
||||
_scriptTimeout = scriptTimeout ?? TimedScriptEvaluator<AlarmPredicateContext, bool>.DefaultTimeout;
|
||||
}
|
||||
|
||||
/// <summary>Raised for every emission the Part9StateMachine produces that the engine should publish.</summary>
|
||||
public event EventHandler<ScriptedAlarmEvent>? OnEvent;
|
||||
|
||||
public IReadOnlyCollection<string> LoadedAlarmIds => _alarms.Keys;
|
||||
|
||||
/// <summary>
|
||||
/// Load a batch of alarm definitions. Compiles every predicate, aggregates any
|
||||
/// compile failures into one <see cref="InvalidOperationException"/>, subscribes
|
||||
/// to upstream input tags, seeds the value cache, loads persisted state from
|
||||
/// the store (falling back to Fresh for first-load alarms), and recomputes
|
||||
/// ActiveState per Phase 7 plan decision #14 (startup recovery).
|
||||
/// </summary>
|
||||
public async Task LoadAsync(IReadOnlyList<ScriptedAlarmDefinition> definitions, CancellationToken ct)
|
||||
{
|
||||
if (_disposed) throw new ObjectDisposedException(nameof(ScriptedAlarmEngine));
|
||||
if (definitions is null) throw new ArgumentNullException(nameof(definitions));
|
||||
|
||||
await _evalGate.WaitAsync(ct).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
UnsubscribeFromUpstream();
|
||||
_alarms.Clear();
|
||||
_alarmsReferencing.Clear();
|
||||
|
||||
var compileFailures = new List<string>();
|
||||
foreach (var def in definitions)
|
||||
{
|
||||
try
|
||||
{
|
||||
var extraction = DependencyExtractor.Extract(def.PredicateScriptSource);
|
||||
if (!extraction.IsValid)
|
||||
{
|
||||
var joined = string.Join("; ", extraction.Rejections.Select(r => r.Message));
|
||||
compileFailures.Add($"{def.AlarmId}: dependency extraction rejected — {joined}");
|
||||
continue;
|
||||
}
|
||||
|
||||
var evaluator = ScriptEvaluator<AlarmPredicateContext, bool>.Compile(def.PredicateScriptSource);
|
||||
var timed = new TimedScriptEvaluator<AlarmPredicateContext, bool>(evaluator, _scriptTimeout);
|
||||
var logger = _loggerFactory.Create(def.AlarmId);
|
||||
|
||||
var templateTokens = MessageTemplate.ExtractTokenPaths(def.MessageTemplate);
|
||||
var allInputs = new HashSet<string>(extraction.Reads, StringComparer.Ordinal);
|
||||
foreach (var t in templateTokens) allInputs.Add(t);
|
||||
|
||||
_alarms[def.AlarmId] = new AlarmState(def, timed, extraction.Reads, templateTokens, logger,
|
||||
AlarmConditionState.Fresh(def.AlarmId, _clock()));
|
||||
|
||||
foreach (var path in allInputs)
|
||||
{
|
||||
if (!_alarmsReferencing.TryGetValue(path, out var set))
|
||||
_alarmsReferencing[path] = set = new HashSet<string>(StringComparer.Ordinal);
|
||||
set.Add(def.AlarmId);
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
compileFailures.Add($"{def.AlarmId}: {ex.Message}");
|
||||
}
|
||||
}
|
||||
|
||||
if (compileFailures.Count > 0)
|
||||
{
|
||||
throw new InvalidOperationException(
|
||||
$"ScriptedAlarmEngine load failed. {compileFailures.Count} alarm(s) did not compile:\n "
|
||||
+ string.Join("\n ", compileFailures));
|
||||
}
|
||||
|
||||
// Seed the value cache with current upstream values + subscribe for changes.
|
||||
foreach (var path in _alarmsReferencing.Keys)
|
||||
{
|
||||
_valueCache[path] = _upstream.ReadTag(path);
|
||||
_upstreamSubscriptions.Add(_upstream.SubscribeTag(path, OnUpstreamChange));
|
||||
}
|
||||
|
||||
// Restore persisted state, falling back to Fresh where nothing was saved,
|
||||
// then re-derive ActiveState from the current predicate per decision #14.
|
||||
foreach (var (alarmId, state) in _alarms)
|
||||
{
|
||||
var persisted = await _store.LoadAsync(alarmId, ct).ConfigureAwait(false);
|
||||
var seed = persisted ?? state.Condition;
|
||||
var afterPredicate = await EvaluatePredicateToStateAsync(state, seed, nowUtc: _clock(), ct)
|
||||
.ConfigureAwait(false);
|
||||
_alarms[alarmId] = state with { Condition = afterPredicate };
|
||||
await _store.SaveAsync(afterPredicate, ct).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
_loaded = true;
|
||||
_engineLogger.Information("ScriptedAlarmEngine loaded {Count} alarm(s)", _alarms.Count);
|
||||
|
||||
// Start the shelving-check timer — ticks every 5s, expires any timed shelves
|
||||
// that have passed their UnshelveAtUtc.
|
||||
_shelvingTimer = new Timer(_ => RunShelvingCheck(),
|
||||
null, TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(5));
|
||||
}
|
||||
finally
|
||||
{
|
||||
_evalGate.Release();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Current persisted state for <paramref name="alarmId"/>. Returns null for
|
||||
/// unknown alarm. Mainly used for diagnostics + the Admin UI status page.
|
||||
/// </summary>
|
||||
public AlarmConditionState? GetState(string alarmId)
|
||||
=> _alarms.TryGetValue(alarmId, out var s) ? s.Condition : null;
|
||||
|
||||
public IReadOnlyCollection<AlarmConditionState> GetAllStates()
|
||||
=> _alarms.Values.Select(a => a.Condition).ToArray();
|
||||
|
||||
public Task AcknowledgeAsync(string alarmId, string user, string? comment, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyAcknowledge(cur, user, comment, _clock()));
|
||||
|
||||
public Task ConfirmAsync(string alarmId, string user, string? comment, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyConfirm(cur, user, comment, _clock()));
|
||||
|
||||
public Task OneShotShelveAsync(string alarmId, string user, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyOneShotShelve(cur, user, _clock()));
|
||||
|
||||
public Task TimedShelveAsync(string alarmId, string user, DateTime unshelveAtUtc, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyTimedShelve(cur, user, unshelveAtUtc, _clock()));
|
||||
|
||||
public Task UnshelveAsync(string alarmId, string user, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyUnshelve(cur, user, _clock()));
|
||||
|
||||
public Task EnableAsync(string alarmId, string user, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyEnable(cur, user, _clock()));
|
||||
|
||||
public Task DisableAsync(string alarmId, string user, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyDisable(cur, user, _clock()));
|
||||
|
||||
public Task AddCommentAsync(string alarmId, string user, string text, CancellationToken ct)
|
||||
=> ApplyAsync(alarmId, ct, cur => Part9StateMachine.ApplyAddComment(cur, user, text, _clock()));
|
||||
|
||||
private async Task ApplyAsync(string alarmId, CancellationToken ct, Func<AlarmConditionState, TransitionResult> op)
|
||||
{
|
||||
EnsureLoaded();
|
||||
if (!_alarms.TryGetValue(alarmId, out var state))
|
||||
throw new ArgumentException($"Unknown alarm {alarmId}", nameof(alarmId));
|
||||
|
||||
await _evalGate.WaitAsync(ct).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
var result = op(state.Condition);
|
||||
_alarms[alarmId] = state with { Condition = result.State };
|
||||
await _store.SaveAsync(result.State, ct).ConfigureAwait(false);
|
||||
if (result.Emission != EmissionKind.None) EmitEvent(state, result.State, result.Emission);
|
||||
}
|
||||
finally { _evalGate.Release(); }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Upstream-change callback. Updates the value cache + enqueues predicate
|
||||
/// re-evaluation for every alarm referencing the changed path. Fire-and-forget
|
||||
/// so driver-side dispatch isn't blocked.
|
||||
/// </summary>
|
||||
internal void OnUpstreamChange(string path, DataValueSnapshot value)
|
||||
{
|
||||
_valueCache[path] = value;
|
||||
if (_alarmsReferencing.TryGetValue(path, out var alarmIds))
|
||||
{
|
||||
_ = ReevaluateAsync(alarmIds.ToArray(), CancellationToken.None);
|
||||
}
|
||||
}
|
||||
|
||||
private async Task ReevaluateAsync(IReadOnlyList<string> alarmIds, CancellationToken ct)
|
||||
{
|
||||
try
|
||||
{
|
||||
await _evalGate.WaitAsync(ct).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
foreach (var id in alarmIds)
|
||||
{
|
||||
if (!_alarms.TryGetValue(id, out var state)) continue;
|
||||
var newState = await EvaluatePredicateToStateAsync(
|
||||
state, state.Condition, _clock(), ct).ConfigureAwait(false);
|
||||
if (!ReferenceEquals(newState, state.Condition))
|
||||
{
|
||||
_alarms[id] = state with { Condition = newState };
|
||||
await _store.SaveAsync(newState, ct).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
}
|
||||
finally { _evalGate.Release(); }
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_engineLogger.Error(ex, "ScriptedAlarmEngine reevaluate failed");
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Evaluate the predicate + apply the resulting state-machine transition.
|
||||
/// Returns the new condition state. Emits the appropriate event if the
|
||||
/// transition produces one.
|
||||
/// </summary>
|
||||
private async Task<AlarmConditionState> EvaluatePredicateToStateAsync(
|
||||
AlarmState state, AlarmConditionState seed, DateTime nowUtc, CancellationToken ct)
|
||||
{
|
||||
var inputs = BuildReadCache(state.Inputs);
|
||||
|
||||
// Cold-start guard — skip the predicate when any referenced upstream tag has no
|
||||
// cached value yet (the upstream subscription hasn't delivered its first push).
|
||||
// Without this, predicates that cast `(double)ctx.GetTag(path).Value` throw NRE on
|
||||
// every tick until the cache fills, spamming the log with identical stack traces.
|
||||
// Bad quality is treated the same: the input isn't available at the predicate's
|
||||
// expected type, so the only defensible move is to hold the prior condition state.
|
||||
if (!AreInputsReady(inputs)) return seed;
|
||||
|
||||
var context = new AlarmPredicateContext(inputs, state.Logger, _clock);
|
||||
|
||||
bool predicateTrue;
|
||||
try
|
||||
{
|
||||
predicateTrue = await state.Evaluator.RunAsync(context, ct).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
throw;
|
||||
}
|
||||
catch (ScriptTimeoutException tex)
|
||||
{
|
||||
state.Logger.Warning("Alarm predicate timed out after {Timeout} — state unchanged", tex.Timeout);
|
||||
return seed;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
state.Logger.Error(ex, "Alarm predicate threw — state unchanged");
|
||||
return seed;
|
||||
}
|
||||
|
||||
var result = Part9StateMachine.ApplyPredicate(seed, predicateTrue, nowUtc);
|
||||
if (result.Emission != EmissionKind.None)
|
||||
EmitEvent(state, result.State, result.Emission);
|
||||
return result.State;
|
||||
}
|
||||
|
||||
private IReadOnlyDictionary<string, DataValueSnapshot> BuildReadCache(IReadOnlySet<string> inputs)
|
||||
{
|
||||
var d = new Dictionary<string, DataValueSnapshot>(StringComparer.Ordinal);
|
||||
foreach (var p in inputs)
|
||||
d[p] = _valueCache.TryGetValue(p, out var v) ? v : _upstream.ReadTag(p);
|
||||
return d;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Returns true when every entry in <paramref name="cache"/> has a non-null value
|
||||
/// and a Good-quality <see cref="DataValueSnapshot.StatusCode"/>. A false here lets
|
||||
/// callers short-circuit script evaluation — predicates that unconditionally cast
|
||||
/// <c>ctx.GetTag(path).Value</c> to a numeric type would otherwise throw
|
||||
/// <see cref="NullReferenceException"/> until the upstream subscription delivers
|
||||
/// its first push.
|
||||
/// </summary>
|
||||
private static bool AreInputsReady(IReadOnlyDictionary<string, DataValueSnapshot> cache)
|
||||
{
|
||||
foreach (var kv in cache)
|
||||
{
|
||||
if (kv.Value is null || kv.Value.Value is null) return false;
|
||||
// OPC UA Part 4 StatusCode: bit 31 = severity 10 (Bad). Treat Good + Uncertain
|
||||
// as "ready"; Uncertain carries a value the script can still inspect + make a
|
||||
// qualified decision from. Only outright Bad is skipped.
|
||||
if ((kv.Value.StatusCode & 0x80000000u) != 0) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
private void EmitEvent(AlarmState state, AlarmConditionState condition, EmissionKind kind)
|
||||
{
|
||||
// Suppressed kind means shelving ate the emission — we don't fire for subscribers
|
||||
// but the state record still advanced so startup recovery reflects reality.
|
||||
if (kind == EmissionKind.Suppressed || kind == EmissionKind.None) return;
|
||||
|
||||
var message = MessageTemplate.Resolve(state.Definition.MessageTemplate, TryLookup);
|
||||
var evt = new ScriptedAlarmEvent(
|
||||
AlarmId: state.Definition.AlarmId,
|
||||
EquipmentPath: state.Definition.EquipmentPath,
|
||||
AlarmName: state.Definition.AlarmName,
|
||||
Kind: state.Definition.Kind,
|
||||
Severity: state.Definition.Severity,
|
||||
Message: message,
|
||||
Condition: condition,
|
||||
Emission: kind,
|
||||
TimestampUtc: _clock());
|
||||
try { OnEvent?.Invoke(this, evt); }
|
||||
catch (Exception ex)
|
||||
{
|
||||
_engineLogger.Warning(ex, "ScriptedAlarmEngine OnEvent subscriber threw for {AlarmId}", state.Definition.AlarmId);
|
||||
}
|
||||
}
|
||||
|
||||
private DataValueSnapshot? TryLookup(string path)
|
||||
=> _valueCache.TryGetValue(path, out var v) ? v : null;
|
||||
|
||||
private void RunShelvingCheck()
|
||||
{
|
||||
if (_disposed) return;
|
||||
var ids = _alarms.Keys.ToArray();
|
||||
_ = ShelvingCheckAsync(ids, CancellationToken.None);
|
||||
}
|
||||
|
||||
private async Task ShelvingCheckAsync(IReadOnlyList<string> alarmIds, CancellationToken ct)
|
||||
{
|
||||
try
|
||||
{
|
||||
await _evalGate.WaitAsync(ct).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
var now = _clock();
|
||||
foreach (var id in alarmIds)
|
||||
{
|
||||
if (!_alarms.TryGetValue(id, out var state)) continue;
|
||||
var result = Part9StateMachine.ApplyShelvingCheck(state.Condition, now);
|
||||
if (!ReferenceEquals(result.State, state.Condition))
|
||||
{
|
||||
_alarms[id] = state with { Condition = result.State };
|
||||
await _store.SaveAsync(result.State, ct).ConfigureAwait(false);
|
||||
if (result.Emission != EmissionKind.None)
|
||||
EmitEvent(state, result.State, result.Emission);
|
||||
}
|
||||
}
|
||||
}
|
||||
finally { _evalGate.Release(); }
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_engineLogger.Warning(ex, "ScriptedAlarmEngine shelving-check failed");
|
||||
}
|
||||
}
|
||||
|
||||
private void UnsubscribeFromUpstream()
|
||||
{
|
||||
foreach (var s in _upstreamSubscriptions)
|
||||
{
|
||||
try { s.Dispose(); } catch { }
|
||||
}
|
||||
_upstreamSubscriptions.Clear();
|
||||
}
|
||||
|
||||
private void EnsureLoaded()
|
||||
{
|
||||
if (!_loaded) throw new InvalidOperationException(
|
||||
"ScriptedAlarmEngine not loaded. Call LoadAsync first.");
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
if (_disposed) return;
|
||||
_disposed = true;
|
||||
_shelvingTimer?.Dispose();
|
||||
UnsubscribeFromUpstream();
|
||||
_alarms.Clear();
|
||||
_alarmsReferencing.Clear();
|
||||
}
|
||||
|
||||
private sealed record AlarmState(
|
||||
ScriptedAlarmDefinition Definition,
|
||||
TimedScriptEvaluator<AlarmPredicateContext, bool> Evaluator,
|
||||
IReadOnlySet<string> Inputs,
|
||||
IReadOnlyList<string> TemplateTokens,
|
||||
ILogger Logger,
|
||||
AlarmConditionState Condition);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One alarm emission the engine pushed to subscribers. Carries everything
|
||||
/// downstream consumers (OPC UA alarm-source adapter + historian sink) need to
|
||||
/// publish the event without re-querying the engine.
|
||||
/// </summary>
|
||||
public sealed record ScriptedAlarmEvent(
|
||||
string AlarmId,
|
||||
string EquipmentPath,
|
||||
string AlarmName,
|
||||
AlarmKind Kind,
|
||||
AlarmSeverity Severity,
|
||||
string Message,
|
||||
AlarmConditionState Condition,
|
||||
EmissionKind Emission,
|
||||
DateTime TimestampUtc);
|
||||
|
||||
/// <summary>
|
||||
/// Upstream source abstraction — intentionally identical shape to the virtual-tag
|
||||
/// engine's so Stream G can compose them behind one driver bridge.
|
||||
/// </summary>
|
||||
public interface ITagUpstreamSource
|
||||
{
|
||||
DataValueSnapshot ReadTag(string path);
|
||||
IDisposable SubscribeTag(string path, Action<string, DataValueSnapshot> observer);
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
using System.Collections.Concurrent;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
|
||||
|
||||
/// <summary>
|
||||
/// Adapter that exposes <see cref="ScriptedAlarmEngine"/> through the driver-agnostic
|
||||
/// <see cref="IAlarmSource"/> surface. The existing Phase 6.1 <c>AlarmTracker</c>
|
||||
/// composition fan-out consumes this alongside Galaxy / AB CIP / FOCAS alarm
|
||||
/// sources — no per-source branching in the fan-out.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Per Phase 7 plan Stream C.6, ack / confirm / shelve / unshelve are OPC UA
|
||||
/// method calls per-condition. This adapter implements <see cref="AcknowledgeAsync"/>
|
||||
/// from the base interface; the richer Part 9 methods (Confirm / Shelve /
|
||||
/// Unshelve / AddComment) live directly on the engine, invoked from OPC UA
|
||||
/// method handlers wired up in Stream G.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// SubscribeAlarmsAsync takes a list of source-node-id filters (typically an
|
||||
/// Equipment path prefix). When the list is empty every alarm matches. The
|
||||
/// adapter doesn't maintain per-subscription state beyond the filter set — it
|
||||
/// checks each emission against every live subscription.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class ScriptedAlarmSource : IAlarmSource, IDisposable
|
||||
{
|
||||
private readonly ScriptedAlarmEngine _engine;
|
||||
private readonly ConcurrentDictionary<string, Subscription> _subscriptions
|
||||
= new(StringComparer.Ordinal);
|
||||
private bool _disposed;
|
||||
|
||||
public ScriptedAlarmSource(ScriptedAlarmEngine engine)
|
||||
{
|
||||
_engine = engine ?? throw new ArgumentNullException(nameof(engine));
|
||||
_engine.OnEvent += OnEngineEvent;
|
||||
}
|
||||
|
||||
public event EventHandler<AlarmEventArgs>? OnAlarmEvent;
|
||||
|
||||
public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
|
||||
IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
|
||||
{
|
||||
if (sourceNodeIds is null) throw new ArgumentNullException(nameof(sourceNodeIds));
|
||||
var handle = new SubscriptionHandle(Guid.NewGuid().ToString("N"));
|
||||
_subscriptions[handle.DiagnosticId] = new Subscription(handle,
|
||||
new HashSet<string>(sourceNodeIds, StringComparer.Ordinal));
|
||||
return Task.FromResult<IAlarmSubscriptionHandle>(handle);
|
||||
}
|
||||
|
||||
public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
|
||||
{
|
||||
if (handle is null) throw new ArgumentNullException(nameof(handle));
|
||||
_subscriptions.TryRemove(handle.DiagnosticId, out _);
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
|
||||
public async Task AcknowledgeAsync(
|
||||
IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken)
|
||||
{
|
||||
if (acknowledgements is null) throw new ArgumentNullException(nameof(acknowledgements));
|
||||
foreach (var a in acknowledgements)
|
||||
{
|
||||
// The base interface doesn't carry a user identity — Stream G provides the
|
||||
// authenticated principal at the OPC UA dispatch layer + proxies through
|
||||
// the engine's richer AcknowledgeAsync. Here we default to "opcua-client"
|
||||
// so callers using the raw IAlarmSource still produce an audit entry.
|
||||
await _engine.AcknowledgeAsync(a.ConditionId, "opcua-client", a.Comment, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
private void OnEngineEvent(object? sender, ScriptedAlarmEvent evt)
|
||||
{
|
||||
if (_disposed) return;
|
||||
|
||||
foreach (var sub in _subscriptions.Values)
|
||||
{
|
||||
if (!Matches(sub, evt)) continue;
|
||||
var payload = new AlarmEventArgs(
|
||||
SubscriptionHandle: sub.Handle,
|
||||
SourceNodeId: evt.EquipmentPath,
|
||||
ConditionId: evt.AlarmId,
|
||||
AlarmType: evt.Kind.ToString(),
|
||||
Message: evt.Message,
|
||||
Severity: evt.Severity,
|
||||
SourceTimestampUtc: evt.TimestampUtc);
|
||||
try { OnAlarmEvent?.Invoke(this, payload); }
|
||||
catch { /* subscriber exceptions don't crash the adapter */ }
|
||||
}
|
||||
}
|
||||
|
||||
private static bool Matches(Subscription sub, ScriptedAlarmEvent evt)
|
||||
{
|
||||
if (sub.Filter.Count == 0) return true;
|
||||
// A subscription matches if any filter is a prefix of the alarm's equipment
|
||||
// path — typical use is "Enterprise/Site/Area/Line" filtering a whole line.
|
||||
foreach (var f in sub.Filter)
|
||||
{
|
||||
if (evt.EquipmentPath.Equals(f, StringComparison.Ordinal)) return true;
|
||||
if (evt.EquipmentPath.StartsWith(f + "/", StringComparison.Ordinal)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
if (_disposed) return;
|
||||
_disposed = true;
|
||||
_engine.OnEvent -= OnEngineEvent;
|
||||
_subscriptions.Clear();
|
||||
}
|
||||
|
||||
private sealed class SubscriptionHandle : IAlarmSubscriptionHandle
|
||||
{
|
||||
public SubscriptionHandle(string id) { DiagnosticId = id; }
|
||||
public string DiagnosticId { get; }
|
||||
}
|
||||
|
||||
private sealed record Subscription(SubscriptionHandle Handle, IReadOnlySet<string> Filter);
|
||||
}
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<LangVersion>latest</LangVersion>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<GenerateDocumentationFile>true</GenerateDocumentationFile>
|
||||
<NoWarn>$(NoWarn);CS1591</NoWarn>
|
||||
<RootNamespace>ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Serilog" Version="4.2.0"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
|
||||
<ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Scripting\ZB.MOM.WW.OtOpcUa.Core.Scripting.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
|
||||
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
Reference in New Issue
Block a user