Merge #855 folder event items: per-item delivery under the node manager, ConditionRefresh cut matches the Server object
Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
# Folder (notifier) event items: per-item delivery (Gitea #855)
|
||||
|
||||
Status: design for #855 (owner decision 2026-11-11: build per-item delivery). Background: #838 (deferral instead of
|
||||
blocking under `Lock`), #854 (sequence cut on Server-object refresh), #826 (per-folder event ACL).
|
||||
|
||||
## Problem
|
||||
|
||||
A condition event reaches an event item on an equipment / raw device folder through the SDK's `MonitoredNode2`
|
||||
for that folder: `OnReportEventAsync` writes it to a bounded channel (4096), and a per-node consumer task decides
|
||||
each item's verdict (memoised per `(item, event type, SourceNode)`) and calls `QueueEvent`. That gives the node
|
||||
manager no per-event, per-item decision point, so a `ConditionRefresh` of a folder item cannot withhold an older
|
||||
event that is still in the channel or in our deferral queue: the refresh is overtaken (the #854 guarantee covers only
|
||||
Server-object items). The channel's consumer also needs `Lock` on a verdict miss, which is why a burst under `Lock`
|
||||
fills the channel and defers (#838).
|
||||
|
||||
## Design
|
||||
|
||||
### Where delivery hooks in
|
||||
|
||||
`DeliverConditionEventAsync` already walks the condition's notifier chain hop by hop (our copy of the SDK's
|
||||
`ReportEventAsync`, #838). At a hop whose `OnReportEventAsync` is the SDK `MonitoredNode2` of **a node this manager
|
||||
owns** (`handler.Target is MonitoredNode2 m && m.Node == node`), the walk no longer calls the handler. It delivers the
|
||||
event itself to that node's attached items (`m.EventMonitoredItems`), one by one: the SDK's audit guard, the verdict
|
||||
(`INodeManager3.ValidateEventRolePermissions` — the SDK's type/source `ReceiveEvents` check plus, under enforcement,
|
||||
the #826 live-notifier + grant check), then the item's gate and cut, then `QueueEvent`.
|
||||
|
||||
This is exactly how Server-object items are served (`OnConditionReportEvent`, #586/#854): same verdict per event, same
|
||||
gate, same cut, same `QueueEvent`.
|
||||
|
||||
### Bypass / coexistence with `MonitoredNode2`
|
||||
|
||||
- **Condition events bypass the channel** for our notifiers. The `MonitoredNode2` stays: the SDK still owns item
|
||||
attachment (subscribe / unsubscribe / transfer / tombstone / revalidation stand-down detach), and its channel still
|
||||
carries everything else that reaches the node — a condition's SDK-raised method **audit** events (only with auditing
|
||||
on) and data-change notifications for attribute items on the folder. Those keep the SDK's cached verdict, so
|
||||
`InvalidateFolderEventVerdicts` stays.
|
||||
- A stood-down item is not in `EventMonitoredItems`, so it receives nothing, as before.
|
||||
- A hop whose handler is anything else (none exists today: conditions are never event notifiers and variables cannot
|
||||
host event items) still goes through the handler — the fallback that keeps the #838 deferral reachable.
|
||||
|
||||
### Consequence for overload
|
||||
|
||||
Every hop the node manager owns now completes synchronously: `QueueEvent` never blocks (the item's own queue discards
|
||||
oldest at `QueueSize`), and the verdict runs on the reporter's thread, which already holds `Lock`. So a burst under one
|
||||
`Lock` hold no longer defers at all, and the #838 deadlock shape (a consumer needing `Lock` while the reporter waits on
|
||||
its channel) is gone for condition events. Folder items stay in report order per item, exactly like Server-object items.
|
||||
|
||||
The #838 deferral queue and the #854 cut machinery remain as the safety net for a hop that does suspend (the fallback
|
||||
above, or a future SDK change). Folder items are brought under the same cut:
|
||||
|
||||
- An event whose delivery continues off `Lock` — queued in the deferral queue, **or** the in-flight event whose walk
|
||||
suspended at a hop (new: marked when the walk suspends, so the hops after the suspension take the gate) — takes the
|
||||
item's gate and is withheld when the item's latest refresh cut supersedes it (`RefreshCut.Supersedes`, unchanged).
|
||||
- `ConditionRefresh` / `ConditionRefresh2` of folder items has the same two paths as the Server object, flag on and off:
|
||||
- **Nothing deferred:** the SDK base walk of the item's notifier (off `Lock`, live condition nodes), per-item verdict
|
||||
as before (#826 filter under enforcement). Kept only if no deferral episode existed at any moment of it; otherwise
|
||||
the cut path runs too and supersedes it inside the same RefreshStart..RefreshEnd. Its closing check takes `Lock`
|
||||
once: a report whose walk suspended (marked under `Lock` before suspending) has registered its deferral by then —
|
||||
without it a folder refresh could pass the check in the instant between the suspension and the count.
|
||||
- **Deferring — the cut:** verdicts per (item, condition) first, off `Lock`, from a live walk. Then one `Lock` hold:
|
||||
watermark, episode, the Retain set, and per item the same walk producing frozen snapshots, with the cut + "replay
|
||||
pending" marker installed under the item's gate. The replay is queued off `Lock`, one event per gate hold.
|
||||
- State per item (`EventItemState`, previously Server-object only) is keyed by the item object for its lifetime, so it
|
||||
survives unsubscribe + resubscribe; stale cuts are cleared when the deferral episode ends, for folder and Server items.
|
||||
|
||||
### Locking
|
||||
|
||||
Unchanged order, now for folder items too: `Lock` → item gate → the SDK item's own lock. Synchronous delivery runs
|
||||
under the reporter's `Lock`; the verdict takes `Lock` re-entrantly and the core node manager's / authorizer's locks
|
||||
(as the Server-object path already does). Off-`Lock` (deferred) delivery computes the verdict **before** taking the item
|
||||
gate, so nothing under a gate takes `Lock` or the event-report gate. A reporter waits at most for one in-progress
|
||||
`QueueEvent` on an item; a refresh waits at most for one deferred delivery already inside the gate, never for a drain.
|
||||
No reporter ever waits on a channel.
|
||||
|
||||
### Bounds
|
||||
|
||||
No new queue. Per item: the SDK item queue (`QueueSize`, DiscardOldest). Deferral (only on the fallback): unchanged,
|
||||
1024 per condition / 65 536 total, coalescing. Cuts: one per refreshed item, sets sized by the conditions, cleared at the
|
||||
end of the deferral episode.
|
||||
|
||||
### ACL (#826)
|
||||
|
||||
Each event is decided per item at delivery against the current generation — no memoised verdict for condition events
|
||||
any more, so a deploy / revocation / reference removal takes effect on the next event without waiting for an
|
||||
invalidation. Refresh replays only conditions the item may see (the same check); a condition omitted for want of a grant
|
||||
is never withheld afterwards (the cut's existing rule).
|
||||
|
||||
### Cost
|
||||
|
||||
The per-event verdict for folder items moves from the SDK's consumer task (cached) to the reporter thread under `Lock`
|
||||
(uncached), as Server-object items already pay. Folder subscribers are few (ScadaBridge subscribes at `i=2253`).
|
||||
|
||||
## Tests
|
||||
|
||||
- `ConditionRefreshDeferralWireTests` / `FolderEventFloodWireTests` / `EventQueueOverflowAclWireTests`: deferral is no
|
||||
longer produced by flooding a folder item; tests that need it stall the folder's hop through a test probe
|
||||
(`NotifierDeliveryStall`, null in production) instead of the folder item's SDK lock (which would now block the reporter,
|
||||
as it would on the Server object). Flood tests now pin that folder delivery never defers.
|
||||
- New `FolderConditionRefreshWireTests`: folder-item refresh during deferral (flag on/off, retained / cleared,
|
||||
ConditionRefresh2, resubscribe), the gate race, newer-than-cut replay, ACL omission not withheld, ACL revocation during
|
||||
deferral, the in-flight suspended event, and two stress tests (production overload with no stall; stall + refresh +
|
||||
reports concurrently).
|
||||
Reference in New Issue
Block a user