gRPC M0 R0.2: tag metadata over gRPC (GetTagInfosFromName, live-verified)

Routes HistorianClient.GetTagMetadataAsync over gRPC when Transport==RemoteGrpc,
via the new Grpc/HistorianGrpcTagClient calling RetrievalService.GetTagInfosFromName
(the plural string-handle metadata op).

- String handle = the Open2 storage-session GUID formatted uppercase (the format
  that resolves the native string-handle path); threaded out of the shared handshake
  via a new HistorianGrpcHandshake.Session { ClientHandle, StorageSessionId, StringHandle }.
- Request btTagNames = uint count + per-name(uint charCount + UTF-16LE) — golden-byte
  unit-tested (BuildTagNamesBuffer).
- Response btTagInfos = uint count + CTagMetadata records — decoded by the existing
  HistorianTagQueryProtocol.ParseGetTagInfoResponse; data type via the shared MapDataType.

The 2020 WCF string-handle wall does NOT apply on the gRPC front door, as the
string-handle-wall RE note predicted. LIVE-VERIFIED against a real 2023 R2 server:
GetTagMetadataAsync returns the requested tag with a valid decoded data type.

216 unit tests pass. Captured framing confirmed live then discarded; no tag names
or identities committed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC

src/AVEVA.Historian.Client/Grpc/HistorianGrpcHandshake.cs

@@ -20,10 +20,30 @@ namespace AVEVA.Historian.Client.Grpc;
 /// </summary>
 internal static class HistorianGrpcHandshake
 {
+    /// <summary>
+    /// The handles produced by a successful OpenConnection. <see cref="ClientHandle"/> is the
+    /// transient <c>uint</c> session token used by StartQuery/GetSystemParameter and the other
+    /// uint-handle ops. <see cref="StorageSessionId"/> is the storage-session GUID used (formatted
+    /// uppercase via <see cref="StringHandle"/>) by the string-handle ops
+    /// (GetTagInfosFromName, GetTagExtendedPropertiesFromName, ExecuteSqlCommand, ...).
+    /// </summary>
+    internal readonly record struct Session(uint ClientHandle, Guid StorageSessionId)
+    {
+        /// <summary>The storage GUID in the uppercase "D" form the native string-handle ops require.</summary>
+        public string StringHandle => StorageSessionId.ToString("D").ToUpperInvariant();
+    }
+
+    /// <summary>Convenience overload for callers that only need the uint client handle.</summary>
     public static uint OpenAuthenticatedConnection(
         HistorianGrpcConnection connection,
         HistorianClientOptions options,
         CancellationToken cancellationToken)
+        => OpenSession(connection, options, cancellationToken).ClientHandle;
+
+    public static Session OpenSession(
+        HistorianGrpcConnection connection,
+        HistorianClientOptions options,
+        CancellationToken cancellationToken)
     {
         DateTime Deadline() => DateTime.UtcNow.Add(options.RequestTimeout);
 
@@ -68,7 +88,7 @@ internal static class HistorianGrpcHandshake
             throw new InvalidOperationException($"gRPC OpenConnection failed (errorLen={err.Length}, responseLen={open2Response.Length}).");
         }
 
-        (uint clientHandle, _) = HistorianNativeHandshake.ParseOpenConnectionResponse(open2Response);
-        return clientHandle;
+        (uint clientHandle, Guid storageSessionId) = HistorianNativeHandshake.ParseOpenConnectionResponse(open2Response);
+        return new Session(clientHandle, storageSessionId);
     }
 }

src/AVEVA.Historian.Client/Grpc/HistorianGrpcTagClient.cs

