feat: OPC UA address-space search plumbing — actor + comm + BrowseService (T15)

src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/BrowseService.cs

@@ -87,4 +87,59 @@ public sealed class BrowseService : IBrowseService
                 new BrowseFailure(BrowseFailureKind.ServerError, ex.Message));
         }
     }
+
+    /// <inheritdoc/>
+    public async Task<SearchAddressSpaceResult> SearchAsync(
+        string siteId,
+        string connectionName,
+        string query,
+        int maxDepth,
+        int maxResults,
+        CancellationToken cancellationToken = default)
+    {
+        // Same CentralUI-side role guard as BrowseChildrenAsync — sites don't
+        // enforce envelope-level roles, so the Designer check must happen here
+        // before any cross-cluster traffic.
+        var state = await _auth.GetAuthenticationStateAsync();
+        if (!state.User.HasClaim(JwtTokenService.RoleClaimType, Roles.Designer))
+        {
+            return new SearchAddressSpaceResult(
+                Array.Empty<AddressSpaceMatch>(),
+                CapReached: false,
+                new BrowseFailure(BrowseFailureKind.ServerError, "Not authorized."));
+        }
+
+        try
+        {
+            return await _communication.SearchAddressSpaceAsync(
+                siteId,
+                new SearchAddressSpaceCommand(connectionName, query, maxDepth, maxResults),
+                cancellationToken);
+        }
+        catch (TimeoutException ex)
+        {
+            // Akka Ask timed out — the site (or its OPC UA session) didn't answer
+            // within CommunicationOptions.QueryTimeout. Surface as a typed Timeout
+            // failure so the picker can render an inline banner.
+            return new SearchAddressSpaceResult(
+                Array.Empty<AddressSpaceMatch>(),
+                CapReached: false,
+                new BrowseFailure(BrowseFailureKind.Timeout, ex.Message));
+        }
+        catch (OperationCanceledException)
+        {
+            // Caller-initiated cancel — propagate so Blazor can drop the response
+            // cleanly. Distinct from Timeout (which the picker renders inline).
+            throw;
+        }
+        catch (Exception ex)
+        {
+            // Any other transport / serialization failure: keep the picker alive
+            // and let the user fall back to manual browse / node-id paste.
+            return new SearchAddressSpaceResult(
+                Array.Empty<AddressSpaceMatch>(),
+                CapReached: false,
+                new BrowseFailure(BrowseFailureKind.ServerError, ex.Message));
+        }
+    }
 }

src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/IBrowseService.cs

@@ -37,4 +37,31 @@ public interface IBrowseService
         string? parentNodeId,
         string? continuationToken = null,
         CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Runs a bounded recursive search of the address space on the live server
