API & Custom Plugin Guide

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <UseWPF>true</UseWPF>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <AssemblyName>Uniflow.Plugin.MyCustomPlugin</AssemblyName>
    <RootNamespace>Uniflow.Plugin.MyCustomPlugin</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- Core Uniflow Host Contracts -->
    <Reference Include="UniflowLibs">
      <HintPath>UniflowLibs.dll</HintPath>
      <Private>false</Private> <!-- Must be false to use host runtime assemblies -->
    </Reference>
  </ItemGroup>

  <ItemGroup>
    <!-- UI & MVVM Libraries -->
    <PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2" />
    <PackageReference Include="WPF-UI" Version="3.0.4" />
  </ItemGroup>

  <ItemGroup>
    <!-- Embed icon and manifest -->
    <Content Include="plugin.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
    <EmbeddedResource Include="icon.png" />
  </ItemGroup>

</Project>

{
  "Id": "uniflow.plugin.mycustomplugin",
  "Name": "My Custom Protocol",
  "Type": "Industrial Protocols",
  "Version": "1.0.0",
  "Author": "Acme Engineering Team",
  "Description": "Integrates proprietary field telemetry controllers over TCP/IP sockets.",
  "SourceType": "uniflow.plugin.mycustomplugin",
  "EntryAssembly": "Uniflow.Plugin.MyCustomPlugin.dll",
  "MinSystemVersion": "1.0.0",
  "LicensePlan": "Free",
  "Platform": "CrossPlatform",
  "DefaultContextAssemblies": [],
  "ReleaseNotes": [
    {
      "version": "1.0.0",
      "release_note": "Initial release of My Custom Protocol plugin."
    }
  ],
  "legal_info": [
    {
      "library_name": "NLog",
      "version": "5.2.0",
      "license_name": "BSD-3-Clause",
      "license_url": "https://licenses.nuget.org/BSD-3-Clause",
      "license_text": "Copyright (c) 2004-2023 Jaroslaw Kowalski <jaak@jkowalski.net>..."
    }
  ]
}

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using UniflowLibs.Contracts.Sources;
using UniflowLibs.Logging;
using UniflowService.Sources;
using UniflowService.Sources.Abstractions;

namespace Uniflow.Plugin.MyCustomPlugin;

/// <summary>
/// Custom protocol source adapter implementation executing inside UniflowService.
/// Manages device network connections, background telemetry polling, catalog publishing, and write operations.
/// </summary>
public class MyCustomSourceAdapter : SourceAdapterBase, IDisposable
{
    private readonly IUniflowLogger _log;
    private string _host = "127.0.0.1";
    private int _port = 5000;
    private int _pollingIntervalMs = 1000;
    private CancellationTokenSource? _cts;
    private PeriodicTimer? _timer;
    private Task? _pollTask;

    /// <summary>
    /// Initializes a new instance of the <see cref="MyCustomSourceAdapter"/> class.
    /// </summary>
    /// <param name="definition">Source DTO containing target address and settings.</param>
    /// <param name="capabilities">Capabilities flags supported by this adapter instance.</param>
    /// <param name="log">Logger instance for diagnostic logs.</param>
    public MyCustomSourceAdapter(SourceDto definition, SourceCapabilities capabilities, IUniflowLogger log) 
        : base(definition, capabilities)
    {
        _log = log?.ForRegion("MyCustomPlugin") ?? NullUniflowLogger.Instance;
        ParseSettings(definition);
    }

    /// <summary>
    /// Parses configuration settings from the source DTO dictionary.
    /// </summary>
    /// <param name="definition">Source DTO containing settings key-value pairs.</param>
    private void ParseSettings(SourceDto definition)
    {
        if (definition.Settings == null) return;
        if (definition.Settings.TryGetValue("Host", out var h) && !string.IsNullOrEmpty(h)) _host = h;
        if (definition.Settings.TryGetValue("Port", out var p) && int.TryParse(p, out var portVal)) _port = portVal;
        if (definition.Settings.TryGetValue("PollingIntervalMs", out var rate) && int.TryParse(rate, out var rateVal)) _pollingIntervalMs = rateVal;
    }

    /// <summary>
    /// Connects to hardware sockets and launches background polling workers during startup.
    /// </summary>
    /// <param name="ct">Cancellation token for startup sequence.</param>
    protected override async Task OnStartAsync(CancellationToken ct)
    {
        _log.Info("Lifecycle", $"Starting custom protocol adapter for {_host}:{_port}...");
        
        // 1. Establish hardware socket or client connection
        await SetConnectionStateAsync(SourceConnectionState.Connecting, $"Connecting to {_host}:{_port}...");
        
        _cts = new CancellationTokenSource();
        _timer = new PeriodicTimer(TimeSpan.FromMilliseconds(_pollingIntervalMs));

        await SetConnectionStateAsync(SourceConnectionState.Connected, $"Connected to {_host}:{_port}");
        _log.Info("Lifecycle", $"Successfully connected to {_host}:{_port}");
        _pollTask = RunPollLoopAsync(_cts.Token);
    }

    /// <summary>
    /// Disconnects network sockets and cleans up background workers during shutdown.
    /// </summary>
    /// <param name="ct">Cancellation token for shutdown sequence.</param>
    protected override async Task OnStopAsync(CancellationToken ct)
    {
        _log.Info("Lifecycle", "Stopping custom protocol adapter...");
        
        // 2. Tear down sockets, cancel background tasks, and clean up resources
        if (_cts != null)
        {
            _cts.Cancel();
            _timer?.Dispose();
            if (_pollTask != null)
            {
                try { await _pollTask.ConfigureAwait(false); } catch { }
            }
            _cts.Dispose();
            _cts = null;
        }

        await SetConnectionStateAsync(SourceConnectionState.Disconnected, "Adapter stopped.");
        _log.Info("Lifecycle", "Adapter stopped successfully.");
    }

    /// <summary>
    /// Disposes resources held by the source adapter when unloaded from the service ALC sandbox.
    /// </summary>
    public void Dispose()
    {
        OnStopAsync(CancellationToken.None).GetAwaiter().GetResult();
        GC.SuppressFinalize(this);
    }

    /// <summary>
    /// Tests network connection health to the configured endpoint.
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A test result indicating success or error details.</returns>
    protected override Task<SourceTestResult> OnTestConnectionAsync(CancellationToken ct)
    {
        _log.Debug("Diagnostics", $"Testing connection to {_host}:{_port}...");
        // Connection test logic (called from UI editor test button via IPC)
        return Task.FromResult(new SourceTestResult
        {
            Success = true
        });
    }

    /// <summary>
    /// Discovers catalog tag descriptors and commands exposed by this custom protocol.
    /// </summary>
    /// <param name="forceRefresh">Forces live device refresh if true.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A catalog snapshot containing available telemetry items.</returns>
    protected override Task<SourceCatalogSnapshot> OnBrowseCatalogAsync(bool forceRefresh, CancellationToken ct)
    {
        _log.Debug("Catalog", "Browsing available tags for custom protocol...");
        // 3. Expose available data points to Uniflow Data Catalog & Rule Engine
        var catalog = BuildEmptyCatalogSnapshot();

        catalog.Items.Add(new SourceItemDescriptor
        {
            Id = "sensor_temp",
            DisplayName = "Ambient Temperature",
            Path = "Sensors/Temperature",
            Category = "Telemetry",
            Kind = SourceItemKind.Value,
            Access = SourceItemAccess.Read,
            ValueType = SourceValueType.Double,
            Unit = "°C",
            IsBrowsable = true,
            IsCached = true,
            SupportsMonitoring = true
        });

        catalog.Items.Add(new SourceItemDescriptor
        {
            Id = "relay_state",
            DisplayName = "Relay Output Switch",
            Path = "Control/Relay1",
            Category = "Actuators",
            Kind = SourceItemKind.Value,
            Access = SourceItemAccess.ReadWrite,
            ValueType = SourceValueType.Bool,
            IsBrowsable = true,
            IsCached = true,
            SupportsMonitoring = true
        });

        return Task.FromResult(catalog);
    }

    /// <summary>
    /// Reads live tag values from device hardware during periodic polling cycles.
    /// </summary>
    /// <param name="itemIds">Specific tag IDs to poll, or null for all monitored tags.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A snapshot containing updated telemetry values.</returns>
    protected override Task<SourceValuesSnapshot> OnRefreshValuesAsync(IReadOnlyCollection<string>? itemIds, CancellationToken ct)
    {
        _log.Debug("Polling", "Polling telemetry tag values from device...");

        // 1. RAW TRAFFIC TELEMETRY (Plugin-level wire / socket traffic)
        // If your custom plugin reads raw bytes from sockets, serial ports, or HTTP endpoints,
        // call ReportTraffic(bytesIn, bytesOut) to report wire I/O.
        // This powers the "Plugin Throughput" graphs and totals on the Uniflow Dashboard.
        ReportTraffic(bytesIn: 64, bytesOut: 0);

        // 2. APPLICATION-LEVEL TELEMETRY
        // SourceAdapterBase automatically tracks application bytes based on values inside SourceValuesSnapshot.
        var snapshot = BuildEmptyValuesSnapshot(fullSnapshot: false);

        snapshot.Values.Add(new SourceItemValue
        {
            ItemId = "sensor_temp",
            Timestamp = DateTimeOffset.UtcNow,
            Value = SourceValueData.FromDouble(23.45) // Read live value from protocol
        });

        snapshot.Values.Add(new SourceItemValue
        {
            ItemId = "relay_state",
            Timestamp = DateTimeOffset.UtcNow,
            Value = SourceValueData.FromBool(true)
        });

        return Task.FromResult(snapshot);
    }

    /// <summary>
    /// Gets the current source traffic snapshot containing cumulative byte totals and real-time throughput rates.
    /// </summary>
    /// <remarks>
    /// Inherited implementation from SourceAdapterBase automatically returns calculated Application-level
    /// and Plugin-level metrics calculated over a sliding 10-second window.
    /// </remarks>
    public override SourceTrafficSnapshot GetTrafficSnapshot()
    {
        return base.GetTrafficSnapshot();
    }

    /// <summary>
    /// Writes an output command value to a writable tag item (e.g. relay switch).
    /// </summary>
    /// <param name="itemId">Target tag item ID.</param>
    /// <param name="value">New value data payload to write.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>True if write succeeded; otherwise, false.</returns>
    public override Task<bool> WriteValueAsync(string itemId, SourceValueData value, CancellationToken ct)
    {
        _log.Info("Control", $"Writing value '{value}' to item '{itemId}'...");
        // 3. Handle outbound writes from Rule Engine "Output Target" nodes
        if (itemId == "relay_state")
        {
            bool state = value.BoolValue ?? false;
            // Transmit protocol write command to device hardware (e.g. 8 bytes sent over socket)...
            ReportTraffic(bytesIn: 0, bytesOut: 8);
            return Task.FromResult(true);
        }
        return Task.FromResult(false);
    }
}

// Example: Receiving 256 bytes from TCP socket
ReportTraffic(bytesIn: 256, bytesOut: 0);

// Example: Transmitting a 64-byte command frame to hardware
ReportTraffic(bytesIn: 0, bytesOut: 64);

public sealed class SourceTrafficSnapshot
{
    public string SourceId { get; set; } = string.Empty;
    public long AppBytesIn { get; set; }
    public long AppBytesOut { get; set; }
    public long AppRateIn { get; set; }        // Bytes per second (10-second sliding window)
    public long AppRateOut { get; set; }       // Bytes per second (10-second sliding window)
    public long PluginBytesIn { get; set; }
    public long PluginBytesOut { get; set; }
    public long PluginRateIn { get; set; }     // Bytes per second (10-second sliding window)
    public long PluginRateOut { get; set; }    // Bytes per second (10-second sliding window)
    public bool HasPluginTraffic { get; set; }
    public DateTimeOffset Timestamp { get; set; }
}

using UniflowLibs.Contracts.Sources;
using UniflowLibs.Logging;
using UniflowService.Sources.Abstractions;

namespace Uniflow.Plugin.MyCustomPlugin;

/// <summary>
/// Factory for constructing <see cref="MyCustomSourceAdapter"/> instances inside UniflowService.
/// </summary>
public class MyCustomSourceAdapterFactory : ISourceAdapterFactory
{
    private readonly string _sourceTypeId;
    private readonly IUniflowLogger _log;

    /// <summary>
    /// Initializes a new instance of the <see cref="MyCustomSourceAdapterFactory"/> class.
    /// </summary>
    /// <param name="sourceTypeId">Plugin source type identifier string.</param>
    /// <param name="log">Host logger instance.</param>
    public MyCustomSourceAdapterFactory(string sourceTypeId, IUniflowLogger log)
    {
        _sourceTypeId = sourceTypeId;
        _log = log ?? NullUniflowLogger.Instance;
    }

    /// <summary>
    /// Checks whether this factory handles creation for the requested source type.
    /// </summary>
    /// <param name="sourceType">Source type identifier string.</param>
    /// <returns>True if supported; otherwise, false.</returns>
    public bool CanCreate(SourceType sourceType) => sourceType.ToString() == _sourceTypeId;

    /// <summary>
    /// Creates a new <see cref="MyCustomSourceAdapter"/> instance with configured capabilities.
    /// </summary>
    /// <param name="definition">Source DTO definition.</param>
    /// <returns>An initialized <see cref="ISourceAdapter"/> instance.</returns>
    public ISourceAdapter Create(SourceDto definition)
    {
        var capabilities = new SourceCapabilities
        {
            CanReadValues = true,
            CanWriteValues = true,
            CanBrowseCatalog = true,
            CanExecuteCommands = false
        };
        return new MyCustomSourceAdapter(definition, capabilities, _log);
    }
}

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using UniflowLibs.Contracts.Ipc;
using UniflowLibs.Contracts.Sources;

namespace Uniflow.Plugin.MyCustomPlugin;

/// <summary>
/// Source editor ViewModel for configuring custom protocol settings in the Uniflow GUI.
/// Implements ISourceEditorViewModel to bind UI controls and communicate with UniflowService via IPC.
/// </summary>
public partial class MyCustomSourceEditorViewModel : ObservableObject, ISourceEditorViewModel
{
    private readonly IIpcClient? _ipc;
    private readonly SourceDto _source;

    [ObservableProperty] private string _host = "127.0.0.1";
    [ObservableProperty] private int _port = 5000;
    [ObservableProperty] private int _pollingIntervalMs = 1000;
    [ObservableProperty] private string _statusMessage = "";

    /// <summary>
    /// Gets the plugin source type identifier string.
    /// </summary>
    public string SourceType { get; }

    /// <summary>
    /// Gets the command for saving current configuration to UniflowService.
    /// </summary>
    public IAsyncRelayCommand SaveCommand { get; }

    /// <summary>
    /// Gets the command for canceling changes and dismissing the editor dialog.
    /// </summary>
    public IRelayCommand CancelCommand { get; }

    /// <summary>
    /// Gets the command for testing network connection health to the hardware endpoint.
    /// </summary>
    public IAsyncRelayCommand TestConnectionCommand { get; }

    /// <summary>
    /// Event raised when source configuration is successfully saved.
    /// </summary>
    public event Action? Saved;

    /// <summary>
    /// Event raised when editing is canceled.
    /// </summary>
    public event Action? Cancelled;

    /// <summary>
    /// Initializes a new instance of the <see cref="MyCustomSourceEditorViewModel"/> class.
    /// </summary>
    /// <param name="ipc">IPC client instance.</param>
    /// <param name="source">Source configuration DTO.</param>
    /// <param name="sourceType">Plugin source type identifier.</param>
    public MyCustomSourceEditorViewModel(IIpcClient? ipc, SourceDto source, string sourceType)
    {
        _ipc = ipc;
        _source = source;
        SourceType = sourceType;

        // Load existing settings
        if (source.Settings != null)
        {
            if (source.Settings.TryGetValue("Host", out var h)) Host = h;
            if (source.Settings.TryGetValue("Port", out var p) && int.TryParse(p, out var portVal)) Port = portVal;
            if (source.Settings.TryGetValue("PollingIntervalMs", out var rate) && int.TryParse(rate, out var rateVal)) PollingIntervalMs = rateVal;
        }

        SaveCommand = new AsyncRelayCommand(OnSaveAsync);
        CancelCommand = new RelayCommand(() => Cancelled?.Invoke());
        TestConnectionCommand = new AsyncRelayCommand(OnTestConnectionAsync);
    }

    /// <summary>
    /// Builds a SourceDto representing the current state of the editor.
    /// Used by host application for deterministic JSON dirty state tracking.
    /// </summary>
    public SourceDto BuildCurrentDto()
    {
        return new SourceDto
        {
            Id = _source.Id,
            SourceType = SourceType,
            Name = _source.Name,
            Enabled = _source.Enabled,
            Notes = _source.Notes,
            Settings = new Dictionary<string, string>
            {
                ["Host"] = Host,
                ["Port"] = Port.ToString(),
                ["PollingIntervalMs"] = PollingIntervalMs.ToString()
            }
        };
    }

