Merge pull request #22 from smdn/introduce-protocolhandler

Introduce protocol abstraction interfaces

Author: smdn

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Protocol/IMuninNodeProfile.cs

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+using System.Text;
+
+using Smdn.Net.MuninPlugin;
+
+namespace Smdn.Net.MuninNode.Protocol;
+
+/// <summary>
+/// An interface for referencing properties that represent the profile of the constructed <c>Munin-Node</c>.
+/// </summary>
+public interface IMuninNodeProfile {
+  /// <summary>
+  /// Gets the string representing the hostname of the node.
+  /// </summary>
+  /// <remarks>
+  /// This value is used as the response to the `node` command.
+  /// </remarks>
+  /// <seealso href="https://guide.munin-monitoring.org/en/latest/master/network-protocol.html">
+  /// Data exchange between master and node - `node` command
+  /// </seealso>
+  public string HostName { get; }
+
+  /// <summary>
+  /// Gets the string representing the version information of the node.
+  /// </summary>
+  /// <remarks>
+  /// This value is used as the response to the `version` command.
+  /// </remarks>
+  /// <seealso href="https://guide.munin-monitoring.org/en/latest/master/network-protocol.html">
+  /// Data exchange between master and node - `version` command
+  /// </seealso>
+  public string Version { get; }
+
+  /// <summary>
+  /// Gets the <see cref="IPluginProvider"/> representing the munin plugins provided by the node.
+  /// </summary>
+  /// <remarks>
+  /// This value is used as the response to the `list`, `config` and `fetch` command.
+  /// </remarks>
+  /// <seealso href="https://guide.munin-monitoring.org/en/latest/master/network-protocol.html">
+  /// Data exchange between master and node - `list`, `config` and `fetch` command
+  /// </seealso>
+  public IPluginProvider PluginProvider { get; }
+
+  /// <summary>
+  /// Gets the <see cref="Encoding"/> used for data exchange with the <c>munin master</c>.
+  /// </summary>
+  public Encoding Encoding { get; }
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Protocol/IMuninProtocolHandler.cs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+using System;
+using System.Buffers;
+using System.Threading;
+using System.Threading.Tasks;
+
+using Smdn.Net.MuninNode.Transport;
+
+namespace Smdn.Net.MuninNode.Protocol;
+
+/// <summary>
+/// Provides an interface that abstracts the handling of data exchange
+/// protocols with <c>munin master</c> in <c>Munin-Node</c>.
+/// </summary>
+/// <seealso href="https://guide.munin-monitoring.org/en/latest/master/network-protocol.html">
+/// Data exchange between master and node
+/// </seealso>
+public interface IMuninProtocolHandler {
+  /// <summary>
+  /// Handles the start of a transaction processing requests from <c>munin master</c>.
+  /// </summary>
+  /// <param name="client">
+  /// The <see cref="IMuninNodeClient"/> to which the request is sent from and
+  /// to which the response should be sent back.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <exception cref="ArgumentNullException">
+  /// <paramref name="client"/> is <see langword="null"/>.
+  /// </exception>
+  /// <exception cref="MuninNodeClientDisconnectedException">
+  /// <paramref name="client"/> has been disconnected.
+  /// </exception>
+  ValueTask HandleTransactionStartAsync(
+    IMuninNodeClient client,
+    CancellationToken cancellationToken
+  );
+
+  /// <summary>
+  /// Handles the end of a transaction processing requests from <c>munin master</c>.
+  /// </summary>
+  /// <param name="client">
+  /// The <see cref="IMuninNodeClient"/> to which the request is sent from and
+  /// to which the response should be sent back.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <exception cref="ArgumentNullException">
+  /// <paramref name="client"/> is <see langword="null"/>.
+  /// </exception>
+  /// <exception cref="MuninNodeClientDisconnectedException">
+  /// <paramref name="client"/> has been disconnected.
+  /// </exception>
+  ValueTask HandleTransactionEndAsync(
+    IMuninNodeClient client,
+    CancellationToken cancellationToken
+  );
+
+  /// <summary>
+  /// Handles commands from the <c>munin master</c> and sends back a response.
+  /// </summary>
+  /// <param name="client">
+  /// The <see cref="IMuninNodeClient"/> to which the request is sent from and
+  /// to which the response should be sent back.
+  /// </param>
+  /// <param name="commandLine">
+  /// The <see cref="ReadOnlySequence{T}"/> representing the command line requested from the <paramref name="client"/>.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation.
+  /// </returns>
+  /// <exception cref="ArgumentNullException">
+  /// <paramref name="client"/> is <see langword="null"/>.
+  /// </exception>
+  /// <exception cref="MuninNodeClientDisconnectedException">
+  /// <paramref name="client"/> has been disconnected.
+  /// </exception>
+  ValueTask HandleCommandAsync(
+    IMuninNodeClient client,
+    ReadOnlySequence<byte> commandLine,
+    CancellationToken cancellationToken
+  );
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Protocol/IMuninProtocolHandlerFactory.cs

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Smdn.Net.MuninNode.Protocol;
+
+/// <summary>
+/// Provides an interface that abstracts the factory for creating the munin
+/// protocol handler used by <c>Munin-Node</c>.
+/// </summary>
+/// <seealso cref="NodeBase"/>
+/// <seealso cref="IMuninProtocolHandler"/>
+public interface IMuninProtocolHandlerFactory {
+  /// <summary>
+  /// Creates and returns a <see cref="IMuninProtocolHandler"/> for the specific <c>Munin-Node</c>.
+  /// </summary>
+  /// <param name="profile">
+  /// The <see cref="IMuninNodeProfile"/> that represents the profile of the <c>Munin-Node</c>
+  /// for which this handler to be created will process requests.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask{IMuninProtocolHandler}"/> that represents the asynchronous operation,
+  /// creating the <see cref="IMuninProtocolHandler"/> bound to the <paramref name="profile"/>.
+  /// </returns>
+  /// <exception cref="ArgumentNullException">
+  /// <paramref name="profile"/> is <see langword="null"/>.
+  /// </exception>
+  ValueTask<IMuninProtocolHandler> CreateAsync(
+    IMuninNodeProfile profile,
+    CancellationToken cancellationToken
+  );
+}