@@ -0,0 +1,110 @@
+using System.Text;
+using Google.Protobuf;
+using Grpc.Core;
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf;
+using GrpcRetrieval = ArchestrA.Grpc.Contract.Retrieval;
+
+namespace AVEVA.Historian.Client.Grpc;
+
+/// <summary>
+/// 2023 R2 gRPC tag-metadata client (roadmap item R0.2). Unlike the WCF singular
+/// <c>GetTagInfoFromName</c> (a <c>uint</c>-handle op), the gRPC front door exposes the plural
+/// <c>RetrievalService.GetTagInfosFromName</c> — a <b>string-handle</b> op keyed off the Open2
+/// storage-session GUID (uppercase). The request <c>btTagNames</c> buffer and response
+/// <c>btTagInfos</c> buffer carry the proven native encodings:
+/// <list type="bullet">
+///   <item>request <c>btTagNames</c> = <c>uint count</c> + per-name(<c>uint charCount</c> + UTF-16LE)</item>
+///   <item>response <c>btTagInfos</c> = <c>uint tagCount</c> + per-tag CTagMetadata record
+///   (the same record <see cref="HistorianTagQueryProtocol.ParseGetTagInfoResponse"/> decodes)</item>
+/// </list>
+/// The string-handle "wall" that blocks this op family on the 2020 WCF transport does not apply on
+/// the gRPC front door (different envelope/registration) — see
+/// <c>docs/reverse-engineering/wcf-string-handle-wall.md</c>.
+/// </summary>
+internal static class HistorianGrpcTagClient
+{
+    public static Task<HistorianTagMetadata?> GetTagMetadataAsync(
+        HistorianClientOptions options,
+        string tag,
+        CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
+        return Task.Run(() => GetTagMetadata(options, tag, cancellationToken), cancellationToken);
+    }
+
+    private static HistorianTagMetadata? GetTagMetadata(HistorianClientOptions options, string tag, CancellationToken cancellationToken)
+    {
+        byte[] tagInfos = GetTagInfosRaw(options, [tag], cancellationToken);
+        if (tagInfos.Length < 4)
+        {
+            return null;
+        }
+
+        IReadOnlyList<HistorianTagInfoResponse> parsed = HistorianTagQueryProtocol.ParseGetTagInfoResponse(tagInfos);
+        if (parsed.Count == 0)
+        {
+            return null;
+        }
+
+        HistorianTagInfoResponse info = parsed[0];
+        return new HistorianTagMetadata(
+            Name: info.TagName,
+            Key: info.TagKey,
+            DataType: HistorianWcfTagClient.MapDataType(info.NativeDataTypeDescriptor),
+            Description: info.Description ?? info.MetadataProvider,
+            EngineeringUnit: info.EngineeringUnit ?? string.Empty,
+            MinRaw: info.MinEU,
+            MaxRaw: info.MaxEU);
+    }
+
+    /// <summary>
+    /// Issues a single <c>GetTagInfosFromName</c> call and returns the raw native <c>btTagInfos</c>
+    /// response buffer. Internal so reverse-engineering probes can capture the framing.
+    /// </summary>
+    internal static byte[] GetTagInfosRaw(HistorianClientOptions options, IReadOnlyList<string> tags, CancellationToken cancellationToken)
+    {
+        using HistorianGrpcConnection connection = HistorianGrpcChannelFactory.Create(options);
+        HistorianGrpcHandshake.Session session = HistorianGrpcHandshake.OpenSession(connection, options, cancellationToken);
+
+        var retrievalClient = new GrpcRetrieval.RetrievalService.RetrievalServiceClient(connection.Channel);
+        byte[] requestBuffer = BuildTagNamesBuffer(tags);
+        GrpcRetrieval.GetTagInfosFromNameResponse response = retrievalClient.GetTagInfosFromName(
+            new GrpcRetrieval.GetTagInfosFromNameRequest
+            {
+                StrHandle = session.StringHandle,
+                BtTagNames = ByteString.CopyFrom(requestBuffer),
+                UiSequence = 0
+            },
+            connection.Metadata,
+            DateTime.UtcNow.Add(options.RequestTimeout),
+            cancellationToken);
+
+        if (!(response.Status?.BSuccess ?? false))
+        {
+            byte[] error = response.Status?.BtError?.ToByteArray() ?? [];
+            throw new InvalidOperationException($"gRPC GetTagInfosFromName failed (errorLen={error.Length}).");
+        }
+
+        return response.BtTagInfos?.ToByteArray() ?? [];
+    }
+
+    /// <summary>Builds the native tag-names request buffer: uint count + per-name(uint charCount + UTF-16LE).</summary>
+    internal static byte[] BuildTagNamesBuffer(IReadOnlyList<string> tags)
+    {
+        using MemoryStream stream = new();
+        using BinaryWriter writer = new(stream, Encoding.Unicode, leaveOpen: true);
+
+        writer.Write((uint)tags.Count);
+        foreach (string tag in tags)
+        {
+            writer.Write((uint)tag.Length);
+            if (tag.Length > 0)
+            {
+                writer.Write(Encoding.Unicode.GetBytes(tag));
+            }
+        }
+
+        return stream.ToArray();
+    }
+}

src/AVEVA.Historian.Client/HistorianClient.cs

@@ -104,7 +104,9 @@ public sealed class HistorianClient : IAsyncDisposable
     public Task<HistorianTagMetadata?> GetTagMetadataAsync(string tag, CancellationToken cancellationToken = default)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(tag);
-        return HistorianWcfTagClient.GetTagMetadataAsync(_options, tag, cancellationToken);
+        return _options.Transport == HistorianTransport.RemoteGrpc
+            ? Grpc.HistorianGrpcTagClient.GetTagMetadataAsync(_options, tag, cancellationToken)
+            : HistorianWcfTagClient.GetTagMetadataAsync(_options, tag, cancellationToken);
     }
 
     public Task<HistorianConnectionStatus> GetConnectionStatusAsync(CancellationToken cancellationToken = default)