NexNet.Asp 0.9.1

This package adds the WebSocket and custom HttpSocket negotiation transport protocol and middleware to ASP.NET servers for integration with NexNet Servers.

NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional, multiplexing, and event-driven functionality into applications. This framework streamlines the transmission of data bidirectionally between servers and clients with resilient connections.

Features

• Automatic reconnection upon timeout or socket losing connection.
• High performance Socket and Pipeline usage.
• Multiple transports and easy extensibility.
• Strong Typed Hubs & Clients.
• Server ↔ Client communication
  • Cancellable Invocations
  • Streaming byte data via INexusDuplexPipe with built-in congestion control.
  • Streaming classes/structs data via NexusChannel<T>
  • Multiplexing method invocations
  • Proxies can return:
    • void for "fire and forget" invocation situations such as notifications.
    • ValueTask for waiting for invocation completion.
    • ValueTask<T> which will return a value from the remote invocation method.
• Server can message multiple connected clients with a single invocation.
• Automatic reconnection of clients upon timeout or loss of connection.
• Thorough use of ValueTasks in hot paths for reduced invocation overhead.
• Ping system to detect timeouts from client and server side.
• No reflection. All hubs and proxies are Source Generated by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs.
• Full asynchronous TPL usage throughout socket reading/writing, processing and execution of invocations and their return values.
• Minimal external package requirements.
• Optional server integration with ASP.NET Core, which enables features such as authentication, proxying, and running multiple Nexus servers on the same application.

Transports Supported

• Unix Domain Sockets (UDS)
• TCP
• TLS over TCP
• QUIC (UDP)
• WebSockets
• HttpSockets (Custom HTTP Negotiation)

Unix Domain Sockets (UDS) Unix Domain Sockets offer the highest efficiency for inter-process communication due to minimal overhead. UDS are suitable when processes communicate on the same host, providing optimal performance without network stack overhead.

TCP

TCP supports reliable network and internet communication. It is the fastest transport method following Unix Domain Sockets, offering reliable, ordered packet delivery over IP networks.

TLS over TCP

TLS over TCP enables secure, encrypted communication using SslStream on both server and client ends. While it maintains good performance, it introduces additional overhead due to encapsulation—using a Socket wrapped by a NetworkStream, further wrapped by an SslStream—making it less performant compared to UDS and plain TCP.

QUIC (UDP)

QUIC is a reliable UDP-based protocol guaranteeing packet transmission, order integrity, and resilience against IP and port changes, such as transitions from Wi-Fi to cellular connections. Implementation requires installing the libmsquic library (sudo apt install libmsquic on Ubuntu) and including the NexNet.Quic NuGet package.

WebSockets (ASP.NET Core)

WebSockets enable real-time, bidirectional data exchange between client and server over persistent TCP connections. NexNet utilizes Binary WebSocket streams, which introduce a minor overhead—specifically, 4 bytes per message header/data frame transmitted.

HttpSockets (ASP.NET Core - Custom HTTP Negotiation)

HttpSockets establish a bidirectional, long-lived data stream by upgrading a standard HTTP connection. Similar to WebSockets in connection upgrade methodology, HttpSockets differ by eliminating WebSocket-specific message header overhead. After connection establishment, the stream is directly managed by the NexNet server, minimizing transmission overhead. The server requires an ASP.NET Core server.

Additional transports can be added wit relative ease as long as the new transport guarantees order and transmission.

ASP.NET Server Integration

The NexNet.Transports.Asp package allows direct integration of NexNet servers into ASP.NET Core applications. It integrates into middleware pipelines, simplifying configuration, routing, and dependency injection.

The package supports integration of NexNet server using WebSocket and HttpSocket connections, enabling easy management and proxying via common reverse proxies such as Nginx. This allows for potential improved connection handling, load balancing, and security.

Abstracting the server away from direct connections can have some advantages such as th following:

• Proxying HTTP connections through reverse proxies provides SSL/TLS termination, reducing cryptographic overhead on application servers.
• Enables centralized traffic management, simplifying enforcement of security policies (e.g., rate-limiting, IP allowlisting, header validation).
• Facilitates consistent logging, monitoring, and metrics collection at proxy level, aiding operational visibility and troubleshooting.
• Provides an additional layer for DDoS mitigation and protection against common web vulnerabilities.
• Allows for additional authentication with the connection prior to handing the connection to the NexusServer.

Sample ASP.NET Server

var builder = WebApplication.CreateBuilder(args);
// If the connection is proxied setup the header forwards.
builder.Services.Configure<ForwardedHeadersOptions>(o => o.ForwardedHeaders = ForwardedHeaders.All);

// Optionally add authentication.  Bearer shown for simplicity.
builder.Services.AddAuthentication().AddBearerToken("BearerTokenScheme", ...);
builder.Services.AddAuthorization();

// Add the Nexus server to the services.  This allows for DI on the ServerNexus constructor
builder.Services.AddNexusServer<ServerNexus, ServerNexus.ClientProxy>();

var app = builder.Build();

// Eanble the headers and authentication.
app.UseForwardedHeaders();
app.UseAuthentication();
app.UseAuthorization();

// Enable, configure and start the nexus. Use UseWebSocketNexusServerAsync for a WebSocket connection instead.
await app.UseHttpSocketNexusServerAsync<ServerNexus, ServerNexus.ClientProxy>(c =>
{
    // Set the connection mapping path.
    c.Path = "/nexus";
    
    // Optionally enable authentication and the scheme to apply.
    c.AspEnableAuthentication = true;
    c.AspAuthenticationScheme = "BearerTokenScheme";
}).StartAsync(app.Lifetime.ApplicationStopped); // Stop the Nexus server upon ASP stopping.

Sample Client Connecting to ASP.NET Server

// Use WebSocketClientConfig for a WebSocket connection.
var config = new HttpSocketClientConfig()
{
    Url = new Uri("http://127.0.0.1:9001/nexus"), // The URI will need to change to ws:// or wss:// for a websocket connection
    AuthenticationHeader = new AuthenticationHeaderValue("Bearer", "SecretTokenValue") // Optional auth header.
};

// Create the client with the configuration.
var client = ClientNexus.CreateClient(config, new ClientNexus());

// Await the connection.  Will throw if the optional authentication fails.
await client.ConnectAsync();

ASP.NET Proxying Configurations

A non-exhaustive list of proxy configurations that are known to work with ASP.NET

Nginx

Below is a simple configuration that will allow for proxy integration with an ASP.NET Core server

server {
    server_name example.com;
    location / {
        proxy_pass         http://backend;
        proxy_http_version 1.1;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection $connection_upgrade;
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }