scadalink-design/docs/plans/2026-05-12-opcua-config-model-design.md

# OPC UA Endpoint Config Model & Form Refactor — Design

**Date**: 2026-05-12
**Branch**: `feature/templates-folder-hierarchy` (and successors)
**Status**: Design approved, ready for implementation planning

## Problem

`DataConnection.PrimaryConfiguration` and `BackupConfiguration` are free-form JSON strings. Today:

- The site-side runtime (`OpcUaDataConnection.cs:44-90`) parses them as a flat `IDictionary<string,string>` and string-fishes ~12 keys (`endpoint` / `EndpointUrl`, `SessionTimeoutMs`, `SecurityMode`, `AutoAcceptUntrustedCerts`, etc.).
- The Central UI form (`DataConnectionForm.razor`) edits them as plain textareas. Its placeholder hints are inconsistent: `{"endpoint":"opc.tcp://..."}` for primary but `{"Host":"backup-host","Port":50101}` for backup — the latter is **not** actually parsed by the runtime.
- There is no schema, no validator, no documentation that's actually checked by code.
- The form's Protocol dropdown still offers "Custom" although no backend adapter exists — selecting it produces a deploy-time `"Unknown protocol type: Custom"` failure.

We want a strongly-typed model for OPC UA endpoint configuration, a validator that's the single source of truth for what's legal, and a form that renders typed controls per field instead of a JSON blob.

## Decision summary

| # | Decision | Choice |
|---|----------|--------|
| 1 | Scope of the model | **Single source of truth** — used by both UI and runtime. Drops the dictionary-key string-fishing in `OpcUaDataConnection.cs`. |
| 2 | Field coverage in the form | **All fields, grouped**: Connection / Timing / Subscription / Heartbeat. Sensible defaults pre-filled. |
| 3 | Custom protocol option | **Remove from dropdown**. OPC UA is the only supported protocol today. |
| 4 | Storage format | **Typed nested JSON** via System.Text.Json with camelCase + `JsonStringEnumConverter`. |
| 5 | Model location | **`ScadaLink.Commons/Types/DataConnections/`** plus a sibling Validators/Serialization namespace. |
| 6 | Validator return type | **`ValidationResult` + `ValidationEntry`** — matches `SemanticValidator` convention. |
| 7 | Form structure | **Shared `<OpcUaEndpointEditor>` Blazor component**, used twice (primary + backup). |
| 8 | Protocol field in UI | **Hidden**; entity field set to `"OpcUa"` implicitly on save. |
| 9 | Validation timing | **On Save click only**. No live per-field validation. |
| 10 | Legacy-row handling | **Best-effort parse + warning banner**. Save rewrites to the new shape. |

## Architecture

```
┌──────────────────────────────────────┐
│ ScadaLink.Commons                    │
│  Types/DataConnections/              │
│    OpcUaEndpointConfig.cs   (POCO)   │
│    OpcUaHeartbeatConfig.cs  (POCO)   │
│    OpcUaSecurityMode.cs     (enum)   │
│  Validators/                         │
│    OpcUaEndpointConfigValidator.cs   │
│  Serialization/                      │
│    OpcUaEndpointConfigSerializer.cs  │
└──────────────────────────────────────┘
                ▲
                │ (referenced by both)
        ┌───────┴────────────────────────┐
        ▼                                ▼
┌──────────────────────────┐   ┌────────────────────────────┐
│ ScadaLink.CentralUI      │   │ ScadaLink.SiteRuntime      │
│  Components/Forms/       │   │  Actors/                   │
│   OpcUaEndpointEditor    │   │   DeploymentManagerActor   │
│   .razor (shared)        │   │     (passes raw JSON to    │
│                          │   │      DataConnectionFactory)│
│  Pages/Admin/            │   │                            │
│   DataConnectionForm     │   │ DataConnections.OpcUa/     │
│   .razor                 │   │   OpcUaDataConnection.cs   │
└──────────────────────────┘   │     (consumes typed model) │
                               └────────────────────────────┘
```

Both sides deserialize from `DataConnection.PrimaryConfiguration` / `BackupConfiguration` strings into the same `OpcUaEndpointConfig` instance. The DB column type does not change.

## The model

```csharp
// ScadaLink.Commons/Types/DataConnections/OpcUaEndpointConfig.cs
namespace ScadaLink.Commons.Types.DataConnections;

public sealed class OpcUaEndpointConfig
{
    // Connection
    public string EndpointUrl { get; set; } = "";
    public OpcUaSecurityMode SecurityMode { get; set; } = OpcUaSecurityMode.None;
    public bool AutoAcceptUntrustedCerts { get; set; } = true;

    // Timing
    public int SessionTimeoutMs { get; set; } = 60000;
    public int OperationTimeoutMs { get; set; } = 15000;

    // Subscription
    public int PublishingIntervalMs { get; set; } = 1000;
    public int SamplingIntervalMs { get; set; } = 1000;
    public int QueueSize { get; set; } = 10;
    public int KeepAliveCount { get; set; } = 10;
    public int LifetimeCount { get; set; } = 30;
    public int MaxNotificationsPerPublish { get; set; } = 100;

    // Heartbeat (optional)
    public OpcUaHeartbeatConfig? Heartbeat { get; set; }
}

public sealed class OpcUaHeartbeatConfig
{
    public string TagPath { get; set; } = "";
    public int MaxSilenceSeconds { get; set; } = 30;
}

public enum OpcUaSecurityMode { None, Sign, SignAndEncrypt }
```

Defaults match the runtime's current fallbacks so a default-constructed config equals the empty/missing-JSON case. Settable properties (not `init`) so the form can `@bind` directly.

## The validator

```csharp
// ScadaLink.Commons/Validators/OpcUaEndpointConfigValidator.cs
public static class OpcUaEndpointConfigValidator
{
    public static ValidationResult Validate(OpcUaEndpointConfig config, string fieldPrefix = "")
    {
        var errors = new List<ValidationEntry>();

        if (string.IsNullOrWhiteSpace(config.EndpointUrl))
            errors.Add(Err("EndpointUrl", "Endpoint URL is required."));
        else if (!Uri.TryCreate(config.EndpointUrl, UriKind.Absolute, out var uri)
                 || uri.Scheme != "opc.tcp")
            errors.Add(Err("EndpointUrl",
                "Endpoint URL must be a valid opc.tcp:// URI."));

        if (config.SessionTimeoutMs <= 0)
            errors.Add(Err("SessionTimeoutMs", "Must be > 0."));
        if (config.OperationTimeoutMs <= 0)
            errors.Add(Err("OperationTimeoutMs", "Must be > 0."));
        if (config.PublishingIntervalMs <= 0)
            errors.Add(Err("PublishingIntervalMs", "Must be > 0."));
        if (config.SamplingIntervalMs <= 0)
            errors.Add(Err("SamplingIntervalMs", "Must be > 0."));
        if (config.QueueSize < 1)
            errors.Add(Err("QueueSize", "Must be ≥ 1."));
        if (config.KeepAliveCount < 1)
            errors.Add(Err("KeepAliveCount", "Must be ≥ 1."));
        if (config.LifetimeCount < config.KeepAliveCount * 3)
            errors.Add(Err("LifetimeCount",
                "Must be at least 3× KeepAliveCount per OPC UA spec."));
        if (config.MaxNotificationsPerPublish < 1)
            errors.Add(Err("MaxNotificationsPerPublish", "Must be ≥ 1."));

        if (config.Heartbeat is { } hb)
        {
            if (string.IsNullOrWhiteSpace(hb.TagPath))
                errors.Add(Err("Heartbeat.TagPath",
                    "Tag path is required when heartbeat is enabled."));
            if (hb.MaxSilenceSeconds <= 0)
                errors.Add(Err("Heartbeat.MaxSilenceSeconds", "Must be > 0."));
        }

        return errors.Count == 0
            ? ValidationResult.Success()
            : ValidationResult.FromErrors(errors);

        ValidationEntry Err(string field, string msg) =>
            new(Field: $"{fieldPrefix}{field}",
                Message: msg,
                Category: ValidationCategory.Schema);
    }
}
```

Key points:
- `fieldPrefix` parameter — form passes `"Primary."` / `"Backup."` so error messages disambiguate.
- `LifetimeCount ≥ 3 × KeepAliveCount` is an actual OPC UA spec constraint and exemplifies the "domain knowledge in the validator" win.
- Static, pure, no DI — trivial to unit-test.

## Serialization & legacy fallback