    /// <summary>
    /// Asynchronously saves updated settings to UniflowService over IPC.
    /// </summary>
    private async Task OnSaveAsync()
    {
        if (_ipc == null) return;

        var dto = BuildCurrentDto();
        _source.Settings = dto.Settings;

        var resp = await _ipc.SendAsync(new IpcRequestEnvelope
        {
            Command = IpcCommand.UpsertSource,
            Payload = new UpsertSourceRequest { Source = _source },
            ClientId = "Uniflow.GUI"
        }, default);

        if (resp.Code == IpcResultCode.Ok)
            Saved?.Invoke();
        else
            StatusMessage = $"Save Failed: {resp.ErrorMessage}";
    }

    /// <summary>
    /// Asynchronously tests connection health to the hardware endpoint over IPC.
    /// </summary>
    private async Task OnTestConnectionAsync()
    {
        if (_ipc == null) return;

        StatusMessage = "Testing connection...";
        var resp = await _ipc.SendAsync(new IpcRequestEnvelope
        {
            Command = IpcCommand.TestSourceConnection,
            Payload = new TestSourceConnectionRequest { Source = _source },
            ClientId = "Uniflow.GUI"
        }, default);

        StatusMessage = resp.Code == IpcResultCode.Ok ? "Connection successful!" : $"Connection failed: {resp.ErrorMessage}";
    }
}

<UserControl x:Class="Uniflow.Plugin.MyCustomPlugin.MyCustomSourceEditorView"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
             MinWidth="420">
    <StackPanel Margin="15">
        <TextBlock Text="Custom Protocol Configuration" FontSize="18" FontWeight="Bold" Margin="0,0,0,15" Foreground="White"/>

        <TextBlock Text="Target Host / IP Address:" Margin="0,5" Foreground="LightGray"/>
        <ui:TextBox Text="{Binding Host, UpdateSourceTrigger=PropertyChanged}" PlaceholderText="e.g. 192.168.1.100"/>

        <TextBlock Text="TCP Port:" Margin="0,12,0,5" Foreground="LightGray"/>
        <ui:NumberBox Value="{Binding Port, UpdateSourceTrigger=PropertyChanged}" Minimum="1" Maximum="65535"/>

        <TextBlock Text="Polling Interval (ms):" Margin="0,12,0,5" Foreground="LightGray"/>
        <ui:NumberBox Value="{Binding PollingIntervalMs, UpdateSourceTrigger=PropertyChanged}" Minimum="100" Maximum="60000"/>

        <TextBlock Text="{Binding StatusMessage}" Foreground="Teal" Margin="0,10" TextWrapping="Wrap"/>
    </StackPanel>
</UserControl>

using System.Windows;
using UniflowLibs.Contracts.Sources;

namespace Uniflow.Plugin.MyCustomPlugin;

/// <summary>
/// Interaction logic for MyCustomHelperDialog.xaml window.
/// </summary>
public partial class MyCustomHelperDialog : Window
{
    /// <summary>
    /// Initializes a new instance of the <see cref="MyCustomHelperDialog"/> class.
    /// </summary>
    public MyCustomHelperDialog()
    {
        InitializeComponent();
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="MyCustomHelperDialog"/> class with source context.
    /// </summary>
    /// <param name="source">Source configuration DTO.</param>
    public MyCustomHelperDialog(SourceDto source) : this()
    {
        // Decode source settings and initialize ViewModel / Catalog Data
    }

    /// <summary>
    /// Closes the helper dialog window.
    /// </summary>
    private void Close_Click(object sender, RoutedEventArgs e)
    {
        Close();
    }
}

/// <summary>
/// Definition class implementing ISourcePluginDefinition for plugin loading.
/// </summary>
public class MyCustomPluginDefinition : ISourcePluginDefinition
{
    /// <summary>
    /// Unique source type identifier.
    /// </summary>
    public string SourceTypeId => "uniflow.plugin.mycustomplugin";

    /// <summary>
    /// Indicates that this plugin provides a custom helper window.
    /// </summary>
    public bool HasHelperWindow => true;

    /// <summary>
    /// Constructs and returns the fully initialized Helper Window instance.
    /// </summary>
    /// <param name="source">Source DTO context.</param>
    /// <returns>Initialized helper window dialog.</returns>
    public object? CreateHelperWindow(SourceDto source)
    {
        return new MyCustomHelperDialog(source);
    }
}

/// <summary>
/// ViewModel for configuring hierarchical topic subscriptions in the Avigilon Helper dialog.
/// </summary>
public partial class AvigilonTopicsConfigurationViewModel : ObservableObject
{
    [ObservableProperty] private MainTopicItem? _selectedMainTopic;
    [ObservableProperty] private BucketItem? _selectedBucket;
    [ObservableProperty] private string _searchAtomicEventsText = string.Empty;

    /// <summary>
    /// Gets the collection of main topic categories.
    /// </summary>
    public ObservableCollection<MainTopicItem> MainTopics { get; } = new();

    /// <summary>
    /// Gets the collection of topic bucket items under the selected category.
    /// </summary>
    public ObservableCollection<BucketItem> Buckets { get; } = new();

    /// <summary>
    /// Gets atomic event items filtered by search text.
    /// </summary>
    public IEnumerable<AtomicEventItem> FilteredAtomicEvents =>
        SelectedBucket == null ? Array.Empty<AtomicEventItem>() :
        string.IsNullOrWhiteSpace(SearchAtomicEventsText) ? SelectedBucket.AtomicEvents :
        SelectedBucket.AtomicEvents.Where(e => e.Name.Contains(SearchAtomicEventsText, StringComparison.OrdinalIgnoreCase));

