Compare commits

...

3 Commits

Author SHA1 Message Date
Joseph Doherty 22136d36d9 feat(testrun): route WaitForAttribute in the Test-Run sandbox (deferred #14)
Closes deferred-work register item #14 with full fidelity. The Central UI Test-Run
sandbox previously threw ScriptSandboxException for Attributes.WaitAsync/WaitForAsync;
now the value-equality forms route to the bound deployed instance over the same
cross-site path inbound Route.To().WaitForAttribute() uses.

- Commons: additive trailing RouteToWaitForAttributeRequest.RequireGoodQuality
  (default false; message-evolution safe) so quality-gated waits route too.
- SiteRuntime: DeploymentManagerActor's routed-wait handler now threads
  request.RequireGoodQuality into the InstanceActor WaitForAttributeRequest
  (previously hard-coded to default).
- CentralUI sandbox: ISandboxInstanceGateway.WaitForAttributeAsync +
  SandboxInstanceGateway impl (via CommunicationService.RouteToWaitForAttributeAsync);
  SandboxAttributeAccessor value-equality WaitAsync/WaitForAsync route through it
  (codec-encoded target, scope-resolved name). Predicate overloads stay unsupported
  (an in-process lambda can't be routed) and throw a clearer, dedicated message.
- Tests: sandbox accessor routing + predicate/unbound rejection (CentralUI);
  site-handler RequireGoodQuality threading (SiteRuntime). Register + the historical
  waitfor-deferred plan doc updated.

Full slnx build 0/0; CentralUI 59, SiteRuntime routed-wait 4, InboundAPI wait 32 green.

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 09:29:38 -04:00
Joseph Doherty 4cd21b342b feat(auditlog): make SiteAuditBacklogReporter cadence configurable (deferred #21)
Consolidates the reporter's poll cadence onto SqliteAuditWriterOptions instead of
the hard-coded 30 s constant, closing deferred-work register item #21 (the config-
shape cleanup its own XML doc flagged as a follow-up).

- SqliteAuditWriterOptions.BacklogPollIntervalSeconds (default 30).
- Reporter reads it via IOptions; precedence explicit-override (tests) > configured
  > 30 s default; a non-positive value falls back to the default. Corrected the
  stale "hard-code / tunable in a follow-up" class-doc.
- Cadence tests + register updated (row 21 -> Resolved).

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 08:56:32 -04:00
Joseph Doherty f480a56737 feat(instance): native-alarm-source-override CSV bulk import (deferred #12) + doc fixes
Closes the operator parity gap the deferred-work register tracked as #12: native
alarm source overrides could only be set one-at-a-time, while attribute overrides
had a CSV bulk path. Adds an all-or-nothing CSV import for native sources.

- Commons: extract the RFC-4180 line splitter into a shared CsvLineSplitter
  (refactor OverrideCsvParser onto it — no behavior change, pinned by its tests);
  new NativeAlarmSourceOverrideCsvParser (header SourceName,Connection,
  SourceReference,Filter; blank = inherited).
- Commons: NativeAlarmSourceOverrideEntry + bulk SetInstanceNativeAlarmSource-
  OverridesCommand (auto-registered via the reflection command registry).
- ManagementService: Deployer-gated handler — flattens once, validates every
  source resolves + is unlocked + no duplicates up front, then upserts the whole
  batch under a single SaveChanges (true all-or-nothing txn). Added to the frozen
  authorization matrix; dispatch-coverage guard passes.
- CLI: `instance native-alarm-source import --instance-id --file` (parity with
  `instance import-overrides`) + README.
- Tests: native parser (Commons), CLI parse/entry mapping, 3 bulk-handler tests
  (happy path single-commit, locked-source reject, unresolved-source reject).

Also corrects a stale XML-doc line in ScriptRuntimeContext (WaitForAttribute
quality-gated mode is shipped, not "planned") and updates the deferred-work
register: marks #7/#13/#15/#16/#20 verified-resolved, #12 as CLI/API-shipped with
only the Central UI upload affordance still pending.

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 08:52:12 -04:00
23 changed files with 1067 additions and 143 deletions
@@ -219,8 +219,8 @@ WD-1 must add `RequireGoodQuality` ONLY as a **trailing defaulted** ctor param o
---
## Out of scope (explicit)
## Out of scope (explicit — at original authoring)
- Routed `WaitForAttribute` is NOT wired into the CentralUI Test-Run sandbox (`ISandboxInstanceGateway`/`SandboxInstanceGateway`); production inbound scripts get it. Follow-up if Test-Run parity is wanted.
- No predicate or quality flag across the wire (§6 is value-equality only, per spec).
- ~~Routed `WaitForAttribute` is NOT wired into the CentralUI Test-Run sandbox~~ **DELIVERED 2026-07-10 (deferred-work #14, full fidelity):** value-equality `Attributes.WaitAsync`/`WaitForAsync` in the sandbox now route to the bound instance via `ISandboxInstanceGateway.WaitForAttributeAsync` → `CommunicationService.RouteToWaitForAttributeAsync`. Predicate overloads stay unsupported (an in-process lambda cannot be routed) and throw a labelled `ScriptSandboxException`.
- ~~No quality flag across the wire~~ **Superseded:** `RouteToWaitForAttributeRequest` gained an additive trailing `bool RequireGoodQuality = false`, honored by the site handler, so quality-gated waits route too. Predicate matching is still value-equality-only across the wire (no cross-process lambda).
- No docker redeploy (no cluster-runtime config change; additive script surface only).
@@ -18,23 +18,30 @@ them and are removed from this table when that plan's task lands.
## Deferred (with rationale + revisit trigger)
| # | Item | Where noted | Rationale for deferral | Revisit trigger |
|---|------|-------------|------------------------|-----------------|
| 7 | SecuredWrite audit rows leave SourceNode NULL | CLAUDE.md Security | Logged follow-up; low-volume channel | First per-node forensic query against secured writes |
| 8 | Hash-chain tamper evidence (T1); CLI verify-chain is a no-op stub | audit-log roadmap :12 | v1.x by locked decision; append-only DB roles are the control | Compliance requirement for cryptographic tamper evidence |
| 9 | Parquet audit archival (T2); endpoint returns 501 | AuditEndpoints.cs:204 | v1.x; 501 + CLI messaging are honest | AuditLog partition volume nears retention ceiling |
| 10 | Aggregated live alarm stream for Alarm Summary | m7 design :252 | Snapshot fan-out acceptable at current instance counts | Alarm Summary latency complaints or >~50 instances/site |
| 11 | Central-persisted OPC UA cert-trust audit | m7 follow-ups | Broadcast-to-both-nodes covers HA | Governance/audit requirement for trust decisions |
| 12 | Native-alarm-source-override CSV import | m7 follow-ups | Parity gap only; attribute CSV shipped | First bulk native-alarm rollout request |
| 13 | WaitForAttribute quality-gated mode | ScriptRuntimeContext.cs:405 | Planned enhancement per spec §4.2 | First script needing Good-only waits |
| 14 | WaitForAttribute in Test-Run sandbox | waitfor-deferred :222 | Test-Run parity gap; production unaffected | Author feedback on Test-Run fidelity |
| 15 | BrowseNext final-page signal not surfaced | BrowseCommands.cs:34 | One wasted round-trip | UX complaint on browse paging |
| 16 | StubOpcUaClient throws on browse | m7 design :245 | Limits offline UI coverage only | Next browse/search UI regression |
| 12 | Native-alarm-source-override CSV import — **Central UI `InstanceConfigure` upload affordance only** (CLI + Management API + parser shipped 2026-07-10, see Resolved) | m7 follow-ups | CLI/API path closes the operator parity gap; the Blazor upload button is polish | First request to bulk-import native sources from the UI rather than the CLI |
| 17 | Unified notifications+site-calls outbox page | stillpending :118 | Explicit M9 decision to keep two pages | Operator confusion reports |
| 18 | Folder drag-drop | same, [PERM] | Permanently closed; menu reorder shipped | — (closed) |
| 19 | Bundle signing / cluster-to-cluster pull / differential bundles | transport-design :402 | v1 manifest hash + AES-GCM held sufficient | Non-repudiation requirement across orgs |
| 20 | Deployment EXPIRED-row purge | DeploymentManagerRepository.cs:310 | Read path already compensates | EXPIRED rows visible in ops queries |
| 21 | SiteAuditBacklogReporter threshold consolidation | SiteAuditBacklogReporter.cs:28 | Config-shape cleanup only | Next SqliteAuditWriterOptions change |
| 22 | KPI history hourly rollups | Component-KpiHistory.md | YAGNI; 90-day retention bounds table | KpiSample query latency on dashboards |
## Resolved (verified against the code 2026-07-10)
Rows removed from the Deferred table above once confirmed shipped. Kept here for traceability.
| # | Item | Resolution |
|---|------|-----------|
| 7 | SecuredWrite audit rows leave SourceNode NULL | Resolved (PLAN-07): `ManagementActor.EmitSecuredWriteAuditAsync` routes through `ICentralAuditWriter`, which stamps `SourceNode` (`central-a`/`central-b`) from `INodeIdentityProvider`. |
| 12 (CLI/API) | Native-alarm-source-override CSV import | Shipped 2026-07-10: shared `CsvLineSplitter`, `NativeAlarmSourceOverrideCsvParser`, bulk all-or-nothing `SetInstanceNativeAlarmSourceOverridesCommand` + ManagementActor handler (Deployer-gated), CLI `instance native-alarm-source import --file`, parser/CLI/handler tests. **UI upload affordance still pending — see row 12 above.** |
| 13 | WaitForAttribute quality-gated ("Good"-only) mode | Already implemented (Commons `WaitForAttribute.RequireGoodQuality`, enforced in `InstanceActor`, threaded through `ScriptRuntimeContext`, tested in `InstanceActorWaitForAttributeTests`). Stale "planned enhancement" doc line corrected 2026-07-10. |
| 14 | WaitForAttribute in Test-Run sandbox | Shipped 2026-07-10 (full fidelity): sandbox `Attributes.WaitAsync`/`WaitForAsync` (value-equality) route to the bound instance via `ISandboxInstanceGateway.WaitForAttributeAsync` → the existing `CommunicationService.RouteToWaitForAttributeAsync` cross-site route. Additive `RouteToWaitForAttributeRequest.RequireGoodQuality` (honored by the site handler) makes quality-gated waits route too. **Predicate-form waits stay unsupported** (an in-process lambda can't be routed) and throw a labelled `ScriptSandboxException`. Tests: sandbox accessor routing (CentralUI), site-handler quality-flag threading (SiteRuntime). |
| 15 | BrowseNext final-page signal not surfaced | Already surfaced (M7 browse work): `RealOpcUaClient` sets `Truncated=false`/`ContinuationToken=null` on the last page; `BrowseNodeResult` carries both; `TreeRow.razor` renders "Load more" only when a continuation token remains — no wasted BrowseNext. |
| 16 | StubOpcUaClient throws on browse | Already resolved: `StubOpcUaClient` supports browse + address-space search, covered by `StubOpcUaClientBrowseTests`/`StubOpcUaClientSearchTests`. |
| 20 | Deployment EXPIRED-row purge | Already resolved (PLAN-04): `PendingDeploymentPurgeActor` central singleton (spawned in `AkkaHostedService`) ticks `IDeploymentManagerRepository.PurgeExpiredPendingDeploymentsAsync` every `CommunicationOptions.PendingDeploymentPurgeInterval` (default 1h), options-validated, tested. |
| 21 | SiteAuditBacklogReporter threshold consolidation | Shipped 2026-07-10: `SqliteAuditWriterOptions.BacklogPollIntervalSeconds` (default 30) now drives the reporter's poll cadence; explicit ctor override still wins (tests), non-positive falls back to the 30 s default. Cadence tests added; stale "hard-code / follow-up" class-doc corrected. |
## New deferrals from review 08 (this plan)
| Item | Rationale | Revisit trigger |
|------|-----------|-----------------|
@@ -1,5 +1,6 @@
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
using ZB.MOM.WW.ScadaBridge.HealthMonitoring;
@@ -25,9 +26,8 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Site;
/// <b>Cadence.</b> 30 s by default — coarse enough to amortise the SQL probe
/// across many reports, fine enough that the central dashboard never lags by
/// more than one health-report interval. Tunable via
/// <see cref="ZB.MOM.WW.ScadaBridge.AuditLog.Site.SqliteAuditWriterOptions"/> in a follow-up
/// if ops needs a different cadence; for now we hard-code the value because the
/// brief calls it out explicitly.
/// <see cref="ZB.MOM.WW.ScadaBridge.AuditLog.Site.SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/>
/// (a non-positive value falls back to the 30 s default).
/// </para>
/// <para>
/// <b>Failure containment.</b> The probe call is wrapped in a try/catch so a
@@ -56,17 +56,42 @@ public sealed class SiteAuditBacklogReporter : IHostedService, IDisposable
/// <param name="queue">The site audit queue used to probe the backlog count.</param>
/// <param name="collector">The site health collector that receives the backlog snapshot.</param>
/// <param name="logger">Logger instance.</param>
/// <param name="refreshInterval">Poll interval override; defaults to <see cref="DefaultRefreshInterval"/> (30 s).</param>
/// <param name="refreshInterval">
/// Explicit poll-interval override (used by tests). When null, the cadence comes from
/// <see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/>, falling back to
/// <see cref="DefaultRefreshInterval"/> (30 s) when that is unset or non-positive.
/// </param>
/// <param name="options">
/// SQLite audit-writer options supplying the configurable poll cadence
/// (<see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/>). Optional so
/// direct construction in tests need not build the options graph.
/// </param>
public SiteAuditBacklogReporter(
ISiteAuditQueue queue,
ISiteHealthCollector collector,
ILogger<SiteAuditBacklogReporter> logger,
TimeSpan? refreshInterval = null)
TimeSpan? refreshInterval = null,
IOptions<SqliteAuditWriterOptions>? options = null)
{
_queue = queue ?? throw new ArgumentNullException(nameof(queue));
_collector = collector ?? throw new ArgumentNullException(nameof(collector));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
_refreshInterval = refreshInterval ?? DefaultRefreshInterval;
// Precedence: explicit override (tests) → configured cadence → 30 s default.
_refreshInterval = refreshInterval ?? ResolveInterval(options) ?? DefaultRefreshInterval;
}
/// <summary>The resolved poll cadence (exposed for tests).</summary>
internal TimeSpan RefreshInterval => _refreshInterval;
/// <summary>
/// Maps <see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/> to a
/// <see cref="TimeSpan"/>, or null when unconfigured / non-positive (caller then
/// falls back to <see cref="DefaultRefreshInterval"/>).
/// </summary>
private static TimeSpan? ResolveInterval(IOptions<SqliteAuditWriterOptions>? options)
{
var seconds = options?.Value.BacklogPollIntervalSeconds ?? 0;
return seconds > 0 ? TimeSpan.FromSeconds(seconds) : null;
}
/// <summary>Starts the background polling loop, running an immediate first probe before entering the timed cycle.</summary>
@@ -24,4 +24,13 @@ public sealed class SqliteAuditWriterOptions
/// <summary>Soft flush interval the writer enforces when fewer than BatchSize events are queued.</summary>
public int FlushIntervalMs { get; set; } = 50;
/// <summary>
/// Poll cadence, in seconds, for the <c>SiteAuditBacklogReporter</c> hosted service
/// that probes the SQLite audit backlog and pushes the snapshot onto the site health
/// report. Half a typical 60 s health-report interval keeps the snapshot fresh without
/// spinning the SQL probe more often than necessary. A non-positive value falls back to
/// the reporter's 30 s default.
/// </summary>
public int BacklogPollIntervalSeconds { get; set; } = 30;
}
@@ -477,6 +477,53 @@ public static class InstanceCommands
});
group.Add(clearCmd);
// import (CSV bulk apply — parity with `instance import-overrides`)
var importIdOption = new Option<int>("--instance-id") { Description = "Instance ID", Required = true };
var importFileOption = new Option<string>("--file")
{
Description = "Path to the override CSV file (columns: SourceName,Connection,SourceReference,Filter; blank field = inherited)",
Required = true
};
var importCmd = new Command("import")
{
Description = "Apply native alarm source overrides from a CSV file (all-or-nothing)"
};
importCmd.Add(importIdOption);
importCmd.Add(importFileOption);
importCmd.SetAction(async (ParseResult result) =>
{
var id = result.GetValue(importIdOption);
var filePath = result.GetValue(importFileOption)!;
string csvText;
try
{
csvText = File.ReadAllText(filePath);
}
catch (Exception ex)
{
OutputFormatter.WriteError($"Cannot read file '{filePath}': {ex.Message}", "FILE_READ_ERROR");
return 1;
}
var parseResult = NativeAlarmSourceOverrideCsvParser.Parse(csvText);
if (parseResult.Errors.Count > 0)
{
foreach (var error in parseResult.Errors)
OutputFormatter.WriteError(error, "INVALID_CSV");
return 1;
}
var overrides = parseResult.Rows
.Select(r => new NativeAlarmSourceOverrideEntry(
r.SourceName, r.Connection, r.SourceReference, r.Filter))
.ToList();
return await CommandHelpers.ExecuteCommandAsync(
result, urlOption, formatOption, usernameOption, passwordOption,
new SetInstanceNativeAlarmSourceOverridesCommand(id, overrides));
});
group.Add(importCmd);
return group;
}
+25
View File
@@ -503,6 +503,31 @@ Clear an instance's native alarm source override, reverting to the inherited bin
scadabridge --url <url> instance native-alarm-source clear --instance-id <int> --source <string>
```
#### `instance native-alarm-source import`
Bulk-apply native alarm source overrides for a single instance from a CSV file
(all-or-nothing — the native-source parity of `instance import-overrides`). The CSV
header is required: `SourceName,Connection,SourceReference,Filter`; a blank override
field keeps the inherited value. Every named source must resolve for the instance and
be unlocked, or the whole batch is rejected before any write.
```sh
scadabridge --url <url> instance native-alarm-source import --instance-id <int> --file <path>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--instance-id` | yes | Instance ID |
| `--file` | yes | Path to the override CSV (`SourceName,Connection,SourceReference,Filter`; blank field = inherited) |
Example CSV:
```csv
SourceName,Connection,SourceReference,Filter
Pressure,OpcB,ns=2;s=Pump.Alarm,Active
Module.Temp,,,
```
#### `instance deploy`
Deploy an instance to its site. Acquires the per-instance operation lock.
@@ -1,4 +1,5 @@
using ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
using ZB.MOM.WW.ScadaBridge.Commons.Types;
using ZB.MOM.WW.ScadaBridge.Communication;
namespace ZB.MOM.WW.ScadaBridge.CentralUI.ScriptAnalysis;
@@ -74,4 +75,22 @@ public sealed class SandboxInstanceGateway : ISandboxInstanceGateway
$"CallScript(\"{canonicalScriptName}\") on bound instance '{_instanceUniqueName}' failed: {response.ErrorMessage}");
return response.ReturnValue;
}
/// <inheritdoc />
public async Task<WaitResult> WaitForAttributeAsync(
string canonicalName, string? targetValueEncoded, TimeSpan timeout, bool requireGoodQuality, CancellationToken ct)
{
// Reuse the inbound-API cross-site wait route (RouteToWaitForAttributeAsync) — the
// same real event-driven waiter Route.To().WaitForAttribute() uses. ParentExecutionId
// is null for the sandbox path (no inbound execution to link).
var request = new RouteToWaitForAttributeRequest(
Guid.NewGuid().ToString(), _instanceUniqueName, canonicalName,
targetValueEncoded, timeout, DateTimeOffset.UtcNow,
ParentExecutionId: null, RequireGoodQuality: requireGoodQuality);
var response = await _comms.RouteToWaitForAttributeAsync(_siteId, request, _runToken);
if (!response.Success)
throw new ScriptSandboxException(
$"WaitForAttribute(\"{canonicalName}\") on bound instance '{_instanceUniqueName}' failed: {response.ErrorMessage}");
return new WaitResult(response.Matched, response.Value, response.Quality, response.TimedOut);
}
}
@@ -114,6 +114,21 @@ public interface ISandboxInstanceGateway
/// <returns>The script result, or null if none.</returns>
Task<object?> CallScriptAsync(
string canonicalScriptName, IReadOnlyDictionary<string, object?>? parameters, CancellationToken ct);
/// <summary>
/// Blocks until the named attribute reaches a target value (value-equality,
/// codec-encoded), optionally quality-gated, or the timeout elapses — routed to the
/// bound deployed instance cross-site. Value-equality only: a script-side predicate
/// cannot be routed, so the sandbox predicate overloads stay unsupported.
/// </summary>
/// <param name="canonicalName">The (already scope-resolved) canonical attribute name.</param>
/// <param name="targetValueEncoded">The <c>AttributeValueCodec</c>-encoded target value, or null for "any change".</param>
/// <param name="timeout">Maximum time to wait.</param>
/// <param name="requireGoodQuality">When true, only a Good-quality value satisfies the wait.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The wait outcome (matched flag, matched value, quality, timed-out flag).</returns>
Task<WaitResult> WaitForAttributeAsync(
string canonicalName, string? targetValueEncoded, TimeSpan timeout, bool requireGoodQuality, CancellationToken ct);
}
/// <summary>
@@ -212,6 +227,26 @@ public class SandboxInstanceContext
"bind one in Test Run to call sibling scripts.");
return _gateway.CallScriptAsync(scriptName, ScriptArgs.Normalize(parameters), CancellationToken.None);
}
/// <summary>
/// Routes a value-equality attribute wait to the bound deployed instance cross-site.
/// Needs a bound instance (the site owns the event-driven waiter); throws when unbound.
/// </summary>
/// <param name="canonicalName">The (already scope-resolved) canonical attribute name.</param>
/// <param name="targetValueEncoded">The codec-encoded target value, or null for "any change".</param>
/// <param name="timeout">Maximum time to wait.</param>
/// <param name="requireGoodQuality">When true, only a Good-quality value satisfies the wait.</param>
/// <returns>The wait outcome.</returns>
public Task<WaitResult> WaitForAttribute(
string canonicalName, string? targetValueEncoded, TimeSpan timeout, bool requireGoodQuality)
{
if (_gateway == null)
throw new ScriptSandboxException(
$"WaitForAttribute(\"{canonicalName}\") needs a deployed instance — " +
"bind one in Test Run to exercise the event-driven attribute waiter.");
return _gateway.WaitForAttributeAsync(
canonicalName, targetValueEncoded, timeout, requireGoodQuality, CancellationToken.None);
}
}
/// <summary>
@@ -342,20 +377,23 @@ public class SandboxAttributeAccessor
=> throw NotInSandbox(nameof(WriteBatchAndWaitAsync));
/// <summary>
/// Sandbox stand-in for <c>AttributeAccessor.WaitAsync</c> (value-equality form);
/// see <see cref="WriteBatchAndWaitAsync"/>.
/// Value-equality attribute wait — routed to the bound deployed instance cross-site
/// (the same real event-driven waiter a site uses). Needs a bound instance; throws
/// <see cref="ScriptSandboxException"/> when the Test Run has no instance bound.
/// </summary>
/// <param name="key">The attribute key to observe.</param>
/// <param name="targetValue">The value to wait for.</param>
/// <param name="targetValue">The value to wait for (codec-normalized), or null for "any change".</param>
/// <param name="timeout">The maximum time to wait.</param>
/// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
/// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
public Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false)
=> throw NotInSandbox(nameof(WaitAsync));
/// <returns>True when the attribute reached the target within the timeout; false on timeout.</returns>
public async Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false)
=> (await _ctx.WaitForAttribute(
Resolve(key), AttributeValueCodec.Encode(targetValue), timeout, requireGoodQuality)).Matched;
/// <summary>
/// Sandbox stand-in for <c>AttributeAccessor.WaitAsync</c> (predicate form);
/// see <see cref="WriteBatchAndWaitAsync"/>.
/// Predicate-form attribute wait. Unsupported in Test Run because a script-side
/// predicate (an in-process lambda) cannot be evaluated on the remote site — only the
/// value-equality overloads route. Throws a clearly-labelled <see cref="ScriptSandboxException"/>.
/// </summary>
/// <param name="key">The attribute key to observe.</param>
/// <param name="predicate">The predicate the attribute value must satisfy.</param>
@@ -363,23 +401,25 @@ public class SandboxAttributeAccessor
/// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
/// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
public Task<bool> WaitAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false)
=> throw NotInSandbox(nameof(WaitAsync));
=> throw PredicateWaitNotRoutable(nameof(WaitAsync));
/// <summary>
/// Sandbox stand-in for <c>AttributeAccessor.WaitForAsync</c> (value-equality form);
/// see <see cref="WriteBatchAndWaitAsync"/>.
/// Value-equality attribute wait returning the full <see cref="WaitResult"/> — routed
/// to the bound deployed instance cross-site. Needs a bound instance; throws
/// <see cref="ScriptSandboxException"/> when the Test Run has no instance bound.
/// </summary>
/// <param name="key">The attribute key to observe.</param>
/// <param name="targetValue">The value to wait for.</param>
/// <param name="targetValue">The value to wait for (codec-normalized), or null for "any change".</param>
/// <param name="timeout">The maximum time to wait.</param>
/// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
/// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
/// <returns>The wait outcome (matched flag, matched value, quality, timed-out flag).</returns>
public Task<WaitResult> WaitForAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false)
=> throw NotInSandbox(nameof(WaitForAsync));
=> _ctx.WaitForAttribute(Resolve(key), AttributeValueCodec.Encode(targetValue), timeout, requireGoodQuality);
/// <summary>
/// Sandbox stand-in for <c>AttributeAccessor.WaitForAsync</c> (predicate form);
/// see <see cref="WriteBatchAndWaitAsync"/>.
/// Predicate-form attribute wait returning the full <see cref="WaitResult"/>.
/// Unsupported in Test Run for the same reason as the predicate <see cref="WaitAsync(string, Func{object?, bool}, TimeSpan, bool)"/>
/// overload — an in-process predicate cannot be routed to the remote site.
/// </summary>
/// <param name="key">The attribute key to observe.</param>
/// <param name="predicate">The predicate the attribute value must satisfy.</param>
@@ -387,12 +427,18 @@ public class SandboxAttributeAccessor
/// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
/// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
public Task<WaitResult> WaitForAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false)
=> throw NotInSandbox(nameof(WaitForAsync));
=> throw PredicateWaitNotRoutable(nameof(WaitForAsync));
private static ScriptSandboxException NotInSandbox(string member) =>
new($"{member}(...) drives live device tags and the site's event-driven " +
"attribute waiter, which aren't available in the central Test Run sandbox — " +
"deploy to a site to exercise batch-write/wait handshakes.");
private static ScriptSandboxException PredicateWaitNotRoutable(string member) =>
new($"{member}(...) with a predicate can't run in Test Run — a script-side " +
"predicate is an in-process lambda that cannot be evaluated on the remote " +
"site. Use the value-equality overload (which routes to the bound instance), " +
"or deploy to a site to exercise predicate waits.");
}
/// <summary>
@@ -87,9 +87,10 @@ public record RouteToSetAttributesResponse(
/// <summary>
/// Request to block until a remote instance attribute reaches a target value
/// (spec §6 — <c>Route.To("inst").WaitForAttribute(name, targetValue, timeout)</c>).
/// Value-equality ONLY across the wire: <see cref="TargetValueEncoded"/> carries the
/// canonical <c>AttributeValueCodec</c>-encoded target; there is no predicate and no
/// quality flag in the comparison. The site evaluates equality and either matches or
/// Value-equality across the wire: <see cref="TargetValueEncoded"/> carries the
/// canonical <c>AttributeValueCodec</c>-encoded target; there is no predicate (a
/// cross-process lambda cannot be routed). <see cref="RequireGoodQuality"/> optionally
/// gates the match on Good quality. The site evaluates the match and either matches or
/// times out.
/// </summary>
/// <param name="ParentExecutionId">
@@ -99,6 +100,12 @@ public record RouteToSetAttributesResponse(
/// so the inbound→site execution-tree link survives the wait path. Additive trailing
/// member — null for the Central UI sandbox path or for callers built before the field existed.
/// </param>
/// <param name="RequireGoodQuality">
/// Quality-gated ("Good"-only) mode (spec §4.2): when true, a value reaching the target at
/// Bad/Uncertain quality is NOT a match — the site holds the wait until the value satisfies
/// the target at Good quality (or times out). Additive trailing member; defaults to
/// <see langword="false"/> (quality-agnostic) so older callers and the wire default are unchanged.
/// </param>
public record RouteToWaitForAttributeRequest(
string CorrelationId,
string InstanceUniqueName,
@@ -106,7 +113,8 @@ public record RouteToWaitForAttributeRequest(
string? TargetValueEncoded,
TimeSpan Timeout,
DateTimeOffset Timestamp,
Guid? ParentExecutionId = null);
Guid? ParentExecutionId = null,
bool RequireGoodQuality = false);
/// <summary>
/// Response from a remote attribute wait. <see cref="Success"/>/<see cref="ErrorMessage"/>
@@ -62,3 +62,26 @@ public record DeleteInstanceNativeAlarmSourceOverrideCommand(
string SourceCanonicalName);
public record ListInstanceNativeAlarmSourceOverridesCommand(int InstanceId);
/// <summary>
/// One entry in a bulk native-alarm-source-override apply: the source binding's
/// canonical name plus the three optional retarget fields (null keeps the inherited
/// value). Mirrors <see cref="SetInstanceNativeAlarmSourceOverrideCommand"/>'s fields
/// for a single source.
/// </summary>
public record NativeAlarmSourceOverrideEntry(
string SourceCanonicalName,
string? ConnectionNameOverride,
string? SourceReferenceOverride,
string? ConditionFilterOverride);
/// <summary>
/// Bulk, all-or-nothing apply of per-instance native-alarm-source overrides — the
/// native-source parity analogue of <see cref="SetInstanceOverridesCommand"/>. Backs
/// the CLI <c>instance native-alarm-source import --file</c> CSV path. Every entry's
/// source must resolve for the instance and be unlocked; if any entry is invalid the
/// whole batch is rejected before any write.
/// </summary>
public record SetInstanceNativeAlarmSourceOverridesCommand(
int InstanceId,
IReadOnlyList<NativeAlarmSourceOverrideEntry> Overrides);
@@ -0,0 +1,113 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Types;
/// <summary>
/// Shared, dependency-free RFC-4180-ish splitter for a single physical CSV line.
/// Extracted so the instance-override CSV parsers (<see cref="OverrideCsvParser"/>
/// and <see cref="NativeAlarmSourceOverrideCsvParser"/>) apply identical quoting
/// rules without duplicating the subtle field-state machine.
/// </summary>
/// <remarks>
/// Quoting rules:
/// <list type="bullet">
/// <item>A field is <i>quoted</i> only if its first non-whitespace char is a
/// <c>"</c> (leading whitespace before the opening quote is allowed and ignored).
/// Inside a quoted field, commas are literal and <c>""</c> is an escaped single
/// quote; the closing <c>"</c> must be the last non-whitespace char of the field
/// (trailing whitespace after the close is allowed and ignored).</item>
/// <item>A <c>"</c> appearing anywhere else in an unquoted field (i.e. after
/// non-whitespace content) is a <b>literal</b> character and is preserved.</item>
/// <item>Unquoted fields are whitespace-trimmed; quoted field values are kept
/// verbatim.</item>
/// </list>
/// </remarks>
public static class CsvLineSplitter
{
/// <summary>
/// Splits a single physical CSV line into its fields, applying the quoting rules
/// described on <see cref="CsvLineSplitter"/>. Returns <c>true</c> with the split
/// <paramref name="fields"/> on success; returns <c>false</c> when a quoted field
/// is opened but never closed before end-of-line (the caller emits a per-line
/// "unterminated" error).
/// </summary>
/// <param name="line">The physical line to split (no trailing newline).</param>
/// <param name="fields">The split fields on success; an empty list on failure.</param>
/// <returns><c>true</c> when the line split cleanly; <c>false</c> on an unterminated quoted field.</returns>
public static bool TrySplit(string line, out List<string> fields)
{
fields = new List<string>();
var field = new System.Text.StringBuilder();
var inQuotes = false; // currently between an opening and closing quote
var quoted = false; // this field opened with a quote → keep value verbatim
var sawContent = false; // any non-whitespace char seen in the current field yet
for (var i = 0; i < line.Length; i++)
{
var c = line[i];
if (inQuotes)
{
if (c == '"')
{
// Doubled quote inside a quoted field → a single literal quote.
if (i + 1 < line.Length && line[i + 1] == '"')
{
field.Append('"');
i++;
}
else
{
inQuotes = false; // closing quote; only trailing whitespace may follow
}
}
else
{
field.Append(c);
}
continue;
}
switch (c)
{
case ',':
fields.Add(Finalize(field, quoted));
field.Clear();
inQuotes = false;
quoted = false;
sawContent = false;
break;
case '"' when !sawContent:
// Opening quote: first non-whitespace char of the field. Any
// leading whitespace seen so far is part of the (ignored) prefix.
field.Clear();
inQuotes = true;
quoted = true;
sawContent = true;
break;
default:
// After a quoted field has closed, only whitespace may appear
// before the next delimiter — it is ignored, not appended.
if (quoted)
break;
// A '"' here (sawContent already true) falls through as a literal.
if (!char.IsWhiteSpace(c))
sawContent = true;
field.Append(c);
break;
}
}
if (inQuotes)
return false; // opened a quoted field that was never closed
fields.Add(Finalize(field, quoted));
return true;
}
private static string Finalize(System.Text.StringBuilder field, bool quoted)
{
var text = field.ToString();
return quoted ? text : text.Trim(); // only unquoted whitespace is trimmed
}
}
@@ -0,0 +1,125 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Types;
/// <summary>
/// One parsed per-instance native-alarm-source-override CSV row: the source
/// binding's canonical name plus the three optional retarget fields. A blank
/// (null) <see cref="Connection"/>/<see cref="SourceReference"/>/<see cref="Filter"/>
/// means "keep the inherited value" — the same blank-is-inherited semantics as the
/// CLI <c>instance native-alarm-source set</c> command. <see cref="LineNumber"/> is
/// the 1-based source line (the header is line 1) so downstream errors can point
/// back at the operator's file.
/// </summary>
public sealed record NativeAlarmSourceOverrideCsvRow(
string SourceName, string? Connection, string? SourceReference, string? Filter, int LineNumber);
/// <summary>
/// Outcome of parsing a native-alarm-source-override CSV: the successfully-parsed
/// <see cref="Rows"/> plus per-line <see cref="Errors"/>. Parsing never throws —
/// malformed rows are reported and excluded, valid rows still flow through.
/// Downstream callers validate source names against the flattened instance; this
/// parser is purely syntactic.
/// </summary>
public sealed record NativeAlarmSourceOverrideCsvParseResult(
IReadOnlyList<NativeAlarmSourceOverrideCsvRow> Rows, IReadOnlyList<string> Errors);
/// <summary>
/// Pure, dependency-free, quote-aware parser turning per-instance
/// native-alarm-source-override CSV text into structured rows plus per-line errors.
/// Callers supply the text (no file I/O). The header row is required and
/// case-insensitive (<c>SourceName,Connection,SourceReference,Filter</c>). Fields
/// follow the shared <see cref="CsvLineSplitter"/> RFC-4180 quoting rules — the same
/// splitter <see cref="OverrideCsvParser"/> uses. The parity analogue of
/// <see cref="OverrideCsvParser"/> for native alarm source retargets.
/// </summary>
public static class NativeAlarmSourceOverrideCsvParser
{
private const string HeaderError =
"Missing or invalid header row. Expected 'SourceName,Connection,SourceReference,Filter'.";
private const int ExpectedColumns = 4;
/// <summary>
/// Parses native-alarm-source-override CSV <paramref name="csvText"/>. Returns
/// parsed rows and any per-line errors; never throws. On a missing/unrecognized
/// header returns zero rows and a single header error.
/// </summary>
/// <param name="csvText">The raw CSV text to parse.</param>
/// <returns>The parsed rows and any per-line errors.</returns>
public static NativeAlarmSourceOverrideCsvParseResult Parse(string csvText)
{
var rows = new List<NativeAlarmSourceOverrideCsvRow>();
var errors = new List<string>();
// Split into physical lines; \r\n and \r are normalized to \n boundaries.
var lines = (csvText ?? string.Empty).Replace("\r\n", "\n").Replace('\r', '\n').Split('\n');
var headerSeen = false;
for (var i = 0; i < lines.Length; i++)
{
var lineNumber = i + 1;
var rawLine = lines[i];
// Skip fully-blank lines (whitespace-only included) without error.
if (string.IsNullOrWhiteSpace(rawLine))
continue;
if (!CsvLineSplitter.TrySplit(rawLine, out var fields))
{
errors.Add($"Line {lineNumber}: Unterminated quoted field.");
continue;
}
if (!headerSeen)
{
if (!TryMatchHeader(fields))
{
errors.Add(HeaderError);
return new NativeAlarmSourceOverrideCsvParseResult(rows, errors);
}
headerSeen = true;
continue;
}
if (fields.Count != ExpectedColumns)
{
errors.Add(
$"Line {lineNumber}: expected {ExpectedColumns} columns but found {fields.Count}.");
continue;
}
var sourceName = fields[0];
if (string.IsNullOrWhiteSpace(sourceName))
{
errors.Add($"Line {lineNumber}: SourceName must not be blank.");
continue;
}
rows.Add(new NativeAlarmSourceOverrideCsvRow(
sourceName,
NullIfEmpty(fields[1]),
NullIfEmpty(fields[2]),
NullIfEmpty(fields[3]),
lineNumber));
}
if (!headerSeen)
errors.Add(HeaderError);
return new NativeAlarmSourceOverrideCsvParseResult(rows, errors);
}
/// <summary>Matches the required 4-column header (case-insensitive).</summary>
private static bool TryMatchHeader(IReadOnlyList<string> fields) =>
fields.Count == ExpectedColumns &&
HeaderEquals(fields[0], "SourceName") &&
HeaderEquals(fields[1], "Connection") &&
HeaderEquals(fields[2], "SourceReference") &&
HeaderEquals(fields[3], "Filter");
private static bool HeaderEquals(string field, string expected) =>
string.Equals(field, expected, StringComparison.OrdinalIgnoreCase);
private static string? NullIfEmpty(string field) => field.Length == 0 ? null : field;
}
@@ -60,7 +60,7 @@ public static class OverrideCsvParser
if (string.IsNullOrWhiteSpace(rawLine))
continue;
if (!SplitFields(rawLine, out var fields))
if (!CsvLineSplitter.TrySplit(rawLine, out var fields))
{
errors.Add($"Line {lineNumber}: Unterminated quoted field.");
continue;
@@ -134,101 +134,4 @@ public static class OverrideCsvParser
string.Equals(field, expected, StringComparison.OrdinalIgnoreCase);
private static string? NullIfEmpty(string field) => field.Length == 0 ? null : field;
/// <summary>
/// RFC-4180-ish field splitter for a single physical line. Quoting rules:
/// <list type="bullet">
/// <item>A field is <i>quoted</i> only if its first non-whitespace char is a
/// <c>"</c> (leading whitespace before the opening quote is allowed and
/// ignored). Inside a quoted field, commas are literal and <c>""</c> is an
/// escaped single quote; the closing <c>"</c> must be the last non-whitespace
/// char of the field (trailing whitespace after the close is allowed and
/// ignored).</item>
/// <item>A <c>"</c> appearing anywhere else in an unquoted field (i.e. after
/// non-whitespace content) is a <b>literal</b> character and is preserved.</item>
/// <item>Unquoted fields are whitespace-trimmed; quoted field values are kept
/// verbatim.</item>
/// </list>
/// Returns <c>true</c> with the split <paramref name="fields"/> on success;
/// returns <c>false</c> when a quoted field is opened but never closed before
/// end-of-line (the caller emits a per-line "unterminated" error).
/// </summary>
private static bool SplitFields(string line, out List<string> fields)
{
fields = new List<string>();
var field = new System.Text.StringBuilder();
var inQuotes = false; // currently between an opening and closing quote
var quoted = false; // this field opened with a quote → keep value verbatim
var sawContent = false; // any non-whitespace char seen in the current field yet
for (var i = 0; i < line.Length; i++)
{
var c = line[i];
if (inQuotes)
{
if (c == '"')
{
// Doubled quote inside a quoted field → a single literal quote.
if (i + 1 < line.Length && line[i + 1] == '"')
{
field.Append('"');
i++;
}
else
{
inQuotes = false; // closing quote; only trailing whitespace may follow
}
}
else
{
field.Append(c);
}
continue;
}
switch (c)
{
case ',':
fields.Add(Finalize(field, quoted));
field.Clear();
inQuotes = false;
quoted = false;
sawContent = false;
break;
case '"' when !sawContent:
// Opening quote: first non-whitespace char of the field. Any
// leading whitespace seen so far is part of the (ignored) prefix.
field.Clear();
inQuotes = true;
quoted = true;
sawContent = true;
break;
default:
// After a quoted field has closed, only whitespace may appear
// before the next delimiter — it is ignored, not appended.
if (quoted)
break;
// A '"' here (sawContent already true) falls through as a literal.
if (!char.IsWhiteSpace(c))
sawContent = true;
field.Append(c);
break;
}
}
if (inQuotes)
return false; // opened a quoted field that was never closed
fields.Add(Finalize(field, quoted));
return true;
}
private static string Finalize(System.Text.StringBuilder field, bool quoted)
{
var text = field.ToString();
return quoted ? text : text.Trim(); // only unquoted whitespace is trimmed
}
}
@@ -270,6 +270,7 @@ public class ManagementActor : ReceiveActor
or SetConnectionBindingsCommand or SetInstanceOverridesCommand or SetInstanceAreaCommand
or SetInstanceAlarmOverrideCommand or DeleteInstanceAlarmOverrideCommand
or SetInstanceNativeAlarmSourceOverrideCommand or DeleteInstanceNativeAlarmSourceOverrideCommand
or SetInstanceNativeAlarmSourceOverridesCommand
or GetDeploymentDiffCommand
or MgmtDeployArtifactsCommand
or QueryDeploymentsCommand
@@ -347,6 +348,7 @@ public class ManagementActor : ReceiveActor
DeleteInstanceAlarmOverrideCommand cmd => await HandleDeleteInstanceAlarmOverride(sp, cmd, user),
ListInstanceAlarmOverridesCommand cmd => await HandleListInstanceAlarmOverrides(sp, cmd, user),
SetInstanceNativeAlarmSourceOverrideCommand cmd => await HandleSetInstanceNativeAlarmSourceOverride(sp, cmd, user),
SetInstanceNativeAlarmSourceOverridesCommand cmd => await HandleSetInstanceNativeAlarmSourceOverrides(sp, cmd, user),
DeleteInstanceNativeAlarmSourceOverrideCommand cmd => await HandleDeleteInstanceNativeAlarmSourceOverride(sp, cmd, user),
ListInstanceNativeAlarmSourceOverridesCommand cmd => await HandleListInstanceNativeAlarmSourceOverrides(sp, cmd, user),
@@ -998,6 +1000,78 @@ public class ManagementActor : ReceiveActor
return existing;
}
private static async Task<object?> HandleSetInstanceNativeAlarmSourceOverrides(
IServiceProvider sp, SetInstanceNativeAlarmSourceOverridesCommand cmd, AuthenticatedUser user)
{
await EnforceSiteScopeForInstance(sp, user, cmd.InstanceId);
var repo = sp.GetRequiredService<ITemplateEngineRepository>();
// All-or-nothing (parity with HandleSetInstanceOverrides). Flatten the
// instance ONCE (script compilation skipped — a lock/resolve check does not
// need it) and validate EVERY requested source up front: a source that does
// not resolve would create a dead override the flattener silently drops, and a
// template-locked source cannot be overridden. Only once the whole batch is
// known valid do we upsert — a mid-batch reject never leaves partial state.
var pipeline = sp.GetRequiredService<IFlatteningPipeline>();
var flattenResult = await pipeline.FlattenAndValidateAsync(
cmd.InstanceId, default, validateScripts: false);
if (flattenResult.IsFailure)
throw new ManagementCommandException(
$"Cannot set native alarm source overrides: the instance could not be flattened ({flattenResult.Error}).");
var resolvedByName = flattenResult.Value.Configuration.NativeAlarmSources
.ToDictionary(s => s.CanonicalName, StringComparer.Ordinal);
// Reject a batch that names the same source twice — the intended override
// would be ambiguous, and the last-writer-wins upsert would silently discard
// the earlier row.
var seen = new HashSet<string>(StringComparer.Ordinal);
foreach (var entry in cmd.Overrides)
{
if (!resolvedByName.TryGetValue(entry.SourceCanonicalName, out var resolvedSource))
throw new ManagementCommandException(
$"Native alarm source '{entry.SourceCanonicalName}' does not resolve for this instance " +
"and cannot be overridden. No overrides were applied.");
if (resolvedSource.IsLocked)
throw new ManagementCommandException(
$"Native alarm source '{entry.SourceCanonicalName}' is locked at the template level and " +
"cannot be overridden. No overrides were applied.");
if (!seen.Add(entry.SourceCanonicalName))
throw new ManagementCommandException(
$"Native alarm source '{entry.SourceCanonicalName}' appears more than once in the batch. " +
"No overrides were applied.");
}
var results = new List<InstanceNativeAlarmSourceOverride>();
foreach (var entry in cmd.Overrides)
{
var existing = await repo.GetNativeAlarmSourceOverrideAsync(cmd.InstanceId, entry.SourceCanonicalName);
if (existing == null)
{
var ovr = new InstanceNativeAlarmSourceOverride(entry.SourceCanonicalName)
{
InstanceId = cmd.InstanceId,
ConnectionNameOverride = entry.ConnectionNameOverride,
SourceReferenceOverride = entry.SourceReferenceOverride,
ConditionFilterOverride = entry.ConditionFilterOverride
};
await repo.AddInstanceNativeAlarmSourceOverrideAsync(ovr);
results.Add(ovr);
}
else
{
existing.ConnectionNameOverride = entry.ConnectionNameOverride;
existing.SourceReferenceOverride = entry.SourceReferenceOverride;
existing.ConditionFilterOverride = entry.ConditionFilterOverride;
await repo.UpdateInstanceNativeAlarmSourceOverrideAsync(existing);
results.Add(existing);
}
}
await repo.SaveChangesAsync();
return results;
}
private static async Task<object?> HandleDeleteInstanceNativeAlarmSourceOverride(
IServiceProvider sp, DeleteInstanceNativeAlarmSourceOverrideCommand cmd, AuthenticatedUser user)
{
@@ -1756,10 +1756,11 @@ public class DeploymentManagerActor : ReceiveActor, IWithTimers
/// Spec §6 (WD-2b): unpacks a routed <see cref="RouteToWaitForAttributeRequest"/>
/// (inbound-API <c>Route.To().WaitForAttribute()</c>) into the deployed
/// Instance Actor's site-local <see cref="WaitForAttributeRequest"/> and relays
/// the result back. Value-equality only across the wire — the predicate is null
/// and <c>RequireGoodQuality</c> is left at its default. The Ask is bounded by the
/// wait timeout plus slack (NOT a fixed 30s), since the wait legitimately blocks
/// for up to <see cref="RouteToWaitForAttributeRequest.Timeout"/>.
/// the result back. Value-equality across the wire — the predicate is null (a
/// cross-process lambda cannot be routed), but <c>RequireGoodQuality</c> is honored
/// from <see cref="RouteToWaitForAttributeRequest.RequireGoodQuality"/>. The Ask is
/// bounded by the wait timeout plus slack (NOT a fixed 30s), since the wait
/// legitimately blocks for up to <see cref="RouteToWaitForAttributeRequest.Timeout"/>.
/// </summary>
private void RouteInboundApiWaitForAttribute(RouteToWaitForAttributeRequest request)
{
@@ -1773,10 +1774,12 @@ public class DeploymentManagerActor : ReceiveActor, IWithTimers
}
var sender = Sender;
// Routed waits are value-equality only (predicate null); RequireGoodQuality left at default.
// Routed waits are value-equality (predicate null — a cross-process lambda
// cannot be routed); RequireGoodQuality is honored from the request.
var inner = new WaitForAttributeRequest(
request.CorrelationId, request.InstanceUniqueName, request.AttributeName,
request.TargetValueEncoded, null, request.Timeout, DateTimeOffset.UtcNow);
request.TargetValueEncoded, null, request.Timeout, DateTimeOffset.UtcNow,
request.RequireGoodQuality);
// Ask bounded by the WAIT timeout + slack — NOT a fixed 30s (the wait legitimately blocks up to request.Timeout).
instanceActor.Ask<WaitForAttributeResponse>(inner, request.Timeout + TimeSpan.FromSeconds(5))
@@ -403,7 +403,9 @@ public class ScriptRuntimeContext
/// <para>
/// <b>Quality-agnostic by default (spec §4.2):</b> a value arriving at Bad
/// quality still satisfies the wait — the match tests the value, not the quality.
/// A quality-gated ("Good"-only) mode is a planned enhancement, deferred per spec §4.2.
/// Opt into a quality-gated ("Good"-only) wait via the <c>requireGoodQuality</c>
/// argument (spec §4.2); the InstanceActor then holds the wait until the value
/// satisfies the test at Good quality (or times out).
/// </para>
///
/// <para>
@@ -0,0 +1,63 @@
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.AuditLog.Site;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
using ZB.MOM.WW.ScadaBridge.HealthMonitoring;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Site;
/// <summary>
/// Deferred-work #21: the backlog reporter's poll cadence is configurable via
/// <see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/> instead of the
/// old hard-coded 30 s constant.
/// </summary>
public class SiteAuditBacklogReporterCadenceTests
{
private static SiteAuditBacklogReporter Create(
IOptions<SqliteAuditWriterOptions>? options, TimeSpan? explicitInterval = null) =>
new(
Substitute.For<ISiteAuditQueue>(),
Substitute.For<ISiteHealthCollector>(),
NullLogger<SiteAuditBacklogReporter>.Instance,
explicitInterval,
options);
[Fact]
public void Cadence_ComesFromOptions_WhenConfigured()
{
var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 12 });
var reporter = Create(options);
Assert.Equal(TimeSpan.FromSeconds(12), reporter.RefreshInterval);
}
[Fact]
public void Cadence_FallsBackToDefault_WhenOptionsNonPositive()
{
var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 0 });
var reporter = Create(options);
Assert.Equal(SiteAuditBacklogReporter.DefaultRefreshInterval, reporter.RefreshInterval);
}
[Fact]
public void Cadence_FallsBackToDefault_WhenNoOptions()
{
var reporter = Create(options: null);
Assert.Equal(SiteAuditBacklogReporter.DefaultRefreshInterval, reporter.RefreshInterval);
}
[Fact]
public void ExplicitInterval_WinsOverOptions()
{
var options = Options.Create(new SqliteAuditWriterOptions { BacklogPollIntervalSeconds = 12 });
var reporter = Create(options, explicitInterval: TimeSpan.FromSeconds(3));
Assert.Equal(TimeSpan.FromSeconds(3), reporter.RefreshInterval);
}
}
@@ -0,0 +1,68 @@
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Types;
namespace ZB.MOM.WW.ScadaBridge.CLI.Tests;
/// <summary>
/// Verifies the CSV parsing + entry-mapping behaviour that backs
/// <c>instance native-alarm-source import</c>: parse errors block the apply step;
/// valid CSV produces the <see cref="NativeAlarmSourceOverrideEntry"/> list the
/// <see cref="SetInstanceNativeAlarmSourceOverridesCommand"/> consumes.
/// </summary>
public class ImportNativeAlarmSourceOverridesTests
{
// ── error path ───────────────────────────────────────────────────────────
[Fact]
public void CsvWithMissingHeader_ProducesErrors()
{
var result = NativeAlarmSourceOverrideCsvParser.Parse("Pressure,ConnA,ref,Active");
Assert.NotEmpty(result.Errors);
Assert.Empty(result.Rows);
}
[Fact]
public void CsvWithBlankSourceName_ProducesError()
{
const string csv = "SourceName,Connection,SourceReference,Filter\n,ConnA,ref,Active";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.NotEmpty(result.Errors);
Assert.Empty(result.Rows);
}
// ── happy path ───────────────────────────────────────────────────────────
[Fact]
public void ValidCsv_ProducesCorrectEntryList()
{
const string csv = """
SourceName,Connection,SourceReference,Filter
Pressure,ConnA,ns=2;s=Pump,Active
Temp,,,
""";
var parseResult = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(parseResult.Errors);
Assert.Equal(2, parseResult.Rows.Count);
// Build the same entry list that the CLI import action produces.
var entries = parseResult.Rows
.Select(r => new NativeAlarmSourceOverrideEntry(
r.SourceName, r.Connection, r.SourceReference, r.Filter))
.ToList();
Assert.Equal("Pressure", entries[0].SourceCanonicalName);
Assert.Equal("ConnA", entries[0].ConnectionNameOverride);
Assert.Equal("ns=2;s=Pump", entries[0].SourceReferenceOverride);
Assert.Equal("Active", entries[0].ConditionFilterOverride);
// All-blank override fields → inherited (null) on every field.
Assert.Equal("Temp", entries[1].SourceCanonicalName);
Assert.Null(entries[1].ConnectionNameOverride);
Assert.Null(entries[1].SourceReferenceOverride);
Assert.Null(entries[1].ConditionFilterOverride);
}
}
@@ -0,0 +1,80 @@
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.CentralUI.ScriptAnalysis;
using ZB.MOM.WW.ScadaBridge.Commons.Types;
namespace ZB.MOM.WW.ScadaBridge.CentralUI.Tests.ScriptAnalysis;
/// <summary>
/// Deferred-work #14 (full fidelity): the Test-Run sandbox routes value-equality
/// <c>WaitAsync</c>/<c>WaitForAsync</c> to the bound instance via
/// <see cref="ISandboxInstanceGateway"/>; predicate overloads and unbound runs still
/// throw a clearly-labelled <see cref="ScriptSandboxException"/>.
/// </summary>
public class SandboxWaitForAttributeTests
{
private static SandboxAttributeAccessor BoundAccessor(ISandboxInstanceGateway gateway) =>
new(new SandboxInstanceContext(gateway), prefix: string.Empty);
[Fact]
public async Task WaitAsync_ValueForm_RoutesThroughGateway_AndReturnsMatched()
{
var gateway = Substitute.For<ISandboxInstanceGateway>();
gateway.WaitForAttributeAsync("Flag", Arg.Any<string?>(), Arg.Any<TimeSpan>(), false, Arg.Any<CancellationToken>())
.Returns(new WaitResult(true, true, "Good", false));
var accessor = BoundAccessor(gateway);
var matched = await accessor.WaitAsync("Flag", true, TimeSpan.FromSeconds(5));
Assert.True(matched);
// The target is codec-encoded and the resolved (root-scope) name is passed through.
await gateway.Received(1).WaitForAttributeAsync(
"Flag", AttributeValueCodec.Encode(true), TimeSpan.FromSeconds(5), false, Arg.Any<CancellationToken>());
}
[Fact]
public async Task WaitForAsync_ValueForm_PassesRequireGoodQuality_AndReturnsFullResult()
{
var gateway = Substitute.For<ISandboxInstanceGateway>();
gateway.WaitForAttributeAsync("Done", Arg.Any<string?>(), Arg.Any<TimeSpan>(), true, Arg.Any<CancellationToken>())
.Returns(new WaitResult(true, 7, "Good", false));
var accessor = BoundAccessor(gateway);
var result = await accessor.WaitForAsync("Done", 7, TimeSpan.FromSeconds(3), requireGoodQuality: true);
Assert.True(result.Matched);
Assert.Equal(7, result.Value);
Assert.Equal("Good", result.Quality);
await gateway.Received(1).WaitForAttributeAsync(
"Done", AttributeValueCodec.Encode(7), TimeSpan.FromSeconds(3), true, Arg.Any<CancellationToken>());
}
[Fact]
public async Task WaitAsync_PredicateForm_Throws()
{
var accessor = BoundAccessor(Substitute.For<ISandboxInstanceGateway>());
var ex = await Assert.ThrowsAsync<ScriptSandboxException>(
() => accessor.WaitAsync("Done", v => v != null, TimeSpan.FromSeconds(1)));
Assert.Contains("predicate", ex.Message, StringComparison.OrdinalIgnoreCase);
}
[Fact]
public async Task WaitForAsync_PredicateForm_Throws()
{
var accessor = BoundAccessor(Substitute.For<ISandboxInstanceGateway>());
await Assert.ThrowsAsync<ScriptSandboxException>(
() => accessor.WaitForAsync("Done", v => v != null, TimeSpan.FromSeconds(1)));
}
[Fact]
public async Task WaitAsync_ValueForm_UnboundInstance_Throws()
{
// No gateway bound → the sandbox has no instance to route to.
var accessor = new SandboxAttributeAccessor(new SandboxInstanceContext(), prefix: string.Empty);
var ex = await Assert.ThrowsAsync<ScriptSandboxException>(
() => accessor.WaitAsync("Flag", true, TimeSpan.FromSeconds(1)));
Assert.Contains("deployed instance", ex.Message, StringComparison.OrdinalIgnoreCase);
}
}
@@ -0,0 +1,148 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types;
namespace ZB.MOM.WW.ScadaBridge.Commons.Tests;
public class NativeAlarmSourceOverrideCsvParserTests
{
[Fact]
public void Parse_SimpleFile_ReturnsRowsNoErrors()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"Pressure,ConnA,ns=2;s=Pump.Alarm,Active\n" +
"Module.Temp,ConnB,ns=2;s=Temp,\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Errors);
Assert.Equal(2, result.Rows.Count);
Assert.Equal("Pressure", result.Rows[0].SourceName);
Assert.Equal("ConnA", result.Rows[0].Connection);
Assert.Equal("ns=2;s=Pump.Alarm", result.Rows[0].SourceReference);
Assert.Equal("Active", result.Rows[0].Filter);
Assert.Equal(2, result.Rows[0].LineNumber);
Assert.Equal("Module.Temp", result.Rows[1].SourceName);
Assert.Equal("ConnB", result.Rows[1].Connection);
Assert.Equal("ns=2;s=Temp", result.Rows[1].SourceReference);
Assert.Null(result.Rows[1].Filter);
Assert.Equal(3, result.Rows[1].LineNumber);
}
[Fact]
public void Parse_BlankOverrideFields_BecomeNullInherited()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"Pressure,,,\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Errors);
var row = Assert.Single(result.Rows);
Assert.Equal("Pressure", row.SourceName);
Assert.Null(row.Connection);
Assert.Null(row.SourceReference);
Assert.Null(row.Filter);
}
[Fact]
public void Parse_HeaderCaseInsensitive_Accepted()
{
const string csv =
"sourcename,CONNECTION,SourceReference,filter\n" +
"Pressure,ConnA,ref,\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Errors);
Assert.Single(result.Rows);
}
[Fact]
public void Parse_QuotedFieldWithComma_PreservesEmbeddedComma()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"Pressure,ConnA,\"ns=2;s=a,b,c\",Active\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Errors);
var row = Assert.Single(result.Rows);
Assert.Equal("ns=2;s=a,b,c", row.SourceReference);
}
[Fact]
public void Parse_MissingHeader_ReturnsHeaderError()
{
const string csv = "Pressure,ConnA,ref,Active\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Rows);
var error = Assert.Single(result.Errors);
Assert.Contains("SourceName,Connection,SourceReference,Filter", error);
}
[Fact]
public void Parse_WrongColumnCount_ReportsPerLineErrorAndSkipsRow()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"Pressure,ConnA\n" +
"Temp,ConnB,ref,Active\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
var error = Assert.Single(result.Errors);
Assert.Contains("Line 2", error);
Assert.Contains("expected 4 columns", error);
// Valid rows still flow through.
var row = Assert.Single(result.Rows);
Assert.Equal("Temp", row.SourceName);
}
[Fact]
public void Parse_BlankSourceName_ReportsError()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
",ConnA,ref,Active\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Rows);
var error = Assert.Single(result.Errors);
Assert.Contains("SourceName must not be blank", error);
}
[Fact]
public void Parse_UnterminatedQuote_ReportsError()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"Pressure,ConnA,\"ns=2;s=open,Active\n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Rows);
Assert.Contains(result.Errors, e => e.Contains("Unterminated quoted field"));
}
[Fact]
public void Parse_BlankLinesSkippedWithoutError()
{
const string csv =
"SourceName,Connection,SourceReference,Filter\n" +
"\n" +
"Pressure,ConnA,ref,Active\n" +
" \n";
var result = NativeAlarmSourceOverrideCsvParser.Parse(csv);
Assert.Empty(result.Errors);
Assert.Single(result.Rows);
}
}
@@ -2874,6 +2874,112 @@ public class ManagementActorTests : TestKit, IDisposable
Assert.Contains("Deployer", response.Message);
}
[Fact]
public void SetInstanceNativeAlarmSourceOverrides_BulkHappyPath_AddsAllAndSavesOnce()
{
// #12: bulk CSV apply. Both sources resolve and are unlocked → each is added,
// and the whole batch commits with a SINGLE SaveChanges (all-or-nothing txn).
var pipeline = Substitute.For<IFlatteningPipeline>();
var flattened = new FlattenedConfiguration
{
NativeAlarmSources = new List<ResolvedNativeAlarmSource>
{
new() { CanonicalName = "Pressure", IsLocked = false, Source = "Template" },
new() { CanonicalName = "Temp", IsLocked = false, Source = "Template" }
}
};
pipeline.FlattenAndValidateAsync(1, Arg.Any<CancellationToken>(), Arg.Any<bool>())
.Returns(Result<FlatteningPipelineResult>.Success(
new FlatteningPipelineResult(flattened, "hash", ValidationResult.Success())));
_services.AddScoped(_ => pipeline);
var actor = CreateActor();
var envelope = Envelope(
new SetInstanceNativeAlarmSourceOverridesCommand(1, new List<NativeAlarmSourceOverrideEntry>
{
new("Pressure", "Opc2", "ns=2;s=P", null),
new("Temp", null, "ns=2;s=T", "Active")
}),
"Deployer");
actor.Tell(envelope);
ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
_templateRepo.ReceivedWithAnyArgs(2).AddInstanceNativeAlarmSourceOverrideAsync(default!, default);
// All-or-nothing: exactly one commit for the whole batch.
_templateRepo.ReceivedWithAnyArgs(1).SaveChangesAsync(default);
}
[Fact]
public void SetInstanceNativeAlarmSourceOverrides_OneLockedSource_RejectsWholeBatch()
{
// #12: all-or-nothing. If ANY entry targets a locked source, the whole batch
// is rejected before any write — no Add, no SaveChanges.
var pipeline = Substitute.For<IFlatteningPipeline>();
var flattened = new FlattenedConfiguration
{
NativeAlarmSources = new List<ResolvedNativeAlarmSource>
{
new() { CanonicalName = "Pressure", IsLocked = false, Source = "Template" },
new() { CanonicalName = "Locked", IsLocked = true, Source = "Template" }
}
};
pipeline.FlattenAndValidateAsync(1, Arg.Any<CancellationToken>(), Arg.Any<bool>())
.Returns(Result<FlatteningPipelineResult>.Success(
new FlatteningPipelineResult(flattened, "hash", ValidationResult.Success())));
_services.AddScoped(_ => pipeline);
var actor = CreateActor();
var envelope = Envelope(
new SetInstanceNativeAlarmSourceOverridesCommand(1, new List<NativeAlarmSourceOverrideEntry>
{
new("Pressure", "Opc2", null, null),
new("Locked", "Opc2", null, null)
}),
"Deployer");
actor.Tell(envelope);
var response = ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5));
Assert.Contains("locked", response.Error, StringComparison.OrdinalIgnoreCase);
_templateRepo.DidNotReceiveWithAnyArgs().AddInstanceNativeAlarmSourceOverrideAsync(default!, default);
_templateRepo.DidNotReceiveWithAnyArgs().SaveChangesAsync(default);
}
[Fact]
public void SetInstanceNativeAlarmSourceOverrides_UnresolvedSource_RejectsWholeBatch()
{
// #12: a source that does not resolve for the instance is rejected up front.
var pipeline = Substitute.For<IFlatteningPipeline>();
var flattened = new FlattenedConfiguration
{
NativeAlarmSources = new List<ResolvedNativeAlarmSource>
{
new() { CanonicalName = "Pressure", IsLocked = false, Source = "Template" }
}
};
pipeline.FlattenAndValidateAsync(1, Arg.Any<CancellationToken>(), Arg.Any<bool>())
.Returns(Result<FlatteningPipelineResult>.Success(
new FlatteningPipelineResult(flattened, "hash", ValidationResult.Success())));
_services.AddScoped(_ => pipeline);
var actor = CreateActor();
var envelope = Envelope(
new SetInstanceNativeAlarmSourceOverridesCommand(1, new List<NativeAlarmSourceOverrideEntry>
{
new("Pressure", "Opc2", null, null),
new("Ghost", "Opc2", null, null)
}),
"Deployer");
actor.Tell(envelope);
var response = ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5));
Assert.Contains("does not resolve", response.Error, StringComparison.OrdinalIgnoreCase);
_templateRepo.DidNotReceiveWithAnyArgs().AddInstanceNativeAlarmSourceOverrideAsync(default!, default);
_templateRepo.DidNotReceiveWithAnyArgs().SaveChangesAsync(default);
}
// ========================================================================
// MoveDataConnectionCommand (M9 / T24a) — guarded cross-site move
// ========================================================================
@@ -124,6 +124,7 @@ public class RequiredRoleMatrixTests
["SetInstanceAlarmOverride"] = [Roles.Deployer],
["DeleteInstanceAlarmOverride"] = [Roles.Deployer],
["SetInstanceNativeAlarmSourceOverride"] = [Roles.Deployer],
["SetInstanceNativeAlarmSourceOverrides"] = [Roles.Deployer],
["DeleteInstanceNativeAlarmSourceOverride"] = [Roles.Deployer],
["GetDeploymentDiff"] = [Roles.Deployer],
["MgmtDeployArtifacts"] = [Roles.Deployer],
@@ -551,6 +551,35 @@ public class DeploymentManagerActorTests : TestKit, IDisposable
Assert.Equal("Good", response.Quality);
}
[Fact]
public async Task RouteInboundApiWaitForAttribute_RequireGoodQuality_IsThreadedToInstanceActor()
{
// #14 (full fidelity): the additive RouteToWaitForAttributeRequest.RequireGoodQuality
// flag must reach the InstanceActor's wait. A static attribute is Good quality, so a
// quality-gated wait whose target equals the current value still matches — proving the
// flag threads through (and does not spuriously reject a Good value).
var actor = CreateDeploymentManager();
await Task.Delay(500);
actor.Tell(new DeployInstanceCommand(
"dep-wait-gq", "WaitPumpGq", "sha256:wait-gq",
MakeConfigJson("WaitPumpGq"), "admin", DateTimeOffset.UtcNow));
ExpectMsg<DeploymentStatusResponse>(TimeSpan.FromSeconds(5));
await Task.Delay(1000);
var encodedTarget = AttributeValueCodec.Encode("42");
actor.Tell(new RouteToWaitForAttributeRequest(
"wait-corr-gq", "WaitPumpGq", "TestAttr", encodedTarget,
TimeSpan.FromSeconds(5), DateTimeOffset.UtcNow,
ParentExecutionId: null, RequireGoodQuality: true));
var response = ExpectMsg<RouteToWaitForAttributeResponse>(TimeSpan.FromSeconds(10));
Assert.Equal("wait-corr-gq", response.CorrelationId);
Assert.True(response.Success, $"Routed quality-gated wait failed: {response.ErrorMessage}");
Assert.True(response.Matched, "A Good-quality attribute at target must satisfy a RequireGoodQuality wait.");
Assert.Equal("Good", response.Quality);
}
[Fact]
public async Task RouteInboundApiWaitForAttribute_UnknownInstance_RepliesNotFound()
{