```csharp
// ScadaLink.Commons/Serialization/OpcUaEndpointConfigSerializer.cs
public static class OpcUaEndpointConfigSerializer
{
    private static readonly JsonSerializerOptions JsonOpts = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        WriteIndented = false,
        Converters = { new JsonStringEnumConverter(JsonNamingPolicy.CamelCase) }
    };

    public static string Serialize(OpcUaEndpointConfig config)
        => JsonSerializer.Serialize(config, JsonOpts);

    public static (OpcUaEndpointConfig Config, bool IsLegacy) Deserialize(string? json)
    {
        if (string.IsNullOrWhiteSpace(json))
            return (new OpcUaEndpointConfig(), false);

        try
        {
            using var doc = JsonDocument.Parse(json);
            if (doc.RootElement.TryGetProperty("endpointUrl", out _))
                return (JsonSerializer.Deserialize<OpcUaEndpointConfig>(json, JsonOpts)!, false);
        }
        catch (JsonException) { /* fall through */ }

        return (LoadLegacy(json), IsLegacy: true);
    }

    private static OpcUaEndpointConfig LoadLegacy(string json)
    {
        var dict = JsonSerializer.Deserialize<Dictionary<string, string>>(json)
                   ?? new();
        var c = new OpcUaEndpointConfig
        {
            EndpointUrl = dict.GetValueOrDefault("endpoint")
                       ?? dict.GetValueOrDefault("EndpointUrl") ?? "",
            SecurityMode = Enum.TryParse<OpcUaSecurityMode>(
                dict.GetValueOrDefault("SecurityMode"), out var sm) ? sm : OpcUaSecurityMode.None,
            AutoAcceptUntrustedCerts = ParseBool(dict, "AutoAcceptUntrustedCerts", true),
            SessionTimeoutMs = ParseInt(dict, "SessionTimeoutMs", 60000),
            OperationTimeoutMs = ParseInt(dict, "OperationTimeoutMs", 15000),
            PublishingIntervalMs = ParseInt(dict, "PublishingIntervalMs", 1000),
            SamplingIntervalMs = ParseInt(dict, "SamplingIntervalMs", 1000),
            QueueSize = ParseInt(dict, "QueueSize", 10),
            KeepAliveCount = ParseInt(dict, "KeepAliveCount", 10),
            LifetimeCount = ParseInt(dict, "LifetimeCount", 30),
            MaxNotificationsPerPublish = ParseInt(dict, "MaxNotificationsPerPublish", 100)
        };
        var hbPath = dict.GetValueOrDefault("HeartbeatTagPath");
        if (!string.IsNullOrWhiteSpace(hbPath))
            c.Heartbeat = new OpcUaHeartbeatConfig
            {
                TagPath = hbPath,
                MaxSilenceSeconds = ParseInt(dict, "HeartbeatMaxSilence", 30)
            };
        return c;
    }
}
```

`Deserialize` returns `(Config, IsLegacy)`. The form raises a Bootstrap warning banner when `IsLegacy=true`. On Save we always `Serialize` — the row gets rewritten to the new shape and the banner disappears on next edit.

## The shared Blazor component

`src/ScadaLink.CentralUI/Components/Forms/OpcUaEndpointEditor.razor`

Parameters:
- `Config` (`[EditorRequired]`) — bound by reference; parent owns the instance.
- `Title` — header text (e.g. "Primary Endpoint").
- `IdPrefix` — disambiguates `for=` attributes when the component appears twice.
- `IsLegacy` — toggles the warning banner.
- `Errors` (`ValidationResult?`) — drives per-field red text via `EndsWith("." + field)` match against `ValidationEntry.Field`.

Rendering: four section labels (Connection, Timing, Subscription, Heartbeat) with Bootstrap `row g-2` grids. Heartbeat starts collapsed behind an "Enable Heartbeat" button; once shown it has a "Remove Heartbeat" button. Per-field error text appears immediately below each control.

## DataConnectionForm changes

