[Client] Central channel manager: ref-counted shared channels, coalesced reconnect, IRetryBudget (#3288)

Applications/ConsoleReferenceClient/ConnectTester.cs

@@ -27,6 +27,9 @@
  * http://opcfoundation.org/License/MIT/1.00/
  * ======================================================================*/
 
+// CS0618: legacy SessionReconnectHandler retained for back-compat demo
+#pragma warning disable CS0618
+
 using System;
 using System.Collections.Generic;
 using System.IO;

Applications/ConsoleReferenceClient/UAClient.cs

@@ -27,8 +27,11 @@
  * http://opcfoundation.org/License/MIT/1.00/
  * ======================================================================*/
 
+// CS0618: this sample retains SessionReconnectHandler for back-compat
+// demonstration; new code should use ManagedSession with channel manager.
+#pragma warning disable CS0618
+
 using System;
-using System.Collections;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
@@ -50,7 +53,7 @@
         public UAClient(
             ApplicationConfiguration configuration,
             ITelemetryContext telemetry,
             Action<IList, IList>? validateResponse)
             : this(
                 configuration,
                 null,
@@ -66,7 +69,7 @@
             ApplicationConfiguration configuration,
             ReverseConnectManager? reverseConnectManager,
             ITelemetryContext telemetry,
             Action<IList, IList>? validateResponse)
         {
             ValidateResponse = validateResponse;
             m_logger = telemetry.CreateLogger<UAClient>();
@@ -107,7 +110,7 @@
         /// <summary>
         /// Action used
         /// </summary>
         internal Action<IList, IList>? ValidateResponse { get; }
 
         /// <summary>
         /// Gets the client session.
@@ -356,7 +359,9 @@
                     {
                         // detach the channel, so it doesn't get
                         // closed when the session is disposed.
+#pragma warning disable CS0618 // sample legacy path
                         Session.DetachChannel();
+#pragma warning restore CS0618
                     }
                     Session.Dispose();
                     // Transiently null after dispose; matches pre-NRT behavior.
@@ -514,7 +519,7 @@
         private readonly Lock m_lock = new();
         private readonly ReverseConnectManager? m_reverseConnectManager;
         private readonly ApplicationConfiguration m_configuration;
         private SessionReconnectHandler? m_reconnectHandler;
         private readonly ILogger m_logger;
         private readonly ITelemetryContext m_telemetry;
         private bool m_disposed;

Applications/McpServer/OpcUaSessionManager.cs

@@ -27,6 +27,11 @@
  * http://opcfoundation.org/License/MIT/1.00/
  * ======================================================================*/
 
+// CS0618: legacy SessionReconnectHandler is intentionally retained in this
+// sample for now; replacing it with ManagedSession / channel manager is a
+// follow-up. Suppress at file scope.
+#pragma warning disable CS0618
+
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;

Directory.Packages.props

@@ -29,6 +29,8 @@
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.Diagnostics" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Http" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.6.0" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.8" />

Docs/DependencyInjection.md

@@ -557,6 +557,39 @@ when the server initiates the session. The
 `ReverseConnect` configuration is also consumed by `Session` /
 `SessionReconnectHandler` for reconnect-via-reverse-hello scenarios.
 
+## Channel manager
+
+`AddClient(...)` automatically registers an `IClientChannelManager`
+singleton (`ClientChannelManager` implementation) built from
+`OpcUaClientOptions.Configuration`. The
+`Func<CancellationToken, Task<ManagedSession>>` delegate wires this
+manager into every new `ManagedSession` it creates, so multiple
+`ManagedSession` instances resolved from the same DI container will
+share underlying transport channels per
+`ConfiguredEndpoint`. Reconnect is coalesced and notified to attached
+sessions transparently. On .NET 8 and later, HTTPS transport channels
+also get the named `IHttpClientFactory` client (`Opc.Ua.Client`) and its
+standard resilience handler through `AddClient(...)`. See
+[Sessions and reconnect § 4](Sessions.md#4-iclientchannelmanager--centralised-channel-sharing-and-reconnect)
+for details on identity, retry policy, HTTPS request resilience, and the
+shared retry budget between channel-manager reconnect and
+`ManagedSession`'s outer `IReconnectPolicy`.
+
+To override the default channel manager (e.g. to inject a custom
+`IChannelReconnectPolicy`):
+
+```csharp
+services.AddOpcUa().AddClient(opt => { ... });
+services.Replace(ServiceDescriptor.Singleton<IClientChannelManager>(sp =>
+    new ClientChannelManager(
+        sp.GetRequiredService<OpcUaClientOptions>().Configuration!,
+        sp.GetRequiredService<ITelemetryContext>(),
+        reconnectPolicy: new ExponentialBackoffChannelReconnectPolicy
+        {
+            MaxAttempts = 5
+        })));
+```
+
 ## Application instance (advanced)
 
 ```csharp

Docs/MigrationGuide.md

@@ -1386,10 +1386,65 @@ Version 2.0 introduces `ManagedSession`, a wrapper around `Session` that automat
 
 - **`ManagedSessionFactory`** is a **new** factory that creates `ManagedSession` instances which handle reconnection and failover automatically. Use this when you want managed-session behavior.
 - **`DefaultSessionFactory`** is **unchanged** — it continues to create raw `Session` instances. Existing code that constructs `DefaultSessionFactory` directly keeps the same behavior in 2.0.
-- **`SessionReconnectHandler`** is **retained** as a supported legacy entry point for callers that already manage raw `Session` instances. The type itself is not removed. Its parameterless legacy constructor remains marked `[Obsolete("Use SessionReconnectHandler(ITelemetryContext, bool, int) instead.")]` in 2.0 (the same attribute was already present in 1.5.378); pass an `ITelemetryContext` to the new ctor when adopting it. It now also requires the wrapped `ISession` to be a `Session` (or a derived type) — passing a `ManagedSession` (or any other `ISession` facade) throws `NotSupportedException`, since those facades drive their own reconnect / failover state machine. New code should still prefer `ManagedSessionFactory` / `ManagedSession.CreateAsync`.
+- **`SessionReconnectHandler`** is now marked **`[Obsolete]`** as of issue [#3288](https://github.com/OPCFoundation/UA-.NETStandard/issues/3288). It remains functional for back-compat with existing callers that own raw `Session` instances. The type itself is not removed. Its parameterless legacy constructor remains marked `[Obsolete("Use SessionReconnectHandler(ITelemetryContext, bool, int) instead.")]`; pass an `ITelemetryContext` to the new ctor when adopting it. It now also requires the wrapped `ISession` to be a `Session` (or a derived type) — passing a `ManagedSession` (or any other `ISession` facade) throws `NotSupportedException`. New code should use `ManagedSessionFactory` / `ManagedSession.CreateAsync` (which transparently uses the new `IClientChannelManager` if registered), or wire `IClientChannelManager` into a raw `Session` via `Session.CreateAsync(IClientChannelManager, ...)`.
+
+- **`IClientBase.AttachChannel(ITransportChannel)` and `DetachChannel()`** are now marked **`[Obsolete]`** as of issue [#3288](https://github.com/OPCFoundation/UA-.NETStandard/issues/3288). They remain functional. New code should use `IClientChannelManager` so transport channels are reference-counted, shared across participants on the same endpoint, and reconnected transparently. See [Sessions and reconnect](Sessions.md#4-iclientchannelmanager--centralised-channel-sharing-and-reconnect).
+
+- **`Session.ReconnectAsync(ITransportWaitingConnection, ITransportChannel, CancellationToken)`** is the underlying instance method; it is *not* marked obsolete. The two convenience extension overloads `ReconnectAsync(connection, ct)` and `ReconnectAsync(channel, ct)` (in `SessionExtensions`) **are** now `[Obsolete]` because they bypass the central channel manager. The simple `ReconnectAsync(ct)` extension is unchanged and routes through the channel manager automatically when one is wired.
 
 For a deeper architectural picture of how `Session`, `ManagedSession`, `SessionReconnectHandler`, and the subscription engines fit together, see [Sessions, Reconnection, and Subscription Engines](Sessions.md).
 
+#### Shared reconnect budget for ManagedSession and the channel manager
+
+`ManagedSession` and `IClientChannelManager` now share one retry deadline for a reconnect cycle instead of
+stacking independent session-level and channel-level budgets. See
+[Sessions and reconnect § 4](Sessions.md#shared-retry-budget-with-managedsession) for the runtime sequence and a
+worked example.
+
+- **`IRetryBudget` and `RetryBudget`** are new core types. `RetryBudget` is a thread-safe implementation backed by
+  `TimeProvider`; it starts timing on the first consumed attempt, reports the remaining time via `TryConsume`, and
+  resets after a successful reconnect so the next reconnect cycle receives a fresh budget.
+- **`IClientChannelManager.ReconnectAsync(channel, IRetryBudget, ct)`** lets the outer `ManagedSession` retry driver
+  pass its deadline into the channel manager. The existing two-argument `ReconnectAsync(channel, ct)` overload still
+  works and uses an unlimited budget for back-compat. On TFMs where the interface does not expose the new overload,
+  the built-in `ClientChannelManager` still accepts it directly; custom managers fall back to the legacy overload.
+- **`IChannelReconnectPolicy.GetDelay(int, IRetryBudget?)`** is available as a default interface method on the TFMs
+  where the stack exposes it. The default delegates to the existing `GetDelay(int)` and clamps the result to the
+  remaining budget. On `net48`, custom policies that need custom budget-aware behavior should implement
+  `IBudgetAwareChannelReconnectPolicy`; otherwise the manager calls the legacy method and applies the same budget
+  clamp around it.
+
+To opt in, set `ReconnectPolicyOptions.MaxTotalReconnectTime` to the end-to-end reconnect window. The default is five
+minutes.
+
+```csharp
+ManagedSession session = await new ManagedSessionBuilder(configuration, telemetry)
+    .UseEndpoint(endpoint)
+    .WithReconnectPolicy(p => p with
+    {
+        MaxTotalReconnectTime = TimeSpan.FromSeconds(30)
+    })
+    .ConnectAsync(ct);
+```
+
+For DI configuration, set the same option on `ManagedSessionOptions.ReconnectPolicy`:
+
+```csharp
+services.AddOpcUa()
+    .AddClient(opt =>
+    {
+        opt.Configuration = config;
+        opt.Session = opt.Session with
+        {
+            Endpoint = endpoint,
+            ReconnectPolicy = opt.Session.ReconnectPolicy with
+            {
+                MaxTotalReconnectTime = TimeSpan.FromSeconds(30)
+            }
+        };
+    });
+```
+
 **Migration**:
 
 **If you use `DefaultSessionFactory`:**
@@ -1459,7 +1514,8 @@ var policy = new ReconnectPolicy
     InitialDelay = TimeSpan.FromSeconds(1),
     MaxDelay = TimeSpan.FromSeconds(30),
     MaxRetries = 0,         // 0 = unlimited
-    JitterFactor = 0.1      // ±10% jitter
+    JitterFactor = 0.1,     // ±10% jitter
+    MaxTotalReconnectTime = TimeSpan.FromMinutes(5)
 };
 ```