fix(history): a folder's event history reads the Galaxy objects behind its native conditions (#886)
v2-ci / unit-tests (push) Has been cancelled
v2-ci / unit-tests (push) Has been cancelled
A notifier folder read one event source, its NodeId identifier (a RawPath or an EquipmentId). AVEVA stores a Galaxy object's A&E history under the object's tag_name (Source_Object), so AVEVA's own alarm and event history reached no production folder. Its lower-case property keys were also missed, so every row read Severity 1 with no ConditionName. Sources. A folder's event history now reads its own source plus the Galaxy object of every native condition that fires on it live: those parented under it and those WireAlarmNotifiers wired to it. Live and history use the same membership. The object comes from the condition's Galaxy alarm reference, its raw tag's attributeRef, up to the first '.': - The composer reads it with the driver's own parser (GalaxyAttributeRef, shared with GalaxyDriver), only for a GalaxyMxGateway tag with an alarm (RawTagPlan.NativeAlarmReference, part of plan equality). - The applier binds it after materialising the condition (IOpcUaAddressSpaceSink.BindNativeAlarmHistory, forwarded by the deferred sink). A rebuild or the condition's removal forgets it. Each object is read with the #882 rule: its own events and <Object>.<Attribute> rows, never a prefix sibling. Fan-out. historiangw's ReadEvents filter is a single predicate, so there is one request per source; the wire contract is unchanged. EventSourceFanOut merges the reads as one source: - order is (time, source position, arrival), reversed for a reverse read; ties are never re-sorted by EventId, so the boundary skip stays stable; - duplicates by EventId are dropped and the merge is cut to the cap; - a truncated source bounds the page at the time it stopped. Paging, continuation points (bound to the whole source set), the walked-back reverse read and the tie-cluster over-fetch are unchanged. A folder with one source is read exactly as before. ACL. Every source is read inside the folder's own HistoryRead, after AuthorizeHistoryRead (#826). A denied folder reads nothing and fails closed. Mapping (EventMapper, property names now case-insensitive): - Severity: an AVEVA row's priority goes through GalaxyAlarmPriority, the table live Galaxy alarms use (MxAccessSeverityMapper now delegates to it), so history matches live. Otherwise severity (OtOpcUa's own rows, which AVEVA stores lower-cased), clamped. AVEVA's own 1-4 severity is ignored. The table ranks a higher priority as more severe, which inverts AVEVA's convention: filed as #887. - An AVEVA row whose source_conditionvariable names a native condition that fires on the folder takes that condition's SourceNode and live ConditionName. Otherwise ConditionName is alarmname or the condition variable's attribute. - alarm_id/alarmid map to AlarmId. Tests: - GalaxyEquipmentEventHistoryWireTests (4, real SDK session, production Gateway backend, AVEVA-shaped fake gateway): equipment EqA backed by objects Oven_007 + OvenDoor_07. Covers object and attribute events from both objects, the prefix sibling excluded, cross-object and in-object ties, forward paging at 1-4 a page, reverse whole and paged, SourceNode/ConditionName/Severity, the raw device folder, ACL deny with no backend call plus a granted positive control, and a rebuild forgetting the bindings. - EventSourceFanOutTests (8), EventMapper AVEVA cases (11), GalaxyAttributeRefTests (16), a composer test and an applier ordering test. - Mutation-checked, 17 mutants, all killed. Covered: parent-only membership, no scope, a case-sensitive condition match, no condition rewrite, no truncation bound, EventId tie order, no sort, no cap, no stop at the bound, unreversed source order, no dedupe, no '.' boundary, priority ignored, case-sensitive keys, no applier bind, no deferred forward, and a composer that ignores the driver type. The forget-on-rematerialise guard survives as belt-and-braces: the rebuild clear covers it. - Live, read-only, no WinRM, vd03 HistorianGateway ea9f21c: equipment folder EQ-886-ZipsenLeft (objects DevWinPlatform + Left_001). It read 0 events before and 92 now, equal to the unfiltered read's rows for both objects. 1/7-event pages and reverse whole/5-event pages agree, and 73 rows resolve to their live condition. diff_runs vs the #882 run: 221/226 identical. The 5 that differ are expected: DevWinPlatform Severity 1 -> 750/1000, and #881 capabilities. Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
+61
-4
@@ -639,14 +639,71 @@ attributes as `DevWinPlatform.CPULoadAvg`. Both are returned by the one request
|
||||
served: a notifier whose source is `X` serves the events whose `SourceName` is `X` or starts with `X.`. The match is
|
||||
on the `.` boundary, so `DevWinPlatform` never serves `DevWinPlatform2` or `DevWinPlatform2.CPULoadAvg`. This matches
|
||||
live delivery, where an attribute alarm's condition fires on the same folder as the object's own events. Each event
|
||||
keeps its own `SourceName` (the attribute's); its `SourceNode` is the condition its stored alarm id names, so an AVEVA
|
||||
row (no OtOpcUa alarm id) has a null `SourceNode`. The attribute events are part of the notifier's own read, so they
|
||||
keeps its own `SourceName` (the attribute's); its `SourceNode` is the condition its stored alarm id names, or, since #886,
|
||||
the native condition that fires on the folder and dials the row's `source_conditionvariable` (below). The attribute events are part of the notifier's own read, so they
|
||||
are governed by that notifier's HistoryRead verdict: with `Security:Acl:Enabled`, a session denied the folder gets
|
||||
`BadUserAccessDenied` and the backend is never called. No attribute-level notifier is exposed; a notifier whose
|
||||
source is itself an attribute name (`DevWinPlatform.CPULoadAvg`) still answers `GoodNoData` from the gateway, whose
|
||||
`Source_Object` is the object. The SqlServer and QuestDB backends match the source exactly, as before: they hold only
|
||||
OtOpcUa's own alarm events. ⚠️ A production folder's source is its NodeId identifier (a RawPath or an EquipmentId),
|
||||
not a Galaxy object name, so AVEVA's own events reach a folder only where those coincide (follow-up [#886](https://gitea.dohertylan.com/dohertj2/lmxopcua/issues/886)).
|
||||
OtOpcUa's own alarm events. A production folder's own source is its NodeId identifier (a RawPath or an EquipmentId),
|
||||
not a Galaxy object name; #886 (below) adds the Galaxy objects behind the folder as further sources.
|
||||
|
||||
#### Galaxy native event history on real folders (Gitea #886)
|
||||
|
||||
**Gap.** Before #886 a notifier folder read exactly one event source, its NodeId identifier. AVEVA stores a Galaxy
|
||||
object's events under the object's `tag_name` (`Source_Object`), which is never a RawPath or an EquipmentId, so AVEVA's
|
||||
own alarm and event history reached no production folder. AVEVA's lower-case property keys (`priority`, `alarm_id`,
|
||||
`source_conditionvariable`, and the keys of OtOpcUa's own events, which AVEVA stores lower-cased: `alarmname`,
|
||||
`alarmid`, `severity`, `message`) were also missed, so every row read Severity 1 with no ConditionName.
|
||||
|
||||
**Rule: a folder's history sources are the folder itself plus the Galaxy objects of the native conditions that fire on it
|
||||
live.** A native Galaxy condition fires live on its Raw parent folder and on every UNS equipment folder wired to it
|
||||
(`WireAlarmNotifiers`). History uses the same membership:
|
||||
|
||||
- The condition's Galaxy reference is its raw tag's `attributeRef` (`tag_name.AttributeName`, the address the driver
|
||||
dials, e.g. `Oven_007.TempHiAlarm`). The composer reads it with the same parser the Galaxy driver uses
|
||||
(`GalaxyAttributeRef`) and only for a `GalaxyMxGateway` tag that carries an alarm (`RawTagPlan.NativeAlarmReference`).
|
||||
The applier hands it to the node manager after it materialises the condition (`BindNativeAlarmHistory`).
|
||||
- The object is the reference up to the first `.` (`Oven_007`). An equipment folder whose tags come from two Galaxy
|
||||
objects reads both.
|
||||
- When a folder is read, the server collects, under the node-manager lock, the object of every native condition whose
|
||||
parent is that folder or that is wired to it. Sources are the folder's own identifier (OtOpcUa's own events, as
|
||||
before) plus those objects, de-duplicated and ordinal-sorted. A folder with no Galaxy conditions keeps its single
|
||||
source and the exact pre-#886 code path.
|
||||
- Each object is read with the #882 rule: the object's own events and `<Object>.<Attribute>` rows, never a prefix
|
||||
sibling (`Oven_007` never serves `Oven_0070`). This serves every alarm of the object, including one whose condition
|
||||
is not wired to this folder, as #882 already does for a folder named after the object.
|
||||
|
||||
**Fan-out and merge (`EventSourceFanOut`).** The historiangw `ReadEvents` filter is a single property predicate, so there
|
||||
is no multi-source request and the wire contract is unchanged: one gateway request per source, sequential within a
|
||||
folder, each with the page's cap. The results are merged into one stream ordered by `(EventTimeUtc, source, arrival)`:
|
||||
time in the read's direction, then the source's position in the folder's ordinal-sorted list (reversed for a reverse
|
||||
read), then the order the source returned them. Ties are deliberately **not** re-sorted by EventId: the Gateway has no
|
||||
intra-timestamp order, and re-sorting could move an unread tie in front of one already sent; a source's own order is what
|
||||
keeps the boundary skip stable, as for a single source. The merge is de-duplicated by EventId and cut to the cap. When a
|
||||
source was truncated at time H, its unread rows are at or after H and, at H, follow the ones it returned, so the page keeps
|
||||
everything before the earliest such H and, at H, each source in merge order up to and including the first one cut there.
|
||||
That prefix is never empty. With the same cap on every source the cut to the cap already stops there; the bound matters
|
||||
for an uncapped or default-capped read. The merge presents itself as one source to the existing paging machinery, so
|
||||
continuation points, boundary-tie skips, the walked-back reverse read (Gateway, which sorts its ties by EventId itself) and
|
||||
the tie-cluster over-fetch (a forward read, reversed for a reverse read, which is why the reverse merge is the forward merge
|
||||
backwards) are unchanged. A continuation point is bound to the folder's whole source set; if a redeploy changes the set
|
||||
between pages, the next page answers `BadContinuationPointInvalid`. A folder with one source is read exactly as before.
|
||||
|
||||
**ACL.** Nothing new is authorized per source. Every source is read inside the folder's own HistoryRead, after
|
||||
`AuthorizeHistoryRead` (#826): with `Security:Acl:Enabled`, a session denied the folder gets `BadUserAccessDenied` and no
|
||||
source is read (fail closed).
|
||||
|
||||
**Mapping AVEVA rows (EventMapper).** Property names are matched case-insensitively.
|
||||
|
||||
| Field | Source | Notes |
|
||||
|---|---|---|
|
||||
| `Severity` | `priority` (AVEVA native rows) through `GalaxyAlarmPriority`, the live Galaxy mapping (`< 250` → 250, `< 500` → 500, `< 750` → 750, else 1000), else `severity` clamped to 1–1000 (OtOpcUa's own rows), else 1 | AVEVA's own `severity` (1–4, or 0 for a system event) is not on the OPC UA scale and is never used for a row that has `priority`. ⚠️ AVEVA ranks priority 1 as the most urgent and 999 as the least; the live mapping treats a higher number as more severe. History follows live so the two agree (lmxopcua#887 tracks the inversion). |
|
||||
| `ConditionName` | The live condition's name when the row's `source_conditionvariable` names a native condition that fires on this folder; else `alarmname` (OtOpcUa's own rows); else the attribute part of `source_conditionvariable` (`TempHiAlarm`) | Live parity: a resolved row shows the same ConditionName as the live condition. |
|
||||
| `SourceNode` | The native condition whose `attributeRef` equals the row's `source_conditionvariable` (case-insensitive, as the Galaxy driver matches it), among the conditions that fire on this folder; else the condition `alarmid` names (OtOpcUa's own rows) | A condition that does not fire on this folder is never named, so history discloses no node outside the folder's live event set. Object-level system events have none. |
|
||||
| `Message` | `message` (OtOpcUa's own rows), else the event type (`Alarm.Set`, `System.Stop`) | Unchanged apart from case. |
|
||||
| `AlarmId` (internal) | `alarmid`, else `alarm_id` | Used only to resolve `SourceNode`. AVEVA's `alarm_id` identifies one alarm occurrence (shared by its Set and Clear), not a condition, so it is never a ConditionName. |
|
||||
|
||||
|
||||
Event-field projection supports the standard
|
||||
`BaseEventType` select clauses — `EventId`, `SourceName`, `Time`, `ReceiveTime`, `Message`,
|
||||
|
||||
@@ -88,6 +88,36 @@ read over SMB and never printed.
|
||||
- Report: [`aveva-history-801/aveva-gate-sdk2-882.json.gz`](aveva-history-801/aveva-gate-sdk2-882.json.gz), sha256 of the
|
||||
JSON `449e689c…9b27` (label `sdk2-882-008f0b36`: the #882 working tree on top of `008f0b36`).
|
||||
|
||||
## #886 re-run (2026-11-12)
|
||||
|
||||
The same harness with the #886 change: a folder's event history also reads the Galaxy objects behind the native conditions
|
||||
that fire on it, and AVEVA's lower-case `priority` / `alarm_id` / `source_conditionvariable` keys are mapped. Same vd03
|
||||
HistorianGateway `ea9f21c`, same event window, read-only, network-only, **no WinRM**. The API key was read over SMB from
|
||||
vd03's OtOpcUa environment backup, kept in a 0600 file, passed by environment and never printed; the local copy was deleted
|
||||
afterwards.
|
||||
|
||||
**The new case is a realistic equipment folder.** `EQ-886-ZipsenLeft` (UNS) is not named after any Galaxy object. Two native
|
||||
conditions are wired to it, as the applier wires a Galaxy deployment: `Plant/Galaxy/DevWinPlatform/CPULoadHiAlarm`
|
||||
(attributeRef `DevWinPlatform.CPULoadHiAlarm`) and `Plant/Galaxy/Left_001/FRR_Warning` (attributeRef `Left_001.FRR_Warning`),
|
||||
each under its own raw device folder.
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| Folder's own source (what it read before #886) | `EQ-886-ZipsenLeft`: **0 events** in AVEVA |
|
||||
| Whole read, wire | **92 events**: `DevWinPlatform` 2 + `DevWinPlatform.CPULoadAvg` 70 + 20 `Left_001` / `Left_001.*` rows (FRR_Warning alarms, user writes, deploy events). They are exactly the unfiltered read's rows named either object or `<object>.*`, in time order across both objects. |
|
||||
| Paging | 1-event pages (92 pages) and 7-event pages (14 pages) equal the whole read, row for row. |
|
||||
| Reverse | Whole and 5-event pages (19 pages): newest first, ties by EventId descending, equal to the expected order. |
|
||||
| SourceNode / ConditionName | **73 rows** resolve to their live condition: 70 `CPULoadAvg` alarm rows → `Plant/Galaxy/DevWinPlatform/CPULoadHiAlarm` / `CPULoadHiAlarm`, 3 `FRR_Warning` rows → `Plant/Galaxy/Left_001/FRR_Warning` / `FRR_Warning`. Every other row (system and user events) has a null SourceNode. |
|
||||
| Severity | The wire equals the backend's mapping for every row. Alarm rows (`priority` 500 / 700) read **750**; priority-999 system and user events read **1000** (live Galaxy table; see lmxopcua#887 on its direction). Before: 1 for every row. |
|
||||
|
||||
`diff_runs.py` against `aveva-gate-sdk2-882.json.gz`: 226 shared cases, **221 identical**. The 5 that differ are expected:
|
||||
the 4 `DevWinPlatform` event cases (same 72 events, ids, times, sources and messages; only Severity changed from 1 to
|
||||
750 × 70 / 1000 × 2) and `metadata.historyServerCapabilities` (#881, merged after that baseline). Seven cases are new
|
||||
(`events886.*`). Harness failures: 0.
|
||||
|
||||
Report: [`aveva-history-801/aveva-gate-sdk2-886.json.gz`](aveva-history-801/aveva-gate-sdk2-886.json.gz), sha256 of the
|
||||
JSON `6ca314ee…c890` (label `sdk2-886-da948e5f-wt`: the #886 working tree on top of `da948e5f`).
|
||||
|
||||
## Files
|
||||
|
||||
- [`aveva-history-801/aveva-gate-sdk2-d46044f5.json.gz`](aveva-history-801/aveva-gate-sdk2-d46044f5.json.gz), sha256 of the JSON `00b5ecb6…fc27`.
|
||||
|
||||
Binary file not shown.
Reference in New Issue
Block a user