- **Removed**: Protocol `<select>`, the JSON `<textarea>` for primary, the JSON `<textarea>` for backup.
- **Added**: Two `<OpcUaEndpointEditor>` instances. The backup one is still gated behind "Add Backup Endpoint" / "Remove Backup" buttons, and `Failover Retry Count` stays in the backup subsection.
- **Code-behind**: `_primaryConfig` and `_backupConfig` (`OpcUaEndpointConfig` instances), `_primaryIsLegacy`/`_backupIsLegacy` flags, `_primaryErrors`/`_backupErrors` (`ValidationResult?`). Save runs the validator on both, bails out on failure, serializes via `OpcUaEndpointConfigSerializer.Serialize`.
- **Protocol on the entity** is set to the literal `"OpcUa"` on create. The column stays so the runtime's protocol-dispatch (`DataConnectionFactory`) is untouched.

## Runtime parser swap

`src/ScadaLink.SiteRuntime/Actors/DeploymentManagerActor.cs:426-456` — today this code parses both JSON strings into `Dictionary<string, string>` and hands the dict to `DataConnectionFactory`.

After the change:
- `DeploymentManagerActor` no longer parses JSON. It passes the raw `PrimaryConfiguration` / `BackupConfiguration` strings straight to the factory.
- `DataConnectionFactory.Create` (OPC UA branch) calls `OpcUaEndpointConfigSerializer.Deserialize(...)`, gets the typed model, and constructs `OpcUaDataConnection` with it.
- `OpcUaDataConnection.cs:44-90` is rewritten to take `OpcUaEndpointConfig` directly. The `connectionDetails.TryGetValue(...)` ladder and the `ParseInt` / `ParseBool` helpers go away. Heartbeat becomes `if (cfg.Heartbeat is { } hb) { ... }`.

Pre-refactor deployment artifacts still load: the serializer's legacy-dict fallback handles them. `IsLegacy` is discarded by the runtime (only the form cares).

## Tests

| Project | New / changed tests |
|---|---|
| `ScadaLink.Commons.Tests` | `OpcUaEndpointConfigSerializerTests`: typed-JSON roundtrip preserves all fields; legacy flat-dict deserializes correctly and sets `IsLegacy=true`; empty/null JSON returns defaults; unknown JSON shape falls back cleanly. |
| `ScadaLink.Commons.Tests` | `OpcUaEndpointConfigValidatorTests`: missing URL → error; bad scheme → error; `LifetimeCount < 3×KeepAliveCount` → error; heartbeat-enabled-but-no-tag-path → error; valid config → `IsValid=true`; `fieldPrefix` applied to every error's `Field`. |
| `ScadaLink.CentralUI.Tests` | `OpcUaEndpointEditorTests` (bUnit): renders all grouped sections; binding mutates the passed `Config`; Enable/Remove Heartbeat toggles the sub-object; passing `Errors` renders per-field red text; `IsLegacy=true` shows the warning banner. |
| `ScadaLink.CentralUI.Tests` | `DataConnectionsFormTests` (bUnit, add if missing): Save with invalid primary URL → no navigation, validator error shown; Save with valid config → repo `AddDataConnectionAsync` called with `Protocol="OpcUa"` and JSON containing `"endpointUrl"` in camelCase. |
| Site/DCL test project | Update existing tests to construct `OpcUaDataConnection` from `OpcUaEndpointConfig` instead of `IDictionary<string,string>`. |

## Out of scope

- No EF Core migration; the legacy-parse path handles pre-existing rows.
- No new protocols. Custom dropdown option is removed. If/when a second protocol lands, the form re-introduces a protocol dropdown and a `if (Protocol == "OpcUa")` branch around the editor component.
- No live (debounced) validation.
- No certificate management UI beyond `AutoAcceptUntrustedCerts`.
- No "Verify endpoint" button.
- No rewrite of `docs/requirements/Component-DataConnectionLayer.md` — a short note pointing at `OpcUaEndpointConfig` as the canonical schema is enough.

## Verification

1. `dotnet build` clean.
2. `dotnet test` for Commons + CentralUI + SiteRuntime/DCL — all green, including new tests.
3. `bash docker/deploy.sh` — rebuild cluster.
4. Browser smoke at `http://localhost:9000/admin/connections`:
   - New connection via site context menu → form shows the OPC UA endpoint editor; no Protocol dropdown.
   - Bad URL → Save → red error under Endpoint URL.
   - Valid config, toggle heartbeat, set timing knobs → Save → row created; reload → fields round-trip.
   - Edit a pre-refactor row → warning banner appears, fields populated from legacy dict; Save rewrites; second edit no banner.
   - Add backup endpoint, save, deploy a template that uses the connection → site logs show primary online and failover settings honored.