From 42ad31aded78c490bdb0a0e974e6b8a4c1a594a6 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 23 Jun 2026 19:31:54 -0400 Subject: [PATCH] docs(historian-gateway): brainstormed design for ZB.MOM.WW.HistorianGateway sidecar --- .../2026-06-23-historian-gateway-design.md | 216 ++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 docs/plans/2026-06-23-historian-gateway-design.md diff --git a/docs/plans/2026-06-23-historian-gateway-design.md b/docs/plans/2026-06-23-historian-gateway-design.md new file mode 100644 index 0000000..0f443ff --- /dev/null +++ b/docs/plans/2026-06-23-historian-gateway-design.md @@ -0,0 +1,216 @@ +# ZB.MOM.WW.HistorianGateway — Design + +**Date:** 2026-06-23 +**Status:** Design approved (brainstorming complete) — ready for implementation planning +**Author:** brainstorming session (Joseph Doherty + Claude) + +## 1. Summary + +A new **full-feature sidecar** in the SCADA/OT sister-project family, modelled on +`MxAccessGateway` (`mxaccessgw`). It does two things: + +1. **Read-only Galaxy metadata server** — exposes the AVEVA System Platform + ("Wonderware") **Galaxy object hierarchy** (areas / objects / templates / + instances / attributes), sourced from the **Galaxy Repository SQL DB**, the same + data `mxaccessgw`'s `galaxy_repository` feature serves today. +2. **Full read/write gRPC API to the AVEVA (Wonderware) Historian** — reads (raw, + aggregate with all 15 retrieval modes, at-time, blocks, events, browse, metadata, + status) **and writes** (historical/backfill values, event send, tag-config + create/delete/rename/extended-properties, plus resilience helpers). + +It reuses the family's **common shared packages and styles**: `ZB.MOM.WW.Auth`, +`ZB.MOM.WW.Theme`, `ZB.MOM.WW.Telemetry`(+`.Serilog`), `ZB.MOM.WW.Health`, +`ZB.MOM.WW.Configuration`, `ZB.MOM.WW.Audit`. + +### Key reframing discovered during brainstorming + +- The historian write surface lives in the **`histsdk`** repo + (`gitea.dohertylan.com/dohertj2/histsdk`, namespace `AVEVA.Historian.Client`), + which is **far ahead** of the stale `scadaproj/ZB.MOM.WW.SPHistorianClient` port + (2026-06-19 snapshot, reads + tag create/delete only, value-writes marked + "blocked"). `histsdk` has since added a **live-validated gRPC write surface**: + `AddHistoricalValuesAsync` (historical/backfill, gRPC-only), `SendEventAsync` + (events, both transports), `EnsureTags`/`DeleteTags`/`RenameTags`/ + `AddTagExtendedProperties` (config writes, gRPC), plus higher-level + `HistorianStoreForwardWriter` (durable outbox) and a redundant-write cluster. +- **Hard server-side limit no client can lift:** `AddS2` *streaming live + process-sample* writes are GATED — the historian runtime cache only ingests from + configured IOServer / Application Server pipelines. "Live current value" writes are + therefore done via the **SQL path** (`aaAnalogTagInsert` → `INSERT INTO History`), + not gRPC. +- **No COM anywhere.** The historian SDK is pure-managed and Galaxy browse is plain + SQL, so — unlike `mxaccessgw` — this sidecar needs **no x86 worker and no + two-process split**. It is a single .NET 10 x64 process. + +## 2. Decisions (locked during brainstorming) + +| Decision | Choice | +|---|---| +| Purpose | **General-purpose gateway** — reusable modern façade over Historian + Galaxy metadata for any gRPC client (the way `mxaccessgw` is the façade for MXAccess). | +| Historian client code | **Vendor `histsdk`** (`AVEVA.Historian.Client`) into the sidecar repo as self-contained vendored source; namespace kept as-is to ease future re-sync. | +| Galaxy browse code | **New shared lib `ZB.MOM.WW.GalaxyRepository`** in scadaproj, extracted from `mxaccessgw`'s `galaxy_repository` browse; consumed by both `mxaccessgw` and this sidecar. | +| Dashboard | **Full Blazor dashboard** on `ZB.MOM.WW.Theme` (login + Galaxy browser + Historian console + API-key admin + status/health). | +| Historian write scope | **All:** historical/backfill writes, event send, tag-config writes, **and** resilience extras (store-and-forward outbox, redundant write fan-out, SQL live-value path). | +| Connection model | **Approach A — stateless gateway over pooled service-identity connections.** Clients authenticate to the gateway (ZB API key); the gateway owns historian credentials and reuses pooled, pre-authenticated connections. | +| Repo location | **New standalone sibling repo** `~/Desktop/HistorianGateway`, gitea remote `historiangw`. | +| Name / namespace | **`ZB.MOM.WW.HistorianGateway`**. | + +## 3. Architecture & solution structure + +Single .NET 10 x64 ASP.NET Core process. + +``` +~/Desktop/HistorianGateway/ + src/ + ZB.MOM.WW.HistorianGateway.Server/ ASP.NET Core host: gRPC services + Blazor dashboard + /healthz + /metrics + ZB.MOM.WW.HistorianGateway.Contracts/ the gateway's own .proto + generated types (for client codegen distribution) + vendor/AVEVA.Historian.Client/ VENDORED from histsdk; ArchestrA.Grpc.Contract.* protos + reads/writes/store-forward/redundancy + tests/ + ZB.MOM.WW.HistorianGateway.Tests/ unit + env-gated live integration + bUnit dashboard + docs/plans/, CLAUDE.md, README.md + ZB.MOM.WW.HistorianGateway.slnx +``` + +**Cross-repo pieces:** + +- **`scadaproj/ZB.MOM.WW.GalaxyRepository`** (new shared lib, plain files — NOT a + nested git repo): carries the **canonical `galaxy_repository.proto`** (adopted from + `mxaccessgw`'s existing contract so OtOpcUa's wire shape is not broken), the SQL + browse provider (connect to Galaxy Repository SQL → hierarchy model), and a + reusable gRPC service implementation both hosts can `MapGrpcService<>()`. + `mxaccessgw` adopting it is a **tracked follow-on** (same "built → adopted" pattern + as the other normalized components); this sidecar consumes it from the start. +- **Shared ZB packages consumed:** `ZB.MOM.WW.Auth` + (Abstractions+Ldap+ApiKeys+AspNetCore), `ZB.MOM.WW.Theme`, `ZB.MOM.WW.Telemetry` + (+`.Serilog`), `ZB.MOM.WW.Health`, `ZB.MOM.WW.Configuration`, `ZB.MOM.WW.Audit`. + +## 4. gRPC API surface + +Gateway's own curated contract (`ZB.MOM.WW.HistorianGateway.Grpc.V1`), grouped by +concern — not a 1:1 SDK dump. The vendored `ArchestrA.Grpc.Contract.*` protos stay +internal; clients see only the gateway contract. + +| Service | RPCs | Notes | +|---|---|---| +| `HistorianRead` | `ReadRaw`, `ReadAggregate`, `ReadBlocks`, `ReadEvents` *(server-streaming)*; `ReadAtTime` | `ReadAggregate` exposes all 15 retrieval modes | +| `HistorianWrite` | `AddHistoricalValues`, `SendEvent`, `WriteLiveValues` | `WriteLiveValues` = SQL path (gRPC streaming is gated) | +| `HistorianTags` | `BrowseTagNames` *(streaming)*, `GetTagMetadata`, `EnsureTags`, `DeleteTags`, `RenameTags`, `AddTagExtendedProperties` | | +| `HistorianStatus` | `Probe`, `GetConnectionStatus`, `GetStoreForwardStatus`, `GetSystemParameter` | | +| `GalaxyRepository` | Browse areas / objects / templates / instances / attributes *(read-only)* | canonical proto from the shared lib | + +**Authorization** is via **API-key scopes at the gateway** (Approach A trust +boundary): `historian:read`, `historian:write`, `historian:tags:write`, +`galaxy:read`. + +## 5. Connection & data flow + +``` +gRPC client ──(ZB API key)──► HistorianGateway ──┬─ pooled, pre-authed gRPC conn ──► AVEVA Historian (RemoteGrpc 2023R2) + ├─ store-forward outbox (SQLite) ─ replays writes on reconnect + ├─ redundant-write fan-out ──────► historian members (All/Any ack) + ├─ SqlConnection ──► Runtime DB (live-value writes via aaAnalogTagInsert/History) + └─ ZB.MOM.WW.GalaxyRepository ──► Galaxy Repository SQL (read-only browse) +``` + +- **Pooled connections:** the expensive auth handshake (`ValidateClientCredential` / + ECDH `ExchangeKey`) runs **once per connection on open**, then is reused across + requests; connections are health-checked with auto-reconnect. Write operations use + the write-enabled session mode (`0x401`). +- **Store-forward:** writes flow through the SDK's `HistorianStoreForwardWriter` — on + an unreachable historian, enqueue to durable SQLite; a background drain replays on + reconnect. +- **Redundancy:** `HistorianRedundantWriteResult` fan-out to configured members under + an All/Any ack policy; per-member result surfaced to the caller. +- **SQL live-write** and **Galaxy browse** are independent SQL paths, each with its + own validated connection config. + +**Configuration** (all `ZB.MOM.WW.Configuration`-validated, aggregated by +`ConfigPreflight` at startup): historian (host, gRPC port 32565, transport=RemoteGrpc, +TLS, service identity/credentials), redundant members, store-forward path, Galaxy +Repository SQL connection string, Runtime DB connection string (SQL live-write), +Auth (LDAP + API-key pepper). Secrets live in the operator environment, never in repo. + +## 6. Cross-cutting infrastructure + dashboard + +- **Auth (`ZB.MOM.WW.Auth`):** gRPC clients use peppered-HMAC API keys (keyId/Bearer), + validated by a gRPC interceptor enforcing per-service scopes. Dashboard uses LDAP + login (`.Ldap`+`.AspNetCore`), cookie auth, `IGroupRoleMapper`, canonical + `ZbClaimTypes`/`ZbCookieDefaults`, canonical-six roles, dev against the shared + GLAuth (`10.100.0.35:3893`, `dc=zb,dc=local`). `DisableLogin` dev/deploy switch. +- **Telemetry (`.Telemetry`+`.Serilog`):** `AddZbTelemetry` (Resource + `service.name=historian-gateway` + standard instrumentation + always-on Prometheus + `/metrics`, OTLP opt-in) + `AddZbSerilog`. App Meters: read/write counts + latency, + store-forward queue depth, pool connection state, redundancy ack outcomes. +- **Health (`.Health`):** three-tier ready/active/healthz + canonical JSON writer. + Probes: historian gRPC (`GrpcDependencyHealthCheck`), Galaxy Repository SQL + + Runtime DB (`DatabaseHealthCheck`), store-forward drain status. +- **Configuration (`.Configuration`):** `OptionsValidatorBase` / `ValidationBuilder` / + `AddValidatedOptions` / `ConfigPreflight` (§5). +- **Audit (`.Audit`, DEEP-adopt):** canonical `AuditEvent` + SQLite `IAuditWriter` + (MxGateway-style). Audited: tag-config writes, historical/event writes, API-key + admin, login/logout. `Actor` wired from the Auth principal via `IAuditActorAccessor`. +- **Dashboard (Blazor, `.Theme`):** Technical-Light side-rail shell + `LoginCard` + `/login`. Pages: **Status** (pool / store-forward / redundancy / version), + **Galaxy browser** (read-only hierarchy tree), **Historian console** (query with + raw/aggregate + mode picker + time range; role-gated write test for value insert / + event send), **API-key admin** (list/create/revoke keys + scopes), **Health**. + +## 7. Error handling + +- **gRPC status mapping:** `ProtocolEvidenceMissingException` (unsupported op/type — + e.g. non-analog tag, non-string event property) → `Unimplemented`/`FailedPrecondition` + with a clear "not in reverse-engineered surface" message; auth → + `Unauthenticated`/`PermissionDenied`; historian down → `Unavailable`; bad range / + unknown tag → `InvalidArgument`/`NotFound`. +- **Gated ops:** live streaming-sample writes (`AddS2`) are **not exposed** (no RPC); + live-value writes route through SQL `WriteLiveValues`. +- **Write resilience:** with store-forward enabled, an unreachable historian returns + *accepted + queued* (not an error); otherwise `Unavailable`. Redundancy surfaces a + per-member result; All-policy fails if any member fails, Any-policy succeeds on ≥1 ack. +- **Pool:** transient failures → reconnect + bounded retry; auth-handshake failure → + fail fast with diagnostic. No secrets/real hostnames in errors or logs (histsdk + safety rule). + +## 8. Testing + +- **Unit:** gRPC services against a faked historian-client seam + faked Galaxy + provider; scope/auth interceptor; config validators; SDK-model ↔ proto mapping. +- **Golden/protocol:** carry over `histsdk`'s golden byte tests for the vendored + client (historical "ON" buffer, event "OS" buffer, registration buffers) so the + vendored copy stays faithful. +- **Integration (env-gated, live, CI/macOS-safe):** real 2023 R2 historian + Galaxy + Repository SQL — read/write round-trips and browse via the self-cleaning + sandbox-tag lifecycle (`HISTORIAN_GRPC_WRITE_SANDBOX_TAG`); skipped when env vars + absent. +- **Dashboard:** bUnit component tests. **Smoke:** `/healthz`, `/metrics`, gRPC + `Probe`. + +## 9. Out of scope / non-goals + +- `AddS2` live streaming process-sample writes (GATED server-side; SQL path covers + live values instead). +- Non-analog tag creation, revision/edit writes, bit-faithful store-forward framing + (per `histsdk` capability matrix — `BOUNDED`/`HARD`/`GATED` items not selected). +- A two-process / x86 worker split (not needed — no COM). +- Re-syncing or replacing the existing stale `scadaproj/ZB.MOM.WW.SPHistorianClient` + port (we vendor `histsdk` instead; the stale port is left as-is). + +## 10. Implementation components (high level) + +1. **`ZB.MOM.WW.GalaxyRepository` shared lib** (scadaproj) — extract from + `mxaccessgw`, canonical proto + SQL browse provider + reusable gRPC service. +2. **Vendor `histsdk`** `AVEVA.Historian.Client` into the new repo + carry its golden + tests. +3. **Repo scaffold + host + shared-package wiring** (Auth/Telemetry/Health/ + Configuration/Audit) + validated options + `ConfigPreflight`. +4. **gRPC contract + services** (Read / Write / Tags / Status / GalaxyRepository). +5. **Connection layer** — pooled pre-authed connections, store-forward, redundancy, + SQL live-write path. +6. **Auth** — API-key scope interceptor + LDAP dashboard auth + Audit wiring. +7. **Blazor dashboard** pages (Theme). +8. **Telemetry + Health** probes/meters. +9. **Tests** — unit / golden / env-gated integration / bUnit. +10. **Docs + repo/gitea setup** — `CLAUDE.md`, `README.md`, gitea remote. + +> `mxaccessgw` adoption of `ZB.MOM.WW.GalaxyRepository` is a separate tracked +> follow-on, not part of the initial sidecar delivery.