mark INodeSessionCallback obsolete

Author: smdn

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.DependencyInjection/MuninNodeBuilder.cs

@@ -23,7 +23,7 @@ public class MuninNodeBuilder : IMuninNodeBuilder {
 #pragma warning restore CS0618
   private readonly List<Func<IServiceProvider, IPlugin>> pluginFactories = new(capacity: 4);
   private Func<IServiceProvider, IPluginProvider>? buildPluginProvider;
-  private Func<IServiceProvider, INodeSessionCallback>? buildSessionCallback;
+  [Obsolete] private Func<IServiceProvider, INodeSessionCallback>? buildSessionCallback;
   private Func<IServiceProvider, IMuninNodeListenerFactory>? buildListenerFactory;
 
   /// <summary>
@@ -64,6 +64,7 @@ Func<IServiceProvider, IPluginProvider> buildPluginProvider
     this.buildPluginProvider = buildPluginProvider;
   }
 
+  [Obsolete]
   internal void SetSessionCallbackFactory(
     Func<IServiceProvider, INodeSessionCallback> buildSessionCallback
   )
@@ -100,7 +101,9 @@ public IMuninNode Build(IServiceProvider serviceProvider)
       pluginProvider: buildPluginProvider is null
         ? new PluginProvider(
             plugins: pluginFactories.Select(factory => factory(serviceProvider)).ToList(),
+#pragma warning disable CS0612
             sessionCallback: buildSessionCallback?.Invoke(serviceProvider)
+#pragma warning restore CS0612
           )
         : buildPluginProvider.Invoke(serviceProvider),
       listenerFactory: buildListenerFactory?.Invoke(serviceProvider),
@@ -110,15 +113,22 @@ public IMuninNode Build(IServiceProvider serviceProvider)
 
   private sealed class PluginProvider : IPluginProvider {
     public IReadOnlyCollection<IPlugin> Plugins { get; }
+
+    [Obsolete]
     public INodeSessionCallback? SessionCallback { get; }
 
     public PluginProvider(
       IReadOnlyCollection<IPlugin> plugins,
+#pragma warning disable CS0618
       INodeSessionCallback? sessionCallback
+#pragma warning restore CS0618
     )
     {
       Plugins = plugins ?? throw new ArgumentNullException(nameof(plugins));
+
+#pragma warning disable CS0612
       SessionCallback = sessionCallback;
+#pragma warning restore CS0612
     }
   }
 

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.DependencyInjection/MuninNodeBuilderExtensions.cs

@@ -106,7 +106,9 @@ Func<IServiceProvider, IPluginProvider> buildPluginProvider
   /// </remarks>
   public static TMuninNodeBuilder UseSessionCallback<TMuninNodeBuilder>(
     this TMuninNodeBuilder builder,
+#pragma warning disable CS0618
     INodeSessionCallback sessionCallback
+#pragma warning restore CS0618
   )
     where TMuninNodeBuilder : MuninNodeBuilder
 #pragma warning restore CS0419