    /// <summary>
    /// Formats checked atomic event selections into comma-separated CSV strings for source settings.
    /// </summary>
    /// <returns>Formatted CSV string of topic selections.</returns>
    public string GetSelectedSubtopicsCsv()
    {
        var resultList = new List<string>();
        foreach (var bucket in Buckets)
        {
            if (bucket.IsSelected)
            {
                var checkedChildren = bucket.AtomicEvents.Where(c => c.IsSelected).ToList();
                if (checkedChildren.Count > 0)
                    resultList.AddRange(checkedChildren.Select(c => c.Name));
                else
                    resultList.Add(bucket.Name);
            }
        }
        return string.Join(",", resultList);
    }
}

using System;
using System.Windows.Controls;
using UniflowLibs.Contracts.Plugins;
using UniflowLibs.Contracts.Sources;
using UniflowLibs.Contracts.Ipc;
using UniflowLibs.Logging;
using UniflowService.Sources.Abstractions;

namespace Uniflow.Plugin.MyCustomPlugin;

/// <summary>
/// Root entry point definition for the custom protocol plugin.
/// Exposes metadata, UI views, factory creators, helper window instances, and rule engine descriptors.
/// </summary>
public class MyCustomPluginDefinition : ISourcePluginDefinition
{
    /// <summary>
    /// Gets the unique plugin source type identifier string.
    /// </summary>
    public string SourceTypeId => "uniflow.plugin.mycustomplugin";

    /// <summary>
    /// Gets the human-readable title of the plugin.
    /// </summary>
    public string Name => "My Custom Protocol";

    /// <summary>
    /// Gets the detailed description of plugin capabilities.
    /// </summary>
    public string Description => "Integrates proprietary field telemetry controllers over TCP/IP sockets.";

    /// <summary>
    /// Gets the 256x256 display icon byte array.
    /// </summary>
    public byte[] SourceImage => GetEmbeddedIconBytes();

    /// <summary>
    /// Creates the backend adapter factory used by UniflowService.
    /// </summary>
    /// <param name="sp">Host service provider.</param>
    /// <returns>An instance of ISourceAdapterFactory.</returns>
    public ISourceAdapterFactory CreateAdapterFactory(IServiceProvider sp)
    {
        var log = (IUniflowLogger?)sp.GetService(typeof(IUniflowLogger)) ?? NullUniflowLogger.Instance;
        return new MyCustomSourceAdapterFactory(SourceTypeId, log);
    }

    /// <summary>
    /// Creates the WPF source editor ViewModel.
    /// </summary>
    /// <param name="sp">Host service provider.</param>
    /// <param name="source">Source DTO instance.</param>
    /// <returns>Editor ViewModel instance implementing ISourceEditorViewModel.</returns>
    public object CreateEditorViewModel(IServiceProvider sp, SourceDto? source)
    {
        var ipc = (IIpcClient?)sp.GetService(typeof(IIpcClient));
        return new MyCustomSourceEditorViewModel(ipc, source ?? new SourceDto { SourceType = SourceTypeId }, SourceTypeId);
    }

    /// <summary>
    /// Gets the WPF UserControl View type.
    /// </summary>
    public Type EditorViewType => typeof(MyCustomSourceEditorView);

    /// <summary>
    /// Gets a value indicating whether a custom helper window button is rendered in the sources table.
    /// </summary>
    public bool HasHelperWindow => true;

    /// <summary>
    /// Instantiates and returns the custom helper window dialog.
    /// </summary>
    /// <param name="source">Source DTO context.</param>
    /// <returns>A WPF Window instance.</returns>
    public object? CreateHelperWindow(SourceDto source)
    {
        return new MyCustomHelperDialog(source);
    }

    /// <summary>
    /// Gets rule engine field descriptors for dynamic Rule Editor parameter resolution.
    /// </summary>
    public PluginRuleIntegration? RuleIntegration => new PluginRuleIntegration
    {
        FieldDescriptors = new List<RuleFieldDescriptor>
        {
            new RuleFieldDescriptor
            {
                TargetItemId = "relay_state",
                ArgumentKey = "Value",
                EditorKind = RuleFieldEditorKind.Boolean
            }
        }
    };

    /// <summary>
    /// Reads and returns the embedded PNG icon file from assembly resources.
    /// </summary>
    /// <returns>Raw byte array of the embedded icon.</returns>
    private byte[] GetEmbeddedIconBytes()
    {
        using var stream = GetType().Assembly.GetManifestResourceStream("Uniflow.Plugin.MyCustomPlugin.icon.png");
        if (stream == null) return Array.Empty<byte>();
        var bytes = new byte[stream.Length];
        stream.Read(bytes, 0, bytes.Length);
        return bytes;
    }
}

public sealed class PluginRuleIntegration
{
    public List<RuleFieldDescriptor> FieldDescriptors { get; set; } = new();
    public List<string> EventOnlyItemIds { get; set; } = new();
    public List<string> DataOnlyItemIds { get; set; } = new();
}

public sealed class RuleFieldDescriptor
{
    public string TargetItemId { get; set; } = "";     // e.g. "avigilon:alarm" or "dblink:table:*"
    public string ArgumentKey { get; set; } = "";      // e.g. "AlarmId", "SetFields", "WhereFields"
    public RuleFieldEditorKind EditorKind { get; set; } = RuleFieldEditorKind.Text;

    // CollectionHelper Properties (1-Column Selection)
    public string? HelperCollectionItemId { get; set; } // Catalog item ID to browse, or "$self:arguments" for node's own arguments
    public string? HelperDialogTitle { get; set; }        // Picker window title
    public string? HelperDisplayProperty { get; set; }     // Display label property (e.g. "Name")
    public string? HelperValueProperty { get; set; }       // Property copied to field (e.g. "Id")
    public string? HelperSubtitleProperty { get; set; }    // Subtitle property (e.g. "State")
    public bool IsMultiSelect { get; set; }                // Enables multi-selection with checkboxes
    public string MultiSelectSeparator { get; set; } = ","; // Separator string to join selected values (defaults to ",")
    public string? SelfArgumentExcludeKeys { get; set; }  // Comma-separated list of keys to exclude when HelperCollectionItemId is "$self:arguments"