+    /// backing <paramref name="connectionName"/> at <paramref name="siteId"/>,
+    /// returning the nodes whose DisplayName or root-relative path contains
+    /// <paramref name="query"/>. The address-space analogue of
+    /// <see cref="BrowseChildrenAsync"/>: it forwards a
+    /// <see cref="SearchAddressSpaceCommand"/> to the owning site via
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/> and
+    /// enforces the same <c>Design</c>-role trust boundary at central. The depth
+    /// and result caps are supplied by the caller (the picker's search box) and
+    /// chosen to stay well under Akka's remote frame size.
+    /// </summary>
+    /// <param name="siteId">The target site identifier.</param>
+    /// <param name="connectionName">Name of the site-local data connection to search against.</param>
+    /// <param name="query">Case-insensitive substring matched against each node's DisplayName and root-relative path.</param>
+    /// <param name="maxDepth">Maximum number of levels below the root to descend.</param>
+    /// <param name="maxResults">Maximum number of matches to return; when reached the walk stops early and the result's <c>CapReached</c> flag is set.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to a <see cref="SearchAddressSpaceResult"/> containing the matches or a <see cref="BrowseFailure"/> on error.</returns>
+    Task<SearchAddressSpaceResult> SearchAsync(
+        string siteId,
+        string connectionName,
+        string query,
+        int maxDepth,
+        int maxResults,
+        CancellationToken cancellationToken = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/BrowseCommands.cs

@@ -40,6 +40,39 @@ public record BrowseNodeResult(
     BrowseFailure? Failure,
     string? ContinuationToken = null);
 
+/// <summary>
+/// Sent from CentralUI to a specific site to run a bounded recursive search of
+/// the address space on the live server backing the given data connection.
+/// </summary>
+/// <remarks>
+/// The address-space analogue of <see cref="BrowseNodeCommand"/>: where browse
+/// walks one level at a time on user demand, search walks the tree itself
+/// (bounded by depth + result caps) and returns the nodes whose DisplayName or
+/// root-relative path contains <see cref="Query"/>. Keyed by
+/// <see cref="ConnectionName"/> for the same reason as browse — the site-side
+/// <c>DataConnectionManagerActor</c> indexes its children by connection name and
+/// the central <c>DataConnections</c> id is intentionally not exposed at the
+/// site. Routed over the same cross-cluster path as browse and resolved by the
+/// owning connection's <c>IAddressSpaceSearchable</c> adapter.
+/// </remarks>
+/// <param name="ConnectionName">Name of the site-local data connection to search against.</param>
+/// <param name="Query">Case-insensitive substring matched against each node's DisplayName and root-relative path.</param>
+/// <param name="MaxDepth">Maximum number of levels below the root to descend. Must be non-negative.</param>
+/// <param name="MaxResults">Maximum number of matches to return; when reached the walk stops early and <see cref="SearchAddressSpaceResult.CapReached"/> is set.</param>
+public record SearchAddressSpaceCommand(
+    string ConnectionName,
+    string Query,
+    int MaxDepth,
+    int MaxResults);
+
+/// <param name="Matches">The matched address-space nodes, in breadth-first discovery order (capped at <see cref="SearchAddressSpaceCommand.MaxResults"/>).</param>
+/// <param name="CapReached">True when a bound (result cap or the adapter's node-visit ceiling) cut the walk short, so more matches may exist than were returned.</param>
+/// <param name="Failure">Structured failure, or null on success. Reuses the browse <see cref="BrowseFailure"/> kinds (the search path mirrors browse exactly).</param>
+public record SearchAddressSpaceResult(
+    IReadOnlyList<AddressSpaceMatch> Matches,
+    bool CapReached,
+    BrowseFailure? Failure);
+
 public record BrowseFailure(
     BrowseFailureKind Kind,
     string Message);

src/ZB.MOM.WW.ScadaBridge.Communication/CommunicationService.cs

@@ -371,6 +371,28 @@ public class CommunicationService
             envelope, _options.QueryTimeout, cancellationToken);
     }
 
+    /// <summary>
+    /// Asks a site to run a bounded recursive search of the address space on the
+    /// live server backing the given data connection. The address-space analogue
+    /// of <see cref="BrowseNodeAsync"/> — used by the CentralUI OPC UA tag picker's
+    /// "find a tag" box. The Ask is bounded by <see cref="CommunicationOptions.QueryTimeout"/>,
+    /// the same latency budget as browse and the other interactive design-time
+    /// queries.
+    /// </summary>
+    /// <param name="siteId">The target site identifier.</param>
+    /// <param name="command">The address-space search command (connection name + query + depth/result caps).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The search result (matches + cap-reached flag + structured failure).</returns>
+    public Task<SearchAddressSpaceResult> SearchAddressSpaceAsync(
+        string siteId,
+        SearchAddressSpaceCommand command,
+        CancellationToken cancellationToken = default)
+    {
+        var envelope = new SiteEnvelope(siteId, command);
+        return GetActor().Ask<SearchAddressSpaceResult>(
+            envelope, _options.QueryTimeout, cancellationToken);
+    }
+
     // ── Test Bindings (one-shot live read of bound tags) ──
 
     /// <summary>

src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Actors/DataConnectionActor.cs

@@ -269,6 +269,12 @@ public class DataConnectionActor : UntypedActor, IWithStash, IWithTimers
                 // an inline banner.
                 HandleBrowse(browse);
                 break;
