Merge pull request #16 from smdn/transport-abstraction-ifcs

Introduce transport layer abstraction interfaces

Author: smdn

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Transport/IMuninNodeClient.cs

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+
+using System;
+using System.Buffers;
+using System.Net;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Smdn.Net.MuninNode.Transport;
+
+/// <summary>
+/// Provides an interface that abstracts the client implementation of
+/// the transport layer that connects to the <c>Munin-Node</c>.
+/// </summary>
+/// <seealso cref="IMuninNodeListener"/>
+public interface IMuninNodeClient : IDisposable, IAsyncDisposable {
+  /// <summary>
+  /// Gets the <see cref="EndPoint"/> that is bound with this instance.
+  /// </summary>
+  /// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
+  /// <value>
+  /// <see langword="null"/> if this client does not have <see cref="EndPoint"/>.
+  /// </value>
+  /// <remarks>
+  /// The value of this property will be used by the <see cref="IAccessRule"/> interface
+  /// to determine if the client is accessible.
+  /// </remarks>
+  /// <seealso cref="IAccessRule.IsAcceptable(IPEndPoint)"/>
+  EndPoint? EndPoint { get; }
+
+  /// <summary>
+  /// Disconnects the active connection.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation,
+  /// disconnecting the active connection.
+  /// </returns>
+  ValueTask DisconnectAsync(CancellationToken cancellationToken);
+
+  /// <summary>
+  /// Waits to receive a response from the server and writes the received data into a buffer.
+  /// </summary>
+  /// <param name="buffer">
+  /// The <see cref="IBufferWriter{Byte}"/> for writing received data.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation,
+  /// returning the number of bytes received.
+  /// </returns>
+  ValueTask<int> ReceiveAsync(IBufferWriter<byte> buffer, CancellationToken cancellationToken);
+
+  /// <summary>
+  /// Sends a request to the server.
+  /// </summary>
+  /// <param name="buffer">
+  /// The <see cref="ReadOnlyMemory{Byte}"/> that contains the data to be sent.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <exception cref="ObjectDisposedException">The client has been disposed.</exception>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation,
+  /// sending the requested data.
+  /// </returns>
+  ValueTask SendAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken);
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Transport/IMuninNodeListener.cs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+
+using System;
+using System.Net;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Smdn.Net.MuninNode.Transport;
+
+/// <summary>
+/// Provides an interface that abstracts the listener implementation of
+/// the transport layer that accepts the connections to the <c>Munin-Node</c>.
+/// </summary>
+/// <seealso cref="IMuninNodeClient"/>
+/// <seealso cref="IMuninNodeListenerFactory"/>
+public interface IMuninNodeListener : IDisposable, IAsyncDisposable {
+  /// <summary>
+  /// Gets the <see cref="EndPoint"/> that is bound with this instance.
+  /// </summary>
+  /// <exception cref="ObjectDisposedException">The instance has been disposed.</exception>
+  /// <exception cref="InvalidOperationException">The instance is not started yet.</exception>
+  /// <value>
+  /// <see langword="null"/> if this instance does not have <see cref="EndPoint"/>.
+  /// </value>
+  EndPoint? EndPoint { get; }
+
+  /// <summary>
+  /// Start the listener and enable to accept connections from clients.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask"/> that represents the asynchronous operation,
+  /// starting the listener.
+  /// </returns>
+  ValueTask StartAsync(CancellationToken cancellationToken);
+
+  /// <summary>
+  /// Waits for a single client and accepts an incoming connection.
+  /// </summary>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <returns>
+  /// The <see cref="ValueTask{IMuninNodeClient}"/> that represents the asynchronous operation,
+  /// creating the <see cref="IMuninNodeClient"/> representing the accepted client.
+  /// </returns>
+  ValueTask<IMuninNodeClient> AcceptAsync(CancellationToken cancellationToken);
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Transport/IMuninNodeListenerFactory.cs

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+
+using System.Net;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Smdn.Net.MuninNode.Transport;
+
+/// <summary>
+/// Provides an interface that abstracts the factory for creating the client
+/// listener implementation of the transport layer used by <c>Munin-Node</c>.
+/// </summary>
+/// <seealso cref="IMuninNodeListener"/>
+public interface IMuninNodeListenerFactory {
+  /// <summary>
+  /// Creates and returns a <see cref="IMuninNodeListener"/> for the specific <c>Munin-Node</c>.
+  /// </summary>
+  /// <param name="endPoint">
+  /// The <see cref="EndPoint"/> that will be bound with the <see cref="IMuninNodeListener"/> used by the <c>Munin-Node</c> to be created.
+  /// </param>
+  /// <param name="node">
+  /// The <see cref="IMuninNode"/> representing the <c>Munin-Node</c> where the <see cref="IMuninNodeListener"/> to be created will be used.
+  /// </param>
+  /// <param name="cancellationToken">
+  /// The <see cref="CancellationToken"/> to monitor for cancellation requests.
+  /// </param>
+  /// <remarks>
+  /// The <paramref name="node"/> parameter should not be used to determine an endpoint to bind to.
+  /// It is intended to be used as a key for the management and identification of the
+  /// <see cref="IMuninNodeListener"/> that has been created.
+  /// </remarks>
+  /// <returns>
+  /// The <see cref="ValueTask{IMuninNodeListener}"/> that represents the asynchronous operation,
+  /// creating the <see cref="IMuninNodeListener"/> bound to the <paramref name="endPoint"/>.
+  /// </returns>
+  ValueTask<IMuninNodeListener> CreateAsync(
+    EndPoint endPoint,
+    IMuninNode node,
+    CancellationToken cancellationToken
+  );
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Transport/MuninNodeClient.cs

@@ -0,0 +1,161 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+
+// TODO: use LoggerMessage.Define
+#pragma warning disable CA1848 // For improved performance, use the LoggerMessage delegates instead of calling 'LoggerExtensions.LogInformation(ILogger, string?, params object?[])'
+
+using System;
+using System.Buffers;
+using System.Net;
+using System.Net.Sockets;
+using System.Threading;
+using System.Threading.Tasks;
+
+using Microsoft.Extensions.Logging;
+
+namespace Smdn.Net.MuninNode.Transport;
+
+internal sealed class MuninNodeClient : IMuninNodeClient {
+  public EndPoint EndPoint => client?.RemoteEndPoint ?? throw new ObjectDisposedException(GetType().FullName);
+
+  private Socket client;
+  private readonly ILogger? logger;
+
+  internal MuninNodeClient(
+    Socket client,
+    ILogger? logger
+  )
+  {
+    this.client = client ?? throw new ArgumentNullException(nameof(client));
+    this.logger = logger;
+  }
+
+  public void Dispose()
+  {
+    Dispose(true);
+    GC.SuppressFinalize(this);
+  }
+
+  public async ValueTask DisposeAsync()
+  {
+    await DisposeAsyncCore().ConfigureAwait(false);
+
+    Dispose(disposing: false);
+    GC.SuppressFinalize(this);
+  }
+
+  private ValueTask DisposeAsyncCore()
+  {
+    client?.Close();
+    client?.Dispose();
+    client = null!;
+
+    return default;
+  }
+
+  // protected virtual
+  private void Dispose(bool disposing)
+  {
+    if (!disposing)
+      return;
+
+    client?.Close();
+    client?.Dispose();
+    client = null!;
+  }
+
+  public ValueTask DisconnectAsync(CancellationToken cancellationToken)
+  {
+    if (client is null)
+      throw new ObjectDisposedException(GetType().FullName);
+
+    return DisposeAsync();
+  }
+
+  public async ValueTask<int> ReceiveAsync(IBufferWriter<byte> buffer, CancellationToken cancellationToken)
+  {
+    if (client is null)
+      throw new ObjectDisposedException(GetType().FullName);
+
+    // holds a reference to the endpoint before the client being disposed
+    var remoteEndPoint = client.RemoteEndPoint;
+
+    const int ReceiveChunkSize = 256;
+    var totalByteCount = 0;
+
+    for (; ; ) {
+      try {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (!client.Connected)
+          return 0;
+
+        var memory = buffer.GetMemory(ReceiveChunkSize);
+
+        var byteCount = await client.ReceiveAsync(
+          buffer: memory,
+          socketFlags: SocketFlags.None,
+          cancellationToken: cancellationToken
+        ).ConfigureAwait(false);
+
+        buffer.Advance(byteCount);
+
+        totalByteCount += byteCount;
+
+        if (byteCount < memory.Length)
+          return totalByteCount;
+      }
+      catch (SocketException ex) when (
+        ex.SocketErrorCode is
+          SocketError.OperationAborted or // ECANCELED (125)
+          SocketError.ConnectionReset // ECONNRESET (104)
+      ) {
+        logger?.LogDebug(
+          "[{RemoteEndPoint}] expected socket exception ({NumericSocketErrorCode} {SocketErrorCode})",
+          remoteEndPoint,
+          (int)ex.SocketErrorCode,
+          ex.SocketErrorCode
+        );
+
+        break; // expected exception
+      }
+      catch (ObjectDisposedException) {
+        logger?.LogDebug(
+          "[{RemoteEndPoint}] socket has been disposed",
+          remoteEndPoint
+        );
+
+        break; // expected exception
+      }
+    }
+
+    return totalByteCount;
+  }
+
+  public async ValueTask SendAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken)
+  {
+    if (client is null)
+      throw new ObjectDisposedException(GetType().FullName);
+
+    try {
+      _ = await client.SendAsync(
+        buffer: buffer,
+        socketFlags: SocketFlags.None,
+        cancellationToken: cancellationToken
+      ).ConfigureAwait(false);
+    }
+    catch (SocketException ex) when (
+      ex.SocketErrorCode is
+        SocketError.Shutdown or // EPIPE (32)
+        SocketError.ConnectionAborted or // WSAECONNABORTED (10053)
+        SocketError.OperationAborted or // ECANCELED (125)
+        SocketError.ConnectionReset // ECONNRESET (104)
+    ) {
+      // expected exception in case of disconnection
+      throw new MuninNodeClientDisconnectedException(
+        message: "client disconnected",
+        innerException: ex
+      );
+    }
+  }
+}

src/Smdn.Net.MuninNode/Smdn.Net.MuninNode.Transport/MuninNodeClientDisconnectedException.cs

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2025 smdn <smdn@smdn.jp>
+// SPDX-License-Identifier: MIT
+
+using System;
+
+namespace Smdn.Net.MuninNode.Transport;
+
+/// <summary>
+/// The exception that is thrown when a connection is disconnected when responding to a <see cref="IMuninNodeClient"/>.
+/// </summary>
+public sealed class MuninNodeClientDisconnectedException : InvalidOperationException {
+  public MuninNodeClientDisconnectedException()
+    : base()
+  {
+  }
+
+  public MuninNodeClientDisconnectedException(string message)
+    : base(message)
+  {
+  }
+
+  public MuninNodeClientDisconnectedException(string message, Exception innerException)
+    : base(message, innerException)
+  {
+  }
+}