add Starting/Started/Stopping/Stopped async methods

Author: smdn

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

@@ -228,6 +228,10 @@ async ValueTask StartAsyncCore()
       if (Logger is not null)
         LogStartingNode(Logger, null);
 
+      await StartingAsync(cancellationToken).ConfigureAwait(false);
+
+      cancellationToken.ThrowIfCancellationRequested();
+
       listener = await listenerFactory.CreateAsync(
         endPoint: GetLocalEndPointToBind(),
         node: this,
@@ -246,13 +250,47 @@ async ValueTask StartAsyncCore()
         cancellationToken: cancellationToken
       ).ConfigureAwait(false);
 
+      sessionCountdownEvent.Reset();
+
+      await StartedAsync(cancellationToken).ConfigureAwait(false);
+
       if (Logger is not null)
         LogStartedNode(Logger, HostName, listener.EndPoint, null);
-
-      sessionCountdownEvent.Reset();
     }
   }
 
+  /// <summary>
+  /// Provides an extension point for starting the <c>Munin-Node</c> instance.
+  /// If overridden in a derived class, it is invoked before the <c>Munin-Node</c> is started
+  /// by a call to the <see cref="StartAsync"/> method.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <seealso cref="StartAsync"/>
+  /// <seealso cref="StartedAsync"/>
+  protected virtual ValueTask StartingAsync(CancellationToken cancellationToken)
+    => default; // nothing to do in this class
+
+  /// <summary>
+  /// Provides an extension point for starting the <c>Munin-Node</c> instance.
+  /// If overridden in a derived class, it is invoked after the <c>Munin-Node</c> is started
+  /// by a call to the <see cref="StartAsync"/> method.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <seealso cref="StartAsync"/>
+  /// <seealso cref="StartingAsync"/>
+  protected virtual ValueTask StartedAsync(CancellationToken cancellationToken)
+    => default; // nothing to do in this class
+
   /// <summary>
   /// Stops accepting connections from clients at the <c>Munin-Node</c> currently running.
   /// </summary>
@@ -277,9 +315,15 @@ public ValueTask StopAsync(CancellationToken cancellationToken = default)
 
     async ValueTask StopAsyncCore()
     {
+      cancellationToken.ThrowIfCancellationRequested();
+
       if (Logger is not null)
         LogStoppingNode(Logger, HostName, null);
 
+      await StoppingAsync(cancellationToken).ConfigureAwait(false);
+
+      cancellationToken.ThrowIfCancellationRequested();
+
       // decrement by the initial value of 1 (re)set in Start()/StartAsync()
       sessionCountdownEvent.Signal();
 
@@ -307,11 +351,45 @@ async ValueTask StopAsyncCore()
         protocolHandler = null;
       }
 
+      await StoppedAsync(cancellationToken).ConfigureAwait(false);
+
       if (Logger is not null)
         LogStoppedNode(Logger, HostName, null);
     }
   }
 
+  /// <summary>
+  /// Provides an extension point for stopping the <c>Munin-Node</c> instance.
+  /// If overridden in a derived class, it is invoked before the <c>Munin-Node</c> is stopped
+  /// by a call to the <see cref="StopAsync"/> method.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <seealso cref="StopAsync"/>
+  /// <seealso cref="StoppedAsync"/>
+  protected virtual ValueTask StoppingAsync(CancellationToken cancellationToken)
+    => default; // nothing to do in this class
+
+  /// <summary>
+  /// Provides an extension point for stopping the <c>Munin-Node</c> instance.
+  /// If overridden in a derived class, it is invoked after the <c>Munin-Node</c> is stopped
+  /// by a call to the <see cref="StopAsync"/> method.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <seealso cref="StopAsync"/>
+  /// <seealso cref="StoppingAsync"/>
+  protected virtual ValueTask StoppedAsync(CancellationToken cancellationToken)
+    => default; // nothing to do in this class
+
   /// <inheritdoc cref="IMuninNode.RunAsync(CancellationToken)"/>
   /// <seealso cref="IMuninNode.RunAsync(CancellationToken)"/>
   /// <seealso cref="StartAsync(CancellationToken)"/>

tests/Smdn.Net.MuninNode/Smdn.Net.MuninNode/NodeBase.cs

@@ -12,6 +12,7 @@
 
 using NUnit.Framework;
 