    // TwoColumnHelper Properties (2-Column Parent/Child Selection)
    public string? HelperColumn1Title { get; set; }        // Parent column header title (e.g. "Select Camera")
    public string? HelperColumn2Title { get; set; }        // Child column header title (e.g. "Select PTZ Preset")
    public string? HelperChildCollectionProperty { get; set; } // Dot-notation child array path (e.g. "ptzInfo.presets")
    public string? HelperChildDisplayProperty { get; set; }  // Child display label property (e.g. "Name")
    public string? HelperChildValueProperty { get; set; }    // Child value property (e.g. "Id")
    public string? HelperChildSubtitleProperty { get; set; } // Child subtitle property
    public string? HelperParentArgumentKey { get; set; }   // Target node field key for parent ID (e.g. "Id")
    public string? HelperChildArgumentKey { get; set; }    // Target node field key for child ID (e.g. "PresetId")

    // Dropdown & Validation
    public List<string>? AllowedValues { get; set; }
    public string? ValidationPattern { get; set; }
    public string? ValidationMessage { get; set; }
    public bool TriggersPortRegeneration { get; set; }
}

public enum RuleFieldEditorKind
{
    Text,               // Simple text input box
    Numeric,            // Number input field
    Dropdown,           // Constrained selection list from AllowedValues
    CollectionHelper,   // Button opening a 1-column catalog item picker dialog
    DateTimeHelper,     // Button opening an interactive Date/Time picker dialog
    Boolean,            // Checkbox control
    ReadOnly,           // Display-only text label
    TwoColumnHelper     // Button opening a 2-column parent/child collection picker dialog
}

public sealed class SourceCommandParameterDescriptor
{
    public string Name { get; set; } = "";
    public string DisplayName { get; set; } = "";
    public SourceValueType ValueType { get; set; } = SourceValueType.String;
    public bool Required { get; set; }
    public List<string>? AllowedValues { get; set; }
    public string? Notes { get; set; }

    /// <summary>Visual header section name in the inspector panel.</summary>
    public string? GroupName { get; set; }

    /// <summary>Conditional visibility expression (e.g. "Action=UPDATE&amp;UpdateMode=WHERE").</summary>
    public string? VisibleWhen { get; set; }

    /// <summary>Default value assigned when the argument is first created.</summary>
    public string? DefaultValue { get; set; }

    /// <summary>When true, this field is inspector-only and generates no input port on the canvas.</summary>
    public bool HiddenFromPorts { get; set; }

    /// <summary>When true, this parameter's selected values dynamically filter which sibling ports appear on the canvas.</summary>
    public bool IsPortFilter { get; set; }

    /// <summary>Prefix prepended to port keys generated from this filter field's values (e.g., "where_").</summary>
    public string? PortKeyPrefix { get; set; }

    /// <summary>Prefix prepended to port labels generated from this filter field's values (e.g., "WHERE ").</summary>
    public string? PortLabelPrefix { get; set; }
}

     new SourceCommandParameterDescriptor
     {
         Name = "Value",
         DisplayName = "Value",
         ValueType = SourceValueType.String,
         Required = true,
         DynamicTypeMap = "Type:Coils=Bool;Coil=Bool;Discrete Input=Bool;Discrete Inputs=Bool;*=Int"
     }
     

