Fifth PR of the alarms-over-gateway epic
(docs/plans/alarms-over-gateway.md). Depends on PR C.1
(AahClientManagedAlarmEventWriter), already merged.
Today HistorianFrameHandler is constructed at Program.cs line 57
without an alarmWriter, so every WriteAlarmEvents frame replies
"Sidecar not configured with an alarm-event writer" and the lmxopcua
side keeps the row queued. C.2 wires a real writer behind a new
OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED toggle.
- Program.BuildAlarmWriter — gated on the env var (default true,
fail-open under accidental misconfiguration). Constructs an
AahClientManagedAlarmEventWriter wrapping a
SdkAlarmHistorianWriteBackend with the same connection config the
read path uses.
- Install-Services.ps1 — appends OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=true
to the OtOpcUaWonderwareHistorian service env block when the
sidecar is installed. Read-only deployments flip it to false at
service-config edit time without re-installing.
- HistorianFrameHandler signature already accepts
IAlarmEventWriter? — supplying non-null at line 57 lights up
the WriteAlarmEvents reply path that's been dormant since PR 3.3.
Until PR D.1 pins the live aahClientManaged entry point, the
SdkAlarmHistorianWriteBackend reports RetryPlease for every event
with a structured diagnostic. The lmxopcua-side
SqliteStoreAndForwardSink retains queued events; same effective
behaviour as today's NullAlarmHistorianSink fallback but with
visible diagnostics rather than silent discard.
Tests:
- 6 BuildAlarmWriter env-var cases — unset / true / false /
unrecognized → default-on / capitalization variants.
- Full sidecar test suite: 56 passed (was 48; 8 new).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fourth PR of the alarms-over-gateway epic
(docs/plans/alarms-over-gateway.md). Independent of Tracks A and B —
the sidecar slot defined in HistorianFrameHandler line 242 is unwired
today; PR C.2 (next) flips it on in Program.cs.
- AlarmHistorianWriteOutcome (sidecar-local, net48 — twin of
Core.AlarmHistorian.HistorianWriteOutcome which is net10): Ack /
RetryPlease / PermanentFail.
- IAlarmHistorianWriteBackend abstraction so the SDK call can be
faked in unit tests.
- AahClientManagedAlarmEventWriter implements IAlarmEventWriter,
delegates to the backend, maps Ack→true / Retry|Permanent→false
for the IPC bool[] reply contract. Backend exception → whole
batch RetryPlease (preserves the sender's queue across transients
rather than dropping). Wrong-count return defends against a
backend bug desyncing queue accounting.
- SdkAlarmHistorianWriteBackend — production binding skeleton.
Reports RetryPlease for every event and logs a structured
diagnostic until PR D.1 pins the live aahClientManaged entry
point against the dev rig. The sender's SqliteStoreAndForwardSink
retains queued events, mirroring today's NullAlarmHistorianSink
behaviour but with visible diagnostics instead of silent discard.
- MapOutcome shared helper — pinned via theory tests so the D.1
swap can change the SDK call site without reshuffling the
HRESULT → outcome mapping.
Tests:
- 6 writer tests — empty batch / single Ack / mixed Ack-Retry-
Permanent-Ack ordering / backend-throw → RetryPlease batch /
cancellation propagates / wrong-count defensive degrade.
- 5 outcome theory cases — hresult 0 → Ack, malformed wins over
hresult 0, comm error → Retry, unknown failure → Retry,
malformed + comm → Permanent.
- Full sidecar test suite: 48 passed (was 42; 6 new).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The sidecar was set to PlatformTarget=x86 + Prefer32Bit=true to mirror
v1's Driver.Galaxy.Host bitness, which itself was x86 only because of
MXAccess COM. PR 7.2 retired Galaxy.Host, so that constraint is gone.
AVEVA Historian 2020 ships an x64 build of every SDK assembly the
sidecar needs (lib\aahClientManaged.dll + aahClient.dll + aahClientCommon.dll
sourced from C:\Program Files (x86)\Wonderware\Historian\x64\; the
remaining three SDK assemblies — Historian.CBE / DPAPI /
ArchestrA.CloudHistorian.Contract — are pure-managed AnyCPU and load
in either bitness). Drop PlatformTarget to x64 on both the sidecar
project and its test project; running 37/37 historian tests + the
live install confirms the SDK loads and serves the named pipe in a
64-bit-native process.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sidecar now serves a length-prefixed, kind-tagged MessagePack pipe protocol
mirroring Galaxy.Host's: 4-byte BE length + 1-byte MessageKind + body, 16 MiB
cap. Hello handshake validates per-process shared secret + protocol major
version + caller SID via ImpersonateNamedPipeClient before any work frame
runs.
Five contract pairs ship in this PR:
ReadRawRequest ↔ ReadRawReply
ReadProcessedRequest ↔ ReadProcessedReply
ReadAtTimeRequest ↔ ReadAtTimeReply
ReadEventsRequest ↔ ReadEventsReply
WriteAlarmEventsRequest ↔ WriteAlarmEventsReply
Timestamps cross the wire as DateTime ticks (long) to dodge MessagePack's
DateTime kind/timezone quirks; both sides convert with DateTime(ticks, Utc).
Sample values cross as MessagePack-serialized byte[] so the .NET 10 client
(PR 3.4) deserializes per the tag's mx_data_type without the sidecar needing
to know OPC UA types.
HistorianFrameHandler dispatches by MessageKind to IHistorianDataSource (the
PR 3.2 lifted interface) for reads, and to a new IAlarmEventWriter strategy
for the alarm-event persistence path. Per-call exceptions surface as
Success=false replies so a single bad request doesn't kill the connection.
WriteAlarmEvents replies carry per-event success flags; the SQLite
store-and-forward sink retries failed slots on the next drain tick.
Program.cs spins the pipe server when OTOPCUA_HISTORIAN_ENABLED=true. Pipe-
only mode (default false) preserves PR 3.1's smoke-test behaviour: the host
still validates env vars and waits for Ctrl-C, but doesn't initialize the
Wonderware SDK.
Sidecar test project gains 8 round-trip tests (37 total now): every contract
pair round-trips through FrameReader/FrameWriter via in-memory streams, the
handler surfaces historian exceptions cleanly, WriteAlarmEvents per-event
status flows through, and the no-writer-configured path returns a clean
error reply.
Added MessagePack 2.5.187 to the sidecar csproj.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move all historian implementation files from Driver.Galaxy.Host/Backend/Historian/
to Driver.Historian.Wonderware/Backend/. Sidecar now owns the aahClientManaged /
aahClientCommon SDK references; Galaxy.Host project-references the sidecar so
MxAccessGalaxyBackend keeps building until PR 7.2 retires Galaxy.Host entirely.
10 source files moved (preserving git history via git mv):
IHistorianDataSource, HistorianDataSource, HistorianClusterEndpointPicker,
HistorianClusterNodeState, HistorianConfiguration, HistorianEventDto,
HistorianHealthSnapshot, HistorianQualityMapper, HistorianSample,
IHistorianConnectionFactory.
2 historian tests moved alongside (HistorianClusterEndpointPickerTests,
HistorianQualityMapperTests). Sidecar test project now hosts 29 tests (1 PR 3.1
smoke + 28 moved historian tests, all passing).
Galaxy.Host's remaining 6 historian-flavored tests (HistorianWiringTests,
HistoryReadAtTimeTests, HistoryReadEventsTests, HistoryReadProcessedTests)
keep passing via the project reference — using directives updated to reach
the new namespace.
Sidecar deliberately speaks no Core.Abstractions — its surface is the legacy
List<HistorianSample> shape; PR 3.4's .NET 10 client translates to the
Core.Abstractions shapes added in PR 1.1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