+using Smdn.Net.MuninNode.Transport;
 using Smdn.Net.MuninPlugin;
 
 namespace Smdn.Net.MuninNode;
@@ -69,6 +70,63 @@ protected override EndPoint GetLocalEndPointToBind()
       );
   }
 
+  private class TestLifecycleLocalNode : NodeBase {
+    public EventHandler? NodeStarting = null;
+    public EventHandler? NodeStarted = null;
+    public EventHandler? NodeStopping = null;
+    public EventHandler? NodeStopped = null;
+
+    private class NullPluginProvider : IPluginProvider {
+      public IReadOnlyCollection<IPlugin> Plugins { get; } = [];
+      public INodeSessionCallback? SessionCallback => null;
+    }
+
+    public override IPluginProvider PluginProvider { get; } = new NullPluginProvider();
+    public override string HostName => "test.munin-node.localhost";
+
+    public TestLifecycleLocalNode()
+#pragma warning disable CS0618
+      : base(
+        listenerFactory: new PseudoMuninNodeListenerFactory(),
+        accessRule: null,
+        logger: null
+      )
+#pragma warning restore CS0618
+    {
+    }
+
+    protected override EndPoint GetLocalEndPointToBind()
+      => new IPEndPoint(IPAddress.Any, port: 0);
+
+    protected override ValueTask StartingAsync(CancellationToken cancellationToken)
+    {
+      NodeStarting?.Invoke(this, EventArgs.Empty);
+
+      return default;
+    }
+
+    protected override ValueTask StartedAsync(CancellationToken cancellationToken)
+    {
+      NodeStarted?.Invoke(this, EventArgs.Empty);
+
+      return default;
+    }
+
+    protected override ValueTask StoppingAsync(CancellationToken cancellationToken)
+    {
+      NodeStopping?.Invoke(this, EventArgs.Empty);
+
+      return default;
+    }
+
+    protected override ValueTask StoppedAsync(CancellationToken cancellationToken)
+    {
+      NodeStopped?.Invoke(this, EventArgs.Empty);
+
+      return default;
+    }
+  }
+
   private static NodeBase CreateNode()
     => CreateNode(accessRule: null, plugins: Array.Empty<IPlugin>());
 
@@ -217,6 +275,72 @@ public async Task StartAsync_Restart()
 #pragma warning restore CS0618
   }
 
+  [Test]
+  public async Task StartAsync_CancellationRequestedBeforeStarting()
+  {
+    await using var node = new TestLifecycleLocalNode();
+    var cancellationToken = new CancellationToken(canceled: true);
+
+    var numberOfInvocationOfStartingAsync = 0;
+    var numberOfInvocationOfStartedAsync = 0;
+
+    node.NodeStarting += (_, _) => numberOfInvocationOfStartingAsync++;
+    node.NodeStarted += (_, _) => numberOfInvocationOfStartedAsync++;
+
+    Assert.That(async () => await node.StartAsync(cancellationToken), Throws.InstanceOf<OperationCanceledException>());
+
+    Assert.That(numberOfInvocationOfStartingAsync, Is.Zero);
+    Assert.That(numberOfInvocationOfStartedAsync, Is.Zero);
+
+    Assert.That(() => _ = node.EndPoint, Throws.InvalidOperationException, "must not be started");
+  }
+
+  [Test]
+  public async Task StartAsync_CancellationRequestedWhileStarting()
+  {
+    await using var node = new TestLifecycleLocalNode();
+    using var cts = new CancellationTokenSource();
+
+    var numberOfInvocationOfStartingAsync = 0;
+    var numberOfInvocationOfStartedAsync = 0;
+
+    node.NodeStarting += (_, _) => {
+      numberOfInvocationOfStartingAsync++;
+      cts.Cancel();
+    };
+    node.NodeStarted += (_, _) => numberOfInvocationOfStartedAsync++;
+
+    Assert.That(async () => await node.StartAsync(cts.Token), Throws.InstanceOf<OperationCanceledException>());
+
+    Assert.That(numberOfInvocationOfStartingAsync, Is.EqualTo(1));
+    Assert.That(numberOfInvocationOfStartedAsync, Is.Zero);
+
+    Assert.That(() => _ = node.EndPoint, Throws.InvalidOperationException, "must not be started");
+  }
+
+  [Test]
+  public async Task StartAsync_CancellationRequestedAfterStarted()
+  {
+    await using var node = new TestLifecycleLocalNode();
+    using var cts = new CancellationTokenSource();
+
+    var numberOfInvocationOfStartingAsync = 0;
+    var numberOfInvocationOfStartedAsync = 0;
+
+    node.NodeStarting += (_, _) => numberOfInvocationOfStartingAsync++;
+    node.NodeStarted += (_, _) => {
+      numberOfInvocationOfStartedAsync++;
+      cts.Cancel();
+    };
+
+    Assert.That(async () => await node.StartAsync(cts.Token), Throws.Nothing, "requested cancellation must be ignored");
+
+    Assert.That(numberOfInvocationOfStartingAsync, Is.EqualTo(1));
+    Assert.That(numberOfInvocationOfStartedAsync, Is.EqualTo(1));
+
+    Assert.That(() => _ = node.EndPoint, Throws.Nothing, "must be started");
+  }
+
   [Test]
   public async Task StopAsync_StartedByStartAsync()
   {
@@ -298,4 +422,79 @@ public async Task StopAsync_WhileProcessingClient()
       Throws.Nothing
     );
   }
