diff --git a/CLAUDE.md b/CLAUDE.md index 89e33b34..fee02b58 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1347,7 +1347,7 @@ historian tagname, which is the tag's driver `FullName`. - **QuestDB** (`Driver.Historian.QuestDb`, `ServerHistorian:QuestDb:*`, Npgsql over PG wire; docker-dev overlay `docker-compose.questdb.yml`): same kinds/status/aggregates/HistoryUpdate as SqlServer, soft delete by tombstone (INSERT only — never `UPDATE`/`DELETE`; every read filters `NOT deleted`). ⚠️ **Timestamps are µs** (`QuestDbConnection.Round`/`BindTimestamp`; `IHistorianDataSource.TimestampResolutionTicks` = 10 steps HistoryRead paging), **pre-1970 cannot be stored** (writer drops, HistoryUpdate `BadOutOfRange`), every write waits for WAL visibility, TTL is enforced on write commits only, set Npgsql `Maximum Pool Size` < QuestDB's 64. `docs/Historian.md` §"QuestDB backend". - **Real status fix:** the recorder used to stamp every sample Good (`192`); it now carries the driver's status. ⚠️ On the **Gateway** backend this changes nothing stored: the gateway discards quality (C-002), so AVEVA still stores Good. - **Comms loss is historized as an outage marker** (`Empty` + `BadNoCommunication`, one per tag per outage) on SqlServer; dropped (`DroppedUnsupportedKind`) on Gateway. Outbox records are **format v2** — drain or delete `ContinuousHistorization:OutboxPath` before downgrading a node. -- **HistoryUpdate** (SqlServer only; Gateway ⇒ `BadHistoryOperationUnsupported`): Insert/Replace/Update/DeleteRaw/DeleteAtTime, gated in both ACL modes — flag off needs the `HistoryUpdate` role from a **Cluster-scoped** grant (+ key re-check), flag on uses `DataPlaneAuthorizer`'s HistoryUpdate operation; `WriteOperate` never implies it. The `HistoryWrite` AccessLevel bit is set only when an updater is wired at materialise time. `docs/Historian.md` §HistoryUpdate, `docs/security.md`. +- **HistoryUpdate** (SqlServer + QuestDb; Gateway ⇒ `BadHistoryOperationUnsupported`): Insert/Replace/Update/DeleteRaw/DeleteAtTime, **Primary-only** since #674 (off-Primary ⇒ `BadInvalidState`, after authorization, same `IDriverPrimaryRoleSource` verdict as the native-ack gate; reads ungated), items with a `SourceTimestamp` past now + `ServerHistorian:HistoryUpdateMaxFutureSkew` (default 1 day, ≤0 disables) ⇒ `BadOutOfRange` in the node manager (every backend), gated in both ACL modes — flag off needs the `HistoryUpdate` role from a **Cluster-scoped** grant (+ key re-check), flag on uses `DataPlaneAuthorizer`'s HistoryUpdate operation; `WriteOperate` never implies it. The `HistoryWrite` AccessLevel bit is set only when an updater is wired at materialise time. `docs/Historian.md` §HistoryUpdate, `docs/security.md`. ⚠️ **SqlServer schema v1 is accepted (#674)** with `AutoCreateSchema=false`: writes/reads/events/retention work; modified reads + HistoryUpdate ⇒ `BadHistoryOperationUnsupported` (nothing sent), retention skips `SampleModified`, one Warning per boot (`SqlServerSchemaBootstrapper.SupportsModifiedTrail`; `RequiredVersion` = 1, `ModifiedTrailVersion` = 2). QuestDB: keep `cairo.ttl.use.wall.clock=true`; a QuestDB trail INSERT retried after a client timeout duplicates (no DEDUP key). - **Modified-value history (#668, Part 11):** every applied HistoryUpdate item leaves a trail row (prior value, principal from the session's API key / `anonymous`, `HistoryModificationType`, time) — SqlServer `hist.SampleModified` (**schema v2**, written by `OUTPUT … INTO` in the same statement ⇒ atomic; ⚠️ no FK/CHECK/trigger on it, and `AutoCreateSchema=false` installs must run `002_sample_modified.sql` before upgrading), QuestDB `{p}sample_modified` (append-only, written **before** the change ⇒ a crash leaves an orphan trail row, never an untracked change). `IsReadModified=true` HistoryRead serves it as `HistoryModifiedData` via `IHistorianDataSource.ReadModifiedAsync` (default ⇒ `NotSupported` ⇒ `BadHistoryOperationUnsupported` on Gateway/Null), paged on `(SourceTime, ModifiedId)`, gated by plain HistoryRead. Live writes and retention never write it; retention/TTL purge it on source time. `IHistorianDataUpdater` methods take a `HistoryUpdateContext`. CLI `historyread --modified`. `docs/Historian.md` §Modified-value history. ### Read path (`ServerHistorian` section) diff --git a/docs/Configuration.md b/docs/Configuration.md index 6e0bb3fb..55c0487b 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -410,7 +410,7 @@ Validated at host start (driver-role nodes) when `ServerHistorian:Enabled` **or* | `ServerHistorian:SqlServer:ConnectionString` | `""` | **Required.** Historian database connection string (not the ConfigDb). Supply via `${secret:OT-HISTORIAN-SQL}` or env `ServerHistorian__SqlServer__ConnectionString`; the database must already exist. | | `ServerHistorian:SqlServer:Schema` | `hist` | Must match `^[A-Za-z_][A-Za-z0-9_]{0,127}$` (spliced into DDL/DML). | | `ServerHistorian:SqlServer:CommandTimeout` | `00:00:30` | Must be `> 0`; rounded up to whole seconds. | -| `ServerHistorian:SqlServer:AutoCreateSchema` | `true` | `true` applies the embedded schema script under an app-lock on first use; `false` only verifies `SchemaVersion >= 1` and fails every historian call (health `LastError`, no crash) if behind. | +| `ServerHistorian:SqlServer:AutoCreateSchema` | `true` | `true` applies the embedded schema scripts under an app-lock on first use (upgrading a v1 schema to v2); `false` only verifies `SchemaVersion >= 1` and fails every historian call (health `LastError`, no crash) if behind. A verified **v1** schema (no `002_sample_modified.sql`) is served with modified-value reads and HistoryUpdate refused `BadHistoryOperationUnsupported`, retention skipping `SampleModified`, and one Warning per boot (#674). | | `ServerHistorian:SqlServer:RetentionDays` | unset | Days of history kept (source time), `>= 1` when set; unset keeps everything. Enables the Primary-gated purge of `hist.Sample`/`hist.Event` (see [Historian.md](Historian.md#retention-retentiondays)). | | `ServerHistorian:SqlServer:PurgeInterval` | `01:00:00` | Purge cadence; must be `> 0`. | | `ServerHistorian:SqlServer:PurgeBatchSize` | `4000` | Rows per `DELETE TOP (n)` batch; `>= 1`. Keep under ~5000 to avoid lock escalation. | @@ -430,7 +430,12 @@ when `ServerHistorian:Enabled` **or** `AlarmHistorian:Enabled` is true (`QuestDb | `ServerHistorian:QuestDb:VisibilityTimeout` | `00:00:05` | Must be `>= 0`. How long a write waits for its rows to become visible to queries (WAL apply); `0` disables the wait. A timeout only logs a Warning. | HistoryUpdate (SqlServer and QuestDb only; QuestDb deletes are soft — tombstones) additionally needs `ServerHistorian:Enabled=true` and a key -whose principal holds the `HistoryUpdate` permission — see [`docs/security.md`](security.md#historyupdate-historian-writes). Full semantics, +whose principal holds the `HistoryUpdate` permission — see [`docs/security.md`](security.md#historyupdate-historian-writes). It is served +only on the redundancy **Primary** (`BadInvalidState` elsewhere, #674) and is bounded by one backend-independent key: + +| Key | Default | Meaning | +|---|---|---| +| `ServerHistorian:HistoryUpdateMaxFutureSkew` | `1.00:00:00` (1 day) | TimeSpan. A HistoryUpdate (Insert / Replace / Update) item whose `SourceTimestamp` is later than server-clock now + this is refused `BadOutOfRange` before any backend sees it (#674 — a far-future typo could otherwise age out a QuestDB TTL table or poison the history). Applies to every backend; the live recorder is not bounded. Non-positive disables the bound. | Full semantics, schema, aggregates and the docker-dev recipe: [`docs/Historian.md`](Historian.md#sql-server-backend) (SqlServer) and [`docs/Historian.md`](Historian.md#questdb-backend) (QuestDb: the µs timestamp rules, pre-1970 limits, TTL and the docker-dev overlay). diff --git a/docs/Historian.md b/docs/Historian.md index f4c1d8e4..e95f1f10 100644 --- a/docs/Historian.md +++ b/docs/Historian.md @@ -85,7 +85,8 @@ consumes the historian. The existing enable gates (`ServerHistorian:Enabled`, `A | Connection | `Endpoint` + `ApiKey` + TLS keys (top-level `ServerHistorian:*`) | `ServerHistorian:SqlServer:*` | `ServerHistorian:QuestDb:*` | Recording stays **Primary-only** (#537) and **at-least-once** with the #538 per-tag quarantine on every backend; -HistoryRead and HistoryUpdate are served from any node (the database is shared). The historian connection string is +HistoryRead is served from any node (the database is shared). HistoryUpdate is **Primary-only** since #674 +(`BadInvalidState` on any other node — see [HistoryUpdate](#primary-only-674)). The historian connection string is **not** a ConfigDb string, and a driver-only node may carry it without breaking the Phase 4 "no ConfigDb" posture. --- @@ -145,6 +146,7 @@ and all HistoryRead calls on historized nodes return `GoodNoData` (empty, not an | `MaxConcurrentHistoryReadBatches` | int | `16` | Process-wide limit on HistoryRead (and HistoryUpdate) batches served **concurrently** (arch-review 03/S3). A flood of history clients degrades to `BadTooManyOperations` rather than exhausting the SDK request-thread pool. With `HistoryReadBatchParallelism` this caps total in-flight gateway reads at `MaxConcurrentHistoryReadBatches × HistoryReadBatchParallelism` (default 16 × 4 = 64). A batch that cannot get a slot within `min(HistoryReadDeadline, 5 s)` fails every handle `BadTooManyOperations`. | | `MaxTimeWeightedRawRows` | int | `1000000` | `SqlServer` / `QuestDb` only (#671). The most raw in-window samples one [time-weighted aggregate](#time-weighted-aggregates-part-13-671) read (TimeAverage, TimeAverage2, **Total**, Total2, Interpolative) may stream into the server-side evaluator — that family is **not** pushed down to SQL. The window query is capped at this + 1 rows; one row past the cap fails **that node** with `BadTooManyOperations` (not counted as a backend fault) instead of holding a pooled connection until `HistoryReadDeadline` and returning `BadTimeout`. Bound rows outside the window do not count; per-sample aggregates are not capped. 1 000 000 ≈ 11.5 days of a 1 Hz tag. Non-positive = unbounded (a `Validate()` warning). | | `HistoryReadDeadline` | TimeSpan | `00:01:00` | Per-request wall-clock deadline for a HistoryRead (and HistoryUpdate) batch (arch-review 03/S3). A node still in flight at the deadline surfaces `BadTimeout`, so one request can never hold an SDK request thread longer than this regardless of node count. Non-positive = unbounded (a `Validate()` warning). | +| `HistoryUpdateMaxFutureSkew` | TimeSpan | `1.00:00:00` | #674. How far past the server clock a HistoryUpdate (Insert / Replace / Update) item's `SourceTimestamp` may lie; an item beyond `now + skew` is refused **`BadOutOfRange`** by the node manager before any backend sees it (every backend). Guards against a far-future typo (a 2062 timestamp). The live recorder is not bounded. Non-positive disables the bound (no warning — a deliberate choice). See [HistoryUpdate](#historyupdate). | **`ServerHistorian:SqlServer`** (read only when `Backend=SqlServer`; bound by `HistorianBackendRegistry.BindSqlServer`): @@ -686,6 +688,25 @@ modification time and the Part 11 `HistoryUpdateType`. A HistoryReadRaw with `Is within one node the order is strict. - **Retention.** The trail ages out on the same **source-time** cutoff as the samples it describes: `SqlServer` purges `hist.SampleModified` per tag alongside `hist.Sample`; QuestDB puts the same TTL on `{p}sample_modified`. +- **SqlServer schema v1 (#674).** With `AutoCreateSchema=false` a database still at schema **version 1** (script `002_sample_modified.sql` not + applied) keeps historizing — live writes, raw/processed/at-time reads, alarm events and retention all work — but has no trail: modified reads + and every HistoryUpdate item answer **`BadHistoryOperationUnsupported`** with nothing sent to SQL, retention skips `SampleModified`, and the + node logs **one Warning per boot**. Apply `002_sample_modified.sql` and restart the node to enable them (the verdict is taken once per + process). `AutoCreateSchema=true` (the default) still upgrades v1 to v2 in place. See [Schema](#schema). +- **QuestDB retry duplicates (#674).** `{p}sample_modified` is append-only with **no DEDUP key** (a key would collapse genuinely distinct + modifications of one sample), and each trail row gets a fresh `modified_id`. So a HistoryUpdate a client **retries** after a timeout — when the + first attempt had in fact landed — records a second trail row for the same change (and, for Insert, the retry is `BadEntryExists`). The + sample itself is idempotent (dedup upsert); only the audit trail can show the duplicate. `SqlServer` has the same exposure only if the client + retries a committed request; there is no request id to dedupe on in either backend. +- **Cross-node ordering (QuestDB).** The per-tag lock is per process; the [Primary-only](#primary-only-674) HistoryUpdate gate (#674) is what keeps + two nodes of a pair from recording concurrent updates of one tag (and so a wrong prior value). Two **separate** pairs sharing one QuestDB can + still race; that is unsupported. +- ⚠️ **Who can read the trail (#674.4).** Modified reads are ordinary HistoryReads: with `Security:Acl:Enabled=false` (the default) **any admitted + session, including Anonymous, can read who rewrote history** (`UserName` is the principal). Turn the ACL flag on, or set + `OpcUa:AllowAnonymous=false`, if the principal names are sensitive (see [security.md](security.md)). +- **Not implemented (#674.5):** `IsDeleteModified` (deleting trail entries — `BadHistoryOperationUnsupported`); recording an **Update** (upsert) as + a split `Insert` / `Replace` — it is recorded as `Update` either way; and **`AuditHistoryUpdateEvent`** (no audit event is emitted for a history + change — the trail is the only record). ```bash otopcua-cli historyread -u opc.tcp://localhost:4840 -U apikey -P otua__ \ @@ -752,7 +773,7 @@ The bootstrapper applies every script above the recorded version, in order, unde | Object | Purpose | |---|---| -| `SchemaVersion(Version, AppliedUtc)` | Applied-script ledger. Required version: **2** (since #668). | +| `SchemaVersion(Version, AppliedUtc)` | Applied-script ledger. Required version: **1**; version **2** adds the modification trail (#668). A v1 database is served with the trail features off (#674 — see below). | | `Tag(TagId int identity, Name nvarchar(400) unique, DataType tinyint, EngineeringUnit, Description, CreatedUtc, UpdatedUtc)` | One row per historian tagname. `DataType` is a `DriverDataType`. | | `Sample(TagId, SourceTimeUtc datetime2(7), ValueKind tinyint, NumValue float, IntValue bigint, StrValue nvarchar(max), StatusCode int, ServerTimeUtc)` | **PK `(TagId, SourceTimeUtc)`** — one value per timestamp (Part 11), which makes redelivery idempotent and rules out tie clusters. `StatusCode` is the uint status stored bit-for-bit. | | `Event(EventId nvarchar(64) PK nonclustered, SourceName, AlarmId, AlarmName, AlarmTypeName, Severity, EventKind, Message, UserName, Comment, EventTimeUtc, ReceivedTimeUtc)` | Alarm history. Clustered on `(EventTimeUtc, EventId)`; extra index `(SourceName, EventTimeUtc)`. | @@ -768,11 +789,14 @@ everywhere (full 100 ns precision — never a `DataTable`, which would round to `sqlcmd -S -U -P -d -I -v Schema=hist -i docs/historian/sqlserver/001_initial.sql`, then the same with `002_sample_modified.sql` (`-v Schema=` supplies the `$(Schema)` placeholder; verified against the docker-dev SQL container). Re-running is a no-op. -⚠️ **Upgrading an existing v1 historian (#668).** A build with this change requires schema **version 2**. With `AutoCreateSchema=true` -(the default) the first historian call after the upgrade applies `002_sample_modified.sql` in place (it only creates `SampleModified`; existing -samples are untouched). With `AutoCreateSchema=false` **every historian call fails** (`missing version 2 (found 1)`, in health `LastError`) -until an operator runs `002_sample_modified.sql` by hand as above — do that before rolling the new build out. Modifications made before the -upgrade have no trail; the trail starts with the first HistoryUpdate after it. +⚠️ **Upgrading an existing v1 historian (#668, #674).** With `AutoCreateSchema=true` (the default) the first historian call after the +upgrade applies `002_sample_modified.sql` in place (it only creates `SampleModified`; existing samples are untouched). With +`AutoCreateSchema=false` a **v1 database is accepted** (#674 — between #668 and #674 it refused every historian call, continuous-historization +drains included): writes, reads, events and retention work, while modified-value reads and HistoryUpdate report +`BadHistoryOperationUnsupported` without touching SQL, retention skips `SampleModified`, and one Warning per boot names the missing script. +Run `002_sample_modified.sql` by hand as above and **restart the node** to enable them (the version is read once per process). Only a schema +below version 1 (`missing version 1 (found 0)`) still fails every call. Modifications made before the upgrade have no trail; the trail starts +with the first HistoryUpdate after it. ### Writes @@ -999,6 +1023,8 @@ equivalent TTL (`QuestDb:RetentionDays`); the Gateway backend's retention is the timeout 0) lets one purger run and the others skip that tick (Debug log). - **Observability.** Counter `otopcua.historian.retention.purged{table=Sample|SampleModified|Event}`; a failed pass logs a Warning and retries next interval — it never affects capture or reads. +- **Schema v1 (#674).** On a v1 schema (no `SampleModified`, `AutoCreateSchema=false`) the trail purge is skipped and omitted from the + pass results; samples and events purge normally. - **Not done: partition switching.** For very large installs (billions of rows) a partitioned `hist.Sample` with sliding-window `SWITCH`/drop is cheaper than row deletes; the purger is deliberately simple batched deletes. Another table is added by one more `DeleteLoopAsync` call in `SqlServerHistorianRetention.PurgeAsync` (as `hist.SampleModified` was, #668). @@ -1195,7 +1221,14 @@ expired day partitions itself, tombstones included. re-read to verify; a very large `RetentionDays` that QuestDB normalises into MONTH/YEAR is re-`ALTER`ed on every boot (harmless). - ⚠️ **TTL is enforced only on write commits.** QuestDB checks for expired partitions when a write commits to the table, so **a quiet table never drops anything**: partitions older than the TTL linger until the next write lands. Do not read a stale-looking partition as a broken TTL. -- Expiry is judged against the wall clock, so a future-dated sample does not expire current data. +- **Expiry is judged against the wall clock** (`min(max timestamp, now)`), so a future-dated sample does not expire current data. + ⚠️ **Keep `cairo.ttl.use.wall.clock` at its default, `true`** (#674). It is what QuestDB documents as protecting a TTL table from a + future-dated row; with it `false` the TTL would be measured from the table's newest timestamp and one far-future row (a 2062 typo) could + drop every older partition — including `{p}sample_modified`, the record of who changed history. Evidence (QuestDB 10.0.1, 2026-10-11): the + default is `true`, and a 2066 row inserted into a 30-day-TTL table evicted nothing inside the TTL, while a partition genuinely older than + 30 days was evicted by that same commit — pinned by `TtlWallClockTests`. (The same run with the flag `false` also kept the in-TTL + partitions, so the test pins the outcome rather than isolating the flag; do not rely on that.) The server-side + `ServerHistorian:HistoryUpdateMaxFutureSkew` bound (default 1 day) is the primary guard: a HistoryUpdate cannot write a far-future row. - The TTL is visible in table metadata: `SELECT table_name, ttlValue, ttlUnit FROM tables() WHERE starts_with(table_name, 'hist_')`. ### Docker-dev recipe @@ -1236,8 +1269,8 @@ dotnet test tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.Integration OPC UA **HistoryUpdate** lets a client insert, replace, update and delete stored raw history. It is available only when the selected backend provides an updater — **`SqlServer` and `QuestDb` do; `Gateway` does not**, and an updater is registered only when `ServerHistorian:Enabled=true`. -Updates go straight to the backend (not through the outbox), are **not Primary-gated** (the database is shared), and share the HistoryRead -batch limiter and `HistoryReadDeadline`. +Updates go straight to the backend (not through the outbox), are **Primary-only** (#674, [below](#primary-only-674)), and share the +HistoryRead batch limiter and `HistoryReadDeadline`. ### Operations @@ -1255,7 +1288,8 @@ caller's principal, in the [modification trail](#modified-value-history-part-11) mixed (Part 11 reports item outcomes in `OperationResults`); it is Bad only for whole-node failures. **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) ⇒ +`SourceTimestamp == DateTime.MinValue` ⇒ `BadInvalidTimestamp`; a **`SourceTimestamp` later than `now + ServerHistorian:HistoryUpdateMaxFutureSkew`** +(default 1 day, server clock; #674) ⇒ **`BadOutOfRange`** — on every backend, never sent; a value the historian cannot type (array, unsupported CLR type) ⇒ `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 @@ -1278,7 +1312,19 @@ outcome, later ones `BadNoEntryExists`. **Unknown tag:** Insert / Update create `ServerHistorian:Enabled=false`); `PerformUpdateType.Remove`; `DeleteRawModifiedDetails.IsDeleteModified=true` (the [modification trail](#modified-value-history-part-11) is an audit record, aged out only by retention); and the out-of-scope detail types — **event** HistoryUpdate (`UpdateEventDetails` / `DeleteEventDetails`) and `UpdateStructureData` — which are not overridden, so the SDK base rejects them. A backend exception is `BadInternalError` for that node and a deadline is `BadTimeout`. -No `AuditHistoryUpdateEvent` is emitted. +On a `SqlServer` database still at schema v1 every item is `BadHistoryOperationUnsupported` ([#674](#modified-value-history-part-11)). +No `AuditHistoryUpdateEvent` is emitted (#674.5, not implemented). + +### Primary-only (#674) + +HistoryUpdate is served only by the node holding the redundancy **Primary** data-plane role — the same verdict +(`IDriverPrimaryRoleSource`, published by `DriverHostActor`) that gates native-alarm acknowledges (#597). On any other node every node of +the request that **passed authorization** is refused **`BadInvalidState`** (node-level code, with a message pointing at the Primary) and +nothing reaches the backend. Authorization runs first, so an unauthorized caller learns `BadUserAccessDenied`, not the node's role. +HistoryRead is **not** gated. Why: rewriting history is a single-writer operation — both backends capture the prior value for the +[modification trail](#modified-value-history-part-11) under a per-tag, **per-process** lock (QuestDB) or statement (SqlServer), so two pair +nodes updating one tag concurrently could record a wrong prior value. A single-node deployment (no redundancy manager) is unaffected. Clients +should send HistoryUpdate to the server advertising the higher `ServiceLevel`. ### The `HistoryWrite` AccessLevel bit diff --git a/docs/security.md b/docs/security.md index 710e3598..87ac8d22 100644 --- a/docs/security.md +++ b/docs/security.md @@ -884,6 +884,7 @@ HistoryUpdate rewrites recorded history, so unlike HistoryRead it is gated **wha - **Flag off (default):** the session's API key is re-checked on the call (`DataPlaneAuthorizer.AuthorizeKeyUsable`, Gitea #563 — an expired or disabled key loses its activation-time roles), then the session must carry the **`HistoryUpdate` role** (`OpcUaDataPlaneRoles.HistoryUpdate`). `ApiKeyInterimRoleMapper` confers it **only from a `Cluster`-scoped grant** carrying `NodePermissions.HistoryUpdate` — narrower-scoped grants confer nothing, for the same reason as `WriteOperate` (honouring a flag without honouring its scope would widen it). A key holding only `WriteOperate` is denied `BadUserAccessDenied`. - **Flag on:** `DataPlaneAuthorizer.Authorize(identity, OpcUaOperation.HistoryUpdate, nodeId, realm)` decides per node and **replaces** the role check (never chained) — a session with no roles succeeds on the strength of a scoped `HistoryUpdate` grant, and a `WriteOperate` grant does not help. - **Availability is separate from authorization.** A node accepts HistoryUpdate only if it is historized **and** the selected historian backend has an updater when the node materialises (the `HistoryWrite` AccessLevel bit). `Backend=Gateway` has none, so it answers `BadHistoryOperationUnsupported` for every node whatever the grant. Operations, result codes and unsupported cases: [`docs/Historian.md` §HistoryUpdate](Historian.md#historyupdate). +- **Primary-only, after authorization (Gitea #674).** An authorized HistoryUpdate on a node that is not the redundancy Primary is refused `BadInvalidState` (the native-alarm-ack verdict, #597); an unauthorized one is told `BadUserAccessDenied` first, so the refusal never reveals the node's role to a caller who may not update. - **Every applied change is attributed (Part 11 modified-value history, Gitea #668).** The session's principal (the API key's `NodeAcl` principal, or the reserved `anonymous`) and key id are passed to the backend with every HistoryUpdate and recorded in the modification trail next to the prior value; a modified-value HistoryRead (`IsReadModified = true`) returns it as diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common/HistorianStatusCodes.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common/HistorianStatusCodes.cs index 9fa08bcf..686b1126 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common/HistorianStatusCodes.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common/HistorianStatusCodes.cs @@ -27,4 +27,10 @@ public static class HistorianStatusCodes /// status, or a tag name longer than . /// public const uint BadInvalidArgument = 0x80AB0000u; + + /// + /// A modified-value read or HistoryUpdate item against a SQL Server schema still at version 1 (no Part 11 + /// modification trail, Gitea #674): refused without touching the database. + /// + public const uint BadHistoryOperationUnsupported = 0x80720000u; } diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs index 99182de6..e2c31a32 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs @@ -154,6 +154,12 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource var bounded = maxValues > 0 && maxValues < int.MaxValue; try { + // #674: a v1 schema has no SampleModified. NotSupportedException is the interface's "no trail" signal (the + // node manager reports BadHistoryOperationUnsupported); it is not a backend failure and sends no query. + await _bootstrap.EnsureAsync(cancellationToken).ConfigureAwait(false); + if (!_bootstrap.SupportsModifiedTrail) + throw new NotSupportedException( + $"Historian schema [{_conn.Schema}] is below version {SqlServerSchemaBootstrapper.ModifiedTrailVersion}: no modified-value history."); var values = new List(); var hasMore = false; var tagId = await ResolveAsync(fullReference, cancellationToken).ConfigureAwait(false); @@ -219,7 +225,7 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource RecordSuccess(); return new HistoryModifiedReadResult(values, hasMore); } - catch (Exception ex) + catch (Exception ex) when (ex is not NotSupportedException) { RecordFailure(ex); throw; diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataUpdater.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataUpdater.cs index d21d4ed2..33bb097f 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataUpdater.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataUpdater.cs @@ -27,21 +27,44 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer; /// value from deleted.* (NULL for an insert), the caller's , the /// and SYSUTCDATETIME(). One statement means the sample change and its /// audit row commit or roll back together: a failed update leaves no audit row. +/// Schema v1 (Gitea #674). Without the trail ( +/// false) a change could not be audited, so every item (and DeleteRaw's single result) reports +/// BadHistoryOperationUnsupported and nothing is sent to the database beyond the one-time schema check. /// internal sealed class SqlServerHistorianDataUpdater : IHistorianDataUpdater { private readonly SqlHistorianConnection _conn; private readonly SqlServerTagCatalog _tags; + private readonly SqlServerSchemaBootstrapper _bootstrap; /// Creates the updater. /// Connection helper. + /// Schema bootstrapper — decides whether the modification trail exists (#674). /// Tag catalog (runs the schema bootstrap itself). - public SqlServerHistorianDataUpdater(SqlHistorianConnection conn, SqlServerTagCatalog tags) + public SqlServerHistorianDataUpdater(SqlHistorianConnection conn, SqlServerSchemaBootstrapper bootstrap, + SqlServerTagCatalog tags) { _conn = conn; + _bootstrap = bootstrap; _tags = tags; } + /// #674: ensures the schema and reports whether the Part 11 trail exists (no SQL after the first success). + /// Cancellation. + /// True when the modification trail is available. + private async Task TrailAvailableAsync(CancellationToken ct) + { + await _bootstrap.EnsureAsync(ct).ConfigureAwait(false); + return _bootstrap.SupportsModifiedTrail; + } + + private static uint[] Unsupported(int count) + { + var codes = new uint[count]; + Array.Fill(codes, HistorianStatusCodes.BadHistoryOperationUnsupported); + return codes; + } + /// public async Task> UpdateDataAsync(string tag, HistoryUpdateMode mode, IReadOnlyList values, HistoryUpdateContext context, CancellationToken ct) @@ -49,6 +72,7 @@ internal sealed class SqlServerHistorianDataUpdater : IHistorianDataUpdater ArgumentNullException.ThrowIfNull(tag); ArgumentNullException.ThrowIfNull(values); ArgumentNullException.ThrowIfNull(context); + if (!await TrailAvailableAsync(ct).ConfigureAwait(false)) return Unsupported(values.Count); var plan = HistoryUpdatePlanner.Plan(tag, mode, values); if (plan.Winners.Count == 0) return HistoryUpdatePlanner.Complete(plan, mode, new Dictionary()); @@ -68,6 +92,7 @@ internal sealed class SqlServerHistorianDataUpdater : IHistorianDataUpdater { ArgumentNullException.ThrowIfNull(tag); ArgumentNullException.ThrowIfNull(context); + if (!await TrailAvailableAsync(ct).ConfigureAwait(false)) return HistorianStatusCodes.BadHistoryOperationUnsupported; if (!HistorianTagNames.IsValid(tag)) return HistorianStatusCodes.BadInvalidArgument; var tagId = await _tags.TryGetTagIdAsync(tag, ct).ConfigureAwait(false); if (tagId is null) return HistoryUpdatePlanner.DeleteRawResult(tagKnown: false, 0); @@ -95,6 +120,7 @@ internal sealed class SqlServerHistorianDataUpdater : IHistorianDataUpdater ArgumentNullException.ThrowIfNull(tag); ArgumentNullException.ThrowIfNull(timesUtc); ArgumentNullException.ThrowIfNull(context); + if (!await TrailAvailableAsync(ct).ConfigureAwait(false)) return Unsupported(timesUtc.Count); if (!HistorianTagNames.IsValid(tag)) { var refused = new uint[timesUtc.Count]; diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianOptions.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianOptions.cs index 4828e4ac..94ba91b0 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianOptions.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianOptions.cs @@ -18,8 +18,10 @@ public sealed partial class SqlServerHistorianOptions /// /// true creates the schema and applies missing scripts on first use; false only verifies - /// that the required schema version (SqlServerSchemaBootstrapper.RequiredVersion, currently 2) exists and - /// fails every historian call with a clear error otherwise. + /// that the base schema version (SqlServerSchemaBootstrapper.RequiredVersion, 1) exists and fails every + /// historian call with a clear error otherwise. A verified v1 schema (no Part 11 modification trail, script 002 + /// not applied) is served with modified reads and HistoryUpdate refused BadHistoryOperationUnsupported + /// and one Warning per boot (Gitea #674). /// public bool AutoCreateSchema { get; set; } = true; diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianProvider.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianProvider.cs index 8b6b5bcd..80cfe919 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianProvider.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianProvider.cs @@ -99,7 +99,7 @@ public sealed class SqlServerHistorianProvider : IHistorianBackendProvider public IHistorianDataUpdater? CreateUpdater(IServiceProvider sp) { var s = Get(sp); - return new SqlServerHistorianDataUpdater(s.Conn, s.Catalog); + return new SqlServerHistorianDataUpdater(s.Conn, s.Bootstrap, s.Catalog); } /// diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianRetention.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianRetention.cs index c8bc8e00..caf31e74 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianRetention.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianRetention.cs @@ -11,7 +11,8 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer; /// DELETE TOP(n) batches (under the lock-escalation threshold). Samples are purged per tag so each /// delete is a seek on the clustered key (TagId, SourceTimeUtc); events seek on CX_Event_Time. /// A session sp_getapplock (timeout 0) serialises purgers that share one database; a loser skips. -/// To purge another table later, add it to . +/// To purge another table later, add it to . On a v1 schema (no Part 11 trail, Gitea #674) +/// the SampleModified purge is skipped and absent from the results. /// internal sealed class SqlServerHistorianRetention : IHistorianRetention { @@ -69,6 +70,8 @@ internal sealed class SqlServerHistorianRetention : IHistorianRetention return []; } + // #674: a v1 schema has no SampleModified table — skip its purge rather than fail the whole pass. + var trail = _bootstrap.SupportsModifiedTrail; long samples = 0, modified = 0; var tagIds = new List(); await using (var cmd = _conn.CreateCommand(conn, $"SELECT TagId FROM {_conn.Q("Tag")}")) @@ -82,21 +85,30 @@ internal sealed class SqlServerHistorianRetention : IHistorianRetention cutoff, id, ct).ConfigureAwait(false); // The Part 11 modification trail (#668) ages out on the SAME source-time cutoff as the samples it // describes; a purge never writes to it (no trigger, no OUTPUT INTO). - modified += await DeleteLoopAsync(conn, - $"DELETE TOP (@n) FROM {_conn.Q("SampleModified")} WHERE TagId = @id AND SourceTimeUtc < @cutoff", - cutoff, id, ct).ConfigureAwait(false); + if (trail) + { + modified += await DeleteLoopAsync(conn, + $"DELETE TOP (@n) FROM {_conn.Q("SampleModified")} WHERE TagId = @id AND SourceTimeUtc < @cutoff", + cutoff, id, ct).ConfigureAwait(false); + } } var events = await DeleteLoopAsync(conn, $"DELETE TOP (@n) FROM {_conn.Q("Event")} WHERE EventTimeUtc < @cutoff", cutoff, null, ct).ConfigureAwait(false); - return - [ - new RetentionPurgeResult("Sample", samples), - new RetentionPurgeResult("SampleModified", modified), - new RetentionPurgeResult("Event", events), - ]; + return trail + ? + [ + new RetentionPurgeResult("Sample", samples), + new RetentionPurgeResult("SampleModified", modified), + new RetentionPurgeResult("Event", events), + ] + : + [ + new RetentionPurgeResult("Sample", samples), + new RetentionPurgeResult("Event", events), + ]; } finally { diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerSchemaBootstrapper.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerSchemaBootstrapper.cs index c1c1a782..2fd1d9b3 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerSchemaBootstrapper.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerSchemaBootstrapper.cs @@ -15,15 +15,27 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer; /// SQL, so a missing schema (or a SQL outage) does not serialise every write, read and alarm event behind one /// semaphore and one round-trip each. /// With AutoCreateSchema=false it only verifies MAX(Version) >= . +/// Schema v1 is accepted (Gitea #674). A database at version 1 (no SampleModified) still serves +/// live writes, raw / processed / at-time reads, alarm events and retention; only the Part 11 modification trail is +/// unavailable — is false, modified reads and HistoryUpdate report +/// BadHistoryOperationUnsupported without touching SQL, and one Warning is logged per instance (= per boot: the +/// provider shares one bootstrapper). Before #674 a v1 database refused EVERY historian call, continuous-historization +/// drains included, until script 002 was applied by hand. /// internal sealed partial class SqlServerSchemaBootstrapper { /// - /// The schema version this build requires: 2 = 002_sample_modified.sql (Part 11 modified-value - /// history, Gitea #668). An existing v1 schema is upgraded in place on the next bootstrap when - /// AutoCreateSchema is on; otherwise the script must be applied by hand. + /// The schema version this build requires to serve at all: 1 = 001_initial.sql. Gitea #674 lowered it from + /// 2 — a missing modification trail disables only the features that need it (). /// - public const int RequiredVersion = 2; + public const int RequiredVersion = 1; + + /// + /// The schema version that carries the Part 11 modification trail: 2 = 002_sample_modified.sql (Gitea #668). + /// An auto-creating bootstrap always upgrades to it; with AutoCreateSchema=false the script must be applied by + /// hand (and the node restarted — the verdict is taken once per instance). + /// + public const int ModifiedTrailVersion = 2; private const string LockResource = "OtOpcUaHistorianSchema"; private const int LockTimeoutMs = 30_000; @@ -34,6 +46,13 @@ internal sealed partial class SqlServerSchemaBootstrapper private readonly SemaphoreSlim _gate = new(1, 1); private readonly BootstrapFailureCache _failure; // guarded by _gate private volatile bool _ready; + private volatile bool _supportsModifiedTrail; + + /// + /// Whether the schema carries the Part 11 modification trail (version >= ). + /// Meaningful only after has succeeded (false before). Taken once per instance. + /// + public bool SupportsModifiedTrail => _supportsModifiedTrail; /// Creates the bootstrapper. /// Connection helper. @@ -99,6 +118,13 @@ internal sealed partial class SqlServerSchemaBootstrapper throw new HistorianSchemaMissingException( $"Historian schema [{_conn.Schema}] is missing version {RequiredVersion} (found {v}) and AutoCreateSchema is false. " + "Apply the docs/historian/sqlserver/NNN_*.sql scripts above version " + v + " in order, or enable AutoCreateSchema."); + _supportsModifiedTrail = v >= ModifiedTrailVersion; + if (!_supportsModifiedTrail) + _log.LogWarning("Historian schema [{Schema}] is at version {Version}, below {TrailVersion}, and AutoCreateSchema is false: " + + "the Part 11 modification trail is unavailable, so modified-value history reads and HistoryUpdate report " + + "BadHistoryOperationUnsupported and retention skips SampleModified. Live historization, reads, events and retention " + + "are unaffected. Apply docs/historian/sqlserver/002_sample_modified.sql and restart the node to enable them.", + _conn.Schema, v, ModifiedTrailVersion); } private async Task ApplyAsync(SqlConnection conn, CancellationToken ct) diff --git a/src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/OtOpcUaServerHostedService.cs b/src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/OtOpcUaServerHostedService.cs index aff63c4d..78827f5f 100644 --- a/src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/OtOpcUaServerHostedService.cs +++ b/src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/OtOpcUaServerHostedService.cs @@ -252,13 +252,15 @@ public sealed class OtOpcUaServerHostedService : IHostedService, IAsyncDisposabl if (_primaryRoleSource is { } primaryRoleSource) { _server.SetNativeAlarmAckPrimaryGate(() => primaryRoleSource.ShouldActAsPrimary); + // Gitea #674: HistoryUpdate is single-writer — only the Primary rewrites history (BadInvalidState elsewhere). + _server.SetHistoryUpdatePrimaryGate(() => primaryRoleSource.ShouldActAsPrimary); } else { // Every driver node registers one (AddOtOpcUaRuntime), so this is a wiring regression, not a mode: // say so rather than let a Secondary silently go back to accepting acks it will revert. _logger.LogWarning( - "OtOpcUaServerHostedService: no IDriverPrimaryRoleSource registered — native-alarm acknowledges are accepted on every node regardless of redundancy role"); + "OtOpcUaServerHostedService: no IDriverPrimaryRoleSource registered — native-alarm acknowledges and HistoryUpdate are accepted on every node regardless of redundancy role"); } // Wire the reverse-path inbound operator-write gateway: a client write to a writable equipment-tag @@ -317,6 +319,11 @@ public sealed class OtOpcUaServerHostedService : IHostedService, IAsyncDisposabl _server.NodeManager.MaxConcurrentHistoryReadBatches = _serverHistorianOptions.MaxConcurrentHistoryReadBatches; _server.NodeManager.HistoryReadDeadline = _serverHistorianOptions.HistoryReadDeadline; + // Gitea #674: HistoryUpdate refuses a SourceTimestamp beyond now + HistoryUpdateMaxFutureSkew (BadOutOfRange), + // judged against the host clock. + _server.NodeManager.HistoryUpdateMaxFutureSkew = _serverHistorianOptions.HistoryUpdateMaxFutureSkew; + _server.NodeManager.Clock = _time; + // ServiceLevel publisher needs IServerInternal — only available after Start. if (_server.CurrentInstance is { } serverInternal) { @@ -382,6 +389,7 @@ public sealed class OtOpcUaServerHostedService : IHostedService, IAsyncDisposabl // Clear the native-alarm-ack router so a late ack doesn't Tell a stopping DriverHostActor. _server?.SetNativeAlarmAckRouter(null); _server?.SetNativeAlarmAckPrimaryGate(null); + _server?.SetHistoryUpdatePrimaryGate(null); // Restore the Null historian so a late HistoryRead doesn't hit a disposed read client. _server?.SetHistorianDataSource(null); _server?.SetHistorianDataUpdater(null); diff --git a/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs b/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs index 0c2780b8..d7b1db61 100644 --- a/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs +++ b/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs @@ -247,6 +247,48 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 /// public Func? NativeAlarmAckPrimaryGate { get; set; } + /// + /// Gitea #674 — whether this node may serve an OPC UA HistoryUpdate right now: the redundancy data-plane + /// verdict (PrimaryGatePolicy.ShouldServiceAsPrimary, as published to IDriverPrimaryRoleSource) — + /// the same source as . + /// + /// false ⇒ every node of the request that passed authorization is refused BadInvalidState + /// and nothing reaches the updater. Rewriting history is a single-writer operation: the SQL backends' + /// prior-value capture (and QuestDB's per-process per-tag lock) assume one node serialises a tag's updates, + /// so both pair nodes accepting updates concurrently could record a wrong prior value in the modification + /// trail. HistoryRead is NOT gated — reads are served from any node. + /// + /// + /// Evaluated AFTER authorization (a caller who may not update learns nothing about the node's role). It must + /// be a cheap, non-blocking read (the host passes a volatile-backed property). Null (the default) allows — the + /// single-node posture, the same default UnmanagedDriverPrimaryRoleSource answers with. + /// + /// + public Func? HistoryUpdatePrimaryGate { get; set; } + + /// + /// Gitea #674 — how far beyond 's now a HistoryUpdate (Insert / Replace / Update) item's + /// SourceTimestamp may lie. An item past now + skew is refused BadOutOfRange before it + /// reaches any backend: a far-future row (a 2062 typo) is never a legitimate history edit, and on a backend whose + /// retention is judged against the newest timestamp it could age out every older partition. Mirrors + /// ServerHistorianOptions.HistoryUpdateMaxFutureSkew; the Host sets it at StartAsync. Non-positive + /// disables the bound. Default 1 day. Live recorder writes are not bounded by this. + /// + public TimeSpan HistoryUpdateMaxFutureSkew { get; set; } = TimeSpan.FromDays(1); + + /// + /// The clock the HistoryUpdate future-skew bound () reads. The Host + /// assigns its at StartAsync; tests inject a fixed clock. Defaults to + /// ; assigning null restores it. + /// + public TimeProvider Clock + { + get => _clock; + set => _clock = value ?? TimeProvider.System; + } + + private volatile TimeProvider _clock = TimeProvider.System; + private volatile IOpcUaNodeWriteGateway _nodeWriteGateway = NullOpcUaNodeWriteGateway.Instance; /// @@ -5365,6 +5407,8 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 List nodesToProcess, IDictionary cache) { + // #674: one "now" per request, so every item of the batch is judged against the same bound. + var latest = LatestAcceptedSourceTime(); ServeHistoryUpdate(context, nodesToProcess, results, errors, handle => { var details = nodesToUpdate[handle.Index]; @@ -5378,7 +5422,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 } var items = (IList?)details.UpdateValues ?? Array.Empty(); - return (updater, tagname, who, ct) => UpdateDataAsync(updater, tagname, mode, items, who, ct); + return (updater, tagname, who, ct) => UpdateDataAsync(updater, tagname, mode, items, latest, who, ct); }); } @@ -5440,22 +5484,40 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 }); } + /// + /// #674: the latest SourceTimestamp a HistoryUpdate item may carry — 's now plus + /// — or null when the bound is disabled (non-positive skew). + /// Saturates at rather than overflowing for an absurd configured skew. + /// + /// The inclusive upper bound, or null for unbounded. + private DateTime? LatestAcceptedSourceTime() + { + var skew = HistoryUpdateMaxFutureSkew; + if (skew <= TimeSpan.Zero) return null; + var now = _clock.GetUtcNow().UtcDateTime; + return skew.Ticks > DateTime.MaxValue.Ticks - now.Ticks + ? new DateTime(DateTime.MaxValue.Ticks, DateTimeKind.Utc) + : now + skew; + } + /// /// Applies one node's UpdateDataDetails: items the server can refuse on its own - /// (SourceTimestamp == DateTime.MinValue ⇒ BadInvalidTimestamp; a value - /// cannot type ⇒ BadTypeMismatch) are answered locally, - /// the rest go to the updater in ONE call, and the per-item codes are stitched back in request order. + /// (SourceTimestamp == DateTime.MinValue ⇒ BadInvalidTimestamp; a SourceTimestamp later than + /// ⇒ BadOutOfRange, #674; a value + /// cannot type ⇒ BadTypeMismatch) are answered locally, the rest go to the updater in ONE call, and the + /// per-item codes are stitched back in request order. /// /// The wired updater. /// The node's historian tagname. /// The update mode. /// The request's values, in order. + /// The latest accepted source time (); null = unbounded. /// The caller, recorded in the modification trail. /// The request deadline. /// The node's result, carrying one operation result per item. private static async Task UpdateDataAsync( IHistorianDataUpdater updater, string tagname, HistoryUpdateMode mode, IList items, - HistoryUpdateContext who, CancellationToken ct) + DateTime? latest, HistoryUpdateContext who, CancellationToken ct) { var codes = new uint[items.Count]; var toSend = new List(items.Count); @@ -5471,6 +5533,11 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 { codes[i] = StatusCodes.BadInvalidTimestamp; } + else if (latest is { } bound && item.SourceTimestamp > bound) + { + // #674: a far-future history edit is refused before any backend sees it (wire timestamps are UTC). + codes[i] = StatusCodes.BadOutOfRange; + } else if (!HistorianValue.TryFromObject(item.Value, out var value)) { codes[i] = StatusCodes.BadTypeMismatch; @@ -5521,6 +5588,21 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2 nodesToProcess = AuthorizeHistoryUpdate(context, nodesToProcess, results, errors); if (nodesToProcess.Count == 0) return; + // #674 — PRIMARY GATE, after authorization (a caller who may not update learns nothing about the node's role). + // Off-Primary every authorized node is refused BadInvalidState and nothing reaches the updater. + if (HistoryUpdatePrimaryGate is { } primary && !primary()) + { + var refusal = new ServiceResult(StatusCodes.BadInvalidState, + new LocalizedText("This server is not the redundancy Primary; update history on the Primary (the server with the higher ServiceLevel).")); + foreach (var handle in nodesToProcess) + { + errors[handle.Index] = refusal; + results[handle.Index] = new HistoryUpdateResult { StatusCode = StatusCodes.BadInvalidState }; + } + + return; + } + // Who is rewriting history — recorded on every modification-trail row (Part 11 ModificationInfo.UserName, #668). var who = HistoryUpdateCallerOf(context); diff --git a/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs b/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs index 11eab2fb..e566b347 100644 --- a/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs +++ b/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs @@ -83,6 +83,21 @@ public sealed class OtOpcUaSdkServer : StandardServer return true; } + /// + /// Gitea #674 — wire the redundancy verdict that decides whether this node serves an OPC UA HistoryUpdate + /// (); on any other node every authorized node of a + /// HistoryUpdate is refused BadInvalidState. Passing null clears it (allow). No-op (returns + /// false) when the node manager has not been created yet (mirrors ). + /// + /// A cheap, non-blocking read of the data-plane Primary verdict; null to allow. + /// true when set on a live node manager; false when no node manager exists yet. + public bool SetHistoryUpdatePrimaryGate(Func? isPrimary) + { + if (_otOpcUaNodeManager is null) return false; + _otOpcUaNodeManager.HistoryUpdatePrimaryGate = isPrimary; + return true; + } + /// /// Wire the reverse-path gateway for inbound operator writes to writable equipment-tag nodes onto the /// created . The host calls this after start with an diff --git a/src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/ServerHistorianOptions.cs b/src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/ServerHistorianOptions.cs index fc6cc012..eea6046f 100644 --- a/src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/ServerHistorianOptions.cs +++ b/src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/ServerHistorianOptions.cs @@ -122,6 +122,16 @@ public sealed class ServerHistorianOptions /// public int MaxTimeWeightedRawRows { get; init; } = 1_000_000; + /// + /// Gitea #674: how far into the future an OPC UA HistoryUpdate (Insert / Replace / Update) item's + /// SourceTimestamp may lie, measured from the server clock. An item beyond now + skew is refused + /// BadOutOfRange by the node manager before any backend sees it — a far-future row is never a legitimate + /// history edit, and on a backend that judges retention against the newest timestamp it could age out every + /// older partition. Applies to every backend. The live recorder is not bounded. Non-positive disables the bound. + /// Default 1 day. + /// + public TimeSpan HistoryUpdateMaxFutureSkew { get; init; } = TimeSpan.FromDays(1); + /// Returns operator-facing misconfiguration warnings for an Enabled historian /// (empty when disabled or correctly configured). Pure — the registration logs each entry. /// diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.IntegrationTests/TtlWallClockTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.IntegrationTests/TtlWallClockTests.cs new file mode 100644 index 00000000..f554da78 --- /dev/null +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.IntegrationTests/TtlWallClockTests.cs @@ -0,0 +1,80 @@ +using Shouldly; +using Xunit; +using ZB.MOM.WW.OtOpcUa.Core.Abstractions; +using ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common; + +namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.IntegrationTests; + +/// +/// Gitea #674.1 — pins the QuestDB TTL behaviour the historian's retention relies on: a table TTL is judged against +/// the wall clock (min(max timestamp, now)), so one far-future row — a 2066 typo that reached the backend +/// without going through the node manager's HistoryUpdateMaxFutureSkew bound — cannot age out every older +/// partition, including the Part 11 modification trail (the record of who changed history). +/// +/// +/// +/// Positive control. A partition genuinely older than the TTL (40 days, against a 30-day TTL) is kept until +/// the far-future commit and evicted BY it — proving TTL housekeeping ran on exactly the commit that could have +/// dropped the in-TTL partitions. Without it the "nothing evicted" assertion would also pass against a table +/// whose TTL never ran. +/// +/// +/// ⚠️ Observed on QuestDB 10.0.1 (2026-10-11): the in-TTL partitions also survived with +/// cairo.ttl.use.wall.clock=false (verified effective via SHOW PARAMETERS), so this test does not +/// isolate that flag — it pins the outcome. Keep the flag at its default (true) regardless; the server-side +/// future-skew bound is the primary guard. +/// +/// +[Collection(QuestDbCollection.Name)] +public sealed class TtlWallClockTests(QuestDbFixture fx) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + private static readonly HistoryUpdateContext Who = new("ttl-test", null); + + [Fact] + public async Task A_far_future_row_evicts_only_partitions_older_than_the_ttl_by_the_wall_clock() + { + fx.SkipIfUnavailable(); + var o = fx.Options(fx.UniquePrefix(), retentionDays: 30); + var c = new QuestDbConnection(o); + var wal = new QuestDbWalVisibility(c, o.VisibilityTimeout); + var tags = new QuestDbTagCatalog(c, new QuestDbSchemaBootstrapper(c, o), wal); + var updater = new QuestDbHistorianDataUpdater(c, tags, wal); + + // Whole seconds (µs-aligned), one row per DAY partition. With the newest row 10 days old, the 40-day partition is + // still inside the TTL measured from the table's max timestamp, so this commit evicts nothing. + var now = DateTime.UtcNow; + var today = new DateTime(now.Year, now.Month, now.Day, now.Hour, now.Minute, now.Second, DateTimeKind.Utc); + DateTime[] older = [today.AddDays(-40), today.AddDays(-20), today.AddDays(-10)]; + (await updater.UpdateDataAsync("ttl.tag", HistoryUpdateMode.Insert, older.Select((t, i) => V(t, i)).ToList(), Who, Ct)) + .ShouldAllBe(code => code == HistorianStatusCodes.GoodEntryInserted); + (await DaysAsync(c, c.SampleTable)).ShouldBe(older.Select(t => t.Date)); + (await DaysAsync(c, c.SampleModifiedTable)).ShouldBe(older.Select(t => t.Date)); + + // The far-future row, then one more ordinary commit (TTL housekeeping runs on commits). + (await updater.UpdateDataAsync("ttl.tag", HistoryUpdateMode.Insert, + [V(new DateTime(2066, 1, 1, 0, 0, 0, DateTimeKind.Utc), 9)], Who, Ct)).ShouldBe([HistorianStatusCodes.GoodEntryInserted]); + (await updater.UpdateDataAsync("ttl.tag", HistoryUpdateMode.Insert, [V(today, 10)], Who, Ct)) + .ShouldBe([HistorianStatusCodes.GoodEntryInserted]); + (await wal.WaitAsync(c.SampleTable, Ct)).ShouldBeTrue(); + (await wal.WaitAsync(c.SampleModifiedTable, Ct)).ShouldBeTrue(); + + // Only the genuinely expired 40-day partition is gone; the 20- and 10-day partitions survive in both tables. + DateTime[] expected = [today.AddDays(-20).Date, today.AddDays(-10).Date, today.Date, new(2066, 1, 1)]; + (await DaysAsync(c, c.SampleTable)).ShouldBe(expected); + (await DaysAsync(c, c.SampleModifiedTable)).ShouldBe(expected); + } + + private static HistorizationValue V(DateTime t, double v) => new(t, HistorianValue.FromDouble(v), HistorianStatusCodes.Good); + + /// The distinct UTC days holding rows, ascending. + private static async Task> DaysAsync(QuestDbConnection c, string table) + { + await using var conn = await c.OpenAsync(Ct); + await using var cmd = c.CreateCommand(conn, $"SELECT ts FROM {table} ORDER BY ts"); + await using var r = await cmd.ExecuteReaderAsync(Ct); + var days = new SortedSet(); + while (await r.ReadAsync(Ct)) days.Add(QuestDbConnection.ReadUtc(r, 0).Date); + return days.ToList(); + } +} diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common.Tests/StatusCodeOracleTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common.Tests/StatusCodeOracleTests.cs index a672a621..177c7c19 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common.Tests/StatusCodeOracleTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common.Tests/StatusCodeOracleTests.cs @@ -14,6 +14,11 @@ public sealed class StatusCodeOracleTests ((uint)Opc.Ua.AggregateBits.Calculated).ShouldBe(HistorianInfoBits.HistorianCalculated); } + /// #674: the v1-schema refusal code is the SDK's BadHistoryOperationUnsupported. + [Fact] + public void History_operation_unsupported_matches_the_SDK() => + HistorianStatusCodes.BadHistoryOperationUnsupported.ShouldBe(Opc.Ua.StatusCodes.BadHistoryOperationUnsupported); + [Fact] public void Interpolated_bits_match_the_SDK() { diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/ModifiedHistoryAtomicityTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/ModifiedHistoryAtomicityTests.cs index 0a3e98ea..9de80da7 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/ModifiedHistoryAtomicityTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/ModifiedHistoryAtomicityTests.cs @@ -54,7 +54,7 @@ public sealed class ModifiedHistoryAtomicityTests(SqlHistorianFixture fx) public async Task A_replace_whose_trail_insert_fails_changes_nothing() { var db = await ReadTestDb.CreateAsync(fx); - var u = new SqlServerHistorianDataUpdater(db.Conn, new SqlServerTagCatalog(db.Conn, db.Boot)); + var u = new SqlServerHistorianDataUpdater(db.Conn, db.Boot, new SqlServerTagCatalog(db.Conn, db.Boot)); (await u.UpdateDataAsync("t", HistoryUpdateMode.Insert, [V(T1, 1)], Who, CancellationToken.None)) .ShouldBe([HistorianStatusCodes.GoodEntryInserted]); (await CountTrailAsync(db)).ShouldBe(1); @@ -78,7 +78,7 @@ public sealed class ModifiedHistoryAtomicityTests(SqlHistorianFixture fx) public async Task Deletes_whose_trail_insert_fails_delete_nothing() { var db = await ReadTestDb.CreateAsync(fx); - var u = new SqlServerHistorianDataUpdater(db.Conn, new SqlServerTagCatalog(db.Conn, db.Boot)); + var u = new SqlServerHistorianDataUpdater(db.Conn, db.Boot, new SqlServerTagCatalog(db.Conn, db.Boot)); await u.UpdateDataAsync("t", HistoryUpdateMode.Insert, [V(T1, 1), V(T2, 2)], Who, CancellationToken.None); await BreakTheTrailAsync(db); @@ -99,7 +99,7 @@ public sealed class ModifiedHistoryAtomicityTests(SqlHistorianFixture fx) public async Task An_over_long_principal_is_truncated_never_refused() { var db = await ReadTestDb.CreateAsync(fx); - var u = new SqlServerHistorianDataUpdater(db.Conn, new SqlServerTagCatalog(db.Conn, db.Boot)); + var u = new SqlServerHistorianDataUpdater(db.Conn, db.Boot, new SqlServerTagCatalog(db.Conn, db.Boot)); var who = new HistoryUpdateContext(new string('p', 500), new string('k', 500)); (await u.UpdateDataAsync("t", HistoryUpdateMode.Insert, [V(T1, 1)], who, CancellationToken.None)) diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaBootstrapIntegrationTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaBootstrapIntegrationTests.cs index f6a1779c..5ec131ad 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaBootstrapIntegrationTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaBootstrapIntegrationTests.cs @@ -32,7 +32,7 @@ public sealed class SchemaBootstrapIntegrationTests(SqlHistorianFixture fx) var s = SqlHistorianFixture.UniqueSchema(); await Boot(Opts(s)).EnsureAsync(CancellationToken.None); await Boot(Opts(s)).EnsureAsync(CancellationToken.None); // fresh instance => re-runs the guarded path - (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.RequiredVersion); + (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.ModifiedTrailVersion); (await ScalarAsync($"SELECT COUNT(*) FROM sys.indexes WHERE name='CX_Event_Time' AND object_id=OBJECT_ID('[{s}].Event')")).ShouldBe(1); } @@ -51,13 +51,14 @@ public sealed class SchemaBootstrapIntegrationTests(SqlHistorianFixture fx) cmd.CommandText = b; await cmd.ExecuteNonQueryAsync(); } - (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.RequiredVersion); + (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.ModifiedTrailVersion); } /// /// #668 upgrade path: a schema left at version 1 (only 001_initial.sql applied, as every pre-#668 install is) /// is upgraded in place by an auto-creating bootstrap — SampleModified appears, both version rows exist, and - /// existing samples are untouched. With AutoCreateSchema=false the same v1 schema is refused. + /// existing samples are untouched. With AutoCreateSchema=false the same v1 schema is accepted with the + /// modification trail switched off and left at v1 (#674). /// [Fact] public async Task A_version_1_schema_is_upgraded_to_version_2_in_place() @@ -81,11 +82,15 @@ public sealed class SchemaBootstrapIntegrationTests(SqlHistorianFixture fx) } (await ScalarAsync($"SELECT COUNT(*) FROM sys.tables WHERE name = 'SampleModified' AND schema_id = SCHEMA_ID('{s}')")).ShouldBe(0); - var refused = await Should.ThrowAsync( - () => Boot(Opts(s, auto: false)).EnsureAsync(CancellationToken.None)); - refused.Message.ShouldContain("missing version 2 (found 1)"); + // #674: verify-only accepts v1 — with the modification trail switched off — and does not upgrade it. + var verifyOnly = Boot(Opts(s, auto: false)); + await verifyOnly.EnsureAsync(CancellationToken.None); + verifyOnly.SupportsModifiedTrail.ShouldBeFalse(); + (await ScalarAsync($"SELECT MAX(Version) FROM [{s}].SchemaVersion")).ShouldBe(1); - await Boot(Opts(s)).EnsureAsync(CancellationToken.None); + var upgrading = Boot(Opts(s)); + await upgrading.EnsureAsync(CancellationToken.None); + upgrading.SupportsModifiedTrail.ShouldBeTrue(); (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(2); (await ScalarAsync($"SELECT MAX(Version) FROM [{s}].SchemaVersion")).ShouldBe(2); @@ -101,7 +106,7 @@ public sealed class SchemaBootstrapIntegrationTests(SqlHistorianFixture fx) var s = SqlHistorianFixture.UniqueSchema(); var tasks = Enumerable.Range(0, 4).Select(_ => Task.Run(() => Boot(Opts(s)).EnsureAsync(CancellationToken.None))).ToArray(); await Task.WhenAll(tasks); - (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.RequiredVersion); + (await ScalarAsync($"SELECT COUNT(*) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.ModifiedTrailVersion); } [Fact] @@ -110,7 +115,7 @@ public sealed class SchemaBootstrapIntegrationTests(SqlHistorianFixture fx) fx.SkipIfUnavailable(); var ex = await Should.ThrowAsync( () => Boot(Opts(SqlHistorianFixture.UniqueSchema(), auto: false)).EnsureAsync(CancellationToken.None)); - ex.Message.ShouldContain("missing version 2"); + ex.Message.ShouldContain("missing version 1 (found 0)"); } [Fact] diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaV1PostureTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaV1PostureTests.cs new file mode 100644 index 00000000..85f14fa0 --- /dev/null +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SchemaV1PostureTests.cs @@ -0,0 +1,181 @@ +using Microsoft.Data.SqlClient; +using Microsoft.Extensions.Logging; +using Shouldly; +using Xunit; +using ZB.MOM.WW.OtOpcUa.Core.Abstractions; +using ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian; +using ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common; + +namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests; + +/// +/// Gitea #674: a database left at schema version 1 (no Part 11 SampleModified trail) with +/// AutoCreateSchema=false keeps historizing. Before #674 the bootstrapper required v2 and refused EVERY call — +/// live writes, raw reads, alarm events, retention — until script 002 was applied by hand. Now only the features +/// that need the trail are refused (BadHistoryOperationUnsupported, nothing sent to SQL), and the +/// bootstrapper logs ONE warning for the whole provider. Built through , the +/// production wiring, so every seam shares the one bootstrapper the way a node does. +/// +[Collection(SqlHistorianCollection.Name)] +public sealed class SchemaV1PostureTests(SqlHistorianFixture fx) +{ + private static CancellationToken Ct => TestContext.Current.CancellationToken; + private static readonly DateTime Recent = DateTime.UtcNow.AddHours(-1); + private static readonly HistoryUpdateContext Who = new("editor", "k1"); + + [Fact] + public async Task A_v1_schema_keeps_historizing_and_refuses_only_the_modified_trail_features() + { + fx.SkipIfUnavailable(); + var s = SqlHistorianFixture.UniqueSchema(); + await ApplyV1Async(s); + var old = DateTime.UtcNow.AddDays(-40); + var loggers = new CapturingLoggerFactory(); + var provider = new SqlServerHistorianProvider(new SqlServerHistorianOptions + { + ConnectionString = fx.ConnectionString, Schema = s, AutoCreateSchema = false, RetentionDays = 30, + }); + var sp = new LoggerServices(loggers); + + // Live writes (the continuous-historization drain) and raw reads work. + var writer = provider.CreateValueWriter(sp); + (await writer.WriteLiveValuesAsync("Plant.Speed", + [new HistorizationValue(old, HistorianValue.FromDouble(1), 0), new HistorizationValue(Recent, HistorianValue.FromDouble(2), 0)], + Ct)).ShouldBeTrue(); + var source = provider.CreateDataSource(sp); + var raw = await source.ReadRawAsync("Plant.Speed", Recent.AddMinutes(-1), Recent.AddMinutes(1), 10, Ct); + raw.Samples.Select(v => v.Value).ShouldBe([2d]); + + // Alarm events are written. + var alarms = provider.CreateAlarmWriter(sp); + (await alarms.WriteBatchAsync( + [new AlarmHistorianEvent("alarm-1", "Plant/Line/Eq", "HiTemp", "LimitAlarm", AlarmSeverity.High, "Activated", "m", "u", null, Recent)], + Ct)).ShouldBe([HistorianWriteOutcome.Ack]); + (await CountAsync($"SELECT COUNT(*) FROM [{s}].Event")).ShouldBe(1); + + // Modified reads: the interface's "no trail" signal (the node manager reports BadHistoryOperationUnsupported), + // not a backend failure — health stays clean. + await Should.ThrowAsync(() => + source.ReadModifiedAsync("Plant.Speed", Recent.AddDays(-1), Recent.AddDays(1), 10, null, Ct)); + source.GetHealthSnapshot().LastError.ShouldBeNull(); + + // HistoryUpdate: every item refused, and NOTHING reaches SQL — a sent MERGE/DELETE would either change the + // samples or fail on the missing SampleModified target; an Insert on an unknown tag would create its Tag row. + var updater = provider.CreateUpdater(sp)!; + var tagsBefore = await CountAsync($"SELECT COUNT(*) FROM [{s}].Tag"); + (await updater.UpdateDataAsync("Plant.Speed", HistoryUpdateMode.Update, + [new HistorizationValue(Recent, HistorianValue.FromDouble(99), 0), new HistorizationValue(Recent.AddSeconds(1), HistorianValue.FromDouble(98), 0)], + Who, Ct)).ShouldBe([HistorianStatusCodes.BadHistoryOperationUnsupported, HistorianStatusCodes.BadHistoryOperationUnsupported]); + (await updater.UpdateDataAsync("Plant.Brand.New", HistoryUpdateMode.Insert, + [new HistorizationValue(Recent, HistorianValue.FromDouble(1), 0)], Who, Ct)) + .ShouldBe([HistorianStatusCodes.BadHistoryOperationUnsupported]); + (await updater.DeleteRawAsync("Plant.Speed", Recent.AddMinutes(-1), Recent.AddMinutes(1), Who, Ct)) + .ShouldBe(HistorianStatusCodes.BadHistoryOperationUnsupported); + (await updater.DeleteAtTimeAsync("Plant.Speed", [Recent], Who, Ct)) + .ShouldBe([HistorianStatusCodes.BadHistoryOperationUnsupported]); + (await CountAsync($"SELECT COUNT(*) FROM [{s}].Tag")).ShouldBe(tagsBefore); + (await source.ReadRawAsync("Plant.Speed", Recent.AddMinutes(-1), Recent.AddMinutes(1), 10, Ct)) + .Samples.Select(v => v.Value).ShouldBe([2d]); + + // Retention purges samples and skips the trail it does not have. + var purge = await provider.CreateRetention(sp)!.PurgeAsync(Ct); + purge.Select(r => r.Table).ShouldBe(["Sample", "Event"]); + purge.Single(r => r.Table == "Sample").Rows.ShouldBe(1); + (await CountAsync($"SELECT COUNT(*) FROM [{s}].Sample")).ShouldBe(1); + + // One warning for the whole provider (= per boot), however many seams and calls touched the bootstrapper. + loggers.Warnings.Count(w => w.Contains("Part 11 modification trail is unavailable")).ShouldBe(1); + (await CountAsync($"SELECT MAX(Version) FROM [{s}].SchemaVersion")).ShouldBe(1); // verify-only: never upgraded + } + + /// + /// #674: AutoCreateSchema=true still upgrades a v1 schema to v2 — the modification trail appears and a + /// HistoryUpdate is recorded in it — and logs no v1 warning. + /// + [Fact] + public async Task Auto_create_still_upgrades_a_v1_schema_and_enables_the_trail() + { + fx.SkipIfUnavailable(); + var s = SqlHistorianFixture.UniqueSchema(); + await ApplyV1Async(s); + var loggers = new CapturingLoggerFactory(); + var provider = new SqlServerHistorianProvider(new SqlServerHistorianOptions + { + ConnectionString = fx.ConnectionString, Schema = s, AutoCreateSchema = true, + }); + var sp = new LoggerServices(loggers); + + (await provider.CreateUpdater(sp)!.UpdateDataAsync("Plant.Speed", HistoryUpdateMode.Insert, + [new HistorizationValue(Recent, HistorianValue.FromDouble(5), 0)], Who, Ct)) + .ShouldBe([HistorianStatusCodes.GoodEntryInserted]); + + (await CountAsync($"SELECT MAX(Version) FROM [{s}].SchemaVersion")).ShouldBe(SqlServerSchemaBootstrapper.ModifiedTrailVersion); + var trail = await provider.CreateDataSource(sp) + .ReadModifiedAsync("Plant.Speed", Recent.AddMinutes(-1), Recent.AddMinutes(1), 10, null, Ct); + trail.Values.ShouldHaveSingleItem().UpdateType.ShouldBe(HistoryModificationType.Insert); + loggers.Warnings.ShouldNotContain(w => w.Contains("Part 11 modification trail is unavailable")); + } + + private async Task ApplyV1Async(string schema) + { + var v1 = new StreamReader(typeof(SqlServerSchemaBootstrapper).Assembly.GetManifestResourceStream("Schema.001_initial.sql")!).ReadToEnd(); + await using var c = new SqlConnection(fx.ConnectionString); + await c.OpenAsync(Ct); + foreach (var b in SqlServerSchemaBootstrapper.SplitBatches(v1.Replace("$(Schema)", schema))) + { + await using var cmd = c.CreateCommand(); + cmd.CommandText = b; + await cmd.ExecuteNonQueryAsync(Ct); + } + } + + private async Task CountAsync(string sql) + { + await using var c = new SqlConnection(fx.ConnectionString); + await c.OpenAsync(Ct); + await using var cmd = c.CreateCommand(); + cmd.CommandText = sql; + return Convert.ToInt64(await cmd.ExecuteScalarAsync(Ct)); + } + + /// The only service the provider resolves is . + private sealed class LoggerServices(ILoggerFactory loggers) : IServiceProvider + { + public object? GetService(Type serviceType) => serviceType == typeof(ILoggerFactory) ? loggers : null; + } + + /// Captures every Warning-or-above message from every logger it creates. + private sealed class CapturingLoggerFactory : ILoggerFactory + { + private readonly List _warnings = []; + + public IReadOnlyList Warnings + { + get { lock (_warnings) return _warnings.ToList(); } + } + + public ILogger CreateLogger(string categoryName) => new Capturing(this); + + public void AddProvider(ILoggerProvider provider) + { + } + + public void Dispose() + { + } + + private sealed class Capturing(CapturingLoggerFactory owner) : ILogger + { + public IDisposable? BeginScope(TState state) where TState : notnull => null; + + public bool IsEnabled(LogLevel logLevel) => true; + + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception? exception, + Func formatter) + { + if (logLevel < LogLevel.Warning) return; + lock (owner._warnings) owner._warnings.Add(formatter(state, exception)); + } + } + } +} diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SqlServerConformanceBackend.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SqlServerConformanceBackend.cs index 79b71ce4..fd17aeaa 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SqlServerConformanceBackend.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.IntegrationTests/SqlServerConformanceBackend.cs @@ -34,7 +34,7 @@ internal sealed class SqlServerConformanceBackend : IConformanceBackend /// public IHistorianDataUpdater CreateUpdater() => - new SqlServerHistorianDataUpdater(_db.Conn, new SqlServerTagCatalog(_db.Conn, _db.Boot)); + new SqlServerHistorianDataUpdater(_db.Conn, _db.Boot, new SqlServerTagCatalog(_db.Conn, _db.Boot)); /// public async Task SeedAsync(string tag, params (DateTime T, HistorianValue V, uint Status)[] samples) => diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.Tests/SchemaScriptTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.Tests/SchemaScriptTests.cs index a260fc32..3f88a628 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.Tests/SchemaScriptTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer.Tests/SchemaScriptTests.cs @@ -32,7 +32,7 @@ public sealed class SchemaScriptTests /// /// #668: schema v2 (the Part 11 modification trail) is embedded, matches its docs copy, records version 2 (which - /// must equal ), and carries none of the constructs an + /// must equal ), and carries none of the constructs an /// OUTPUT … INTO target forbids (FOREIGN KEY / CHECK / trigger) — any of them would fail every HistoryUpdate. /// [Fact] @@ -45,7 +45,8 @@ public sealed class SchemaScriptTests text.ShouldContain("[SampleModified]"); text.ShouldContain("PRIMARY KEY CLUSTERED (TagId, SourceTimeUtc, ModifiedId)"); text.ShouldContain("VALUES (2, SYSUTCDATETIME())"); - SqlServerSchemaBootstrapper.RequiredVersion.ShouldBe(2); + SqlServerSchemaBootstrapper.ModifiedTrailVersion.ShouldBe(2); + SqlServerSchemaBootstrapper.RequiredVersion.ShouldBe(1); // #674: v1 is still served, without the trail var ddl = string.Join('\n', text.Split('\n').Where(l => !l.TrimStart().StartsWith("--", StringComparison.Ordinal))); ddl.ShouldNotContain("FOREIGN KEY", Case.Insensitive); ddl.ShouldNotContain("CHECK", Case.Insensitive); diff --git a/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/History/HistoryUpdateTests.cs b/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/History/HistoryUpdateTests.cs index 4448d22c..5f1cb99d 100644 --- a/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/History/HistoryUpdateTests.cs +++ b/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/History/HistoryUpdateTests.cs @@ -558,6 +558,190 @@ public sealed class HistoryUpdateTests : IDisposable finally { await host.DisposeAsync(); } } + // ───────────────────────────── #674 future-skew bound ───────────────────────────── + + /// + /// #674: an item whose SourceTimestamp lies beyond now + HistoryUpdateMaxFutureSkew is refused + /// BadOutOfRange by the node manager and never reaches the backend; an item exactly AT the bound and one in + /// the past are sent. Judged against the injected clock, not the wall clock. + /// + [Fact] + public async Task A_source_time_beyond_the_future_skew_is_bad_out_of_range_and_never_sent() + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + nm.Clock = new FakeClock(Start); + nm.HistoryUpdateMaxFutureSkew = TimeSpan.FromHours(1); + WireAcl(nm, enabled: false, NodePermissions.HistoryUpdate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + var atBound = Start.AddHours(1); + + var (results, errors) = Update(nm, KeyIdentity(OpcUaDataPlaneRoles.HistoryUpdate), nodeId, + PerformUpdateType.Update, Value(T1, 1d), Value(atBound.AddTicks(1), 2d), Value(atBound, 3d), + Value(new DateTime(2062, 1, 1, 0, 0, 0, DateTimeKind.Utc), 4d)); + + errors[0].StatusCode.Code.ShouldBe(StatusCodes.Good); + results[0].OperationResults.Select(c => c.Code).ShouldBe( + [ + StatusCodes.GoodEntryInserted, StatusCodes.BadOutOfRange, StatusCodes.GoodEntryInserted, + StatusCodes.BadOutOfRange, + ]); + updater.UpdateCalls.ShouldHaveSingleItem().Values.Select(v => v.TimestampUtc).ShouldBe([T1, atBound]); + } + finally { await host.DisposeAsync(); } + } + + /// #674: every mode is bounded, and a request whose items are ALL out of range sends nothing. + [Theory] + [InlineData(PerformUpdateType.Insert)] + [InlineData(PerformUpdateType.Replace)] + [InlineData(PerformUpdateType.Update)] + public async Task Every_update_mode_is_bounded_and_an_all_refused_request_sends_nothing(PerformUpdateType type) + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + nm.Clock = new FakeClock(Start); + WireAcl(nm, enabled: false, NodePermissions.HistoryUpdate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + + // Default skew: one day. + var (results, _) = Update(nm, KeyIdentity(OpcUaDataPlaneRoles.HistoryUpdate), nodeId, type, + Value(Start.AddDays(1).AddSeconds(1), 1d)); + + results[0].OperationResults.Select(c => c.Code).ShouldBe([StatusCodes.BadOutOfRange]); + updater.UpdateCalls.ShouldBeEmpty(); + } + finally { await host.DisposeAsync(); } + } + + /// #674: a non-positive skew disables the bound — a far-future item reaches the backend. + [Fact] + public async Task A_non_positive_skew_disables_the_bound() + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + nm.Clock = new FakeClock(Start); + nm.HistoryUpdateMaxFutureSkew = TimeSpan.Zero; + WireAcl(nm, enabled: false, NodePermissions.HistoryUpdate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + var farFuture = new DateTime(2062, 1, 1, 0, 0, 0, DateTimeKind.Utc); + + var (results, _) = Insert(nm, KeyIdentity(OpcUaDataPlaneRoles.HistoryUpdate), nodeId, Value(farFuture, 1d)); + + results[0].OperationResults.Select(c => c.Code).ShouldBe([StatusCodes.GoodEntryInserted]); + updater.UpdateCalls.ShouldHaveSingleItem().Values.ShouldHaveSingleItem().TimestampUtc.ShouldBe(farFuture); + } + finally { await host.DisposeAsync(); } + } + + // ───────────────────────────── #674 Primary gate ───────────────────────────── + + /// + /// #674: off-Primary, an authorized HistoryUpdate is refused BadInvalidState per node — on every arm + /// (update data, delete raw, delete at time) — and NOTHING reaches the updater. + /// + [Fact] + public async Task Off_primary_every_arm_is_bad_invalid_state_and_nothing_is_sent() + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + var consulted = 0; + nm.HistoryUpdatePrimaryGate = () => { Interlocked.Increment(ref consulted); return false; }; + WireAcl(nm, enabled: false, NodePermissions.HistoryUpdate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + var identity = KeyIdentity(OpcUaDataPlaneRoles.HistoryUpdate); + + var (results, errors) = Insert(nm, identity, nodeId, Value(T1, 1d)); + var (rawResults, rawErrors) = Call(nm, identity, typeof(DeleteRawModifiedDetails), + new DeleteRawModifiedDetails { NodeId = nodeId, StartTime = T1, EndTime = T2 }); + var (atResults, atErrors) = Call(nm, identity, typeof(DeleteAtTimeDetails), + new DeleteAtTimeDetails { NodeId = nodeId, ReqTimes = new DateTimeCollection { T1 } }); + + foreach (var (r, e) in new[] { (results, errors), (rawResults, rawErrors), (atResults, atErrors) }) + { + e[0].StatusCode.Code.ShouldBe(StatusCodes.BadInvalidState); + r[0].StatusCode.Code.ShouldBe(StatusCodes.BadInvalidState); + } + + consulted.ShouldBe(3); + updater.UpdateCalls.ShouldBeEmpty(); + updater.DeleteRawCalls.ShouldBeEmpty(); + updater.DeleteAtTimeCalls.ShouldBeEmpty(); + } + finally { await host.DisposeAsync(); } + } + + /// + /// #674: on the Primary the gate allows and the update REACHES the updater — the allow leg that makes the deny + /// leg meaningful (a gate that refused everything, or one never consulted, fails one of the two). + /// + [Fact] + public async Task On_primary_the_update_reaches_the_updater() + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + var consulted = 0; + nm.HistoryUpdatePrimaryGate = () => { Interlocked.Increment(ref consulted); return true; }; + WireAcl(nm, enabled: false, NodePermissions.HistoryUpdate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + + var (results, errors) = Insert(nm, KeyIdentity(OpcUaDataPlaneRoles.HistoryUpdate), nodeId, Value(T1, 1d)); + + errors[0].StatusCode.Code.ShouldBe(StatusCodes.Good); + results[0].OperationResults.Select(c => c.Code).ShouldBe([StatusCodes.GoodEntryInserted]); + updater.UpdateCalls.ShouldHaveSingleItem().Tag.ShouldBe(Tagname); + consulted.ShouldBe(1); + } + finally { await host.DisposeAsync(); } + } + + /// + /// #674: the Primary gate runs AFTER authorization — an unauthorized caller is told BadUserAccessDenied + /// (not the node's role) and the gate is never consulted. + /// + [Fact] + public async Task The_primary_gate_runs_after_authorization() + { + var (host, server) = await BootAsync(); + try + { + var nm = server.NodeManager!; + var updater = new FakeUpdater(); + nm.HistorianDataUpdater = updater; + var consulted = 0; + nm.HistoryUpdatePrimaryGate = () => { Interlocked.Increment(ref consulted); return false; }; + WireAcl(nm, enabled: false, NodePermissions.WriteOperate); + var nodeId = Historized(nm, AddressSpaceRealm.Raw, RawPath); + + var (results, _) = Insert(nm, KeyIdentity(OpcUaDataPlaneRoles.WriteOperate), nodeId, Value(T1, 1d)); + + results[0].StatusCode.Code.ShouldBe(StatusCodes.BadUserAccessDenied); + consulted.ShouldBe(0); + updater.UpdateCalls.ShouldBeEmpty(); + } + finally { await host.DisposeAsync(); } + } + // ───────────────────────────── helpers ───────────────────────────── private static DataValue Value(DateTime timestamp, object value) => diff --git a/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerHistoryReadModifiedTests.cs b/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerHistoryReadModifiedTests.cs index fc12cc7f..164638c1 100644 --- a/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerHistoryReadModifiedTests.cs +++ b/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerHistoryReadModifiedTests.cs @@ -203,6 +203,28 @@ public sealed class NodeManagerHistoryReadModifiedTests : IDisposable await host.DisposeAsync(); } + /// + /// #674: the HistoryUpdate Primary gate does not reach HistoryRead — a closed gate neither refuses a read nor is + /// consulted by one (reads are served from any redundancy node), for modified and raw reads alike. + /// + [Fact] + public async Task The_history_update_primary_gate_is_not_consulted_for_reads() + { + var (host, nm, node, src) = await SetupAsync([Mod(1, 1, 1, HistoryModificationType.Update, "u", Epoch)]); + var consulted = 0; + nm.HistoryUpdatePrimaryGate = () => { Interlocked.Increment(ref consulted); return false; }; + + var modified = Read(nm, node, Epoch, Epoch.AddHours(1), max: 10, cp: null); + var raw = Read(nm, node, Epoch, Epoch.AddHours(1), max: 10, cp: null, modified: false); + + modified.Error.StatusCode.Code.ShouldBe(StatusCodes.Good); + modified.Data!.DataValues.Count.ShouldBe(1); + raw.Error.StatusCode.Code.ShouldNotBe(StatusCodes.BadInvalidState); + src.Calls.ShouldBe(1); + consulted.ShouldBe(0); + await host.DisposeAsync(); + } + [Fact] public async Task A_backend_failure_is_isolated_to_its_node() { diff --git a/tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/ServerHistorianOptionsTests.cs b/tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/ServerHistorianOptionsTests.cs index 4f38cc8a..767ec21f 100644 --- a/tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/ServerHistorianOptionsTests.cs +++ b/tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Historian/ServerHistorianOptionsTests.cs @@ -1,3 +1,4 @@ +using Microsoft.Extensions.Configuration; using Xunit; using ZB.MOM.WW.OtOpcUa.Runtime.Historian; @@ -99,6 +100,29 @@ public sealed class ServerHistorianOptionsTests Assert.Contains(w, m => m.Contains("MaxTimeWeightedRawRows")); } + /// + /// #674: the HistoryUpdate future-skew bound defaults to one day and binds from configuration as a TimeSpan; + /// a non-positive value is a deliberate "disabled", not a misconfiguration, so it does not warn. + /// + [Fact] + public void HistoryUpdateMaxFutureSkew_defaults_to_one_day_binds_and_zero_is_silent() + { + Assert.Equal(TimeSpan.FromDays(1), new ServerHistorianOptions().HistoryUpdateMaxFutureSkew); + var bound = new ConfigurationBuilder() + .AddInMemoryCollection(new Dictionary + { + ["ServerHistorian:HistoryUpdateMaxFutureSkew"] = "00:05:00", + }) + .Build() + .GetSection(ServerHistorianOptions.SectionName) + .Get(); + Assert.Equal(TimeSpan.FromMinutes(5), bound!.HistoryUpdateMaxFutureSkew); + var w = new ServerHistorianOptions + { Enabled = true, Endpoint = "https://h:5222", ApiKey = "histgw_x_y", HistoryUpdateMaxFutureSkew = TimeSpan.Zero } + .Validate(); + Assert.Empty(w); + } + [Fact] public void Disabled_with_nonpositive_HistoryRead_knobs_is_silent() {