     new SourceCommandParameterDescriptor
     {
         Name = "content",
         DisplayName = "Content",
         ValueType = SourceValueType.String,
         Required = true,
         DynamicTypeMap = "format:Bytes=ByteArray;*=String"
     }
     

// Example: Registering SET and WHERE field pickers for database table operations
new RuleFieldDescriptor
{
    TargetItemId = "dblink:table:*",
    ArgumentKey = "SetFields",
    EditorKind = RuleFieldEditorKind.CollectionHelper,
    HelperCollectionItemId = "$self:arguments", // Lists the node's own argument fields
    HelperDialogTitle = "Select SET Fields (Group 1)",
    IsMultiSelect = true,
    MultiSelectSeparator = ",",
    TriggersPortRegeneration = true,
    SelfArgumentExcludeKeys = "Action,UpdateMode,WhereOperator,WhereFields,SetFields" // Exclude internal control parameters
}

var tableParams = new List<SourceCommandParameterDescriptor>
{
    // Action selector dropdown
    new() { 
        Name = "Action", DisplayName = "Action", ValueType = SourceValueType.String, Required = true,
        AllowedValues = new List<string> { "INSERT", "UPDATE", "DELETE" },
        DefaultValue = "INSERT",
        GroupName = "Database Operation",
        HiddenFromPorts = true 
    },

    // Update Mode selector (visible only when Action=UPDATE)
    new() { 
        Name = "UpdateMode", DisplayName = "Update Mode", ValueType = SourceValueType.String, Required = false,
        AllowedValues = new List<string> { "STRICT", "WHERE" },
        DefaultValue = "STRICT",
        GroupName = "Database Operation",
        HiddenFromPorts = true,
        VisibleWhen = "Action=UPDATE",
        Notes = "STRICT requires PKEY. WHERE uses custom filter fields." 
    },

    // Group 1: Fields to SET (visible when Action=UPDATE & UpdateMode=WHERE)
    new() { 
        Name = "SetFields", DisplayName = "Fields to Set", ValueType = SourceValueType.String, Required = false,
        GroupName = "SET Clause (Group 1)",
        HiddenFromPorts = true,
        VisibleWhen = "Action=UPDATE&UpdateMode=WHERE",
        IsPortFilter = true,
        Notes = "Columns updated in SET clause." 
    },

    // Group 2: WHERE Clause Fields (visible when Action=UPDATE & UpdateMode=WHERE)
    new() { 
        Name = "WhereFields", DisplayName = "WHERE Fields", ValueType = SourceValueType.String, Required = false,
        GroupName = "WHERE Clause (Group 2)",
        HiddenFromPorts = true,
        VisibleWhen = "Action=UPDATE&UpdateMode=WHERE",
        IsPortFilter = true,
        PortKeyPrefix = "where_",
        PortLabelPrefix = "WHERE ",
        Notes = "Columns used in WHERE clause." 
    },

    // Group 2: Logical Operator (AND/OR)
    new() { 
        Name = "WhereOperator", DisplayName = "WHERE Operator", ValueType = SourceValueType.String, Required = false,
        AllowedValues = new List<string> { "AND", "OR" },
        DefaultValue = "AND",
        GroupName = "WHERE Clause (Group 2)",
        HiddenFromPorts = true,
        VisibleWhen = "Action=UPDATE&UpdateMode=WHERE" 
    }
};

// Add actual table columns
foreach (var col in discoveredColumns)
{
    tableParams.Add(new SourceCommandParameterDescriptor
    {
        Name = col.Name,
        DisplayName = col.Name,
        ValueType = col.Type,
        GroupName = "Column Values"
    });
}

public PluginRuleIntegration? RuleIntegration => new PluginRuleIntegration
{
    FieldDescriptors = new List<RuleFieldDescriptor>
    {
        // SET Fields multi-select argument picker
        new RuleFieldDescriptor
        {
            TargetItemId = "dblink:table:*",
            ArgumentKey = "SetFields",
            EditorKind = RuleFieldEditorKind.CollectionHelper,
            HelperCollectionItemId = "$self:arguments",
            HelperDialogTitle = "Select SET Fields (Group 1)",
            IsMultiSelect = true,
            MultiSelectSeparator = ",",
            TriggersPortRegeneration = true,
            SelfArgumentExcludeKeys = "Action,UpdateMode,WhereOperator,WhereFields,SetFields"
        },
        // WHERE Fields multi-select argument picker
        new RuleFieldDescriptor
        {
            TargetItemId = "dblink:table:*",
            ArgumentKey = "WhereFields",
            EditorKind = RuleFieldEditorKind.CollectionHelper,
            HelperCollectionItemId = "$self:arguments",
            HelperDialogTitle = "Select WHERE Fields (Group 2)",
            IsMultiSelect = true,
            MultiSelectSeparator = ",",
            TriggersPortRegeneration = true,
            SelfArgumentExcludeKeys = "Action,UpdateMode,WhereOperator,WhereFields,SetFields"
        }
    }
};

public PluginRuleIntegration? RuleIntegration => new PluginRuleIntegration
{
    FieldDescriptors = new List<RuleFieldDescriptor>
    {
        new RuleFieldDescriptor
        {
            TargetItemId = "avigilon:alarm",
            ArgumentKey = "AlarmId",
            EditorKind = RuleFieldEditorKind.CollectionHelper,
            HelperCollectionItemId = "avigilon:alarms", // Catalog point that returns alarm list
            HelperDialogTitle = "Select Avigilon Alarm",
            HelperDisplayProperty = "Name",
            HelperValueProperty = "Id",
            HelperSubtitleProperty = "State"
        }
    }
};

public PluginRuleIntegration? RuleIntegration => new PluginRuleIntegration
{
    FieldDescriptors = new List<RuleFieldDescriptor>
    {
        // Camera Picker helper for Milestone Event Trigger
        new RuleFieldDescriptor
        {
            TargetItemId = "milestone:event:trigger",
            ArgumentKey = "Source",
            EditorKind = RuleFieldEditorKind.CollectionHelper,
            HelperCollectionItemId = "milestone:cameras",
            HelperDialogTitle = "Select Camera",
            HelperDisplayProperty = "Name",
            HelperValueProperty = "Id",
            HelperSubtitleProperty = "Description"
        },
        // Event Type helper for Milestone Event Trigger
        new RuleFieldDescriptor
        {
            TargetItemId = "milestone:event:trigger",
            ArgumentKey = "Type",
            EditorKind = RuleFieldEditorKind.CollectionHelper,
            HelperCollectionItemId = "milestone:eventTypes",
            HelperDialogTitle = "Select Event Type",
            HelperDisplayProperty = "DisplayName",
            HelperValueProperty = "Id",
            HelperSubtitleProperty = "Name"
        }
    }
};

// Inside PluginUiProvider — loads a plugin's RuleIntegration at runtime
public static async Task<PluginRuleIntegration?> GetRuleIntegrationAsync(IIpcClient? ipc, string sourceType)
{
    if (string.IsNullOrWhiteSpace(sourceType)) return null;

    var asm = await EnsureUiAssemblyLoadedAsync(ipc, sourceType);
    if (asm == null) return null;

    // Find the ISourcePluginDefinition type and read its RuleIntegration property
    var pluginDefType = asm.GetTypes()
        .FirstOrDefault(t => typeof(ISourcePluginDefinition).IsAssignableFrom(t) && !t.IsAbstract);

    if (pluginDefType != null)
    {
        var instance = Activator.CreateInstance(pluginDefType) as ISourcePluginDefinition;
        return instance?.RuleIntegration;
    }
    return null;
}

   var vm = new CollectionItemPickerViewModel(
       ipcClient, sourceId, 
       collectionItemId: descriptor.HelperCollectionItemId,
       title: descriptor.HelperDialogTitle ?? "Select Item",
       displayProperty: descriptor.HelperDisplayProperty ?? "Name",
       valueProperty: descriptor.HelperValueProperty ?? "Id",
       subtitleProperty: descriptor.HelperSubtitleProperty ?? "");
   