+
+  [Test]
+  public async Task StopAsync_CancellationRequestedBeforeStopping()
+  {
+    await using var node = new TestLifecycleLocalNode();
+
+    await node.StartAsync();
+
+    var cancellationToken = new CancellationToken(canceled: true);
+
+    var numberOfInvocationOfStoppingAsync = 0;
+    var numberOfInvocationOfStoppedAsync = 0;
+
+    node.NodeStopping += (_, _) => numberOfInvocationOfStoppingAsync++;
+    node.NodeStopped += (_, _) => numberOfInvocationOfStoppedAsync++;
+
+    Assert.That(async () => await node.StopAsync(cancellationToken), Throws.InstanceOf<OperationCanceledException>());
+
+    Assert.That(numberOfInvocationOfStoppingAsync, Is.Zero);
+    Assert.That(numberOfInvocationOfStoppedAsync, Is.Zero);
+
+    Assert.That(() => _ = node.EndPoint, Throws.Nothing, "must not be stopped");
+  }
+
+  [Test]
+  public async Task StopAsync_CancellationRequestedWhileStopping()
+  {
+    await using var node = new TestLifecycleLocalNode();
+
+    await node.StartAsync();
+
+    using var cts = new CancellationTokenSource();
+
+    var numberOfInvocationOfStoppingAsync = 0;
+    var numberOfInvocationOfStoppedAsync = 0;
+
+    node.NodeStopping += (_, _) => {
+      numberOfInvocationOfStoppingAsync++;
+      cts.Cancel();
+    };
+    node.NodeStopped += (_, _) => numberOfInvocationOfStoppedAsync++;
+
+    Assert.That(async () => await node.StopAsync(cts.Token), Throws.InstanceOf<OperationCanceledException>());
+
+    Assert.That(numberOfInvocationOfStoppingAsync, Is.EqualTo(1));
+    Assert.That(numberOfInvocationOfStoppedAsync, Is.Zero);
+
+    Assert.That(() => _ = node.EndPoint, Throws.Nothing, "must not be stopped");
+  }
+
+  [Test]
+  public async Task StopAsync_CancellationRequestedAfterStopped()
+  {
+    await using var node = new TestLifecycleLocalNode();
+
+    await node.StartAsync();
+
+    using var cts = new CancellationTokenSource();
+
+    var numberOfInvocationOfStoppingAsync = 0;
+    var numberOfInvocationOfStoppedAsync = 0;
+
+    node.NodeStopping += (_, _) => numberOfInvocationOfStoppingAsync++;
+    node.NodeStopped += (_, _) => {
+      numberOfInvocationOfStoppedAsync++;
+      cts.Cancel();
+    };
+
+    Assert.That(async () => await node.StopAsync(cts.Token), Throws.Nothing, "requested cancellation must be ignored");
+
+    Assert.That(numberOfInvocationOfStoppingAsync, Is.EqualTo(1));
+    Assert.That(numberOfInvocationOfStoppedAsync, Is.EqualTo(1));
+
+    Assert.That(() => _ = node.EndPoint, Throws.InvalidOperationException, "must be stopped");
+  }
 }