@@ -135,12 +137,15 @@ public static TMuninNodeBuilder UseSessionCallback<TMuninNodeBuilder>(
 #pragma warning restore CS0419
     => UseSessionCallback(
       builder: builder,
+#pragma warning disable CS0612
       buildSessionCallback: _ => new SessionCallbackFuncWrapper(
         reportSessionStartedAsyncFunc,
         reportSessionClosedAsyncFunc
       )
+#pragma warning restore CS0612
     );
 
+  [Obsolete]
   private sealed class SessionCallbackFuncWrapper(
     Func<string, CancellationToken, ValueTask>? reportSessionStartedAsyncFunc,
     Func<string, CancellationToken, ValueTask>? reportSessionClosedAsyncFunc
@@ -162,7 +167,9 @@ public ValueTask ReportSessionClosedAsync(string sessionId, CancellationToken ca
   /// </remarks>
   public static TMuninNodeBuilder UseSessionCallback<TMuninNodeBuilder>(
     this TMuninNodeBuilder builder,
+#pragma warning disable CS0618
     Func<IServiceProvider, INodeSessionCallback> buildSessionCallback
+#pragma warning restore CS0618
   )
     where TMuninNodeBuilder : MuninNodeBuilder
 #pragma warning restore CS0419
@@ -172,7 +179,9 @@ Func<IServiceProvider, INodeSessionCallback> buildSessionCallback
     if (buildSessionCallback is null)
       throw new ArgumentNullException(nameof(buildSessionCallback));
 
+#pragma warning disable CS0612
     builder.SetSessionCallbackFactory(buildSessionCallback);
+#pragma warning restore CS0612
 
     return builder;
   }

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode/LocalNode.Create.cs

@@ -20,6 +20,8 @@ partial class LocalNode {
 #pragma warning restore IDE0040
   private class ReadOnlyCollectionPluginProvider : IPluginProvider {
     public IReadOnlyCollection<IPlugin> Plugins { get; }
+
+    [Obsolete]
     public INodeSessionCallback? SessionCallback => null;
 
     public ReadOnlyCollectionPluginProvider(IReadOnlyCollection<IPlugin> plugins)

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode/NodeBase.cs

@@ -562,13 +562,14 @@ CancellationToken cancellationToken
       LogSessionStarted(Logger, null);
 
     try {
-      // TODO: rename INodeSessionCallback to ITransactionCallback
+#pragma warning disable CS0612,CS0618
       if (PluginProvider.SessionCallback is INodeSessionCallback pluginProviderSessionCallback)
         await pluginProviderSessionCallback.ReportSessionStartedAsync(sessionId, cancellationToken).ConfigureAwait(false);
 
       foreach (var pluginSessionCallback in EnumerateSessionCallbackForPlugins(PluginProvider)) {
         await pluginSessionCallback.ReportSessionStartedAsync(sessionId, cancellationToken).ConfigureAwait(false);
       }
+#pragma warning restore CS0612,CS0618
 
       // https://docs.microsoft.com/ja-jp/dotnet/standard/io/pipelines
       var pipe = new Pipe();
@@ -582,17 +583,22 @@ await Task.WhenAll(
         LogSessionClosed(Logger, null);
     }
     finally {
+#pragma warning disable CS0612,CS0618
       foreach (var pluginSessionCallback in EnumerateSessionCallbackForPlugins(PluginProvider)) {
         await pluginSessionCallback.ReportSessionClosedAsync(sessionId, cancellationToken).ConfigureAwait(false);
       }
 
       if (PluginProvider.SessionCallback is INodeSessionCallback pluginProviderSessionCallback)
         await pluginProviderSessionCallback.ReportSessionClosedAsync(sessionId, cancellationToken).ConfigureAwait(false);
+#pragma warning restore CS0612,CS0618
 
       await protocolHandler.HandleTransactionEndAsync(client, cancellationToken).ConfigureAwait(false);
     }
 
+    [Obsolete]
+#pragma warning disable CS0618
     static IEnumerable<INodeSessionCallback> EnumerateSessionCallbackForPlugins(IPluginProvider pluginProvider)
+#pragma warning restore CS0618
     {
       foreach (var plugin in pluginProvider.EnumeratePlugins(flattenMultigraphPlugins: true)) {
         if (plugin.SessionCallback is INodeSessionCallback pluginSessionCallback)

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/AggregatePluginProvider.cs

@@ -17,15 +17,19 @@ namespace Smdn.Net.MuninPlugin;
 #pragma warning disable IDE0055
 public sealed class AggregatePluginProvider :
   ReadOnlyCollection<IPluginProvider>,
+#pragma warning disable CS0618
   INodeSessionCallback,
-  IPluginProvider
+#pragma warning restore CS0618
+  IPluginProvider,
+  ITransactionCallback
 {
 #pragma warning restore IDE0055
   /*
    * IPluginProvider
    */
   public IReadOnlyCollection<IPlugin> Plugins { get; }
 
+  [Obsolete]
   INodeSessionCallback? IPluginProvider.SessionCallback => this;
 
   /*
@@ -37,6 +41,7 @@ public AggregatePluginProvider(IList<IPluginProvider> pluginProviders)
     Plugins = Items.SelectMany(static provider => provider.Plugins).ToList();
   }
 
+#pragma warning disable CS0618
   /*
    * INodeSessionCallback
    */
@@ -59,4 +64,28 @@ async ValueTask INodeSessionCallback.ReportSessionClosedAsync(string sessionId,
         await sessionCallback.ReportSessionClosedAsync(sessionId, cancellationToken).ConfigureAwait(false);
     }
   }
+#pragma warning restore CS0618
+
+  /*
+   * ITransactionCallback
+   */
+  async ValueTask ITransactionCallback.StartTransactionAsync(CancellationToken cancellationToken)
+  {
+    foreach (var provider in Items) {
+      cancellationToken.ThrowIfCancellationRequested();
+
+      if (provider is ITransactionCallback transactionCallback)
+        await transactionCallback.StartTransactionAsync(cancellationToken).ConfigureAwait(false);
+    }
+  }
+
+  async ValueTask ITransactionCallback.EndTransactionAsync(CancellationToken cancellationToken)
+  {
+    foreach (var provider in Items) {
+      cancellationToken.ThrowIfCancellationRequested();
+
+      if (provider is ITransactionCallback transactionCallback)
+        await transactionCallback.EndTransactionAsync(cancellationToken).ConfigureAwait(false);
+    }
+  }
 }

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/INodeSessionCallback.cs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2023 smdn <smdn@smdn.jp>
 // SPDX-License-Identifier: MIT
 
+using System;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -9,6 +10,7 @@ namespace Smdn.Net.MuninPlugin;
 /// <summary>
 /// Defines the callbacks when a request session from the <c>munin-update</c> starts or ends.
 /// </summary>
+[Obsolete(message: ObsoleteMessage.TypeReference)]
 public interface INodeSessionCallback {
   /// <summary>
   /// Implements a callback to be called when <c>munin-update</c> starts a session.
@@ -25,4 +27,15 @@ public interface INodeSessionCallback {
   /// <param name="sessionId">A unique ID that <see cref="MuninNode.NodeBase"/> associates with the session.</param>
   /// <param name="cancellationToken">The <see cref="CancellationToken" /> to monitor for cancellation requests.</param>
   ValueTask ReportSessionClosedAsync(string sessionId, CancellationToken cancellationToken);
+
+  internal static class ObsoleteMessage {
+    public const string TypeReference =
+      $"{nameof(INodeSessionCallback)} is deprecated and will be removed in the next major version release. " +
+      $"Use ${nameof(ITransactionCallback)} interface instead.";
+
+    public const string SessionCallbackProperty =
+      $"{nameof(INodeSessionCallback)} is deprecated and will be removed in the next major version release. " +
+      $"Instead of setting an object that implements ${nameof(INodeSessionCallback)} to the property, " +
+      $"implement the ${nameof(ITransactionCallback)} interface to the type itself.";
+  }
 }

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/IPlugin.cs

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2023 smdn <smdn@smdn.jp>
 // SPDX-License-Identifier: MIT
 
+using System;
+
 namespace Smdn.Net.MuninPlugin;
 
 /// <summary>
@@ -25,5 +27,8 @@ public interface IPlugin {
   /// <remarks>Callbacks of this interface can be used to initiate bulk collection of field values.</remarks>
   /// <seealso cref="INodeSessionCallback"/>
   /// <seealso cref="MuninNode.NodeBase"/>
+#pragma warning disable CS0618
+  [Obsolete(message: INodeSessionCallback.ObsoleteMessage.SessionCallbackProperty)]
+#pragma warning restore CS0618
   INodeSessionCallback? SessionCallback { get; }
 }

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/IPluginProvider.cs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2023 smdn <smdn@smdn.jp>
 // SPDX-License-Identifier: MIT
 
+using System;
 using System.Collections.Generic;
 
 namespace Smdn.Net.MuninPlugin;
@@ -21,5 +22,8 @@ public interface IPluginProvider {
   /// <summary>Gets a <see cref="INodeSessionCallback"/>, which defines the callbacks when a request session from the <c>munin-update</c> starts or ends, such as fetching data or getting configurations.</summary>
   /// <seealso cref="INodeSessionCallback"/>
   /// <seealso cref="MuninNode.NodeBase"/>
+#pragma warning disable CS0618
+  [Obsolete(message: INodeSessionCallback.ObsoleteMessage.SessionCallbackProperty)]
+#pragma warning restore CS0618
   INodeSessionCallback? SessionCallback { get; }
 }

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/MultigraphPlugin.cs

@@ -19,6 +19,9 @@ public class MultigraphPlugin : IMultigraphPlugin {
   public IPluginGraphAttributes GraphAttributes => throw new NotSupportedException();
 
   /// <inheritdoc cref="IPlugin.SessionCallback"/>
+#pragma warning disable CS0618
+  [Obsolete(message: INodeSessionCallback.ObsoleteMessage.SessionCallbackProperty)]
+#pragma warning restore CS0618
   public INodeSessionCallback? SessionCallback => throw new NotSupportedException();
 
   public MultigraphPlugin(string name, IReadOnlyCollection<IPlugin> plugins)

src/Smdn.Net.MuninNode/Smdn.Net.MuninPlugin/Plugin.cs

@@ -8,7 +8,16 @@
 
 namespace Smdn.Net.MuninPlugin;
 
-public class Plugin : IPlugin, IPluginDataSource, INodeSessionCallback {
+#pragma warning disable IDE0055
+public class Plugin :
+  IPlugin,
+  IPluginDataSource,
+#pragma warning disable CS0618
+  INodeSessionCallback,
+#pragma warning restore CS0618
+  ITransactionCallback
+{
+#pragma warning restore IDE0055
   public string Name { get; }
 
   public PluginGraphAttributes GraphAttributes { get; }
@@ -21,6 +30,9 @@ public class Plugin : IPlugin, IPluginDataSource, INodeSessionCallback {
 
   IReadOnlyCollection<IPluginField> IPluginDataSource.Fields => Fields;
 
+#pragma warning disable CS0618
+  [Obsolete(message: INodeSessionCallback.ObsoleteMessage.SessionCallbackProperty)]
+#pragma warning restore CS0618
   INodeSessionCallback? IPlugin.SessionCallback => this;
 #pragma warning restore CA1033
 
@@ -37,15 +49,31 @@ IReadOnlyCollection<IPluginField> fields
     Fields = fields ?? throw new ArgumentNullException(nameof(fields));
   }
 
+  [Obsolete]
   ValueTask INodeSessionCallback.ReportSessionStartedAsync(string sessionId, CancellationToken cancellationToken)
     => ReportSessionStartedAsync(sessionId, cancellationToken);
 
+  [Obsolete($"This method will be removed in the next major version release. Override {nameof(StartTransactionAsync)} instead.")]
   protected virtual ValueTask ReportSessionStartedAsync(string sessionId, CancellationToken cancellationToken)
     => default; // do nothing in this class
 
+  [Obsolete]
   ValueTask INodeSessionCallback.ReportSessionClosedAsync(string sessionId, CancellationToken cancellationToken)
     => ReportSessionClosedAsync(sessionId, cancellationToken);
 
+  [Obsolete($"This method will be removed in the next major version release. Override {nameof(EndTransactionAsync)} instead.")]
   protected virtual ValueTask ReportSessionClosedAsync(string sessionId, CancellationToken cancellationToken)
     => default; // do nothing in this class
+
+  ValueTask ITransactionCallback.StartTransactionAsync(CancellationToken cancellationToken)
+    => StartTransactionAsync(cancellationToken);
+
+  protected virtual ValueTask StartTransactionAsync(CancellationToken cancellationToken)
+    => default; // do nothing in this class
+
+  ValueTask ITransactionCallback.EndTransactionAsync(CancellationToken cancellationToken)
+    => EndTransactionAsync(cancellationToken);
+
+  protected virtual ValueTask EndTransactionAsync(CancellationToken cancellationToken)
+    => default; // do nothing in this class
 }