feat(scripting): out-of-process pre-emptible script runner behind Scripting:Runner (lmxopcua#780 P1)

Opt-in (Scripting:Runner=OutOfProcess; InProcess stays the default and its code path is unchanged). Implements the P1 slice of docs/plans/2026-11-09-out-of-process-script-runner-design.md with the owner's §14 decisions: - Options: Scripting:Runner (InProcess | Shadow | OutOfProcess), Scripting:Runner:Seams, Scripting:Worker:* (Shards 2, HardGrace max(1 s,T), HeapLimitBytes 512 MiB, QuarantineAfterKills 2, UnavailableGrace 5 s, IsolationProbationRuns 20, PeCacheDir validated absolute + outside the content root (fail closed), ExecutablePath). Shadow is not implemented yet: runs InProcess with a startup Warning. - Core.Scripting: IScriptRunner seam + InProcessScriptRunner (today's guard, the parity baseline). - Core.Scripting.Protocol: protobuf envelopes, 4-byte LE framing (zero/oversize/truncated/garbage refused), Variant carrying the exact CLR type; unsupported types are explicit failures. - ScriptWorker app: compiles in the worker, P-thread scheduler, host-driven soft cancel, fail-fast watchdog, heartbeats, ctx.Logger forwarding, exits on pipe EOF / parent gone, forbidden-assembly self-check; Akka and Grpc.Core.Api excluded from its folder. Shipped in script-worker/ (Build + Publish). - Core.Scripting.OutOfProcess: K shards + isolation worker, soft T / hard T+G kill, attribution (deadline kill = one key; crash = suspects -> isolation; isolation crash = strike), kill-strike quarantine, backoff 250 ms -> 30 s, fail closed, cleared allow-listed env, nonce + pid handshake on a current-user pipe, Windows Job Object. - VirtualTag + Calculation seams use the runner when selected; a runner-side failure (worker restarted / runner unavailable) publishes BadResourceUnavailable (0x80040000) — ScadaBridge#112. Script faults keep BadInternalError. The scripted-alarm seam stays in process (alarms last). Tests: new ZB.MOM.WW.OtOpcUa.ScriptWorker.Tests (Category=ScriptWorker, real processes; green on macOS and on windev/Windows), seam tests in Host/Runtime/Calculation suites; mutation-checked. Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 23:31:51 -05:00
parent f5c30ed0ef
commit 69a6e0b4c8
49 changed files with 5107 additions and 25 deletions
@@ -0,0 +1,141 @@
+using System.Collections.Concurrent;
+using Serilog;
+using Serilog.Core;
+using ZB.MOM.WW.OtOpcUa.Commons.Engines;
+using ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms;
+using ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+/// <summary>
+///     <see cref="IScriptRunner"/> over today's in-process machinery: a <see cref="CompiledScriptCache{TContext, TResult}"/>
+///     per context kind and one <see cref="ScriptRunGuard"/> (lmxopcua#780, design §11). It produces the outcomes and
+///     reason strings the seams' own in-process paths produce, which makes it the parity baseline the out-of-process
+///     runner is tested against, and the in-process half of the future shadow mode (P2).
+/// </summary>
+/// <remarks>
+///     The seams do not route their <see cref="ScriptRunnerMode.InProcess"/> path through this class: they keep their
+///     existing guard code, so the default mode is unchanged byte for byte. Unlike those paths, this runner remembers
+///     compile failures by source for every kind (Calculation already did, R07:P4).
+/// </remarks>
+public sealed class InProcessScriptRunner : IScriptRunner, IDisposable
+{
+    private readonly CompiledScriptCache<VirtualTagContext, object?> _valueCache = new();
+    private readonly CompiledScriptCache<AlarmPredicateContext, bool> _predicateCache = new();
+    private readonly ConcurrentDictionary<string, string> _compileFailures = new(StringComparer.Ordinal);
+    private readonly ScriptRunGuard _guard;
+
+    /// <summary>Initializes the runner.</summary>
+    /// <param name="scripting">Run-guard knobs; null ⇒ defaults.</param>
+    /// <param name="logger">Where quarantine lines go; null ⇒ Serilog's global logger.</param>
+    public InProcessScriptRunner(ScriptingOptions? scripting = null, ILogger? logger = null)
+    {
+        _guard = new ScriptRunGuard(scripting, logger);
+    }
+
+    /// <summary>The run guard (diagnostics / tests).</summary>
+    public ScriptRunGuard RunGuard => _guard;
+
+    /// <inheritdoc />
+    public async Task<ScriptRunOutcome> RunAsync(ScriptInvocation invocation, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(invocation);
+        var key = ScopedKey(invocation.Kind, invocation.Key);
+        var failureKey = ScopedKey(invocation.Kind, invocation.Source);
+        if (_compileFailures.TryGetValue(failureKey, out var known)) return ScriptRunOutcome.Failed(known);
+        var logger = invocation.ScriptLogger ?? Logger.None;
+
+        try
+        {
+            switch (invocation.Kind)
+            {
+                case ScriptContextKind.VirtualTag:
+                case ScriptContextKind.Calculation:
+                {
+                    var evaluator = await Task.Run(() => _valueCache.GetOrCompile(invocation.Source), ct).ConfigureAwait(false);
+                    var context = new VirtualTagContext(invocation.Inputs, static (_, _) => { }, logger);
+                    var value = await _guard.RunAsync(key, invocation.Source, evaluator, context, invocation.Timeout, ct)
+                        .ConfigureAwait(false);
+                    return ScriptRunOutcome.Ok(value);
+                }
+                case ScriptContextKind.AlarmPredicate:
+                {
+                    var evaluator = await Task.Run(() => _predicateCache.GetOrCompile(invocation.Source), ct).ConfigureAwait(false);
+                    var context = new AlarmPredicateContext(invocation.Inputs, logger);
+                    var value = await _guard.RunAsync(key, invocation.Source, evaluator, context, invocation.Timeout, ct)
+                        .ConfigureAwait(false);
+                    return ScriptRunOutcome.Ok(value);
+                }
+                default:
+                    return ScriptRunOutcome.Failed($"unsupported script kind {invocation.Kind}");
+            }
+        }
+        catch (CompilationErrorException ex)
+        {
+            return RememberCompileFailure(failureKey, $"compile error: {ex.Message}");
+        }
+        catch (ScriptSandboxViolationException ex)
+        {
+            return RememberCompileFailure(failureKey, $"sandbox violation: {ex.Message}");
+        }
+        catch (ScriptTimeoutException)
+        {
+            return ScriptRunOutcome.Failed($"{ScriptEvalFailureReasons.TimedOutPrefix}{invocation.Timeout.TotalSeconds:F1}s");
+        }
+        catch (ScriptRunRefusedException ex)
+        {
+            return ScriptRunOutcome.Failed(ex.Message);
+        }
+        catch (ScriptQuarantinedException ex)
+        {
+            return ScriptRunOutcome.Failed(ex.Message);
+        }
+        catch (OperationCanceledException) when (ct.IsCancellationRequested)
+        {
+            return ScriptRunOutcome.Failed("evaluation cancelled");
+        }
+        catch (Exception ex)
+        {
+            return ScriptRunOutcome.Failed($"script threw: {ex.Message}");
+        }
+    }
+
+    /// <inheritdoc />
+    public void Reset(ScriptContextKind kind)
+    {
+        var prefix = ScopedKey(kind, string.Empty);
+        foreach (var k in _compileFailures.Keys)
+            if (k.StartsWith(prefix, StringComparison.Ordinal)) _compileFailures.TryRemove(k, out _);
+        foreach (var k in _guard.QuarantinedKeys)
+            if (k.StartsWith(prefix, StringComparison.Ordinal)) _guard.Reset(k);
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyCollection<string> QuarantinedKeys(ScriptContextKind kind)
+    {
+        var prefix = ScopedKey(kind, string.Empty);
+        return _guard.QuarantinedKeys
+            .Where(k => k.StartsWith(prefix, StringComparison.Ordinal))
+            .Select(k => k[prefix.Length..])
+            .ToArray();
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        _valueCache.Dispose();
+        _predicateCache.Dispose();
+    }
+
+    /// <summary>The runner-internal key: <c>{kind}:{key}</c>.</summary>
+    /// <param name="kind">The context kind.</param>
+    /// <param name="key">The seam's key.</param>
+    /// <returns>The namespaced key.</returns>
+    public static string ScopedKey(ScriptContextKind kind, string key) => $"{(int)kind}:{key}";
+
+    private ScriptRunOutcome RememberCompileFailure(string failureKey, string reason)
+    {
+        _compileFailures.TryAdd(failureKey, reason);
+        return ScriptRunOutcome.Failed(reason);
+    }
+}