fix(inbound-api): API-method recompile/invalidate reaches the peer central node; stale doc; locked-override name rule (ScadaBridge#103)

(a) Inbound API compile state (#75) is per central node: a recompile cleared the
known-bad record only on the node that answered, and the peer kept refusing the
unchanged script with SCRIPT_COMPILE_FAILED (the per-request revision check only
notices a changed script). Create / update / delete (ManagementActor post-commit),
RecompileApiMethod, and API methods written by a Transport bundle import now publish
InboundApiMethodInvalidated on the central cache-invalidation topic (#100 item 3).
The new InboundApiCacheInvalidationHandler drops that method's compiled handler,
known-bad record and cached ApiMethod row on the peer, which compiles the current
text on its next request.

(b) docs/components/InboundAPI.md no longer claims a direct DB edit stays stale
until restart: the per-request revision check picks it up once the node's cached
row expires (ApiMethodCacheTtl, 5 s). Component-InboundAPI, Component-Host and the
#85 cache audit describe the peer invalidation.

(c) Decision: the import's locked-override warnings keep EXACT (ordinal) name
matching, because FlatteningService matches override names ordinally. An override
differing from a locked member only by case never reaches that member's lock check
(the flattener drops it as unresolved), so a "targets a LOCKED member" warning for it
would be false. The comparer is now named (LockedOverrideNameComparer) and documented,
and pinned by tests on both sides (flattener + import).

Tests: the peer's known-bad record is cleared by a recompile (and validate leaves it
alone); create/update/delete and the import publish the invalidation; the handler
drops only the named method; composition root registers the handler; case-only
override gets no lock warning; the flattener matches override names exactly.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 16:04:07 -05:00
parent 153609ef8a
commit 0c2e852a62
16 changed files with 304 additions and 24 deletions
@@ -1399,6 +1399,12 @@ public sealed class BundleImporter : IBundleImporter
=> resolutionMap != null
&& ResolveOrDefault(resolutionMap, entityType, name).Action == ResolutionAction.Skip;
/// <summary>
/// How <see cref="CollectLockedOverrideWarnings"/> matches override names to template
/// members: ordinal, exactly as the flattener does (ScadaBridge#103).
/// </summary>
private static readonly StringComparer LockedOverrideNameComparer = StringComparer.Ordinal;
/// <summary>
/// Best-effort scan for instance overrides that target a LOCKED template member.
/// The flattener drops such overrides (an override on a locked attribute / alarm /
@@ -1416,6 +1422,16 @@ public sealed class BundleImporter : IBundleImporter
/// instance's template is resolved from the bundle DTO (the version about to be
/// written) first, else the pre-existing target template.
/// </para>
/// <para>
/// Member names match EXACTLY (<see cref="LockedOverrideNameComparer"/>, ordinal), as the
/// flattener does: <c>FlatteningService.ApplyInstanceOverrides</c> /
/// <c>ApplyInstanceAlarmOverrides</c> / <c>ApplyInstanceNativeAlarmSourceOverrides</c> look
/// the override name up in ordinal-keyed dictionaries (ScadaBridge#103 decision). An override
/// whose name differs from a locked member only by case therefore never reaches that member's
/// lock check — the flattener drops it as unresolved — so a "targets a LOCKED member" warning
/// for it would be false. The SQL indexes on member names being case-insensitive does not
/// change this: they stop two members differing only by case, not a case-mismatched override.
/// </para>
/// </summary>
private static IReadOnlyList<(string Instance, string Message)> CollectLockedOverrideWarnings(
BundleContentDto content,
@@ -1439,15 +1455,15 @@ public sealed class BundleImporter : IBundleImporter
HashSet<string> lockedSources;
if (bundleTemplates.TryGetValue(inst.TemplateName, out var dto))
{
lockedAttrs = new(dto.Attributes.Where(a => a.IsLocked).Select(a => a.Name), StringComparer.Ordinal);
lockedAlarms = new(dto.Alarms.Where(a => a.IsLocked).Select(a => a.Name), StringComparer.Ordinal);
lockedSources = new(dto.NativeAlarmSources.Where(s => s.IsLocked).Select(s => s.Name), StringComparer.Ordinal);
lockedAttrs = new(dto.Attributes.Where(a => a.IsLocked).Select(a => a.Name), LockedOverrideNameComparer);
lockedAlarms = new(dto.Alarms.Where(a => a.IsLocked).Select(a => a.Name), LockedOverrideNameComparer);
lockedSources = new(dto.NativeAlarmSources.Where(s => s.IsLocked).Select(s => s.Name), LockedOverrideNameComparer);
}
else if (targetByName.TryGetValue(inst.TemplateName, out var tgt))
{
lockedAttrs = new(tgt.Attributes.Where(a => a.IsLocked).Select(a => a.Name), StringComparer.Ordinal);
lockedAlarms = new(tgt.Alarms.Where(a => a.IsLocked).Select(a => a.Name), StringComparer.Ordinal);
lockedSources = new(tgt.NativeAlarmSources.Where(s => s.IsLocked).Select(s => s.Name), StringComparer.Ordinal);
lockedAttrs = new(tgt.Attributes.Where(a => a.IsLocked).Select(a => a.Name), LockedOverrideNameComparer);
lockedAlarms = new(tgt.Alarms.Where(a => a.IsLocked).Select(a => a.Name), LockedOverrideNameComparer);
lockedSources = new(tgt.NativeAlarmSources.Where(s => s.IsLocked).Select(s => s.Name), LockedOverrideNameComparer);
}
else
{
@@ -2528,7 +2544,7 @@ public sealed class BundleImporter : IBundleImporter
private void PublishScriptArtifactChanges(IReadOnlyList<ImportResolution> resolutions)
{
if (_scriptArtifactChangeBus is null)
if (_scriptArtifactChangeBus is null && _cacheInvalidationPublisher is null)
{
return;
}
@@ -2560,11 +2576,21 @@ public sealed class BundleImporter : IBundleImporter
return;
}
_scriptArtifactChangeBus!.Publish(new ScriptArtifactsChanged(
_scriptArtifactChangeBus?.Publish(new ScriptArtifactsChanged(
ArtifactKind: kind,
Names: names,
Source: "BundleImport",
OccurredAtUtc: _timeProvider.GetUtcNow()));
// ScadaBridge#103: the node-local bus above only reaches this node's executor; the
// peer central node is told per imported API method too.
if (kind == ScriptArtifactKinds.ApiMethod && _cacheInvalidationPublisher is not null)
{
foreach (var name in names)
{
_cacheInvalidationPublisher.Publish(new InboundApiMethodInvalidated(name));
}
}
}
}