feat(inbound-api): surface method compile errors to operators — api-method validate/recompile + compile state on get (ScadaBridge#75)

The data plane answers a broken inbound method with the generic "Script compilation failed for this method"; the Roslyn diagnostic reached only the central log, and the known-bad cache could not be observed or reset per method. - InboundScriptExecutor keeps the diagnostics with each known-bad record and exposes GetCompileState(name, currentScript): IsCompiled / IsKnownBad / LastCompileError, judged against the current script text (a record for older text is reported as not compiled yet). - Management: ValidateApiMethodCommand (compile the stored script, return ApiMethodCompileResult, register nothing, cache untouched) and RecompileApiMethodCommand (CompileAndRegister without re-sending the entity, drops the node's ApiMethodCache row, audited "Recompile"). Both Designer, like UpdateApiMethod; dispatched through the shared ApiMethodCompileOperations. GetApiMethod keeps the entity fields top-level and adds isCompiled, isKnownBad, lastCompileError and compileStateNode. Compile state is per central node and every result names the node. - CLI: api-method validate --id, api-method recompile --id. - Central UI: the API-method edit page shows the saved script's compile state and last error, with Validate and Recompile actions (same operations, same Designer gate, fresh DI scope). - RequiredRoleMatrixTests entries; ManagementSurfaceParityTests covers the new CLI leaves; ApiMethodCompileDiagnosticsTests + an executor CompileState test. - Docs: CLI README, Component-CLI/ManagementService/InboundAPI, components/*. Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:28:41 -05:00
parent 65ffa1dad4
commit 3dd492a77f
18 changed files with 542 additions and 15 deletions
@@ -712,6 +712,31 @@ public class InboundScriptExecutorTests
        Assert.True(_executor.CompileAndRegister(good));
    }

+    /// <summary>
+    /// ScadaBridge#75: a failure on the data-plane (lazy-compile) path is observable per method
+    /// with its real diagnostic while the caller only gets the generic message; the state is
+    /// judged against the current script text and clears on a successful compile.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Fact]
+    public async Task CompileState_ReportsTheLazyCompileFailureWithItsDiagnostic()
+    {
+        var method = new ApiMethod("diag", "return doesNotExist;") { Id = 1, TimeoutSeconds = 10 };
+        Assert.Equal(new ApiMethodCompileState(false, false, null), _executor.GetCompileState("diag", method.Script));
+
+        var result = await _executor.ExecuteAsync(method, new Dictionary<string, object?>(), _route, TimeSpan.FromSeconds(10));
+
+        Assert.Equal("Script compilation failed for this method", result.ErrorMessage);
+        var state = _executor.GetCompileState("diag", method.Script);
+        Assert.True(state.IsKnownBad);
+        Assert.Contains("doesNotExist", state.LastCompileError);
+        // A different script text is a different revision: the record no longer describes it.
+        Assert.False(_executor.GetCompileState("diag", "return 1;").IsKnownBad);
+
+        Assert.True(_executor.CompileAndRegister(new ApiMethod("diag", "return 1;") { Id = 1, TimeoutSeconds = 10 }));
+        Assert.Equal(new ApiMethodCompileState(true, false, null), _executor.GetCompileState("diag", "return 1;"));
+    }
+
    // --- _knownBadMethods must be bounded so a spam attack of
    //     unique method names cannot grow the cache without bound. ---

@@ -0,0 +1,135 @@
+using System.Text.Json;
+using Akka.Actor;
+using Akka.TestKit.Xunit2;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using NSubstitute;
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi;
+using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
+using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
+using ZB.MOM.WW.ScadaBridge.InboundAPI;
+
+namespace ZB.MOM.WW.ScadaBridge.ManagementService.Tests;
+
+/// <summary>
+/// ScadaBridge#75: an inbound method whose script fails to compile answers callers with a
+/// generic message and its real diagnostic used to reach only the central log. The
+/// management surface now returns the diagnostics (<c>ValidateApiMethod</c>), shows the
+/// node's compile state on <c>GetApiMethod</c>, and can clear a stale failure without a
+/// full-replace update (<c>RecompileApiMethod</c>).
+/// </summary>
+public class ApiMethodCompileDiagnosticsTests : TestKit
+{
+    private const string BrokenScript = "return doesNotExist;";
+    private readonly ServiceCollection _services = new ServiceCollection().AddTestConfigurationTransaction();
+    private readonly IInboundApiRepository _apiRepo = Substitute.For<IInboundApiRepository>();
+    private readonly IAuditService _audit = Substitute.For<IAuditService>();
+    private readonly InboundScriptExecutor _executor =
+        new(NullLogger<InboundScriptExecutor>.Instance, Substitute.For<IServiceProvider>());
+    private readonly ApiMethod _method = new("Broken", BrokenScript) { Id = 5, TimeoutSeconds = 10 };
+
+    /// <summary>Initializes the harness with a real executor and a stubbed repository.</summary>
+    public ApiMethodCompileDiagnosticsTests()
+    {
+        _services.AddScoped(_ => _apiRepo);
+        _services.AddScoped(_ => _audit);
+        _services.AddSingleton(_executor);
+        _apiRepo.GetApiMethodByIdAsync(5, Arg.Any<CancellationToken>()).Returns(_method);
+        _apiRepo.SaveChangesAsync(Arg.Any<CancellationToken>()).Returns(1);
+    }
+
+    private JsonElement Send(object command, string role = "Designer")
+    {
+        var actor = Sys.ActorOf(Props.Create(() => new ManagementActor(
+            _services.BuildServiceProvider(), NullLogger<ManagementActor>.Instance)));
+        actor.Tell(new ManagementEnvelope(
+            new AuthenticatedUser("designer", "Designer", new[] { role }, Array.Empty<string>()),
+            command, Guid.NewGuid().ToString("N")));
+        var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(30));
+        return JsonDocument.Parse(response.JsonData).RootElement.Clone();
+    }
+
+    /// <summary>
+    /// After the data plane recorded a compile failure, GetApiMethod reports it with the real
+    /// compiler diagnostic, alongside the unchanged entity fields.
+    /// </summary>
+    [Fact]
+    public void Get_AfterACompileFailure_ReportsKnownBadWithTheDiagnostic()
+    {
+        Assert.False(_executor.CompileAndRegister(_method));
+
+        var result = Send(new GetApiMethodCommand(5), role: "Viewer");
+
+        Assert.Equal("Broken", result.GetProperty("name").GetString());
+        Assert.Equal(BrokenScript, result.GetProperty("script").GetString());
+        Assert.True(result.GetProperty("isKnownBad").GetBoolean());
+        Assert.False(result.GetProperty("isCompiled").GetBoolean());
+        Assert.Contains("doesNotExist", result.GetProperty("lastCompileError").GetString());
+    }
+
+    /// <summary>Validate returns the diagnostics and leaves the handler cache untouched.</summary>
+    [Fact]
+    public void Validate_ReturnsDiagnostics_WithoutRecordingAFailure()
+    {
+        var result = Send(new ValidateApiMethodCommand(5));
+
+        Assert.False(result.GetProperty("success").GetBoolean());
+        Assert.Contains(result.GetProperty("errors").EnumerateArray(),
+            e => e.GetString()!.Contains("doesNotExist", StringComparison.Ordinal));
+        var state = _executor.GetCompileState("Broken", BrokenScript);
+        Assert.False(state.IsKnownBad);
+        Assert.False(state.IsCompiled);
+    }
+
+    /// <summary>
+    /// A failure recorded for unchanged script text is cleared by a recompile once the cause
+    /// outside the script is gone — here modelled by the stored row now compiling — without
+    /// re-sending the entity. The recompile is audited.
+    /// </summary>
+    [Fact]
+    public void Recompile_ClearsAStaleFailure_AndIsAudited()
+    {
+        Assert.False(_executor.CompileAndRegister(_method));
+        _method.Script = "return 1;";
+
+        var result = Send(new RecompileApiMethodCommand(5));
+
+        Assert.True(result.GetProperty("success").GetBoolean());
+        Assert.Empty(result.GetProperty("errors").EnumerateArray());
+        var state = _executor.GetCompileState("Broken", "return 1;");
+        Assert.True(state.IsCompiled);
+        Assert.False(state.IsKnownBad);
+        _audit.Received(1).LogAsync("designer", "Recompile", "ApiMethod", "5", "Broken",
+            Arg.Any<object?>(), Arg.Any<CancellationToken>());
+    }
+
+    /// <summary>A recompile of a still-broken script records the new diagnostics.</summary>
+    [Fact]
+    public void Recompile_StillBroken_RecordsTheDiagnostics()
+    {
+        var result = Send(new RecompileApiMethodCommand(5));
+
+        Assert.False(result.GetProperty("success").GetBoolean());
+        var state = _executor.GetCompileState("Broken", BrokenScript);
+        Assert.True(state.IsKnownBad);
+        Assert.Contains("doesNotExist", state.LastCompileError);
+    }
+
+    /// <summary>Validate and recompile are Designer operations, like UpdateApiMethod.</summary>
+    /// <param name="command">The command name to send.</param>
+    [Theory]
+    [InlineData("Validate")]
+    [InlineData("Recompile")]
+    public void ValidateAndRecompile_RequireDesigner(string command)
+    {
+        var actor = Sys.ActorOf(Props.Create(() => new ManagementActor(
+            _services.BuildServiceProvider(), NullLogger<ManagementActor>.Instance)));
+        object message = command == "Validate" ? new ValidateApiMethodCommand(5) : new RecompileApiMethodCommand(5);
+        actor.Tell(new ManagementEnvelope(
+            new AuthenticatedUser("viewer", "Viewer", new[] { "Viewer" }, Array.Empty<string>()),
+            message, Guid.NewGuid().ToString("N")));
+
+        ExpectMsg<ManagementUnauthorized>(TimeSpan.FromSeconds(10));
+    }
+}
@@ -116,6 +116,9 @@ public class RequiredRoleMatrixTests
        ["CreateApiMethod"] = [Roles.Designer],
        ["UpdateApiMethod"] = [Roles.Designer],
        ["DeleteApiMethod"] = [Roles.Designer],
+        // ScadaBridge#75: compile diagnostics + targeted recompile — UpdateApiMethod's authority.
+        ["ValidateApiMethod"] = [Roles.Designer],
+        ["RecompileApiMethod"] = [Roles.Designer],
        ["CreateTemplateFolder"] = [Roles.Designer],
        ["RenameTemplateFolder"] = [Roles.Designer],
        ["MoveTemplateFolder"] = [Roles.Designer],