Implement C# bindings for Transport Services API

[zamderax]

Overview

This issue tracks the implementation of C# bindings for the Transport Services API using the existing FFI interface in src/ffi/.

Implementation Plan

1. Directory Structure

Create the following structure under bindings/csharp/:

bindings/csharp/
├── README.md
├── TransportServices.sln
├── src/
│   └── TransportServices/
│       ├── TransportServices.csproj
│       ├── Native/
│       │   ├── NativeMethods.cs
│       │   ├── NativeTypes.cs
│       │   └── SafeHandles.cs
│       ├── Connection.cs
│       ├── Endpoints.cs
│       ├── Errors.cs
│       ├── Listener.cs
│       ├── Message.cs
│       ├── PathMonitor.cs
│       ├── Preconnection.cs
│       ├── Properties.cs
│       ├── Runtime.cs
│       └── SecurityParameters.cs
├── tests/
│   └── TransportServices.Tests/
│       ├── TransportServices.Tests.csproj
│       ├── ConnectionTests.cs
│       ├── ListenerTests.cs
│       └── IntegrationTests.cs
└── examples/
    ├── Client/
    │   ├── Client.csproj
    │   └── Program.cs
    └── Server/
        ├── Server.csproj
        └── Program.cs

2. Native Interop Layer

NativeMethods.cs

• Define P/Invoke signatures for all FFI functions
• Map C function names to C# methods
• Handle platform-specific library loading (Windows: .dll, Linux: .so, macOS: .dylib)

NativeTypes.cs

• Define C# structs matching FFI types from src/ffi/types.rs
• Use StructLayout attributes for proper memory layout
• Define enums for error codes, connection states, etc.

SafeHandles.cs

• Implement SafeHandle classes for proper resource management
• Ensure handles are properly released when objects are disposed

3. High-Level C# API

Core Classes Implementation

Runtime.cs

• Singleton pattern for runtime management
• Initialize and shutdown FFI runtime
• Handle async/await integration with Tokio runtime

Preconnection.cs

• Builder pattern for connection configuration
• Methods: AddRemote(), AddLocal(), SetTransportProperties()
• InitiateAsync() returns Task
• ListenAsync() returns Task

Connection.cs

• Implement IDisposable for proper cleanup
• Async methods: SendAsync(), ReceiveAsync(), CloseAsync()
• Event handlers for connection state changes
• Properties for querying connection state

Listener.cs

• Implement IDisposable
• AcceptAsync() returns Task
• Methods for managing listening state

Message.cs

• Wrapper around message data and properties
• Support for both byte[] and string content
• Message properties and context

Endpoints.cs

• Classes for LocalEndpoint and RemoteEndpoint
• Support for various identifier types (IP, hostname, port)

Properties.cs

• TransportProperties and ConnectionProperties classes
• Strongly-typed property setters/getters
• Multipath policy configuration

PathMonitor.cs

• Interface change notifications
• Network path monitoring
• Integration with connection migration

4. Build Configuration

TransportServices.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>
  
  <ItemGroup>
    <None Include="../../target/release/libtransport_services.*" 
          CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

5. Platform-Specific Considerations

• Use DllImport with platform-specific library names
• Handle different calling conventions if needed
• Package native libraries appropriately for NuGet

6. Testing Strategy

• Unit tests for each high-level class
• Integration tests with actual network connections
• Mock native calls for isolated testing
• Performance benchmarks

7. Documentation

• XML documentation comments on all public APIs
• README with getting started guide
• Examples demonstrating common use cases
• API reference documentation

8. NuGet Package

• Create .nuspec file for NuGet packaging
• Include native libraries for all supported platforms
• Set up CI/CD for automated package publishing

9. Error Handling

• Convert FFI error codes to C# exceptions
• Implement TransportServicesException hierarchy
• Provide meaningful error messages

10. Memory Management

• Ensure proper cleanup of unmanaged resources
• Use SafeHandle for all native handles
• Implement finalizers where necessary
• Consider using Memory and Span for efficient data transfer

Dependencies

• .NET 6.0 or later
• Native transport_services library built with FFI support
• Platform-specific runtime dependencies

Success Criteria

• Complete API coverage of FFI interface
• Idiomatic C# API following .NET conventions
• Comprehensive test suite
• Published NuGet package
• Documentation and examples
• Cross-platform support (Windows, Linux, macOS)