docs(historian): fix-wave docs and stale comments
- Historian.md: Empty samples always Bad (writer/updater/read clamp), long-name refusal, 5 s bootstrap failure cache, AtTime after now, info-bit masking, HistoryUpdate does NOT type-check (M-1 decision), DeleteRaw needs both bounds, reverse Raw paging, the historian/historization metric prefixes, and provisioning numeric-only lines qualified as Gateway. - CLAUDE.md numeric-only lines qualified as Gateway backend. - Stale 'sole historian' lines in DriverLifecycle, ServiceHosting and the retired Wonderware stub; Client.CLI exit-code contract. - ServerHistorianOptions: Endpoint/Backend XML docs untangled, Validate() indented; Program.cs comments are backend-neutral; T10 week-test day count. Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
This commit is contained in:
Joseph Doherty
@@ -1414,9 +1414,10 @@ only the recorder + outbox knobs:
|
||||
hook for added historized value tags — and, since #600.1, for **changed** raw tags that flip to historized or change their resolved historian name or DataType — the gateway-backed `GatewayTagProvisioner` calls the gateway's
|
||||
`EnsureTags` so a brand-new historized tag exists in the historian before the recorder's `WriteLiveValues`
|
||||
land. The hook is wrapped so a faulted/synchronously-throwing provisioner can **never** block or fail a
|
||||
deploy. Non-numeric (`String`/`DateTime`/`Reference`) data types are skipped (not provisioned); the
|
||||
recorder likewise drops + meters non-numeric values. Continuous historization is **numeric-analog only** in
|
||||
v1 (`UInt16→UInt4` is a documented fallback).
|
||||
deploy. **Gateway backend:** non-numeric (`String`/`DateTime`/`Reference`) data types are skipped (not
|
||||
provisioned), the recorder likewise drops + meters non-numeric values, and continuous historization is
|
||||
**numeric-analog only** (`UInt16→UInt4` is a documented fallback). The **SqlServer** backend provisions and
|
||||
records every type (see "Pluggable backends" above).
|
||||
|
||||
The provisioner is registered by the Host's `AddHistorianProvisioning` (`Runtime.ServiceCollectionExtensions`),
|
||||
built via `GatewayHistorian.CreateProvisioner`, and **gated on the same `ServerHistorian:Enabled` flag as the
|
||||
|
||||
+4
-2
@@ -225,8 +225,10 @@ otopcua-cli historyread -u opc.tcp://localhost:4840/OtOpcUa \
|
||||
|
||||
Inserts, replaces, updates or deletes stored history on a historized node via the OPC UA `HistoryUpdate`
|
||||
service (requires a server whose historian backend supports updates and a session holding the history-write
|
||||
permission). Prints one line per item (`index time StatusCodeName`) followed by the overall service
|
||||
result; any Bad item or service result exits non-zero.
|
||||
permission). Prints one line per item (`index time StatusCodeName`; a code the SDK has no name for prints as
|
||||
`0xXXXXXXXX`) followed by the overall service result. It exits non-zero unless **every** result is Good: a Bad
|
||||
**or Uncertain** item, a non-Good node or service result, or a Good service result that is missing per-item
|
||||
results (fewer than the items sent, printed as `(no result returned)`) all fail the command.
|
||||
|
||||
```bash
|
||||
# Insert two values
|
||||
|
||||
@@ -620,8 +620,9 @@ Implementation:
|
||||
`GatewayAlarmHistorianWriter` (the gateway `SendEvent` path; see
|
||||
[AlarmHistorian.md](AlarmHistorian.md)).
|
||||
|
||||
The HistorianGateway is the sole historian backend; its config keys and
|
||||
deployment prerequisites are in [Historian.md](Historian.md).
|
||||
The historian backend is pluggable (`ServerHistorian:Backend` = `Gateway`, the default, or `SqlServer`);
|
||||
the HistorianGateway is the Gateway backend. Config keys and deployment prerequisites for both are in
|
||||
[Historian.md](Historian.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
+50
-12
@@ -278,6 +278,10 @@ holds during the FasterLog recovery scan at start-up); the lifetime count is the
|
||||
**`otopcua.historian.outbox.unreadable`** (`IHistorizationOutbox.UnreadableCount`). A growing value means
|
||||
undecodable records are being skipped.
|
||||
|
||||
> **Metric prefixes differ.** The outbox's other two gauges are `otopcua.historization.outbox.depth` and
|
||||
> `otopcua.historization.outbox.dropped`; the unreadable gauge is **`otopcua.historian.outbox.unreadable`**
|
||||
> (the name the design fixed). All three describe the same outbox — search for both prefixes.
|
||||
|
||||
⚠️ **Rollback: drain or delete the outbox before downgrading.** A node running a pre-v2 build cannot read v2
|
||||
records — its outbox deserializes every record in its constructor and fails to start on the first v2 one. Before
|
||||
rolling a node back, let the outbox drain to zero (`otopcua.historization.outbox.depth`) or stop the node and
|
||||
@@ -287,8 +291,12 @@ Upgrading needs no action.
|
||||
**Delivery semantics on `SqlServer`.** Writes are *insert-if-absent* on `(TagId, SourceTimeUtc)`: the outbox's
|
||||
at-least-once redelivery (and both pair nodes writing the same sample in a boot window) converges on one row, and the
|
||||
first-stored sample wins. **Duplicate timestamps inside one batch collapse to the first.** A `NaN` / `±Infinity` `Double`
|
||||
cannot be stored in a SQL `float`, so the **value writer stores it as an `Empty` sample keeping its status** — the tag
|
||||
is not quarantined for one bad reading (HistoryUpdate behaves differently: see [below](#historyupdate)). A duplicate-key
|
||||
cannot be stored in a SQL `float`, so the **value writer stores it as an `Empty` sample** — the tag is not quarantined for
|
||||
one bad reading (HistoryUpdate behaves differently: see [below](#historyupdate)). ⚠️ **An `Empty` sample is always Bad**
|
||||
(the quality contract: a stored sample is never served better than "no value"): a non-finite `Double` that arrived with a
|
||||
Good or Uncertain status is stored as `Empty` + **`BadOutOfRange`** (`0x803C0000`), and any other `Empty` with a non-Bad
|
||||
status as `Empty` + **`BadNoData`** (`0x809B0000`). An existing Bad code — the comms-loss `BadNoCommunication` marker, a
|
||||
driver's own Bad publish — is stored as it is. A duplicate-key
|
||||
error (2627/2601) rolls the whole statement back, so the writer re-runs the statement (at most twice) instead of
|
||||
treating the error as success.
|
||||
|
||||
@@ -362,21 +370,22 @@ values are counted in `RecorderStatus.SuppressedNotPrimary`, and each gate trans
|
||||
## Tag auto-provisioning (EnsureTags)
|
||||
|
||||
When a deploy adds a historized tag, the server auto-ensures it exists in the historian via the gateway's
|
||||
`EnsureTags` **before** the first value or HistoryRead lands. `AddressSpaceApplier.Apply()` fires a
|
||||
`EnsureTags` (Gateway) or the `Tag`-row `MERGE` (SqlServer) **before** the first value or HistoryRead lands. `AddressSpaceApplier.Apply()` fires a
|
||||
**non-blocking, fire-and-forget** `IHistorianProvisioning.EnsureTagsAsync` for each added historized value
|
||||
tag (with the resolved historian name — the `historianTagname` override when set, else the driver
|
||||
`FullName`); the hook is wrapped so a faulted, slow, or throwing provisioner can **never** block or fail a
|
||||
deploy. Non-numeric (`String`/`DateTime`/`Reference`) types are skipped, not provisioned.
|
||||
deploy. On the **Gateway backend**, non-numeric (`String`/`DateTime`/`Reference`) types are skipped, not provisioned;
|
||||
the SqlServer backend provisions every type (below).
|
||||
|
||||
**Wiring + gating.** The concrete provisioner comes from the selected backend's provider (`CreateProvisioning`):
|
||||
the gateway-backed `GatewayTagProvisioner`, or — for `SqlServer` — `SqlServerTagProvisioner` (one `MERGE … WITH (HOLDLOCK)`
|
||||
upsert per chunk of 400 tags; every data type is provisionable so `skipped` is always 0; a blank or over-400-character
|
||||
name fails alone; a null unit/description in a request keeps the stored value). It is registered by the Host's
|
||||
`AddHistorianProvisioning` and gated on the **same**
|
||||
`ServerHistorian:Enabled` flag as the read path — both target the same single gateway. When the section is
|
||||
`ServerHistorian:Enabled` flag as the read path — both use the one resolved backend. When the section is
|
||||
disabled (or absent) the applier resolves the no-op `NullHistorianProvisioning` and **provisioning does not
|
||||
run** (so on a read-only-historian deployment, ensure tags exist by some other means). The Host requires the
|
||||
API key to carry the `historian:tags:write` scope for `EnsureTags` to succeed.
|
||||
run** (so on a read-only-historian deployment, ensure tags exist by some other means). On the Gateway backend the
|
||||
API key must carry the `historian:tags:write` scope for `EnsureTags` to succeed.
|
||||
|
||||
**Observability.** Every dispatch logs an Information tally —
|
||||
`historian provisioning completed (dispatched=N, requested=…, ensured=…, skipped=…, failed=…)`. A line
|
||||
@@ -530,6 +539,11 @@ paging time-based:
|
||||
> `NumValuesPerNode` samples at a time across successive pages, advancing the cursor one tick past
|
||||
> the timestamp once the cluster is fully drained.
|
||||
>
|
||||
> **Reverse reads** (`start > end`, newest first) page the same way in the opposite direction: a drained
|
||||
> cluster steps the cursor one tick **down**, the read ends when that would reach the (excluded) `end`, and
|
||||
> the over-fetched cluster is sliced in descending order. Before the fix a reverse read with a small
|
||||
> `NumValuesPerNode` stopped after its first page with `GoodNoData`.
|
||||
>
|
||||
> **Short pages within a cluster still carry a continuation point.** A within-cluster page that
|
||||
> returns fewer than `NumValuesPerNode` samples (because the cluster happened to be smaller than
|
||||
> the cap, or is the final partial batch) is not the last page if the cluster itself has not been
|
||||
@@ -643,12 +657,22 @@ everywhere (full 100 ns precision — never a `DataTable`, which would round to
|
||||
transient SQL errors (connection, timeout, deadlock 1205 …), bootstrap failures, cancellation and any unclassified error;
|
||||
`PermanentFail` (dead-letter) only for data errors SQL will reject forever (truncation 2628/8152, conversion, null, range, constraint).
|
||||
`SourceName` is the event's `EquipmentPath`; `Severity` is the numeric Part 9 value (Low 200, Medium 500, High 700, Critical 900).
|
||||
- **Tag names** are `nvarchar(400)`. `EnsureTags` fails a longer name individually, but the live-value writer's tag-create
|
||||
path does **not** reject one (the parameter silently truncates) — keep historian tagnames under 400 characters.
|
||||
- **Tag names** are `nvarchar(400)`, and a longer name is **refused, never truncated** (a truncating parameter would resolve
|
||||
it onto whichever tag owns its first 400 characters): `EnsureTags` fails it individually, the live-value writer returns
|
||||
`false` for that tag (a per-tag failure, so the #538 quarantine eventually abandons it — logged as a Warning), the updater
|
||||
answers `BadInvalidArgument` for every item, and reads treat it as not found (Raw empty, AtTime / Processed `BadNoData`). An
|
||||
event read filtered by a source name over 400 characters returns no events. Keep historian tagnames under 400 characters.
|
||||
- **Schema bootstrap failures are cached for 5 s.** With `AutoCreateSchema=false` and the schema missing (or SQL down), every
|
||||
historian call fails fast with the last bootstrap error for 5 s before SQL is tried again, so a missing schema does not
|
||||
serialise every write, read and alarm event behind one round-trip each; each retry that fails logs a Warning. If
|
||||
`sp_releaseapplock` fails after an auto-create, the connection pool is cleared so the session holding the applock is closed
|
||||
rather than returned to the pool.
|
||||
|
||||
### Raw reads
|
||||
|
||||
`ReadRawAsync` returns every sample as stored — outage markers (`Empty` + Bad status) included.
|
||||
`ReadRawAsync` returns every sample as stored — outage markers (`Empty` + Bad status) included. The one exception is defensive:
|
||||
a row with no value whose stored status is **not** Bad (only a build from before the writer forced `Empty` samples Bad could
|
||||
have written one) is served with `BadNoData`, on Raw and AtTime alike.
|
||||
|
||||
| Request | Window | Order |
|
||||
|---|---|---|
|
||||
@@ -674,6 +698,10 @@ outage marker and counts as Bad whatever its code). Per requested time `T` (the
|
||||
| `p` usable, **`n` Bad** | **`p`'s value held** (not interpolated into the outage), `UncertainDataSubNormal` + Interpolated |
|
||||
| `Double` / `Int64` with a usable `n` | linear interpolation of `NumValue`; `Int64` is computed **through `double`** and rounded to the nearest integer (ties away from zero), keeping the `Int64` type. Status `Good` + Interpolated when both neighbours are Good, else `UncertainDataSubNormal` + Interpolated |
|
||||
| `Boolean` / `String` / `DateTime`, **or `T` after the last sample** | **stepped**: `p`'s value with `p`'s status + Interpolated |
|
||||
| `T` after the last sample **and after now** | `p`'s value held, `UncertainDataSubNormal` + Interpolated (the value is not known to still hold) |
|
||||
|
||||
Setting Interpolated (or, in aggregates, Calculated) first clears any historian bit the stored status already carries, so a
|
||||
result never has both.
|
||||
|
||||
⚠️ Because `Int64` interpolation goes through `double`, magnitudes beyond 2^53 lose precision.
|
||||
|
||||
@@ -791,8 +819,18 @@ mixed (Part 11 reports item outcomes in `OperationResults`); it is Bad only for
|
||||
|
||||
**Per-item rejections** (answered without touching SQL; other items still proceed): a null item ⇒ `BadInvalidArgument`;
|
||||
`SourceTimestamp == DateTime.MinValue` ⇒ `BadInvalidTimestamp`; a value the historian cannot type (array, unsupported CLR type) ⇒
|
||||
`BadTypeMismatch`; and a **`NaN` / `±Infinity` `Double` ⇒ `BadInvalidArgument`** — it cannot live in a SQL `float`, and unlike the live-value
|
||||
writer (which stores it as `Empty`) an operator's explicit update is rejected rather than silently rewritten. A caller-supplied status code is stored as given.
|
||||
`BadTypeMismatch`; a **`NaN` / `±Infinity` `Double` ⇒ `BadInvalidArgument`** — it cannot live in a SQL `float`, and unlike the live-value
|
||||
writer (which stores it as `Empty`) an operator's explicit update is rejected rather than silently rewritten; and a **null value with a
|
||||
Good or Uncertain status ⇒ `BadInvalidArgument`** — an `Empty` sample is always Bad, so a null value is accepted only with a Bad status
|
||||
(an operator-authored outage marker). A caller-supplied status code is otherwise stored as given.
|
||||
|
||||
**No DataType check.** HistoryUpdate does **not** compare a value's type with the node's `DataType`: a value is stored as sent (a `String`
|
||||
written to a `Double` node's history is stored and later read back as a `String`), exactly as the live recorder stores whatever type the
|
||||
driver publishes. Only a value the historian cannot represent at all is refused (`BadTypeMismatch`, above). Part 11 §6.8 permits a
|
||||
server to answer `BadTypeMismatch` for a value of the wrong type; this server deliberately does not.
|
||||
|
||||
**`DeleteRawModifiedDetails` needs both bounds:** a `StartTime` or `EndTime` of `DateTime.MinValue` (the wire's "unspecified") is
|
||||
`BadInvalidArgument` for that node and never reaches the backend.
|
||||
|
||||
**Duplicate timestamps inside one request** (compared at 100 ns): *Insert* — the first occurrence is applied, later ones are `BadEntryExists`;
|
||||
*Replace* / *Update* — the last one wins and every earlier occurrence reports the winner's code; *DeleteAtTime* — the first reports the real
|
||||
|
||||
@@ -8,7 +8,7 @@ A production OtOpcUa deployment runs **one binary per node**. The historian back
|
||||
| Process | Project | Runtime | Platform | Responsibility |
|
||||
|---|---|---|---|---|
|
||||
| **OtOpcUa Host** | `src/Server/ZB.MOM.WW.OtOpcUa.Host` | .NET 10 | AnyCPU | Single fused binary. The resolved [`EffectiveRoles`](#role-gating) decides what to mount: `admin` (Blazor + auth + control-plane singletons), `driver` (OPC UA endpoint + per-driver actors), or both. |
|
||||
| **ZB.MOM.WW.HistorianGateway** *(external — separate deployment)* | not in this repo | .NET 10 | — | The sole historian backend. OtOpcUa talks gRPC to it (via the `ZB.MOM.WW.HistorianGateway.Client` package) for HistoryRead, alarm `SendEvent`, and continuous `WriteLiveValues`. Must run `RuntimeDb:Enabled=true` + `RuntimeDb:EventReadsEnabled=true`; the API key must carry `historian:read` + `historian:write` + `historian:tags:write`. |
|
||||
| **ZB.MOM.WW.HistorianGateway** *(external — separate deployment)* | not in this repo | .NET 10 | — | The default historian backend (`ServerHistorian:Backend=Gateway`; `SqlServer` needs no sidecar). OtOpcUa talks gRPC to it (via the `ZB.MOM.WW.HistorianGateway.Client` package) for HistoryRead, alarm `SendEvent`, and continuous `WriteLiveValues`. Must run `RuntimeDb:Enabled=true` + `RuntimeDb:EventReadsEnabled=true`; the API key must carry `historian:read` + `historian:write` + `historian:tags:write`. |
|
||||
|
||||
Galaxy access still uses the separately-installed **mxaccessgw** sidecar (see `docs/v2/Galaxy.ParityRig.md`); the gateway owns the MXAccess COM bitness constraint (its worker is x86 net48). Nothing in the OtOpcUa repo carries that constraint anymore. (The bespoke Wonderware historian sidecar this deployment used to ship was retired — see [drivers/Historian.Wonderware.md](drivers/Historian.Wonderware.md).)
|
||||
|
||||
|
||||
@@ -2,8 +2,9 @@
|
||||
|
||||
> **This backend has been retired.** The bespoke Wonderware TCP/ArchestrA historian sidecar
|
||||
> (`OtOpcUaWonderwareHistorian`) and its `Driver.Historian.Wonderware*` projects — plus the vestigial
|
||||
> `Historian.Wonderware` driver type — were removed. **HistorianGateway is now the sole historian
|
||||
> backend** for OtOpcUa (read, alarm-write, and continuous historization).
|
||||
> `Historian.Wonderware` driver type — were removed. **HistorianGateway is now the default historian
|
||||
> backend** for OtOpcUa (read, alarm-write, and continuous historization); a plain SQL Server backend is the
|
||||
> alternative (`ServerHistorian:Backend=SqlServer`, see [Historian.md](../Historian.md)).
|
||||
|
||||
## What replaced it
|
||||
|
||||
|
||||
@@ -265,30 +265,29 @@ if (hasDriver)
|
||||
|
||||
// Config-gated server-side HistoryRead backend. When the ServerHistorian section is enabled this
|
||||
// overrides the NullHistorianDataSource default from AddOtOpcUaRuntime (last registration wins) with
|
||||
// a read-only HistorianGateway-backed data source the node manager's HistoryRead overrides
|
||||
// block-bridge to. The factory lives in the Gateway driver (which owns the package-client adapter
|
||||
// and the ServerHistorianOptions -> client-options mapping); Runtime owns the gating.
|
||||
// the selected backend's data source (Gateway or SqlServer, built by the resolved provider) that the
|
||||
// node manager's HistoryRead overrides block-bridge to. Runtime owns the gating.
|
||||
builder.Services.AddServerHistorian(
|
||||
builder.Configuration,
|
||||
(_, sp) => historianProvider.CreateDataSource(sp));
|
||||
|
||||
// Config-gated historian tag provisioning. When the ServerHistorian section is enabled this registers the
|
||||
// gateway-backed GatewayTagProvisioner (overriding the NullHistorianProvisioning default) so that deploying
|
||||
// a historized tag auto-ensures it in the historian via the gateway's EnsureTags. The AddressSpaceApplier
|
||||
// (constructed in WithOtOpcUaRuntimeActors) resolves IHistorianProvisioning and fires a non-blocking
|
||||
// EnsureTagsAsync for added historized tags on every deploy; without this registration the applier falls
|
||||
// back to the no-op NullHistorianProvisioning and provisioning never reaches the gateway. Gated on the SAME
|
||||
// ServerHistorian:Enabled flag as the read path — both target the same single gateway.
|
||||
// selected backend's provisioner (GatewayTagProvisioner -> the gateway's EnsureTags, or the SqlServer Tag-row
|
||||
// MERGE), overriding the NullHistorianProvisioning default, so deploying a historized tag auto-ensures it in
|
||||
// the historian. The AddressSpaceApplier (constructed in WithOtOpcUaRuntimeActors) resolves
|
||||
// IHistorianProvisioning and fires a non-blocking EnsureTagsAsync for added/changed historized tags on every
|
||||
// deploy; without this registration the applier falls back to the no-op NullHistorianProvisioning. Gated on
|
||||
// the SAME ServerHistorian:Enabled flag as the read path — both use the one resolved backend.
|
||||
builder.Services.AddHistorianProvisioning(
|
||||
builder.Configuration,
|
||||
(_, sp) => historianProvider.CreateProvisioning(sp));
|
||||
|
||||
// Continuous historization of driver (non-Galaxy) tag values. Gated on ContinuousHistorization:Enabled
|
||||
// AND the ServerHistorian gateway being configured: the recorder drains driver-tag live values to the
|
||||
// SAME single gateway's WriteLiveValues SQL path, sourcing endpoint/key/TLS from the ServerHistorian
|
||||
// section (this section carries only the recorder + outbox knobs). When both are on, register the durable
|
||||
// crash-safe outbox + the gateway-backed live-value writer here; WithOtOpcUaRuntimeActors (below) spawns
|
||||
// the recorder actor itself, gated on the same options.
|
||||
// AND ServerHistorian:Enabled: the recorder drains driver-tag live values through the selected backend's
|
||||
// value writer (the gateway's WriteLiveValues, or the SqlServer Sample table), which takes its connection
|
||||
// from the ServerHistorian section (this section carries only the recorder + outbox knobs). When both are
|
||||
// on, register the durable crash-safe outbox + the backend's live-value writer here;
|
||||
// WithOtOpcUaRuntimeActors (below) spawns the recorder actor itself, gated on the same options.
|
||||
var continuousHistorizationOptions = builder.Configuration
|
||||
.GetSection(ContinuousHistorizationOptions.SectionName).Get<ContinuousHistorizationOptions>()
|
||||
?? new ContinuousHistorizationOptions();
|
||||
@@ -317,8 +316,9 @@ if (hasDriver)
|
||||
return outbox;
|
||||
});
|
||||
|
||||
// Gateway-backed live-value writer over its OWN gRPC channel to the same single gateway (a second
|
||||
// channel to a co-located sidecar is cheap — the gateway pools the historian sessions server-side).
|
||||
// The backend's live-value writer. On Gateway it opens its OWN gRPC channel to the same gateway (a second
|
||||
// channel to a co-located sidecar is cheap — the gateway pools the historian sessions server-side); on
|
||||
// SqlServer it shares the provider's connection helper, schema bootstrapper and tag catalog.
|
||||
builder.Services.AddSingleton<IHistorianValueWriter>(sp => historianProvider.CreateValueWriter(sp));
|
||||
}
|
||||
|
||||
|
||||
@@ -4,12 +4,13 @@ namespace ZB.MOM.WW.OtOpcUa.Runtime.Historian;
|
||||
|
||||
/// <summary>
|
||||
/// Binds the <c>ServerHistorian</c> configuration section that gates the server-side
|
||||
/// HistoryRead backend. When <see cref="Enabled"/> is <c>true</c>, <c>AddServerHistorian</c>
|
||||
/// registers a read-only <c>HistorianGateway</c>-backed <c>IHistorianDataSource</c> (supplied by
|
||||
/// historian. <see cref="Backend"/> selects the provider (<c>Gateway</c> by default, or <c>SqlServer</c>,
|
||||
/// whose own keys live in the <c>ServerHistorian:SqlServer</c> sub-section). When <see cref="Enabled"/> is
|
||||
/// <c>true</c>, <c>AddServerHistorian</c> registers that backend's <c>IHistorianDataSource</c> (supplied by
|
||||
/// the Host) in place of the <c>NullHistorianDataSource</c> default; otherwise the Null default
|
||||
/// survives and HistoryRead returns <c>GoodNoData</c>-empty.
|
||||
/// <para>
|
||||
/// The read client talks gRPC to the <c>ZB.MOM.WW.HistorianGateway</c> sidecar
|
||||
/// On the Gateway backend the read client talks gRPC to the <c>ZB.MOM.WW.HistorianGateway</c> sidecar
|
||||
/// (<c>historian_gateway.v1</c>) over <see cref="Endpoint"/>, authenticating with the
|
||||
/// peppered-HMAC <see cref="ApiKey"/> (<c>histgw_<id>_<secret></c>) in the
|
||||
/// <c>Authorization: Bearer</c> header. This is the READ path only — there are no
|
||||
@@ -24,17 +25,12 @@ public sealed class ServerHistorianOptions
|
||||
public const string SectionName = "ServerHistorian";
|
||||
|
||||
/// <summary>
|
||||
/// When <c>true</c>, the HistorianGateway read client is registered as the
|
||||
/// When <c>true</c>, the selected backend's data source is registered as the
|
||||
/// <c>IHistorianDataSource</c>; when <c>false</c> (the default) the no-op
|
||||
/// <c>NullHistorianDataSource</c> stays in place and HistoryRead returns empty.
|
||||
/// </summary>
|
||||
public bool Enabled { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Absolute gateway endpoint URI the read client dials (e.g. <c>https://host:5222</c>).
|
||||
/// The scheme selects the transport: <c>https://</c> = TLS, <c>http://</c> = h2c plaintext.
|
||||
/// Required when <see cref="Enabled"/> is <c>true</c>.
|
||||
/// </summary>
|
||||
/// <summary>
|
||||
/// Selects the historian backend provider (case-insensitive). Default <c>"Gateway"</c>; the Host's
|
||||
/// <c>HistorianBackendRegistry</c> owns the set of valid names. Gateway-specific keys
|
||||
@@ -49,6 +45,12 @@ public sealed class ServerHistorianOptions
|
||||
public bool IsGatewayBackend =>
|
||||
string.Equals(Backend?.Trim(), GatewayBackendName, StringComparison.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Gateway backend only: absolute gateway endpoint URI the read client dials (e.g.
|
||||
/// <c>https://host:5222</c>). The scheme selects the transport: <c>https://</c> = TLS, <c>http://</c> = h2c
|
||||
/// plaintext. Required when the Gateway backend is consumed (<see cref="Enabled"/>, or an enabled
|
||||
/// <c>AlarmHistorian</c>).
|
||||
/// </summary>
|
||||
public string Endpoint { get; init; } = "";
|
||||
|
||||
/// <summary>
|
||||
@@ -129,17 +131,17 @@ public sealed class ServerHistorianOptions
|
||||
// Gateway-specific checks apply only to the Gateway backend (other backends carry their own options).
|
||||
if (IsGatewayBackend)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(Endpoint))
|
||||
warnings.Add("ServerHistorian:Endpoint is empty while the historian is enabled — the read client has no gateway address to dial.");
|
||||
// archreview 06/S-11 warning parity: a non-empty but unparseable / non-absolute-http(s) Endpoint
|
||||
// is just as fatal (it throws in the gateway client factory). Warn on it here so the Runtime-side
|
||||
// registration logs describe malformed endpoints too, consistent with the Host's fail-fast
|
||||
// ServerHistorianOptionsValidator (which turns this same condition into a startup failure).
|
||||
else if (!Uri.TryCreate(Endpoint, UriKind.Absolute, out var uri)
|
||||
|| (uri.Scheme != Uri.UriSchemeHttp && uri.Scheme != Uri.UriSchemeHttps))
|
||||
warnings.Add($"ServerHistorian:Endpoint ('{Endpoint}') is not an absolute http(s) URI while the historian is enabled — the read client cannot dial it (e.g. https://host:5222).");
|
||||
if (string.IsNullOrWhiteSpace(ApiKey))
|
||||
warnings.Add("ServerHistorian:ApiKey is empty while the historian is enabled — the gateway gRPC surface will reject unauthenticated calls.");
|
||||
if (string.IsNullOrWhiteSpace(Endpoint))
|
||||
warnings.Add("ServerHistorian:Endpoint is empty while the historian is enabled — the read client has no gateway address to dial.");
|
||||
// archreview 06/S-11 warning parity: a non-empty but unparseable / non-absolute-http(s) Endpoint
|
||||
// is just as fatal (it throws in the gateway client factory). Warn on it here so the Runtime-side
|
||||
// registration logs describe malformed endpoints too, consistent with the Host's fail-fast
|
||||
// ServerHistorianOptionsValidator (which turns this same condition into a startup failure).
|
||||
else if (!Uri.TryCreate(Endpoint, UriKind.Absolute, out var uri)
|
||||
|| (uri.Scheme != Uri.UriSchemeHttp && uri.Scheme != Uri.UriSchemeHttps))
|
||||
warnings.Add($"ServerHistorian:Endpoint ('{Endpoint}') is not an absolute http(s) URI while the historian is enabled — the read client cannot dial it (e.g. https://host:5222).");
|
||||
if (string.IsNullOrWhiteSpace(ApiKey))
|
||||
warnings.Add("ServerHistorian:ApiKey is empty while the historian is enabled — the gateway gRPC surface will reject unauthenticated calls.");
|
||||
}
|
||||
// MaxTieClusterOverfetch is intentionally checked AFTER the Enabled early-return above:
|
||||
// the over-fetch code path only runs when a real IHistorianDataSource is wired in,
|
||||
|
||||
+1
-1
@@ -187,7 +187,7 @@ public sealed class ProcessedReadTests(SqlHistorianFixture fx)
|
||||
public async Task A_weekly_interval_over_four_centuries_lands_samples_in_the_right_week()
|
||||
{
|
||||
// Hand-computed (calendar arithmetic, independent of SQL): 1601-01-01 → 2027-01-01 is 155 593 days =
|
||||
// 22 227.57 weeks ⇒ 22 228 intervals (under the 100k cap). 2026-10-09 08:00 is 155 498 days in ⇒ week
|
||||
// 22 227.57 weeks ⇒ 22 228 intervals (under the 100k cap). 2026-10-09 08:00 is 155 509 days in ⇒ week
|
||||
// index 22 215, which starts Monday 2026-10-05 00:00; every fixture sample (t0 … t0+40 s) is in it.
|
||||
var db = await ReadTestDb.CreateAsync(fx);
|
||||
await db.SeedAAsync();
|
||||
|
||||
Reference in New Issue
Block a user