Joseph Doherty
133 lines
8.9 KiB
C#
133 lines
8.9 KiB
C#
using System.Text.Json;
|
|
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
|
|
using ZB.MOM.WW.ScadaBridge.Commons.Types.Debugging;
|
|
using ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;
|
|
using ZB.MOM.WW.ScadaBridge.ScriptAnalysis;
|
|
|
|
namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
|
|
|
|
/// <summary>
|
|
/// Outcome of a Flow Debugger run or replay as the page consumes it: the built
|
|
/// <see cref="FlowGraph"/> (null on failure), the raw server result (null when the command
|
|
/// itself was refused), and a classified error.
|
|
/// </summary>
|
|
/// <param name="Graph">The flow graph built from the returned audit events; null when the command failed outright.</param>
|
|
/// <param name="Raw">The server's <see cref="FlowDebugRunResult"/>; null when no result came back.</param>
|
|
/// <param name="Error">Human-readable failure, null on success.</param>
|
|
/// <param name="ErrorCode">Machine-readable failure code (<c>STANDBY_NODE</c>, <c>NO_TRIGGER_WITHIN_WINDOW</c>, <c>UNAUTHORIZED</c>, <c>SERVICE_UNAVAILABLE</c>, …), null on success.</param>
|
|
/// <param name="LogsTruncated">
|
|
/// Step logs (design 2026-09-09 D7): true when the inline trace collector dropped low-priority
|
|
/// <c>ScriptLog</c> rows to protect room for the step rows — the run's lines are incomplete inline,
|
|
/// while Replay (which reads the never-truncated audit store) is complete. Mirrors
|
|
/// <see cref="FlowDebugRunResult.LogsTruncated"/> so the page can note it without unwrapping the raw result.
|
|
/// </param>
|
|
public sealed record FlowDebugOutcome(
|
|
FlowGraph? Graph, FlowDebugRunResult? Raw, string? Error, string? ErrorCode, bool LogsTruncated = false)
|
|
{
|
|
/// <summary>True when a graph was built (the run may still have finished incomplete — see <see cref="Raw"/>).</summary>
|
|
public bool Success => Graph != null && Error == null;
|
|
|
|
/// <summary>Creates a failed outcome.</summary>
|
|
public static FlowDebugOutcome Fail(string error, string errorCode) => new(null, null, error, errorCode);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Outcome of a Retry / Discard relayed from a Flow Debugger node (follow-ups plan 2026-09-06 D4).
|
|
/// <see cref="Message"/> is operator-facing and uses the same wording as the Site Calls /
|
|
/// Notification report pages, whether the relay was refused before it left the page or the
|
|
/// owning site / outbox answered.
|
|
/// </summary>
|
|
/// <param name="Success">True when the relay was applied (site <c>Applied</c>, or outbox success).</param>
|
|
/// <param name="Message">What happened, in the report pages' words.</param>
|
|
public sealed record FlowOutboundActionResult(bool Success, string Message);
|
|
|
|
/// <summary>
|
|
/// One script of an instance as the Flow Debugger's script picker shows it (design 2026-09-08 §5):
|
|
/// canonical name, trigger kind, the trigger's attribute for write kinds, the effective parameter
|
|
/// definitions for call kinds, and the script's own execution timeout (client Ask sizing).
|
|
/// </summary>
|
|
/// <param name="CanonicalName">Path-qualified script name from the flattened configuration (<c>Module.Script</c> for a composed member).</param>
|
|
/// <param name="TriggerType">The effective trigger type, or null when the script has none.</param>
|
|
/// <param name="TriggerAttribute">The monitored attribute of a write-kind trigger; null for every other kind.</param>
|
|
/// <param name="ParameterDefinitions">JSON parameter definitions the Inputs card renders for a call kind; null = none.</param>
|
|
/// <param name="ExecutionTimeoutSeconds">The script's own execution timeout, or null to use the site default.</param>
|
|
public sealed record FlowScriptOption(
|
|
string CanonicalName, string? TriggerType, string? TriggerAttribute,
|
|
string? ParameterDefinitions, int? ExecutionTimeoutSeconds)
|
|
{
|
|
/// <summary>True when the debugger fires this script by writing <see cref="TriggerAttribute"/>.</summary>
|
|
public bool IsWriteKind => ScriptTriggerAttribute.IsWriteKind(TriggerType);
|
|
|
|
/// <summary>Picker label suffix: <c>ValueChange: Level</c>, <c>Call</c>, <c>no trigger</c>…</summary>
|
|
public string TriggerLabel => string.IsNullOrWhiteSpace(TriggerType) ? "no trigger"
|
|
: TriggerAttribute is { } a ? $"{TriggerType}: {a}" : TriggerType!;
|
|
}
|
|
|
|
/// <summary>
|
|
/// CentralUI facade over the Flow Debugger (design 2026-09-05 §5.5/§7.1, script entry
|
|
/// 2026-09-08 §5): the instance's script list read from its flattened configuration, static
|
|
/// shape prediction from script syntax, and the four management commands (Live run of a
|
|
/// method, of a script, of a value change; Replay) dispatched to the per-node <c>ManagementActor</c>
|
|
/// through the in-process <c>ManagementActorHolder</c> — the SAME Ask path the HTTP
|
|
/// <c>/management</c> endpoint uses, so the server stays the single enforcer of the Deployer
|
|
/// gate and the active-node refusal (<c>STANDBY_NODE</c>).
|
|
/// </summary>
|
|
public interface IFlowDebugService
|
|
{
|
|
/// <summary>Predicts the flow shape of an inbound API method from its script and the site scripts its constant routes resolve to.</summary>
|
|
/// <param name="apiMethodId">The method id.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The predicted flow; <see cref="PredictedFlow.Empty"/> when the method does not exist.</returns>
|
|
Task<PredictedFlow> PredictMethodAsync(int apiMethodId, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>The instance's scripts from its flattened configuration, ordered by canonical name; empty when the instance does not exist.</summary>
|
|
/// <param name="instanceId">The instance id.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<IReadOnlyList<FlowScriptOption>> GetInstanceScriptsAsync(int instanceId, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Predicts the flow of running <paramref name="scriptName"/>: the write + spawned script for a write kind, a RouteCall root + the script for a call kind.</summary>
|
|
/// <param name="instanceId">The instance id.</param>
|
|
/// <param name="scriptName">Canonical script name (case-insensitive).</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<PredictedFlow> PredictScriptAsync(int instanceId, string scriptName, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Runs an inbound API method with tracing on the active central node and returns the flow.</summary>
|
|
/// <param name="apiMethodId">The method id.</param>
|
|
/// <param name="parameters">Flat JSON object of parameters, or null.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<FlowDebugOutcome> RunMethodAsync(int apiMethodId, JsonElement? parameters, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Runs a script by name (write kinds take <paramref name="value"/>, call kinds <paramref name="parameters"/>) and returns the flow.</summary>
|
|
/// <param name="instanceId">The instance id.</param>
|
|
/// <param name="scriptName">Canonical script name (case-insensitive).</param>
|
|
/// <param name="parameters">Call kinds: flat JSON object of parameters, or null.</param>
|
|
/// <param name="value">Write kinds: the new value for the trigger's attribute, in canonical string form.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<FlowDebugOutcome> RunScriptAsync(int instanceId, string scriptName, JsonElement? parameters, string? value, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Rebuilds a past flow from the central audit store.</summary>
|
|
/// <param name="executionId">Any execution id in the chain.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<FlowDebugOutcome> ReplayAsync(Guid executionId, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Relays a Retry of a parked outbound node to its owner — the Site Call Audit relay for an
|
|
/// <see cref="FlowStepKind.ApiCall"/> / <see cref="FlowStepKind.DbCall"/> (keyed by the step's
|
|
/// <see cref="FlowStep.CorrelationId"/> = <c>TrackedOperationId</c> and <see cref="FlowStep.SiteId"/>),
|
|
/// the Notification Outbox for a <see cref="FlowStepKind.Notify"/> (<c>CorrelationId</c> =
|
|
/// <c>NotificationId</c>). A step that is not outbound, not <see cref="FlowStepOutcome.Parked"/>,
|
|
/// has no correlation id, or (site kinds) no site id is refused with a message and never relayed.
|
|
/// </summary>
|
|
/// <param name="step">The outbound step to retry.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<FlowOutboundActionResult> RetryOutboundAsync(FlowStep step, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Relays a Discard of a parked outbound node to its owner. Same routing and refusals as
|
|
/// <see cref="RetryOutboundAsync"/>.
|
|
/// </summary>
|
|
/// <param name="step">The outbound step to discard.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
Task<FlowOutboundActionResult> DiscardOutboundAsync(FlowStep step, CancellationToken cancellationToken = default);
|
|
}
|