docs+test(r2-02): bulkhead doc sweep + parsed-knob-must-be-wired guard (01/U-6, OVERALL theme 1)
This commit is contained in:
@@ -13,7 +13,7 @@
|
|||||||
{ "id": 9, "subject": "S-8 docs + form: fix WriteIdempotentAttribute's false 'reads via reflection' claim; note the non-idempotent production default; disable Write/Ack retry cells in the razor", "status": "completed", "blockedBy": [7, 5] },
|
{ "id": 9, "subject": "S-8 docs + form: fix WriteIdempotentAttribute's false 'reads via reflection' claim; note the non-idempotent production default; disable Write/Ack retry cells in the razor", "status": "completed", "blockedBy": [7, 5] },
|
||||||
{ "id": 10, "subject": "U-6 delete (Core): remove BulkheadMaxConcurrent/MaxQueue from DriverResilienceOptions + parser shape/merge/doc-example; add BulkheadKeys_InStoredJson_AreIgnored (migration-free contract)", "status": "completed", "blockedBy": [2, 6] },
|
{ "id": 10, "subject": "U-6 delete (Core): remove BulkheadMaxConcurrent/MaxQueue from DriverResilienceOptions + parser shape/merge/doc-example; add BulkheadKeys_InStoredJson_AreIgnored (migration-free contract)", "status": "completed", "blockedBy": [2, 6] },
|
||||||
{ "id": 11, "subject": "U-6 delete (AdminUI): strip bulkhead fields from ResilienceFormModel + the two razor inputs; update ResilienceFormModelTests", "status": "completed", "blockedBy": [5, 10] },
|
{ "id": 11, "subject": "U-6 delete (AdminUI): strip bulkhead fields from ResilienceFormModel + the two razor inputs; update ResilienceFormModelTests", "status": "completed", "blockedBy": [5, 10] },
|
||||||
{ "id": 12, "subject": "U-6 doc sweep (seam xmldocs, OTOPCUA0001 message + analyzer tests, operator docs; leave migrations/WedgeDetector/historical plans) + Options_properties_are_exactly_the_pipeline_wired_set knob-inertness guard", "status": "pending", "blockedBy": [10, 11] },
|
{ "id": 12, "subject": "U-6 doc sweep (seam xmldocs, OTOPCUA0001 message + analyzer tests, operator docs; leave migrations/WedgeDetector/historical plans) + Options_properties_are_exactly_the_pipeline_wired_set knob-inertness guard", "status": "completed", "blockedBy": [10, 11] },
|
||||||
{ "id": 13, "subject": "C-7 RED tests: unknown top-level key / unknown capability / unknown per-policy field survive round-trip; malformed JSON sets ParseFailed and ToJson returns the original text", "status": "pending", "blockedBy": [11] },
|
{ "id": 13, "subject": "C-7 RED tests: unknown top-level key / unknown capability / unknown per-policy field survive round-trip; malformed JSON sets ParseFailed and ToJson returns the original text", "status": "pending", "blockedBy": [11] },
|
||||||
{ "id": 14, "subject": "C-7 implement: JsonObject-bag FromJson/ToJson (TagConfigJson idiom), ParseFailed + RawStoredJson, blank->null contract preserved, parser-interop test green", "status": "pending", "blockedBy": [13] },
|
{ "id": 14, "subject": "C-7 implement: JsonObject-bag FromJson/ToJson (TagConfigJson idiom), ParseFailed + RawStoredJson, blank->null contract preserved, parser-interop test green", "status": "pending", "blockedBy": [13] },
|
||||||
{ "id": 15, "subject": "C-7 razor: ParseFailed warning banner + input lockout + explicit discard button; raw pane shows the stored ResilienceConfig; live-/run on docker-dev :9200 (rebuild BOTH centrals; SQL-mangle + unknown-key survival checks; also drive task 5 warnings and task 9 disabled cells)", "status": "pending", "blockedBy": [14] },
|
{ "id": 15, "subject": "C-7 razor: ParseFailed warning banner + input lockout + explicit discard button; raw pane shows the stored ResilienceConfig; live-/run on docker-dev :9200 (rebuild BOTH centrals; SQL-mangle + unknown-key survival checks; also drive task 5 warnings and task 9 disabled cells)", "status": "pending", "blockedBy": [14] },
|
||||||
|
|||||||
+1
-1
@@ -19,7 +19,7 @@ The lifecycle facade `OpcUaApplicationHost` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUa
|
|||||||
|
|
||||||
## Resilience and capability dispatch
|
## Resilience and capability dispatch
|
||||||
|
|
||||||
Driver-capability calls (`IReadable.ReadAsync`, `IWritable.WriteAsync`, `ITagDiscovery.DiscoverAsync`, `ISubscribable.SubscribeAsync/UnsubscribeAsync`, the `IHostConnectivityProbe` probe loop, `IAlarmSource` surfaces, and the four `IHistoryProvider` reads) are routed through a `CapabilityInvoker` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs`) so the Polly resilience pipeline (retry / timeout / breaker / bulkhead) applies. There is one invoker per `(DriverInstance, IDriver)` pair; all invokers share the process-singleton `DriverResiliencePipelineBuilder`, which keys pipelines on `(DriverInstanceId, hostName, DriverCapability)`. Per-instance resilience options come from `DriverTypeRegistry` (the driver's tier) plus per-instance JSON overrides parsed from `DriverInstance.ResilienceConfig` by `DriverResilienceOptionsParser`.
|
Driver-capability calls (`IReadable.ReadAsync`, `IWritable.WriteAsync`, `ITagDiscovery.DiscoverAsync`, `ISubscribable.SubscribeAsync/UnsubscribeAsync`, the `IHostConnectivityProbe` probe loop, `IAlarmSource` surfaces, and the four `IHistoryProvider` reads) are routed through a `CapabilityInvoker` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs`) so the Polly resilience pipeline (retry / timeout / breaker) applies. There is one invoker per `(DriverInstance, IDriver)` pair; all invokers share the process-singleton `DriverResiliencePipelineBuilder`, which keys pipelines on `(DriverInstanceId, hostName, DriverCapability)`. Per-instance resilience options come from `DriverTypeRegistry` (the driver's tier) plus per-instance JSON overrides parsed from `DriverInstance.ResilienceConfig` by `DriverResilienceOptionsParser`.
|
||||||
|
|
||||||
The `OTOPCUA0001` Roslyn analyzer (`src/Tooling/ZB.MOM.WW.OtOpcUa.Analyzers/UnwrappedCapabilityCallAnalyzer.cs`, category `OtOpcUa.Resilience`, severity Warning) flags direct driver-capability calls that bypass the invoker.
|
The `OTOPCUA0001` Roslyn analyzer (`src/Tooling/ZB.MOM.WW.OtOpcUa.Analyzers/UnwrappedCapabilityCallAnalyzer.cs`, category `OtOpcUa.Resilience`, severity Warning) flags direct driver-capability calls that bypass the invoker.
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Read/Write Operations
|
# Read/Write Operations
|
||||||
|
|
||||||
The v2 server routes OPC UA Read and Write operations to each driver's `IReadable` and `IWritable` capabilities through `CapabilityInvoker` so the Polly pipeline (retry / timeout / breaker / bulkhead) applies uniformly across Galaxy, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client drivers. The per-variable `OnReadValue` and `OnWriteValue` hooks described in the sections below live in `DriverNodeManager` (the planned ADR-002 Phase 7 Stream G successor to the v1 `DriverNodeManager`); `GenericDriverNodeManager` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`) handles address-space population and alarm routing during discovery. The current `OtOpcUaNodeManager` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs`) is a push-model `CustomNodeManager2` that receives values from the Akka actor layer via `WriteValue`; OPC UA client reads return the cached pushed value.
|
The v2 server routes OPC UA Read and Write operations to each driver's `IReadable` and `IWritable` capabilities through `CapabilityInvoker` so the Polly pipeline (retry / timeout / breaker) applies uniformly across Galaxy, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client drivers. The per-variable `OnReadValue` and `OnWriteValue` hooks described in the sections below live in `DriverNodeManager` (the planned ADR-002 Phase 7 Stream G successor to the v1 `DriverNodeManager`); `GenericDriverNodeManager` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`) handles address-space population and alarm routing during discovery. The current `OtOpcUaNodeManager` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs`) is a push-model `CustomNodeManager2` that receives values from the Akka actor layer via `WriteValue`; OPC UA client reads return the cached pushed value.
|
||||||
|
|
||||||
## Driver vs virtual dispatch
|
## Driver vs virtual dispatch
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -320,7 +320,7 @@ Responses: `202 Accepted` (`{ outcome, deploymentId, revisionHash }`) when a dep
|
|||||||
|
|
||||||
## OTOPCUA0001 Analyzer — Compile-Time Guard
|
## OTOPCUA0001 Analyzer — Compile-Time Guard
|
||||||
|
|
||||||
Per-capability resilience (retry, timeout, circuit-breaker, bulkhead) is applied by `CapabilityInvoker` in `src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/`. A driver-capability call made **outside** the invoker bypasses resilience entirely — which in production looks like inconsistent timeouts, un-wrapped retries, and unbounded blocking.
|
Per-capability resilience (retry, timeout, circuit-breaker) is applied by `CapabilityInvoker` in `src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/`. A driver-capability call made **outside** the invoker bypasses resilience entirely — which in production looks like inconsistent timeouts, un-wrapped retries, and unbounded blocking.
|
||||||
|
|
||||||
`OTOPCUA0001` (Roslyn analyzer at `src/Tooling/ZB.MOM.WW.OtOpcUa.Analyzers/UnwrappedCapabilityCallAnalyzer.cs`) fires with category `OtOpcUa.Resilience` and default severity **Warning** (per `AnalyzerReleases.Shipped.md`) when a method on one of the seven guarded capability interfaces (`IReadable`, `IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`, `IAlarmSource`, `IHistoryProvider` — all in `ZB.MOM.WW.OtOpcUa.Core.Abstractions`) is invoked **outside** a lambda passed to `CapabilityInvoker.ExecuteAsync` / `ExecuteWriteAsync`. `AlarmSurfaceInvoker` is **not** a wrapper home — its own implementation is covered transitively because it routes through the inner `CapabilityInvoker.ExecuteAsync`. The analyzer walks up the syntax tree from the call site, finds any enclosing invoker invocation, and verifies the call lives transitively inside that invocation's anonymous-function argument — a sibling pattern (do the call, then invoke `ExecuteAsync` on something unrelated nearby) does not satisfy the rule.
|
`OTOPCUA0001` (Roslyn analyzer at `src/Tooling/ZB.MOM.WW.OtOpcUa.Analyzers/UnwrappedCapabilityCallAnalyzer.cs`) fires with category `OtOpcUa.Resilience` and default severity **Warning** (per `AnalyzerReleases.Shipped.md`) when a method on one of the seven guarded capability interfaces (`IReadable`, `IWritable`, `ITagDiscovery`, `ISubscribable`, `IHostConnectivityProbe`, `IAlarmSource`, `IHistoryProvider` — all in `ZB.MOM.WW.OtOpcUa.Core.Abstractions`) is invoked **outside** a lambda passed to `CapabilityInvoker.ExecuteAsync` / `ExecuteWriteAsync`. `AlarmSurfaceInvoker` is **not** a wrapper home — its own implementation is covered transitively because it routes through the inner `CapabilityInvoker.ExecuteAsync`. The analyzer walks up the syntax tree from the call site, finds any enclosing invoker invocation, and verifies the call lives transitively inside that invocation's anonymous-function argument — a sibling pattern (do the call, then invoke `ExecuteAsync` on something unrelated nearby) does not satisfy the rule.
|
||||||
|
|
||||||
|
|||||||
@@ -30,7 +30,7 @@ There is also a separate **push** path for persisting alarm transitions from any
|
|||||||
|
|
||||||
## Dispatch through `CapabilityInvoker`
|
## Dispatch through `CapabilityInvoker`
|
||||||
|
|
||||||
All four HistoryRead surfaces are wrapped by `CapabilityInvoker` (`Core/Resilience/CapabilityInvoker.cs`) with `DriverCapability.HistoryRead`. The Polly pipeline keyed on `(DriverInstanceId, HostName, DriverCapability.HistoryRead)` provides timeout, circuit-breaker, and bulkhead defaults per the driver's stability tier (see [docs/v2/driver-stability.md](v2/driver-stability.md)).
|
All four HistoryRead surfaces are wrapped by `CapabilityInvoker` (`Core/Resilience/CapabilityInvoker.cs`) with `DriverCapability.HistoryRead`. The Polly pipeline keyed on `(DriverInstanceId, HostName, DriverCapability.HistoryRead)` provides timeout and circuit-breaker defaults per the driver's stability tier (see [docs/v2/driver-stability.md](v2/driver-stability.md)).
|
||||||
|
|
||||||
The dispatch point is `DriverNodeManager` in `ZB.MOM.WW.OtOpcUa.Server`. When the OPC UA stack calls `HistoryRead`, the node manager:
|
The dispatch point is `DriverNodeManager` in `ZB.MOM.WW.OtOpcUa.Server`. When the OPC UA stack calls `HistoryRead`, the node manager:
|
||||||
|
|
||||||
|
|||||||
@@ -35,8 +35,6 @@ public sealed class DriverInstance
|
|||||||
/// Null = use the driver's tier defaults. When populated, expected shape:
|
/// Null = use the driver's tier defaults. When populated, expected shape:
|
||||||
/// <code>
|
/// <code>
|
||||||
/// {
|
/// {
|
||||||
/// "bulkheadMaxConcurrent": 16,
|
|
||||||
/// "bulkheadMaxQueue": 64,
|
|
||||||
/// "capabilityPolicies": {
|
/// "capabilityPolicies": {
|
||||||
/// "Read": { "timeoutSeconds": 5, "retryCount": 5, "breakerFailureThreshold": 3 },
|
/// "Read": { "timeoutSeconds": 5, "retryCount": 5, "breakerFailureThreshold": 3 },
|
||||||
/// "Write": { "timeoutSeconds": 5, "retryCount": 0, "breakerFailureThreshold": 5 }
|
/// "Write": { "timeoutSeconds": 5, "retryCount": 0, "breakerFailureThreshold": 5 }
|
||||||
|
|||||||
@@ -26,7 +26,9 @@ public sealed class DriverInstanceResilienceStatus
|
|||||||
/// <summary>Rolling count of consecutive Polly pipeline failures for this (instance, host).</summary>
|
/// <summary>Rolling count of consecutive Polly pipeline failures for this (instance, host).</summary>
|
||||||
public int ConsecutiveFailures { get; set; }
|
public int ConsecutiveFailures { get; set; }
|
||||||
|
|
||||||
/// <summary>Current Polly bulkhead depth (in-flight calls) for this (instance, host).</summary>
|
/// <summary>In-flight capability-call depth for this (instance, host). Formerly fed a Polly
|
||||||
|
/// concurrency-limiter strategy that was removed (R2-02/01/U-6); the column name is retained to avoid a
|
||||||
|
/// migration on a reader-less entity — it now carries the tracker's in-flight-call count.</summary>
|
||||||
public int CurrentBulkheadDepth { get; set; }
|
public int CurrentBulkheadDepth { get; set; }
|
||||||
|
|
||||||
/// <summary>Most recent process recycle time (Tier C only; null for in-process tiers).</summary>
|
/// <summary>Most recent process recycle time (Tier C only; null for in-process tiers).</summary>
|
||||||
|
|||||||
@@ -2,7 +2,7 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
|||||||
|
|
||||||
/// <summary>
|
/// <summary>
|
||||||
/// Abstraction over the Phase 6.1 resilience pipeline that wraps a single driver instance's
|
/// Abstraction over the Phase 6.1 resilience pipeline that wraps a single driver instance's
|
||||||
/// capability calls (retry / circuit-breaker / bulkhead / tracker telemetry). The Runtime
|
/// capability calls (retry / circuit-breaker / in-flight accounting / tracker telemetry). The Runtime
|
||||||
/// dispatch layer (<c>DriverInstanceActor</c>) consumes this interface instead of the concrete
|
/// dispatch layer (<c>DriverInstanceActor</c>) consumes this interface instead of the concrete
|
||||||
/// <c>CapabilityInvoker</c> so the actor assembly does NOT pull in
|
/// <c>CapabilityInvoker</c> so the actor assembly does NOT pull in
|
||||||
/// <c>ZB.MOM.WW.OtOpcUa.Core</c> (which drags in Polly + driver hosting) — the same boundary
|
/// <c>ZB.MOM.WW.OtOpcUa.Core</c> (which drags in Polly + driver hosting) — the same boundary
|
||||||
@@ -15,7 +15,7 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
|||||||
/// this interface without adapters. Callers pass the resolved <c>hostName</c> per call (a
|
/// this interface without adapters. Callers pass the resolved <c>hostName</c> per call (a
|
||||||
/// multi-host driver resolves it from the tag reference via <see cref="IPerCallHostResolver"/>;
|
/// multi-host driver resolves it from the tag reference via <see cref="IPerCallHostResolver"/>;
|
||||||
/// a single-host driver passes its <see cref="IDriver.DriverInstanceId"/>) so per-host breaker
|
/// a single-host driver passes its <see cref="IDriver.DriverInstanceId"/>) so per-host breaker
|
||||||
/// isolation + bulkhead-depth accounting key on the right target.
|
/// isolation + in-flight-depth accounting key on the right target.
|
||||||
/// </remarks>
|
/// </remarks>
|
||||||
public interface IDriverCapabilityInvoker
|
public interface IDriverCapabilityInvoker
|
||||||
{
|
{
|
||||||
|
|||||||
@@ -28,7 +28,7 @@ public interface IPerCallHostResolver
|
|||||||
/// <summary>
|
/// <summary>
|
||||||
/// Resolve the host name for the given driver-side full reference. Returned value is
|
/// Resolve the host name for the given driver-side full reference. Returned value is
|
||||||
/// used as the <c>hostName</c> argument to the Phase 6.1 <c>CapabilityInvoker</c> so
|
/// used as the <c>hostName</c> argument to the Phase 6.1 <c>CapabilityInvoker</c> so
|
||||||
/// per-host breaker isolation + per-host bulkhead accounting both kick in.
|
/// per-host breaker isolation + per-host in-flight accounting both kick in.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
/// <param name="fullReference">The full reference of the tag or resource.</param>
|
/// <param name="fullReference">The full reference of the tag or resource.</param>
|
||||||
/// <returns>The host name responsible for serving the reference.</returns>
|
/// <returns>The host name responsible for serving the reference.</returns>
|
||||||
|
|||||||
@@ -52,7 +52,7 @@ public sealed class AlarmSurfaceInvoker
|
|||||||
|
|
||||||
/// <summary>
|
/// <summary>
|
||||||
/// Subscribe to alarm events for a set of source node ids, fanning out by resolved host
|
/// Subscribe to alarm events for a set of source node ids, fanning out by resolved host
|
||||||
/// so per-host breakers / bulkheads apply. Returns one handle per host — callers that
|
/// so per-host breakers apply. Returns one handle per host — callers that
|
||||||
/// don't care about per-host separation may concatenate them. Each returned handle wraps
|
/// don't care about per-host separation may concatenate them. Each returned handle wraps
|
||||||
/// the driver's opaque handle together with its resolved host so <see cref="UnsubscribeAsync"/>
|
/// the driver's opaque handle together with its resolved host so <see cref="UnsubscribeAsync"/>
|
||||||
/// routes through the same host's pipeline that the subscription was created on.
|
/// routes through the same host's pipeline that the subscription was created on.
|
||||||
|
|||||||
@@ -40,7 +40,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
|
|||||||
/// pipeline-invalidate can take effect without restarting the invoker.
|
/// pipeline-invalidate can take effect without restarting the invoker.
|
||||||
/// </param>
|
/// </param>
|
||||||
/// <param name="driverType">Driver type name for structured-log enrichment (e.g. <c>"Modbus"</c>).</param>
|
/// <param name="driverType">Driver type name for structured-log enrichment (e.g. <c>"Modbus"</c>).</param>
|
||||||
/// <param name="statusTracker">Optional resilience-status tracker. When wired, every capability call records start/complete so Admin <c>/hosts</c> can surface <see cref="ResilienceStatusSnapshot.CurrentInFlight"/> as the bulkhead-depth proxy.</param>
|
/// <param name="statusTracker">Optional resilience-status tracker. When wired, every capability call records start/complete so Admin <c>/hosts</c> can surface <see cref="ResilienceStatusSnapshot.CurrentInFlight"/> as the in-flight-call-depth proxy.</param>
|
||||||
public CapabilityInvoker(
|
public CapabilityInvoker(
|
||||||
DriverResiliencePipelineBuilder builder,
|
DriverResiliencePipelineBuilder builder,
|
||||||
string driverInstanceId,
|
string driverInstanceId,
|
||||||
|
|||||||
@@ -15,7 +15,7 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Resilience;
|
|||||||
/// </summary>
|
/// </summary>
|
||||||
/// <remarks>
|
/// <remarks>
|
||||||
/// Per-device isolation. Composition from outside-in:
|
/// Per-device isolation. Composition from outside-in:
|
||||||
/// <b>Timeout → Retry (when capability permits) → Circuit Breaker (when tier permits) → Bulkhead</b>.
|
/// <b>Timeout → Retry (when capability permits) → Circuit Breaker (when tier permits)</b>.
|
||||||
///
|
///
|
||||||
/// <para>Pipeline resolution is lock-free on the hot path: the inner
|
/// <para>Pipeline resolution is lock-free on the hot path: the inner
|
||||||
/// <see cref="ConcurrentDictionary{TKey,TValue}"/> caches a <see cref="ResiliencePipeline"/> per key;
|
/// <see cref="ConcurrentDictionary{TKey,TValue}"/> caches a <see cref="ResiliencePipeline"/> per key;
|
||||||
@@ -39,7 +39,7 @@ public sealed class DriverResiliencePipelineBuilder
|
|||||||
/// <param name="statusTracker">When non-null, every built pipeline wires Polly telemetry into
|
/// <param name="statusTracker">When non-null, every built pipeline wires Polly telemetry into
|
||||||
/// the tracker — retries increment <c>ConsecutiveFailures</c>, breaker-open stamps
|
/// the tracker — retries increment <c>ConsecutiveFailures</c>, breaker-open stamps
|
||||||
/// <c>LastBreakerOpenUtc</c>, breaker-close resets failures. Feeds Admin <c>/hosts</c> +
|
/// <c>LastBreakerOpenUtc</c>, breaker-close resets failures. Feeds Admin <c>/hosts</c> +
|
||||||
/// the Polly bulkhead-depth column. Absent tracker means no telemetry (unit tests +
|
/// the in-flight-call-depth column. Absent tracker means no telemetry (unit tests +
|
||||||
/// deployments that don't care about resilience observability).</param>
|
/// deployments that don't care about resilience observability).</param>
|
||||||
/// <param name="logger">When non-null, retry / circuit-breaker-open / breaker-close events are
|
/// <param name="logger">When non-null, retry / circuit-breaker-open / breaker-close events are
|
||||||
/// logged (instance + host + capability + attempt/exception). This is the operator-facing
|
/// logged (instance + host + capability + attempt/exception). This is the operator-facing
|
||||||
|
|||||||
@@ -101,7 +101,7 @@ public sealed class DriverResilienceStatusTracker
|
|||||||
/// <summary>
|
/// <summary>
|
||||||
/// Record the entry of a capability call for this (instance, host). Increments the
|
/// Record the entry of a capability call for this (instance, host). Increments the
|
||||||
/// in-flight counter used as the <see cref="ResilienceStatusSnapshot.CurrentInFlight"/>
|
/// in-flight counter used as the <see cref="ResilienceStatusSnapshot.CurrentInFlight"/>
|
||||||
/// surface (a cheap stand-in for Polly bulkhead depth). Paired with
|
/// surface (in-flight capability-call depth). Paired with
|
||||||
/// <see cref="RecordCallComplete"/>; callers use try/finally.
|
/// <see cref="RecordCallComplete"/>; callers use try/finally.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
/// <param name="driverInstanceId">The driver instance identifier.</param>
|
/// <param name="driverInstanceId">The driver instance identifier.</param>
|
||||||
@@ -159,7 +159,7 @@ public sealed record ResilienceStatusSnapshot
|
|||||||
/// <summary>
|
/// <summary>
|
||||||
/// In-flight capability calls against this (instance, host). Bumped on call entry +
|
/// In-flight capability calls against this (instance, host). Bumped on call entry +
|
||||||
/// decremented on completion. Feeds <c>DriverInstanceResilienceStatus.CurrentBulkheadDepth</c>
|
/// decremented on completion. Feeds <c>DriverInstanceResilienceStatus.CurrentBulkheadDepth</c>
|
||||||
/// for Admin <c>/hosts</c> — a cheap proxy for the Polly bulkhead depth until the full
|
/// for Admin <c>/hosts</c> — in-flight capability-call depth until the full
|
||||||
/// telemetry observer lands.
|
/// telemetry observer lands.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
public int CurrentInFlight { get; init; }
|
public int CurrentInFlight { get; init; }
|
||||||
|
|||||||
@@ -14,7 +14,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
|
|||||||
/// <para>Wire layer is libplctag 1.6.x. Per-device host addresses use
|
/// <para>Wire layer is libplctag 1.6.x. Per-device host addresses use
|
||||||
/// the <c>ab://gateway[:port]/cip-path</c> canonical form parsed via
|
/// the <c>ab://gateway[:port]/cip-path</c> canonical form parsed via
|
||||||
/// <see cref="AbCipHostAddress.TryParse"/>; those strings become the <c>hostName</c> key
|
/// <see cref="AbCipHostAddress.TryParse"/>; those strings become the <c>hostName</c> key
|
||||||
/// for Polly bulkhead + circuit-breaker isolation.</para>
|
/// for Polly per-host circuit-breaker isolation.</para>
|
||||||
///
|
///
|
||||||
/// <para>Tier A — in-process, shares server lifetime, no
|
/// <para>Tier A — in-process, shares server lifetime, no
|
||||||
/// sidecar. <see cref="ReinitializeAsync"/> is the Tier-B escape hatch for recovering
|
/// sidecar. <see cref="ReinitializeAsync"/> is the Tier-B escape hatch for recovering
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
|
|||||||
/// <summary>
|
/// <summary>
|
||||||
/// Parsed <c>ab://gateway[:port]/cip-path</c> host-address string used by the AbCip driver
|
/// Parsed <c>ab://gateway[:port]/cip-path</c> host-address string used by the AbCip driver
|
||||||
/// as the <c>hostName</c> key across <see cref="Core.Abstractions.IHostConnectivityProbe"/>,
|
/// as the <c>hostName</c> key across <see cref="Core.Abstractions.IHostConnectivityProbe"/>,
|
||||||
/// <see cref="Core.Abstractions.IPerCallHostResolver"/>, and the Polly bulkhead key
|
/// <see cref="Core.Abstractions.IPerCallHostResolver"/>, and the Polly per-host pipeline key
|
||||||
/// <c>(DriverInstanceId, hostName)</c>.
|
/// <c>(DriverInstanceId, hostName)</c>.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
/// <remarks>
|
/// <remarks>
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
|
|||||||
|
|
||||||
/// <summary>
|
/// <summary>
|
||||||
/// FOCAS driver configuration. One instance supports N CNC devices. Each device gets its own
|
/// FOCAS driver configuration. One instance supports N CNC devices. Each device gets its own
|
||||||
/// <c>(DriverInstanceId, HostAddress)</c> bulkhead key at the Phase 6.1 resilience layer.
|
/// <c>(DriverInstanceId, HostAddress)</c> per-host pipeline key at the Phase 6.1 resilience layer.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
public sealed class FocasDriverOptions
|
public sealed class FocasDriverOptions
|
||||||
{
|
{
|
||||||
|
|||||||
@@ -1627,7 +1627,7 @@ public sealed class DriverHostActor : ReceiveActor, IWithTimers
|
|||||||
else
|
else
|
||||||
{
|
{
|
||||||
// Attach the per-instance Phase 6.1 resilience invoker so this driver's capability calls
|
// Attach the per-instance Phase 6.1 resilience invoker so this driver's capability calls
|
||||||
// route through the retry/breaker/bulkhead/telemetry pipeline. The tier defaults are layered
|
// route through the retry/breaker/telemetry pipeline. The tier defaults are layered
|
||||||
// with the per-instance ResilienceConfig from the artifact; the pass-through factory yields a
|
// with the per-instance ResilienceConfig from the artifact; the pass-through factory yields a
|
||||||
// no-op invoker on nodes without the real resilience factory bound.
|
// no-op invoker on nodes without the real resilience factory bound.
|
||||||
var invoker = _invokerFactory.Create(spec.DriverInstanceId, spec.DriverType, spec.ResilienceConfig);
|
var invoker = _invokerFactory.Create(spec.DriverInstanceId, spec.DriverType, spec.ResilienceConfig);
|
||||||
|
|||||||
@@ -139,7 +139,7 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
|
|||||||
private readonly IDriver _driver;
|
private readonly IDriver _driver;
|
||||||
|
|
||||||
/// <summary>Phase 6.1 resilience seam: every guarded driver-capability call this actor makes is
|
/// <summary>Phase 6.1 resilience seam: every guarded driver-capability call this actor makes is
|
||||||
/// routed through this invoker (retry / breaker / bulkhead / tracker telemetry). Defaults to
|
/// routed through this invoker (retry / breaker / in-flight accounting / tracker telemetry). Defaults to
|
||||||
/// <see cref="NullDriverCapabilityInvoker"/> (a genuine pass-through) when none is supplied — so
|
/// <see cref="NullDriverCapabilityInvoker"/> (a genuine pass-through) when none is supplied — so
|
||||||
/// unit tests + the F7 skeleton path behave exactly as a raw driver call. The fused Host builds a
|
/// unit tests + the F7 skeleton path behave exactly as a raw driver call. The fused Host builds a
|
||||||
/// real per-instance invoker via <see cref="IDriverCapabilityInvokerFactory"/> and injects it at
|
/// real per-instance invoker via <see cref="IDriverCapabilityInvokerFactory"/> and injects it at
|
||||||
|
|||||||
@@ -12,7 +12,7 @@ namespace ZB.MOM.WW.OtOpcUa.Analyzers;
|
|||||||
/// Diagnostic analyzer that flags direct invocations of Phase 6.1-wrapped driver-capability
|
/// Diagnostic analyzer that flags direct invocations of Phase 6.1-wrapped driver-capability
|
||||||
/// methods when the call is NOT already running inside a <c>CapabilityInvoker.ExecuteAsync</c>
|
/// methods when the call is NOT already running inside a <c>CapabilityInvoker.ExecuteAsync</c>
|
||||||
/// or <c>CapabilityInvoker.ExecuteWriteAsync</c> lambda. The wrapping is what gives us
|
/// or <c>CapabilityInvoker.ExecuteWriteAsync</c> lambda. The wrapping is what gives us
|
||||||
/// per-host breaker isolation, retry semantics, bulkhead-depth accounting, and alarm-ack
|
/// per-host breaker isolation, retry semantics, in-flight-depth accounting, and alarm-ack
|
||||||
/// idempotence guards — raw calls bypass all of that.
|
/// idempotence guards — raw calls bypass all of that.
|
||||||
/// </summary>
|
/// </summary>
|
||||||
/// <remarks>
|
/// <remarks>
|
||||||
@@ -102,7 +102,7 @@ public sealed class UnwrappedCapabilityCallAnalyzer : DiagnosticAnalyzer
|
|||||||
private static readonly DiagnosticDescriptor Rule = new(
|
private static readonly DiagnosticDescriptor Rule = new(
|
||||||
id: DiagnosticId,
|
id: DiagnosticId,
|
||||||
title: "Driver capability call must be wrapped in CapabilityInvoker",
|
title: "Driver capability call must be wrapped in CapabilityInvoker",
|
||||||
messageFormat: "Call to '{0}' is not wrapped in CapabilityInvoker.ExecuteAsync / ExecuteWriteAsync. Without the wrapping, Phase 6.1 resilience (retry, breaker, bulkhead, tracker telemetry) is bypassed for this call.",
|
messageFormat: "Call to '{0}' is not wrapped in CapabilityInvoker.ExecuteAsync / ExecuteWriteAsync. Without the wrapping, Phase 6.1 resilience (retry, breaker, tracker telemetry) is bypassed for this call.",
|
||||||
category: "OtOpcUa.Resilience",
|
category: "OtOpcUa.Resilience",
|
||||||
defaultSeverity: DiagnosticSeverity.Warning,
|
defaultSeverity: DiagnosticSeverity.Warning,
|
||||||
isEnabledByDefault: true,
|
isEnabledByDefault: true,
|
||||||
|
|||||||
@@ -8,6 +8,34 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Tests.Resilience;
|
|||||||
[Trait("Category", "Unit")]
|
[Trait("Category", "Unit")]
|
||||||
public sealed class DriverResilienceOptionsTests
|
public sealed class DriverResilienceOptionsTests
|
||||||
{
|
{
|
||||||
|
/// <summary>
|
||||||
|
/// 01/U-6 knob-inertness guard (OVERALL theme #1): the public property set of
|
||||||
|
/// <see cref="DriverResilienceOptions"/> must be EXACTLY the pipeline-wired knobs. Every option a
|
||||||
|
/// parser can populate must map to a strategy the builder actually composes — a parsed-but-unapplied
|
||||||
|
/// knob (the bulkhead genre this pass deleted) is inertness the interface-forwarding and
|
||||||
|
/// unwrapped-dispatch guards can't catch. To add a knob: wire it in <c>DriverResiliencePipelineBuilder</c>,
|
||||||
|
/// add a behavior test that proves it engages, THEN add it to the expected set below.
|
||||||
|
/// (<c>RecycleIntervalSeconds</c> is itself Tier-C-dormant per 01/U-2 — a documented open question,
|
||||||
|
/// explicitly out of this pass's scope; it stays in the expected list as the recycle scheduler, not
|
||||||
|
/// the Polly pipeline, is its consumer.)
|
||||||
|
/// </summary>
|
||||||
|
[Fact]
|
||||||
|
public void Options_properties_are_exactly_the_pipeline_wired_set()
|
||||||
|
{
|
||||||
|
var expected = new[] { "Tier", "CapabilityPolicies", "RecycleIntervalSeconds" };
|
||||||
|
|
||||||
|
var actual = typeof(DriverResilienceOptions)
|
||||||
|
.GetProperties()
|
||||||
|
.Select(p => p.Name)
|
||||||
|
.OrderBy(n => n)
|
||||||
|
.ToArray();
|
||||||
|
|
||||||
|
actual.ShouldBe(expected.OrderBy(n => n).ToArray(),
|
||||||
|
"DriverResilienceOptions must expose only pipeline-wired knobs — a new option needs a builder " +
|
||||||
|
"strategy + a behavior test before it is added to the expected set (guards against the deleted " +
|
||||||
|
"bulkhead 'parsed-but-unapplied' genre; see 01/U-6).");
|
||||||
|
}
|
||||||
|
|
||||||
/// <summary>Verifies that tier defaults cover every capability.</summary>
|
/// <summary>Verifies that tier defaults cover every capability.</summary>
|
||||||
/// <param name="tier">The driver tier to test.</param>
|
/// <param name="tier">The driver tier to test.</param>
|
||||||
[Theory]
|
[Theory]
|
||||||
|
|||||||
Reference in New Issue
Block a user