Add native SCTP socket adapter

Author: ammarheidari

README.md

@@ -45,7 +45,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Observability | Phase 7 profile added for commercial metrics, trace categories, and health signals |
 | Deployment profiles | Phase 7 profiles added for commercial Linux and local development use |
 | Phase 7 status | Commercialization foundation complete; commercial production remains blocked on native SCTP verification, external lab evidence, signing, and SBOM |
-| Native SCTP implementation | Phase 8 started: Linux SCTP socket probe, socket factory, and endpoint connection planner added; full production readiness still requires native transport completion and lab verification |
+| Native SCTP implementation | Phase 8 started: Linux SCTP socket probe, socket factory, endpoint connection planner, and native socket adapter added; full production readiness still requires native transport completion and lab verification |
 
 ## Requirements
 

docs/PHASE8_NATIVE_SCTP.md

@@ -36,3 +36,14 @@ NativeSctpConnectionPlan plan = await new NativeSctpConnectionPlanner()
 ```
 
 The planner resolves the remote endpoint and optional local endpoint before a socket attempts bind/connect. Phase 8 currently resolves IPv4 endpoints because the Linux native SCTP path starts with IPv4 verification.
+
+## Socket Adapter
+
+`NativeSctpSocketAdapter` wraps a native SCTP socket behind the SDK `ISctpSocket` contract.
+
+```csharp
+using Socket socket = factory.CreateSocket();
+using NativeSctpSocketAdapter adapter = new(socket, options);
+```
+
+The adapter exposes lifecycle state and `SctpTransportHealth` snapshots. It currently sends and receives complete socket messages through the native socket API; SCTP ancillary metadata handling is tracked separately before production readiness can be claimed.

docs/SCTP_TRANSPORT.md

@@ -128,3 +128,5 @@ The probe does not mark the transport production-ready by itself. It is the firs
 `NativeSctpSocketFactory` centralizes socket creation and throws `NativeSctpUnavailableException` when the current platform cannot create native SCTP sockets.
 
 `NativeSctpConnectionPlanner` resolves configured SCTP endpoints to `IPEndPoint` values before native bind/connect attempts.
+
+`NativeSctpSocketAdapter` wraps an SCTP socket as `ISctpSocket` and reports `SctpTransportHealth` snapshots for native associations.

src/sigtran.net.Tests/Program.cs

@@ -33,6 +33,7 @@
 Run("Native SCTP platform probe reports socket creation capability", NativeSctpPlatformProbeReportsSocketCreationCapability);
 Run("Native SCTP socket factory creates or reports unsupported platform", NativeSctpSocketFactoryCreatesOrReportsUnsupportedPlatform);
 Run("Native SCTP connection planner resolves endpoints", NativeSctpConnectionPlannerResolvesEndpoints);
+Run("Native SCTP socket adapter reports lifecycle health", NativeSctpSocketAdapterReportsLifecycleHealth);
 Run("TCAP BER element encodes short and long lengths", TcapBerElementEncodesShortAndLongLengths);
 Run("TCAP transaction identifiers use BER context tags", TcapTransactionIdentifiersUseBerContextTags);
 Run("TCAP BER Invoke component round-trips", TcapBerInvokeComponentRoundTrips);
@@ -447,6 +448,29 @@ static void NativeSctpConnectionPlannerResolvesEndpoints()
     Assert(plan.Describe().Contains("remote=127.0.0.1:2905", StringComparison.Ordinal), plan.Describe());
 }
 
+static void NativeSctpSocketAdapterReportsLifecycleHealth()
+{
+    NativeSctpPlatformCapability capability = NativeSctpPlatform.Probe();
+    if (!capability.CanCreateSocket)
+    {
+        Assert(!capability.CanCreateSocket, capability.Describe());
+        return;
+    }
+
+    using Socket socket = new NativeSctpSocketFactory().CreateSocket();
+    SctpConnectionOptions options = new(new SctpEndpoint("127.0.0.1", 2905), outboundStreams: 2, inboundStreams: 3);
+    using NativeSctpSocketAdapter adapter = new(socket, options);
+
+    AssertEqual(SctpAssociationState.Closed, adapter.AssociationState, "native adapter initial state");
+    adapter.MarkEstablished();
+    SctpTransportHealth health = adapter.GetHealthSnapshot();
+
+    Assert(health.IsEstablished, "native adapter health should be established");
+    AssertEqual((ushort)2, health.OutboundStreams, "native adapter outbound streams");
+    AssertEqual((ushort)3, health.InboundStreams, "native adapter inbound streams");
+    AssertEqual((uint)SctpPayloadProtocolIdentifiers.M3ua, health.DefaultPayloadProtocolIdentifier, "native adapter PPID");
+}
+
 static void TcapBerElementEncodesShortAndLongLengths()
 {
     Span<byte> shortBuffer = stackalloc byte[8];

src/sigtran.net/Layers/SCTP/NativeSctpSocketAdapter.cs

@@ -0,0 +1,123 @@
+using System.Net.Sockets;
+
+using sigtran.net.Core.Interfaces;
+
+namespace sigtran.net.Layers.SCTP;
+
+/// <summary>
+/// Wraps a native SCTP socket as the SDK packet transport contract.
+/// </summary>
+public sealed class NativeSctpSocketAdapter : ISctpSocket
+{
+    private readonly Socket _socket;
+    private readonly SctpConnectionOptions _options;
+    private long _sentMessages;
+    private long _receivedMessages;
+    private bool _disposed;
+    private SctpAssociationState _associationState;
+
+    /// <summary>Creates a native SCTP socket adapter.</summary>
+    /// <param name="socket">The native SCTP socket.</param>
+    /// <param name="options">The SCTP connection options.</param>
+    /// <param name="associationState">The initial association state.</param>
+    public NativeSctpSocketAdapter(
+        Socket socket,
+        SctpConnectionOptions options,
+        SctpAssociationState associationState = SctpAssociationState.Closed)
+    {
+        _socket = socket ?? throw new ArgumentNullException(nameof(socket));
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+        _associationState = associationState;
+    }
+
+    /// <summary>The current association state.</summary>
+    public SctpAssociationState AssociationState => _disposed ? SctpAssociationState.Closed : _associationState;
+
+    /// <summary>Marks the association as established.</summary>
+    public void MarkEstablished()
+    {
+        ThrowIfDisposed();
+        _associationState = SctpAssociationState.Established;
+    }
+
+    /// <summary>Marks the association as failed.</summary>
+    public void MarkFailed()
+    {
+        if (!_disposed)
+        {
+            _associationState = SctpAssociationState.Failed;
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task SendAsync(ReadOnlyMemory<byte> data, CancellationToken ct = default)
+    {
+        ThrowIfDisposed();
+        if (data.IsEmpty)
+        {
+            throw new ArgumentException("SCTP payload must not be empty.", nameof(data));
+        }
+
+        int sent = await _socket.SendAsync(data, SocketFlags.None, ct).ConfigureAwait(false);
+        if (sent != data.Length)
+        {
+            throw new InvalidDataException($"Native SCTP send wrote {sent} bytes for a {data.Length} byte message.");
+        }
+
+        Interlocked.Increment(ref _sentMessages);
+    }
+
+    /// <inheritdoc />
+    public async Task<int> ReceiveAsync(Memory<byte> buffer, CancellationToken ct = default)
+    {
+        ThrowIfDisposed();
+        if (buffer.IsEmpty)
+        {
+            throw new ArgumentException("Receive buffer must not be empty.", nameof(buffer));
+        }
+
+        int received = await _socket.ReceiveAsync(buffer, SocketFlags.None, ct).ConfigureAwait(false);
+        if (received > 0)
+        {
+            Interlocked.Increment(ref _receivedMessages);
+        }
+
+        return received;
+    }
+
+    /// <summary>Captures a native SCTP transport health snapshot.</summary>
+    /// <returns>The transport health snapshot.</returns>
+    public SctpTransportHealth GetHealthSnapshot()
+    {
+        return new(
+            AssociationState,
+            _options.RemoteEndpoint,
+            _options.LocalEndpoint,
+            _options.OutboundStreams,
+            _options.InboundStreams,
+            _options.DefaultPayloadProtocolIdentifier,
+            Interlocked.Read(ref _sentMessages),
+            Interlocked.Read(ref _receivedMessages));
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        if (_disposed)
+        {
+            return;
+        }
+
+        _disposed = true;
+        _associationState = SctpAssociationState.Closed;
+        _socket.Dispose();
+    }
+
+    private void ThrowIfDisposed()
+    {
+        if (_disposed)
+        {
+            throw new ObjectDisposedException(nameof(NativeSctpSocketAdapter));
+        }
+    }
+}