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
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,85 @@
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
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.Types.InboundApi;
|
||||
using ZB.MOM.WW.ScadaBridge.InboundAPI;
|
||||
|
||||
namespace ZB.MOM.WW.ScadaBridge.ManagementService;
|
||||
|
||||
/// <summary>
|
||||
/// Operator access to inbound API method compilation (ScadaBridge#75): the real compile
|
||||
/// diagnostics, this node's compile state, and a recompile that does not need the entity
|
||||
/// re-sent. Shared by the <see cref="ManagementActor"/> handlers (CLI / Management API) and
|
||||
/// the Central UI, which call it under the same role gate, so every surface reports the same
|
||||
/// thing. Compile state is per central node — each node compiles and caches independently —
|
||||
/// so every result names the node it came from.
|
||||
/// </summary>
|
||||
public static class ApiMethodCompileOperations
|
||||
{
|
||||
/// <summary>
|
||||
/// Compiles the method's stored script and returns the diagnostics. Nothing is registered
|
||||
/// and the known-bad cache is untouched, so a validate never changes what requests see.
|
||||
/// </summary>
|
||||
/// <param name="sp">The scoped service provider.</param>
|
||||
/// <param name="apiMethodId">The API method id.</param>
|
||||
/// <returns>The compile outcome and its diagnostics.</returns>
|
||||
public static async Task<ApiMethodCompileResult> ValidateAsync(IServiceProvider sp, int apiMethodId)
|
||||
{
|
||||
var method = await LoadAsync(sp, apiMethodId);
|
||||
var valid = RequireExecutor(sp).ValidateCompilation(method, out var errors);
|
||||
return new ApiMethodCompileResult(method.Id, method.Name, valid, errors, NodeName(sp));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Re-runs <c>CompileAndRegister</c> on the method's stored script: a success replaces the
|
||||
/// cached handler and clears the known-bad record, a failure records the new diagnostics
|
||||
/// (a previously working handler is never replaced by a failed compile, but the stored row
|
||||
/// stays authoritative, see <see cref="InboundScriptExecutor.CompileAndRegister(ApiMethod, out IReadOnlyList{string})"/>).
|
||||
/// The node's cached row is dropped too, so the next request reads the stored row.
|
||||
/// Audited as <c>Recompile</c>.
|
||||
/// </summary>
|
||||
/// <param name="sp">The scoped service provider.</param>
|
||||
/// <param name="apiMethodId">The API method id.</param>
|
||||
/// <param name="user">The acting user, for the audit row.</param>
|
||||
/// <returns>The compile outcome and its diagnostics.</returns>
|
||||
public static async Task<ApiMethodCompileResult> RecompileAsync(IServiceProvider sp, int apiMethodId, string user)
|
||||
{
|
||||
var method = await LoadAsync(sp, apiMethodId);
|
||||
var compiled = RequireExecutor(sp).CompileAndRegister(method, out var errors);
|
||||
sp.GetService<ApiMethodCache>()?.Invalidate(method.Name);
|
||||
|
||||
var result = new ApiMethodCompileResult(method.Id, method.Name, compiled, errors, NodeName(sp));
|
||||
await sp.GetRequiredService<IAuditService>().LogAsync(
|
||||
user, "Recompile", "ApiMethod", method.Id.ToString(), method.Name,
|
||||
new { method.Id, method.Name, Compiled = compiled, ErrorCount = errors.Count, result.Node });
|
||||
await sp.GetRequiredService<IInboundApiRepository>().SaveChangesAsync();
|
||||
return result;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// This node's compile state for <paramref name="method"/>, or <c>null</c> on a host that
|
||||
/// runs no inbound API executor.
|
||||
/// </summary>
|
||||
/// <param name="sp">The service provider.</param>
|
||||
/// <param name="method">The API method, with its current stored script.</param>
|
||||
/// <returns>The compile state, or <c>null</c>.</returns>
|
||||
public static ApiMethodCompileStatus? GetStatus(IServiceProvider sp, ApiMethod method)
|
||||
{
|
||||
var executor = sp.GetService<InboundScriptExecutor>();
|
||||
if (executor is null)
|
||||
return null;
|
||||
var state = executor.GetCompileState(method.Name, method.Script);
|
||||
return new ApiMethodCompileStatus(state.IsCompiled, state.IsKnownBad, state.LastCompileError, NodeName(sp));
|
||||
}
|
||||
|
||||
private static async Task<ApiMethod> LoadAsync(IServiceProvider sp, int apiMethodId) =>
|
||||
await sp.GetRequiredService<IInboundApiRepository>().GetApiMethodByIdAsync(apiMethodId)
|
||||
?? throw new ManagementCommandException($"ApiMethod with ID {apiMethodId} not found.");
|
||||
|
||||
private static InboundScriptExecutor RequireExecutor(IServiceProvider sp) =>
|
||||
sp.GetService<InboundScriptExecutor>()
|
||||
?? throw new ManagementCommandException("The inbound API script executor is not available on this node.");
|
||||
|
||||
private static string? NodeName(IServiceProvider sp) => sp.GetService<INodeIdentityProvider>()?.NodeName;
|
||||
}
|
||||
@@ -328,6 +328,9 @@ public class ManagementActor : ReceiveActor
|
||||
or CreateSharedSchemaCommand or UpdateSharedSchemaCommand or DeleteSharedSchemaCommand
|
||||
or CreateDatabaseConnectionDefCommand or UpdateDatabaseConnectionDefCommand or DeleteDatabaseConnectionDefCommand
|
||||
or CreateApiMethodCommand or UpdateApiMethodCommand or DeleteApiMethodCommand
|
||||
// ScadaBridge#75: operator compile diagnostics + targeted recompile, the same
|
||||
// authority as UpdateApiMethod (which recompiles as a side effect).
|
||||
or ValidateApiMethodCommand or RecompileApiMethodCommand
|
||||
or CreateTemplateFolderCommand or RenameTemplateFolderCommand
|
||||
or MoveTemplateFolderCommand or ReorderTemplateFolderCommand or DeleteTemplateFolderCommand
|
||||
or MoveTemplateToFolderCommand
|
||||
@@ -526,6 +529,8 @@ public class ManagementActor : ReceiveActor
|
||||
CreateApiMethodCommand cmd => await HandleCreateApiMethod(sp, cmd, user.Username),
|
||||
UpdateApiMethodCommand cmd => await HandleUpdateApiMethod(sp, cmd, user.Username),
|
||||
DeleteApiMethodCommand cmd => await HandleDeleteApiMethod(sp, cmd, user.Username),
|
||||
ValidateApiMethodCommand cmd => await ApiMethodCompileOperations.ValidateAsync(sp, cmd.ApiMethodId),
|
||||
RecompileApiMethodCommand cmd => await ApiMethodCompileOperations.RecompileAsync(sp, cmd.ApiMethodId, user.Username),
|
||||
|
||||
// Security
|
||||
ListRoleMappingsCommand => await HandleListRoleMappings(sp),
|
||||
@@ -3802,7 +3807,26 @@ public class ManagementActor : ReceiveActor
|
||||
private static async Task<object?> HandleGetApiMethod(IServiceProvider sp, GetApiMethodCommand cmd)
|
||||
{
|
||||
var repo = sp.GetRequiredService<IInboundApiRepository>();
|
||||
return await repo.GetApiMethodByIdAsync(cmd.ApiMethodId);
|
||||
var method = await repo.GetApiMethodByIdAsync(cmd.ApiMethodId);
|
||||
if (method is null)
|
||||
return null;
|
||||
// ScadaBridge#75: the entity fields stay top-level (additive), plus this node's
|
||||
// compile state so an operator can see why a method fails without firing it.
|
||||
var status = ApiMethodCompileOperations.GetStatus(sp, method);
|
||||
return new
|
||||
{
|
||||
method.Id,
|
||||
method.Name,
|
||||
method.Script,
|
||||
method.ParameterDefinitions,
|
||||
method.ReturnDefinition,
|
||||
method.TimeoutSeconds,
|
||||
method.TraceAllCalls,
|
||||
status?.IsCompiled,
|
||||
status?.IsKnownBad,
|
||||
status?.LastCompileError,
|
||||
CompileStateNode = status?.Node,
|
||||
};
|
||||
}
|
||||
|
||||
private static async Task<object?> HandleCreateApiMethod(IServiceProvider sp, CreateApiMethodCommand cmd, string user)
|
||||
|
||||
Reference in New Issue
Block a user