Add native SCTP connector

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, endpoint connection planner, and native socket adapter 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, native socket adapter, and client connector added; full production readiness still requires native transport completion and lab verification |
 
 ## Requirements
 

docs/PHASE8_NATIVE_SCTP.md

@@ -47,3 +47,14 @@ 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.
+
+## Connector
+
+`NativeSctpConnector` builds a connection plan, optionally binds the local endpoint, applies `SctpConnectionOptions.ConnectTimeout`, and returns an established `NativeSctpSocketAdapter`.
+
+```csharp
+NativeSctpConnector connector = new();
+NativeSctpSocketAdapter socket = await connector.ConnectAsync(options);
+```
+
+The connector is Linux-native only through `NativeSctpSocketFactory`; unsupported platforms fail before attempting network I/O.

docs/SCTP_TRANSPORT.md

@@ -130,3 +130,5 @@ The probe does not mark the transport production-ready by itself. It is the firs
 `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.
+
+`NativeSctpConnector` performs the client-side bind/connect path and returns an established native adapter.

src/sigtran.net.Tests/Program.cs

@@ -34,6 +34,7 @@
 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("Native SCTP connector reports unsupported platform safely", NativeSctpConnectorReportsUnsupportedPlatformSafely);
 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);
@@ -471,6 +472,26 @@ static void NativeSctpSocketAdapterReportsLifecycleHealth()
     AssertEqual((uint)SctpPayloadProtocolIdentifiers.M3ua, health.DefaultPayloadProtocolIdentifier, "native adapter PPID");
 }
 
+static void NativeSctpConnectorReportsUnsupportedPlatformSafely()
+{
+    NativeSctpConnector connector = new();
+    NativeSctpPlatformCapability capability = NativeSctpPlatform.Probe();
+    SctpConnectionOptions options = new(
+        new SctpEndpoint("127.0.0.1", 2905),
+        connectTimeout: TimeSpan.FromMilliseconds(10));
+
+    if (!capability.CanCreateSocket)
+    {
+        NativeSctpUnavailableException exception = AssertThrows<NativeSctpUnavailableException>(() =>
+            connector.ConnectAsync(options).GetAwaiter().GetResult());
+        AssertEqual(capability.Status, exception.Capability.Status, "native SCTP connector unsupported status");
+    }
+    else
+    {
+        Assert(capability.CanCreateSocket, capability.Describe());
+    }
+}
+
 static void TcapBerElementEncodesShortAndLongLengths()
 {
     Span<byte> shortBuffer = stackalloc byte[8];

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

@@ -0,0 +1,57 @@
+using System.Net.Sockets;
+
+namespace sigtran.net.Layers.SCTP;
+
+/// <summary>
+/// Connects native SCTP client associations.
+/// </summary>
+public sealed class NativeSctpConnector
+{
+    private readonly INativeSctpSocketFactory _socketFactory;
+    private readonly NativeSctpConnectionPlanner _planner;
+
+    /// <summary>Creates a native SCTP connector.</summary>
+    /// <param name="socketFactory">The socket factory.</param>
+    /// <param name="planner">The connection planner.</param>
+    public NativeSctpConnector(
+        INativeSctpSocketFactory? socketFactory = null,
+        NativeSctpConnectionPlanner? planner = null)
+    {
+        _socketFactory = socketFactory ?? new NativeSctpSocketFactory();
+        _planner = planner ?? new NativeSctpConnectionPlanner();
+    }
+
+    /// <summary>Connects a native SCTP association.</summary>
+    /// <param name="options">The SCTP connection options.</param>
+    /// <param name="ct">A cancellation token.</param>
+    /// <returns>The connected native SCTP socket adapter.</returns>
+    public async Task<NativeSctpSocketAdapter> ConnectAsync(SctpConnectionOptions options, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        NativeSctpConnectionPlan plan = await _planner.BuildAsync(options, ct).ConfigureAwait(false);
+        Socket socket = _socketFactory.CreateSocket();
+        NativeSctpSocketAdapter? adapter = null;
+
+        try
+        {
+            if (plan.LocalEndpoint is not null)
+            {
+                socket.Bind(plan.LocalEndpoint);
+            }
+
+            using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
+            timeout.CancelAfter(options.ConnectTimeout);
+            await socket.ConnectAsync(plan.RemoteEndpoint, timeout.Token).ConfigureAwait(false);
+
+            adapter = new NativeSctpSocketAdapter(socket, options, SctpAssociationState.Established);
+            return adapter;
+        }
+        catch
+        {
+            adapter?.MarkFailed();
+            socket.Dispose();
+            throw;
+        }
+    }
+}