2 Commits

Author SHA1 Message Date
Joseph Doherty 64c9793b91 docs(c2): correct event-read gating messages — WCF not served on 2023 R2
The gRPC ReadEvents throws no longer advise "use the WCF transport for event
reads": that path is moot on 2023 R2 (net.tcp is reset at the framing layer,
live-disproven 2026-06-25). Messages now state event reads are auth-solved but
server-gated over gRPC and have no WCF fallback on 2023 R2, citing the two
evidence docs. WCF orchestrator remarks scoped to legacy 2020 historians; row
layout noted as decoded. String/comment only; throw behavior unchanged.

Claude-Session: https://claude.ai/code/session_012SDSQ3AcaXqPcBtDESBRii
2026-06-25 17:11:19 -04:00
Joseph Doherty f1c57f7149 docs(c2): record WCF event-read spike live result (RED — transport not served on 2023 R2)
WCF net.tcp (RemoteTcpIntegrated) against the live 2023 R2 historian is reset
at the socket-write/framing layer before any auth — both the event spike and a
basic Probe/ReadRaw throw the identical CommunicationException/SocketException
("forcibly closed by the remote host"). The 2023 R2 box does not serve the
legacy WCF transport; C2's "route via WCF" unblock is moot on this server class.
Sanitized: counts + native return codes + buffer lengths only.

