[WotCon] Materialize WoT Thing Descriptions into the server address space

src/Opc.Ua.WotCon.Server/EventIds.cs

@@ -46,5 +46,6 @@ internal static class WotConServerEventIds
         public const int AssetRegistry = 0;
         public const int WotAssetFileManager = 40;
         public const int WotConnectivityNodeManager = 50;
+        public const int WotRegistryNodeManager = 60;
     }
 }

src/Opc.Ua.WotCon.Server/Hosting/OpcUaWotRegistryServerBuilderExtensions.cs

@@ -0,0 +1,200 @@
+/* ========================================================================
+ * Copyright (c) 2005-2026 The OPC Foundation, Inc. All rights reserved.
+ *
+ * OPC Foundation MIT License 1.00
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * The complete license agreement can be found here:
+ * http://opcfoundation.org/License/MIT/1.00/
+ * ======================================================================*/
+
+using System;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+using Opc.Ua;
+using Opc.Ua.Server;
+using Opc.Ua.Server.Hosting;
+using Opc.Ua.Wot;
+using Opc.Ua.WotCon.Bindings;
+using Opc.Ua.WotCon.Server;
+using Opc.Ua.WotCon.Server.Materialization;
+using Opc.Ua.WotCon.Server.Registry;
+using Opc.Ua.XRegistry.Server;
+
+namespace Microsoft.Extensions.DependencyInjection
+{
+    /// <summary>
+    /// <see cref="IOpcUaBuilder"/> extensions that host the WoT Connectivity 1.1
+    /// registry (<c>WoTRegistry</c>) on the OPC UA server registered via
+    /// <c>.AddServer(...)</c>. The registry service, materialization coordinator,
+    /// binder registry and projection host are registered as singletons; the
+    /// stable <see cref="WotRegistryNodeManager"/> is attached at server start.
+    /// </summary>
+    public static class OpcUaWotRegistryServerBuilderExtensions
+    {
+        /// <summary>
+        /// Default configuration section for the registry options.
+        /// </summary>
+        public const string DefaultConfigurationSection = "OpcUa:WotConRegistry:Server";
+
+        /// <summary>
+        /// Registers the WoT Connectivity 1.1 registry NodeManager configured by
+        /// <paramref name="configure"/>.
+        /// </summary>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="ArgumentNullException"></exception>
+        public static IOpcUaBuilder AddWotRegistryServer(
+            this IOpcUaBuilder builder,
+            Action<WotRegistryServerOptions>? configure = null)
+        {
+            if (builder is null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (configure is not null)
+            {
+                builder.Services.AddOptions<WotRegistryServerOptions>().Configure(configure);
+            }
+            else
+            {
+                builder.Services.AddOptions<WotRegistryServerOptions>();
+            }
+            RegisterCommonServices(builder.Services);
+            return builder;
+        }
+
+        /// <summary>
+        /// Registers the WoT Connectivity 1.1 registry NodeManager with options
+        /// bound from the supplied configuration section.
+        /// </summary>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="ArgumentNullException"></exception>
+        public static IOpcUaBuilder AddWotRegistryServer(
+            this IOpcUaBuilder builder,
+            IConfiguration configuration)
+        {
+            if (configuration is null)
+            {
+                throw new ArgumentNullException(nameof(configuration));
+            }
+            return builder.AddWotRegistryServer(
+                configuration.GetSection(DefaultConfigurationSection));
+        }
+
+        /// <summary>
+        /// Registers the WoT Connectivity 1.1 registry NodeManager with options
+        /// bound from the supplied configuration section.
+        /// </summary>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="ArgumentNullException"></exception>
+        public static IOpcUaBuilder AddWotRegistryServer(
+            this IOpcUaBuilder builder,
+            IConfigurationSection section)
+        {
+            if (builder is null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (section is null)
+            {
+                throw new ArgumentNullException(nameof(section));
+            }
+            builder.Services.AddOptions<WotRegistryServerOptions>().Bind(section);
+            RegisterCommonServices(builder.Services);
+            return builder;
+        }
+
+        private static void RegisterCommonServices(IServiceCollection services)
+        {
+            services.TryAddSingleton(sp =>
+                sp.GetRequiredService<IOptions<WotRegistryServerOptions>>().Value
+                ?? new WotRegistryServerOptions());
+
+            services.EnsureWotBinderRegistry();
+
+            services.TryAddSingleton<IWotTargetVariableResolver>(new WotTargetVariableResolver());
+
+            services.TryAddSingleton<IWotProjectionBindingRuntimeFactory>(sp =>
+                new WotProjectionBindingRuntimeFactory(
+                    sp.GetRequiredService<IWotBindingChannelFactory>(),
+                    sp.GetRequiredService<IWotTargetVariableResolver>()));
+
+            services.TryAddSingleton<IWotRegistryService>(sp =>
+            {
+                WotRegistryServerOptions options =
+                    sp.GetRequiredService<WotRegistryServerOptions>();
+                // A store registered in DI wins over one set on the options, so a deployment can
+                // supply a shared store the same way the xRegistry server does.
+                IXRegistryResourceStore? resourceStore =
+                    sp.GetService<IXRegistryResourceStore>() ?? options.ResourceStore;
+                IWotRegistryStore store = string.IsNullOrEmpty(options.StorageFolder)
+                    ? new InMemoryWotRegistryStore()
+                    : resourceStore is null
+                        ? new FileWotRegistryStore(options.StorageFolder!)
+                        : new FileWotRegistryStore(options.StorageFolder!, resourceStore);
+                return new WotRegistryService(store, options.Bounds);
+            });
+
+            services.TryAddSingleton<IWotProjectionHost>(sp =>
+                new LifecycleWotProjectionHost(
+                    sp.GetRequiredService<INodeManagerLifecycle>(),
+                    sp.GetRequiredService<IWotProjectionBindingRuntimeFactory>()));
+
+            services.TryAddSingleton(sp =>
+            {
+                WotRegistryServerOptions options =
+                    sp.GetRequiredService<WotRegistryServerOptions>();
+                var converterOptions = new WotNodeSetConverterOptions
+                {
+                    MaxJsonDocumentSize = options.Bounds.MaxDocumentBytes,
+                    MaxResolverDocumentBytes = options.Bounds.MaxDocumentBytes
+                };
+                return new WotMaterializationCoordinator(
+                    sp.GetRequiredService<IWotRegistryService>(),
+                    sp.GetRequiredService<IWotProjectionHost>(),
+                    sp.GetRequiredService<IWotBinderRegistry>(),
+                    converterOptions,
+                    // Both seams are optional: a deployment that registers neither gets exactly
+                    // the previous behaviour. Registering an IWotDocumentConverter replaces the
+                    // Thing Description to NodeSet conversion; registering IWotNodeSetContributor
+                    // instances adds nodes (typically controller-specific StructureType DataTypes)
+                    // to the converted NodeSet before it is materialized.
+                    sp.GetService<IWotDocumentConverter>(),
+                    sp.GetServices<IWotNodeSetContributor>(),
+                    sp.GetService<IWotNodeSetResolver>());
+            });
+
+            services.TryAddSingleton(sp =>
+                new WotRegistryNodeManagerFactory(
+                    sp.GetRequiredService<WotRegistryServerOptions>(),
+                    sp.GetRequiredService<IWotRegistryService>(),
+                    sp.GetRequiredService<WotMaterializationCoordinator>()));
+
+            services.AddSingleton(sp =>
+                new OpcUaServerNodeManagerRegistration(
+                    sp.GetRequiredService<WotRegistryNodeManagerFactory>()));
+
+            services.AddOpcUa();
+        }
+    }
+}

src/Opc.Ua.WotCon.Server/Materialization/IWotDocumentConverter.cs

@@ -0,0 +1,180 @@
+/* ========================================================================
+ * Copyright (c) 2005-2026 The OPC Foundation, Inc. All rights reserved.
+ *
+ * OPC Foundation MIT License 1.00
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * The complete license agreement can be found here:
+ * http://opcfoundation.org/License/MIT/1.00/
+ * ======================================================================*/
+
+using System;
+using System.Collections.Immutable;
+using System.Threading;
+using System.Threading.Tasks;
+using Opc.Ua.Export;
+using Opc.Ua.Wot;
+using Opc.Ua.WotCon.Server.Registry;
+
+namespace Opc.Ua.WotCon.Server.Materialization
+{
+    /// <summary>
+    /// The result of converting one registry document to a NodeSet2 model.
+    /// </summary>
+    public sealed class WotConversionOutput
+    {
+        /// <summary>
+        /// Initializes a successful or failed conversion output.
+        /// </summary>
+        public WotConversionOutput(
+            UANodeSet? nodeSet,
+            ImmutableArray<string> errors,
+            ExpandedNodeId rootNodeId = default)
+        {
+            NodeSet = nodeSet;
+            Errors = errors.IsDefault ? [] : errors;
+            RootNodeId = rootNodeId;
+        }
+
+        /// <summary>
+        /// Gets the produced NodeSet2, or <c>null</c> on failure.
+        /// </summary>
+        public UANodeSet? NodeSet { get; }
+
+        /// <summary>
+        /// Gets the conversion error messages.
+        /// </summary>
+        public ImmutableArray<string> Errors { get; }
+
+        /// <summary>
+        /// Gets the root node of the projection (the type a Thing Model
+        /// materializes or the top-level instance a Thing Description projects),
+        /// as an absolute <see cref="ExpandedNodeId"/> whose namespace URI is
+        /// resolved from the produced NodeSet, or <c>ExpandedNodeId.Null</c>
+        /// when the document has no identifiable root.
+        /// </summary>
+        public ExpandedNodeId RootNodeId { get; }
+
+        /// <summary>
+        /// Gets whether the conversion succeeded.
+        /// </summary>
+        public bool Succeeded => NodeSet is not null && Errors.IsEmpty;
+
+        /// <summary>
+        /// Creates a successful output.
+        /// </summary>
+        public static WotConversionOutput Success(UANodeSet nodeSet)
+        {
+            return new WotConversionOutput(
+                        nodeSet,
+                        [],
+                        WotNodeSetConverter.TrySelectProjectionRoot(nodeSet));
+        }
+
+        /// <summary>
+        /// Creates a failed output.
+        /// </summary>
+        public static WotConversionOutput Failure(params string[] errors)
+        {
+            return new WotConversionOutput(null, [.. errors]);
+        }
+    }
+
+    /// <summary>
+    /// Converts a stored registry document to a NodeSet2 model. The default
+    /// implementation delegates to <see cref="WotNodeSetConverter"/> and resolves
+    /// TM references from the registry snapshot; a test double can substitute a
+    /// deterministic conversion.
+    /// </summary>
+    public interface IWotDocumentConverter
+    {
+        /// <summary>
+        /// Converts a resource's default document to a NodeSet2 model.
+        /// </summary>
+        ValueTask<WotConversionOutput> ConvertAsync(
+            WotResource resource,
+            ReadOnlyMemory<byte> content,
+            WotRegistrySnapshot snapshot,
+            CancellationToken cancellationToken);
+    }
+
+    /// <summary>
+    /// The production converter over <see cref="WotNodeSetConverter"/>.
+    /// </summary>
+    public sealed class WotNodeSetDocumentConverter : IWotDocumentConverter
+    {
+        /// <summary>
+        /// Initializes a new converter with the supplied options.
+        /// </summary>
+        public WotNodeSetDocumentConverter(WotNodeSetConverterOptions? options = null)
+        {
+            m_options = options ?? new WotNodeSetConverterOptions();
+        }
+
+        /// <inheritdoc/>
+        public async ValueTask<WotConversionOutput> ConvertAsync(
+            WotResource resource,
+            ReadOnlyMemory<byte> content,
+            WotRegistrySnapshot snapshot,
+            CancellationToken cancellationToken)
+        {
+            try
+            {
+                using var document = WotDocument.Parse(content, m_options);
+                var resolver = new SnapshotThingResolver(snapshot);
+                // One resolution context per top-level conversion, seeded from
+                // the configured converter options, so depth/document/byte
+                // bounds and cycle detection apply across every link resolved
+                // while converting this resource.
+                var resolution = new WotResolutionContext(m_options.ToResolverOptions());
+                WotConversionResult<UANodeSet> result = await WotNodeSetConverter.ToNodeSetResultAsync(
+                    document, m_options, resolver, resolution, cancellationToken).ConfigureAwait(false);
+                ImmutableArray<string>.Builder errors = ImmutableArray.CreateBuilder<string>();
+                foreach (WotDiagnostic diagnostic in result.Diagnostics)
+                {
+                    if (diagnostic.Severity == WotDiagnosticSeverity.Error)
+                    {
+                        errors.Add(diagnostic.ToString());
+                    }
+                }
+                if (result.Value is null && errors.Count == 0)
+                {
+                    errors.Add("The document could not be converted to a NodeSet.");
+                }
+                if (errors.Count != 0 || result.Value is null)
+                {
+                    return new WotConversionOutput(null, errors.ToImmutable());
+                }
+                return new WotConversionOutput(
+                    result.Value,
+                    [],
+                    WotNodeSetConverter.TrySelectProjectionRoot(result.Value));
+            }
+            catch (Exception ex) when (ex is System.Text.Json.JsonException or FormatException)
+            {
+                return WotConversionOutput.Failure(ex.Message);
+            }
+        }
+
+        private readonly WotNodeSetConverterOptions m_options;
+    }
+}