   <DataTemplate>
       <StackPanel>
           <TextBlock Text="{Binding DisplayName}" FontWeight="Bold" />
           <TextBlock Text="{Binding Subtitle}" FontSize="10" Foreground="Gray" />
       </StackPanel>
   </DataTemplate>
   

new RuleFieldDescriptor
{
    TargetItemId = "avigilon:bookmark:insert",
    ArgumentKey = "CameraIds",
    EditorKind = RuleFieldEditorKind.CollectionHelper,
    HelperCollectionItemId = "avigilon:cameras",
    HelperDialogTitle = "Select Target Cameras",
    HelperDisplayProperty = "Name",
    HelperValueProperty = "Id",
    HelperSubtitleProperty = "Location",
    IsMultiSelect = true,          // Renders item checkboxes and Select All / Clear action controls
    MultiSelectSeparator = ","     // Delimiter used to join selected item values (default is ",")
}

new RuleFieldDescriptor
{
    TargetItemId = "avigilon:camera:commands:preset",
    ArgumentKey = "Id",
    EditorKind = RuleFieldEditorKind.TwoColumnHelper,
    HelperCollectionItemId = "avigilon:cameras",         // Parent collection item ID
    HelperDialogTitle = "Select PTZ Preset",             // Modal window title
    HelperColumn1Title = "Select Camera",                 // Column 1 header
    HelperColumn2Title = "Select PTZ Preset",             // Column 2 header
    HelperDisplayProperty = "Name",                       // Parent display property
    HelperValueProperty = "Id",                           // Parent value property
    HelperSubtitleProperty = "Location",                 // Parent subtitle property
    HelperChildCollectionProperty = "ptzInfo.presets",   // Nested dot-notation child array path
    HelperChildDisplayProperty = "Name",                  // Child display property
    HelperChildValueProperty = "Id",                      // Child value property
    HelperParentArgumentKey = "Id",                       // Target node parameter key for parent ID
    HelperChildArgumentKey = "PresetId"                   // Target node parameter key for child ID
}

protected override Task<SourceCatalogSnapshot> OnBrowseCatalogAsync(bool forceRefresh, CancellationToken ct)
{
    var catalog = BuildEmptyCatalogSnapshot();

    // 1. Declare an event descriptor
    catalog.Items.Add(new SourceItemDescriptor
    {
        Id = "event:camera_intrusion",                     // Technical event identifier / subscription type
        DisplayName = "Camera Intrusion Detection",       // Human-friendly event name
        Path = "Events/Security/Intrusion",
        Category = "Security Events",
        Kind = SourceItemKind.Event,                      // Marks this item as an event
        Access = SourceItemAccess.Read,
        ValueType = SourceValueType.Json,
        IsBrowsable = true,
        Metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
        {
            // Event family categorization (e.g. "EVENT", "SYSTEM", "OBJECT_DELTA", "CATALOG_IDS")
            ["event.family"] = "EVENT",

            // Schema fields exposed by event payloads: "FieldName:DataType;..."
            ["graph.fields"] = "AlarmId:string;CameraName:string;Zone:string;Confidence:double;Timestamp:datetime;Snapshot:string"
        }
    });

    return Task.FromResult(catalog);
}

using UniflowLibs.Contracts.Plugins;

public class MyEventSchemaProvider : IEventSchemaProvider
{
    // 1. Return available event type identifiers
    public IReadOnlyList<string> GetEventTypes() => new[]
    {
        "ALARM_TRIGGERED",
        "MOTION_DETECTED",
        "DEVICE_DISCONNECTED"
    };

    // 2. Return typed schema fields for the specified event type
    public IReadOnlyList<EventFieldDescriptor> GetEventFields(string eventType)
    {
        return eventType switch
        {
            "ALARM_TRIGGERED" => new List<EventFieldDescriptor>
            {
                new() { Name = "AlarmId", DisplayName = "Alarm ID", DataType = GraphPortDataType.String },
                new() { Name = "Priority", DisplayName = "Priority", DataType = GraphPortDataType.Int32 },
                new() { Name = "State", DisplayName = "State", DataType = GraphPortDataType.String },
                new() { Name = "Timestamp", DisplayName = "Timestamp", DataType = GraphPortDataType.DateTime }
            },
            _ => new List<EventFieldDescriptor>
            {
                new() { Name = "Payload", DisplayName = "Payload", DataType = GraphPortDataType.String }
            }
        };
    }

    // 3. Return the event family classification
    public string GetEventFamily(string eventType)
    {
        if (eventType.StartsWith("SYSTEM_")) return "SYSTEM";
        return "EVENT";
    }
}

/// <summary>
/// Rebuilds output ports on an EventInput rule graph node matching selected schema fields.
/// </summary>
/// <param name="selectedFields">List of schema fields selected in the EventPickerDialog.</param>
private void RebuildEventPorts(IReadOnlyList<EventFieldDescriptor> selectedFields)
{
    Dto.Ports.Clear();

    // 1. Primary boolean trigger pulse
    Dto.Ports.Add(CreatePort("trigger", "Trigger", GraphPortDirection.Output, GraphPortDataType.Bool, true));

    // 2. Typed schema payload ports
    foreach (var field in selectedFields)
    {
        Dto.Ports.Add(CreatePort(field.Name, field.DisplayName, GraphPortDirection.Output, field.DataType, true));
    }
}

var payload = new Dictionary<string, object>
{
    ["AlarmId"] = Guid.NewGuid().ToString(),
    ["CameraName"] = "North Gate PTZ",
    ["Zone"] = "Perimeter West",
    ["Confidence"] = 0.94,
    ["Timestamp"] = DateTime.UtcNow
};

await NotifyEventAsync(new SourceEventMessage
{
    SourceId = SourceId,
    EventType = "event:camera_intrusion",
    EventFamily = "EVENT",
    Timestamp = DateTimeOffset.UtcNow,
    Payload = payload
}, cancellationToken);

// Information: Routine lifecycle events, connection status changes
_log.Info("Lifecycle", $"Connected to host {_host}:{_port}");

// Debug: Detailed diagnostic traces, packet dumps, catalog updates
_log.Debug("Diagnostics", $"Polled 14 items in {sw.ElapsedMilliseconds} ms");

// Warning: Recoverable issues, retries, non-critical protocol warnings
_log.Warn("Protocol", $"Transient timeout receiving frame. Retrying (attempt {retryCount})...");

// Error: Unhandled exceptions, failed connections, data parse errors
_log.Error("Sockets", ex, $"Failed to connect to hardware endpoint at {_host}:{_port}");