Claude-Session: https://claude.ai/code/session_012SDSQ3AcaXqPcBtDESBRii
2026-06-25 16:58:56 -04:00
3 changed files with 93 additions and 18 deletions
@@ -0,0 +1,63 @@
# WCF event-read spike — live result (2026-06-25): WCF transport not served on 2023 R2
Settles the open question behind **C2** ("event reads over gRPC are gated; the only listed unblock is
*route event reads via WCF*"). The gRPC event-read path is a proven server-side dead-end
(`grpc-event-query-capture.md`: auth fully solved, every client-controllable layer byte-matched to the
stock client, yet the server scopes 0 rows to our connection). This spike tested the **WCF** leg.
## What was run
A Windows-only, env-gated diagnostic (`tests/AVEVA.Historian.Client.Tests/WcfEventReadSpikeTests.cs`,
gated by `HISTORIAN_WCF_EVENT_HOST`) drove `HistorianWcfEventOrchestrator.ReadEventsAsync` directly
over `RemoteTcpIntegrated` (WCF `net.tcp`, port 32568) against the **live 2023 R2 historian**, with a
−90d window (the engine holds tens of thousands of events in that range), run from the native Windows
capture rig over VPN. Auth supplied as explicit domain credentials (consumed by the app-level
`ValidateClientCredential` SSPI rounds).
## Result — RED (transport not served), sanitized
Event spike:
| field | value |
|---|---|
| outcome | `THREW System.ServiceModel.CommunicationException` ("The socket connection was aborted") |
| inner | `System.Net.Sockets.SocketException` — "An existing connection was forcibly closed by the remote host" |
| events observed | 0 |
| LastUpdC3ReturnCode / LastRTag2ReturnCode / LastAddReturnCode(EnsT2) | 0 / 0 / 0 |
| LastEnsT2PayloadSha256 | empty |
| LastResultBufferLength | 0 |
All native return codes are `0` and the EnsT2 payload sha256 is empty: the chain failed at the **first
WCF call** (`GetInterfaceVersion`), *before* any auth token round or CM_EVENT registration ran.
Corroboration — a basic (non-event) `RemoteTcpIntegrated` `ProbeAsync` + `ReadRawAsync` (the committed
`RemoteTcpIntegrationTests`) throws the **identical** exception, with the stack landing in
`System.ServiceModel.Channels.SocketConnection.WriteAsync` — i.e. the failure is **transport-wide**, not
event-specific, and not auth-specific (it never reaches auth).
Phase 0 (reachability) had confirmed TCP 32568 is **open** (the connect succeeds). So the port accepts a
socket, but the moment the SDK writes its `net.tcp` binary-SOAP framing the server **resets the
connection** (RST at the socket-write layer).
## Conclusion
The **2023 R2 historian does not serve the legacy WCF NetTcp transport.** A raw RST at the first socket
write — before any security negotiation, SOAP fault, or auth exchange — is the signature of a listener
that does not speak `net.tcp` binary SOAP, not of an auth/SPN problem or event-row scoping. (The earlier
WCF event-chain native return codes 76/85 documented in `HistorianWcfEventOrchestrator` were only ever
observed against a **2020** historian; against 2023 R2 there is no WCF endpoint to reach at all.)
Therefore **C2's "route event reads via WCF" unblock is moot on 2023 R2** — there is no WCF endpoint to
route to. Event reads are unavailable on the 2023 R2 historian over **both** transports:
- **gRPC** — auth-solved but retrieval-server-gated (server scopes 0 rows to our connection;
`grpc-event-query-capture.md`).
- **WCF (`net.tcp`)** — transport not served on 2023 R2 (connection reset at framing).
The WCF event-read managed path would only ever apply to a legacy **2020** historian, which the gateway
does not target (the gateway runs `RemoteGrpc` against 2023 R2). The only remaining theoretical unblock
is server-side (AVEVA exposing event-row retrieval to a managed gRPC connection) — not client-fixable.
**C2 is closed won't-fix** for the gateway's target (2023 R2). `ReadEventsAsync` over gRPC keeps its
honest no-row throw; the gating messages are corrected so they no longer point operators at the WCF
transport as a live fallback on 2023 R2.
@@ -34,13 +34,16 @@ namespace AVEVA.Historian.Client.Grpc;
/// (the read path proved the front-door session is sufficient over gRPC).
/// </para>
/// <para>
/// <b>Live status (2026-06-22):</b> the chain runs end-to-end and <c>StartEventQuery</c> succeeds, but
/// <c>GetNextEventQueryResultBuffer</c> <b>long-polls</b> when the query has no rows — it blocks to the
/// call deadline instead of returning the synchronous 5-byte code-85 terminal the 2020 WCF op returns.
/// A poll-deadline expiry is therefore treated as the no-data terminal (see the loop). The idle dev box
/// holds no events, so <b>row-level retrieval is not yet live-verified</b>; verifying parsed rows over
/// gRPC awaits an event-bearing 2023 R2 server. This is tooled + completes cleanly, NOT proven to
/// return rows.
/// <b>Live status — server-gated (settled 2026-06-25):</b> the chain runs end-to-end and
/// <c>StartEventQuery</c> succeeds, but <c>GetNextEventQueryResultBuffer</c> <b>long-polls</b> to the
/// no-data terminal (instead of the synchronous 5-byte code-85 terminal the 2020 WCF op returns); a
/// poll-deadline expiry is treated as that terminal (see the loop). This is <b>not</b> an empty-box
/// artifact: the live 2023 R2 server holds tens of thousands of events yet scopes <b>0 rows</b> to a
/// managed connection. Every client-controllable layer was byte-matched to the stock client that returns
/// rows (see <c>docs/reverse-engineering/grpc-event-query-capture.md</c>) — the gate is a server-internal
/// per-connection retrieval working-set, <b>not client-fixable</b>. The legacy WCF transport is not a
/// fallback on 2023 R2 (<c>docs/reverse-engineering/wcf-event-read-spike-results.md</c>). Tooled +
/// completes cleanly, but proven NOT to return rows over a managed connection.
/// </para>
/// </summary>
internal sealed class HistorianGrpcEventOrchestrator
@@ -101,9 +104,11 @@ internal sealed class HistorianGrpcEventOrchestrator
{
throw new ProtocolEvidenceMissingException(
$"ReadEvents over gRPC did not return rows within {OverallBudget.TotalSeconds:0}s: StartEventQuery " +
"succeeds but the CM_EVENT registration replay stalls and GetNextEventQueryResultBuffer long-polls " +
"(no synchronous code-85 terminal over gRPC). Row-level retrieval is not yet verified over gRPC " +
"(the dev box holds no events) — use the WCF transport for event reads.");
"succeeds but GetNextEventQueryResultBuffer long-polls to the no-data terminal. Event-row retrieval " +
"over gRPC is auth-solved but server-gated — the 2023 R2 server scopes 0 rows to a managed connection " +
"(see docs/reverse-engineering/grpc-event-query-capture.md). The legacy WCF transport is NOT a fallback " +
"on 2023 R2 (live-disproven 2026-06-25: net.tcp is reset at the framing layer — see " +
"docs/reverse-engineering/wcf-event-read-spike-results.md), so there is no event-read path on a 2023 R2 historian.");
}
foreach (HistorianEvent evt in events)
@@ -169,16 +174,19 @@ internal sealed class HistorianGrpcEventOrchestrator
// reaches the no-data terminal with ZERO rows (the gRPC server long-polls GetNext rather than
// returning the WCF code-85 terminal), we cannot distinguish "genuinely no events in range"
// from "the CM_EVENT registration replay didn't fully land over gRPC" — so we refuse to return
// a possibly-false empty list and surface the unverified state instead. An event-bearing 2023 R2
// server will return rows here and exercise the parse path; flip this once that is captured.
// a possibly-false empty list and surface the gated state instead. Proven server-gated: the live
// 2023 R2 server holds tens of thousands of events yet scopes 0 to a managed gRPC connection
// (grpc-event-query-capture.md); WCF is not a 2023 R2 fallback (wcf-event-read-spike-results.md).
if (events.Count == 0)
{
throw new ProtocolEvidenceMissingException(
"ReadEvents over gRPC: the chain completes and StartEventQuery succeeds, but " +
"GetNextEventQueryResultBuffer returns no rows (it long-polls to the no-data terminal " +
$"after the CM_EVENT registration replay; last={LastErrorBufferDescription}). Row-level " +
"retrieval is not yet verified over gRPC (the dev box holds no events) — use the WCF " +
"transport for event reads until a capture against an event-bearing 2023 R2 server confirms it.");
$"after the CM_EVENT registration replay; last={LastErrorBufferDescription}). Event-row retrieval " +
"over gRPC is auth-solved but server-gated — the 2023 R2 server scopes 0 rows to a managed connection " +
"(see docs/reverse-engineering/grpc-event-query-capture.md). The legacy WCF transport is NOT a fallback " +
"on 2023 R2 (live-disproven 2026-06-25: net.tcp is reset at the framing layer — see " +
"docs/reverse-engineering/wcf-event-read-spike-results.md).");
}
return events;
@@ -9,9 +9,13 @@ namespace AVEVA.Historian.Client.Wcf;
/// <remarks>
/// Mirrors HistorianWcfReadOrchestrator but targets IRetrievalServiceContract4 for the event flow.
/// Event row buffer layout is undecoded as of this pass — when StartEventQuery succeeds, this
/// orchestrator returns an empty enumeration but logs the row-buffer length via the
/// <see cref="LastResultBufferLength"/> diagnostic so a follow-up capture can decode the wire shape.
/// Applies to <b>legacy 2020-era WCF (net.tcp) historians only</b>. The event row-buffer layout is now
/// decoded (<see cref="HistorianEventRowProtocol"/>; verified against real captured rows). Note: a
/// <b>2023 R2</b> historian does NOT serve this WCF transport at all — net.tcp is reset at the framing
/// layer before any auth (live-disproven 2026-06-25; see
/// <c>docs/reverse-engineering/wcf-event-read-spike-results.md</c>), so this orchestrator is not a
/// fallback for 2023 R2 deployments. The native return codes 76/85 noted below were 2020-historian
/// observations.
/// </remarks>
internal sealed class HistorianWcfEventOrchestrator
{