docs(grpc): transport matrix + plan reflect ReadEvents + live-verified writes
- README transport matrix: gRPC writes (EnsureTag/DeleteTag/RenameTags/ AddTagExtendedProperties) flip to live-verified; note the async-rename retry and the extended-property read-back parser gap. ReadEvents gRPC -> tooled-but-bounded (StartEventQuery works, GetNext long-polls, throws on no-row pending an event-bearing server). Refresh the closing production-pattern guidance. - grpc-tooling-completion.md: mark items #1 (writes, done) and #2 (ReadEvents, tooled/bounded) with the live outcomes and follow-ups. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
This commit is contained in:
@@ -88,10 +88,10 @@ request rides the RPC but the server faults on an unmet precondition) ·
|
||||
| `GetRuntimeParameterAsync` | ✅ | ✅ | tooled + live-verified over gRPC (`StatusService.GetRuntimeParameter`, the 2020 `GETRP` buffers ride unchanged) |
|
||||
| `GetTagExtendedPropertiesAsync` | ✅ | ✅ | tooled + live-verified over gRPC (`RetrievalService.GetTagExtendedPropertiesFromName`, the `GetTepByNm` buffers ride unchanged) |
|
||||
| `ExecuteSqlCommandAsync` | ✅ | ⛔ | gRPC request rides `RetrievalService.ExecuteSqlCommand`, but the server-side `CSrvDbConnection.ExecuteSqlCommand` faults (`IndexOutOfRange`, native err 38) — an unmet DB-connection precondition; bounded behind `ProtocolEvidenceMissingException`. Use WCF |
|
||||
| `ReadEventsAsync` | ✅ | 🔌 | gRPC `StartEventQuery`/`GetNextEventQueryResultBuffer`/`EndEventQuery` recovered, but the read needs the full CM_EVENT registration state machine (RTag2+EnsT2) ported — not yet tooled |
|
||||
| `ReadEventsAsync` | ✅ | ⚠️ | tooled + routed over gRPC: the full CM_EVENT registration replay (`UpdateClientStatus`→`RegisterTags`→`EnsureTags` + discovery probes) runs and `StartEventQuery` succeeds, but `GetNextEventQueryResultBuffer` **long-polls** on no data (it blocks to the deadline rather than returning the synchronous 5-byte code-85 terminal the WCF op gives). The read is **hard-bounded** (≤30s) and throws `ProtocolEvidenceMissingException` on the no-row path rather than assert a false empty. Row-level retrieval is **not yet live-verified** — the dev box holds no events; pending a capture against an event-bearing 2023 R2 server. Use WCF for event reads |
|
||||
| `SendEventAsync` | ✅ | 🔌 | rides `AddStreamValues` family; no distinct event-send RPC, framing uncaptured over gRPC |
|
||||
| `EnsureTagAsync` / `DeleteTagAsync` / `RenameTagsAsync` | ✅ | 🧪 | tooled + routed over gRPC (`HistoryService.EnsureTags` / `DeleteTags` / `StartJob`, write-enabled 0x401 session, WCF serializers reused); sandbox-gated — not yet run destructively against a live box |
|
||||
| `AddTagExtendedPropertiesAsync` | ✅ | 🧪 | tooled + routed over gRPC (`HistoryService.AddTagExtendedProperties`, write-enabled session); sandbox-gated. gRPC also exposes `DeleteTagExtendedProperties` (WCF delete was server-blocked) |
|
||||
| `EnsureTagAsync` / `DeleteTagAsync` / `RenameTagsAsync` | ✅ | ✅ | live-verified 2026-06-22 over gRPC (`HistoryService.EnsureTags` / `DeleteTags` / `StartJob`, write-enabled 0x401 session, WCF serializers reused) via a self-cleaning sandbox-tag lifecycle. Rename is an async StartJob — transiently rejectable right after create, so callers should retry |
|
||||
| `AddTagExtendedPropertiesAsync` | ✅ | ✅ | live-verified 2026-06-22 over gRPC (`HistoryService.AddTagExtendedProperties`, write-enabled session). NOTE: reading a written prop back via `GetTagExtendedPropertiesAsync` can hit a shared-parser evidence gap (value marker `0x01` vs the captured compact-string `0x09`); the write itself is confirmed. gRPC also exposes `DeleteTagExtendedProperties` (WCF delete was server-blocked) |
|
||||
| `GetConnectionStatusAsync` | ✅ | ❌ | synthesized from an authenticated probe — no dedicated RPC on either transport (gRPC `PingServer`/`GetHistorianConsoleStatus` could synthesize it) |
|
||||
| `ReadBlocksAsync` | ❌ | ❌ | `StartBlockRetrievalQuery` never captured on either transport — throws `ProtocolEvidenceMissingException` |
|
||||
|
||||
@@ -105,12 +105,20 @@ confirmed by tooling the read-side config ops (`GetRuntimeParameter`,
|
||||
the server accepts them. Two caveats surfaced when capturing the rest: `ExecuteSqlCommand`
|
||||
is **server-walled** (the front-door `CSrvDbConnection` faults on a DB-connection
|
||||
precondition the managed session doesn't establish — the same *class* of wall as
|
||||
`OpenStorageConnection`), and `ReadEvents` needs the CM_EVENT registration state
|
||||
machine ported. The remaining 🔌 rows are **capture-and-wire** items (route the
|
||||
existing serializer into a gRPC orchestrator + live-capture), not
|
||||
protocol-discovery — but per "capture first, never guess wire bytes" they stay
|
||||
untooled until each is verified live. The natural production pattern today remains
|
||||
WCF for config/writes and `RemoteGrpc` for reads + `AddHistoricalValuesAsync`.
|
||||
`OpenStorageConnection`), and `ReadEvents` is now tooled over gRPC (the CM_EVENT
|
||||
registration state machine is ported and `StartEventQuery` succeeds) but its row
|
||||
retrieval is not yet live-verified: the gRPC server long-polls
|
||||
`GetNextEventQueryResultBuffer` on no data instead of returning the WCF code-85
|
||||
terminal, so on the idle dev box the bounded read throws
|
||||
`ProtocolEvidenceMissingException` rather than fabricate an empty result —
|
||||
confirming rows awaits an event-bearing 2023 R2 server. The remaining 🔌 row
|
||||
(`SendEventAsync`) is a **capture-and-wire** item (route the existing serializer
|
||||
into a gRPC orchestrator + live-capture), not protocol-discovery — but per
|
||||
"capture first, never guess wire bytes" it stays untooled until verified live. The
|
||||
natural production pattern today: `RemoteGrpc` now covers reads,
|
||||
`AddHistoricalValuesAsync`, and the tag-config writes (create/delete/rename/extended
|
||||
properties, live-verified) — use WCF for SQL, events, and reading extended
|
||||
properties back until those gRPC gaps close.
|
||||
|
||||
> A 2023 R2 server reports History interface version 12 (vs. 11 on 2020). The
|
||||
> connect-time version gate accepts both — they are byte-compatible — so gRPC
|
||||
|
||||
Reference in New Issue
Block a user