+            case SearchAddressSpaceCommand search:
+                // Search is the address-space analogue of browse — same rule:
+                // never stash; the adapter has no session yet here, so
+                // HandleSearch short-circuits to ConnectionNotConnected.
+                HandleSearch(search);
+                break;
             case ReadTagValuesCommand read:
                 // Same rule as browse — never stash; adapter is not yet
                 // connected, so HandleReadTagValues short-circuits to
@@ -353,6 +359,9 @@ public class DataConnectionActor : UntypedActor, IWithStash, IWithTimers
             case BrowseNodeCommand browse:
                 HandleBrowse(browse);
                 break;
+            case SearchAddressSpaceCommand search:
+                HandleSearch(search);
+                break;
             case ReadTagValuesCommand read:
                 HandleReadTagValues(read);
                 break;
@@ -497,6 +506,12 @@ public class DataConnectionActor : UntypedActor, IWithStash, IWithTimers
                 // throw ConnectionNotConnectedException — mapped by HandleBrowse.
                 HandleBrowse(browse);
                 break;
+            case SearchAddressSpaceCommand search:
+                // Same rule as browse — never stashed; while reconnecting the
+                // adapter is not Connected so the adapter call throws
+                // ConnectionNotConnectedException, mapped by HandleSearch.
+                HandleSearch(search);
+                break;
             case ReadTagValuesCommand read:
                 // Same rule as browse — never stashed; while reconnecting the
                 // adapter is not Connected so HandleReadTagValues short-circuits
@@ -1203,6 +1218,83 @@ public class DataConnectionActor : UntypedActor, IWithStash, IWithTimers
         }).PipeTo(sender);
     }
 
+    /// <summary>
+    /// Handles a <see cref="SearchAddressSpaceCommand"/> forwarded by the
+    /// <see cref="DataConnectionManagerActor"/> — the address-space analogue of
+    /// <see cref="HandleBrowse"/>. The capability check (does this adapter support
+    /// search?) and all failure mapping live here because the adapter is held by
+    /// this actor, not the manager. The search path reuses the browse
+    /// <see cref="BrowseFailure"/> kinds rather than inventing a parallel set.
+    ///
+    /// Failure mapping:
+    /// <list type="bullet">
+    ///   <item><see cref="BrowseFailureKind.NotBrowsable"/> — adapter is not <see cref="IAddressSpaceSearchable"/>, or it threw <see cref="NotSupportedException"/> (searchable adapter, but the server/protocol cannot search); message carried verbatim in the latter case.</item>
+    ///   <item><see cref="BrowseFailureKind.ConnectionNotConnected"/> — adapter threw <see cref="ConnectionNotConnectedException"/>.</item>
+    ///   <item><see cref="BrowseFailureKind.Timeout"/> — adapter threw <see cref="OperationCanceledException"/>.</item>
+    ///   <item><see cref="BrowseFailureKind.ServerError"/> — any other exception, message carried verbatim.</item>
+    /// </list>
+    ///
+    /// The adapter already caps the match list at <c>MaxResults</c>, so unlike
+    /// <see cref="HandleBrowse"/> there is no frame-budget clip here — the bound is
+    /// supplied by the caller (B6) and chosen to stay well under Akka's remote
+    /// frame size. The reply is sent via <c>PipeTo(sender)</c>, the same pattern
+    /// used by <see cref="HandleBrowse"/>.
+    /// </summary>
+    private void HandleSearch(SearchAddressSpaceCommand command)
+    {
+        var sender = Sender;
+
+        if (_adapter is not IAddressSpaceSearchable searchable)
+        {
+            _log.Debug("[{0}] Search requested but adapter does not implement IAddressSpaceSearchable", _connectionName);
+            sender.Tell(new SearchAddressSpaceResult(
+                Array.Empty<AddressSpaceMatch>(),
+                CapReached: false,
+                new BrowseFailure(
+                    BrowseFailureKind.NotBrowsable,
+                    $"Connection '{_connectionName}' does not support search.")));
+            return;
+        }
+
+        _log.Debug("[{0}] Searching address space for '{1}' (maxDepth={2}, maxResults={3})",
+            _connectionName, command.Query, command.MaxDepth, command.MaxResults);
+
+        searchable.SearchAddressSpaceAsync(command.Query, command.MaxDepth, command.MaxResults).ContinueWith(t =>
+        {
+            if (t.IsCompletedSuccessfully)
+            {
+                // The adapter already bounded the walk by MaxResults — pass the
+                // matches and the cap flag straight through.
+                return new SearchAddressSpaceResult(t.Result.Matches, t.Result.CapReached, Failure: null);
+            }
+
+            var baseEx = t.Exception?.GetBaseException();
+            return baseEx switch
+            {
+                ConnectionNotConnectedException notConnected => new SearchAddressSpaceResult(
+                    Array.Empty<AddressSpaceMatch>(),
+                    CapReached: false,
+                    new BrowseFailure(BrowseFailureKind.ConnectionNotConnected, notConnected.Message)),
+                OperationCanceledException => new SearchAddressSpaceResult(
+                    Array.Empty<AddressSpaceMatch>(),
+                    CapReached: false,
+                    new BrowseFailure(BrowseFailureKind.Timeout, "Search cancelled.")),
+                // Adapter reachable but the protocol/server cannot search. Carry
+                // the adapter's explanatory message through as NotBrowsable.
+                NotSupportedException notSupported => new SearchAddressSpaceResult(
+                    Array.Empty<AddressSpaceMatch>(),
+                    CapReached: false,
+                    new BrowseFailure(BrowseFailureKind.NotBrowsable, notSupported.Message)),
+                _ => new SearchAddressSpaceResult(
+                    Array.Empty<AddressSpaceMatch>(),
+                    CapReached: false,
+                    new BrowseFailure(
+                        BrowseFailureKind.ServerError,
+                        baseEx?.Message ?? "Unknown search error.")),
+            };
+        }).PipeTo(sender);
+    }
+
     /// <summary>
     /// Estimated-byte ceiling for a single <see cref="BrowseNodeResult"/>, kept
     /// comfortably below Akka's default 128 KB remote frame size. A browse reply

src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Actors/DataConnectionManagerActor.cs

@@ -50,6 +50,7 @@ public class DataConnectionManagerActor : ReceiveActor
         Receive<RemoveConnectionCommand>(HandleRemoveConnection);
         Receive<GetAllHealthReports>(HandleGetAllHealthReports);
         Receive<BrowseNodeCommand>(HandleBrowse);
+        Receive<SearchAddressSpaceCommand>(HandleSearch);
         Receive<ReadTagValuesCommand>(HandleReadTagValues);
     }
 
@@ -189,6 +190,32 @@ public class DataConnectionManagerActor : ReceiveActor
         }
     }
 
+    /// <summary>
+    /// Routes a <see cref="SearchAddressSpaceCommand"/> from the central UI's OPC
+    /// UA tag picker to the child <see cref="DataConnectionActor"/> that owns the
+    /// named connection — the address-space analogue of <see cref="HandleBrowse"/>.
+    /// Same split: the manager owns <see cref="BrowseFailureKind.ConnectionNotFound"/>
+    /// (only it knows the per-site connection set); the capability check and every
+    /// other failure live inside the child where the adapter is held.
+    /// </summary>
+    private void HandleSearch(SearchAddressSpaceCommand command)
+    {
+        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
+        {
+            actor.Forward(command);
+        }
+        else
+        {
+            _log.Warning("No connection actor for {0} during search", command.ConnectionName);
+            Sender.Tell(new SearchAddressSpaceResult(
+                Array.Empty<AddressSpaceMatch>(),
+                CapReached: false,
+                new BrowseFailure(
+                    BrowseFailureKind.ConnectionNotFound,
+                    $"No data connection named '{command.ConnectionName}' at this site.")));
+        }
+    }
+
     /// <summary>
     /// Routes a <see cref="ReadTagValuesCommand"/> from the CentralUI's Test
     /// Bindings dialog to the child <see cref="DataConnectionActor"/> that