From 9d98e6a34674f5ef18a7cb58850f8a6a746d78be Mon Sep 17 00:00:00 2001 From: DJGosnell Date: Sun, 17 Sep 2023 01:28:27 -0400 Subject: [PATCH 1/4] Expanded readme for new features. --- README.md | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9a864c9..aff49c5 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ # NexNet [![Action Workflow](https://github.com/Dtronix/NexNet/actions/workflows/dotnet.yml/badge.svg)](https://github.com/Dtronix/NexNet/actions) [![NexNet](https://img.shields.io/nuget/v/NexNet.svg?maxAge=60)](https://www.nuget.org/packages/NexNet) [![NexNet.Generator](https://img.shields.io/nuget/v/NexNet.Generator.svg?maxAge=60)](https://www.nuget.org/packages/NexNet.Generator) [![NexNet.Quic](https://img.shields.io/nuget/v/NexNet.Quic.svg?maxAge=60)](https://www.nuget.org/packages/NexNet.Quic) -NexNet is a .NET real-time asynchronous networking library that provides bidirectional communication between a server and multiple clients. +NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional event-driven functionality into their applications. This framework streamlines the transmission of updates bidirectionally between server-side code and connected clients with resilient communication channels. - - Depends upon [MemoryPack](https://github.com/Cysharp/MemoryPack) for message serialization. Internally packages Marc Gravell's [Pipelines.Sockets.Unofficial](https://github.com/Dtronix/Pipelines.Sockets.Unofficial/tree/nexnet-v1) with additional performance modifications for Pipeline socket transports. +Depends upon [MemoryPack](https://github.com/Cysharp/MemoryPack) for message serialization. Internally packages Marc Gravell's [Pipelines.Sockets.Unofficial](https://github.com/Dtronix/Pipelines.Sockets.Unofficial/tree/nexnet-v1) with additional performance modifications for Pipeline socket transports. ## Usage @@ -34,7 +33,6 @@ partial class InvocationSampleClientNexus [Nexus(NexusType = NexusType.Server)] partial class InvocationSampleServerNexus { - private long _counter = 0; public void UpdateInfo(int userId, int status, string? customStatus) { // Do something with the data. @@ -43,9 +41,6 @@ partial class InvocationSampleServerNexus public ValueTask UpdateInfoAndWait(int userId, int status, string? customStatus) { // Do something with the data. - if(_counter++ % 10000 == 0) - Console.WriteLine($"Counter: {_counter}"); - return default; } @@ -88,15 +83,15 @@ MaxWarmupIterationCount=3 MinIterationCount=3 MinWarmupIterationCount=1 ## Method Invocation Table Some methods are handled differently based upon the arguments passed and there are limitations placed upon the types of arguments which can be used together. Most of these incompatibilities handled with Diagnostic Errors provided by the `NexNet.Generator`. Below is a table which shows valid combinations of arguments and return values. -| | CancellationToken | NexusDuplexPipe | Args | -|--------------------|-------------------|-----------------|------| -| void | | | X | -| ValueTask | X | | X | -| ValueTask | | X | X | -| ValueTask<T> | X | | X | +| | CancellationToken | INexusDuplexPipe | INexusChannel | Args | +|--------------|-------------------|------------------|------------------|------| +| void | | | | X | +| ValueTask | X | | | X | +| ValueTask | | X | X | X | +| ValueTask | X | | | X | Notes: -- `CancellationToken`s can't be combined with `NexusDuplexPipe` due to pipes having built-in cancellation/completion notifications. +- `CancellationToken`s can't be combined with `NexusDuplexPipe` nor `INexusChannel` due to pipes/channels having built-in cancellation/completion notifications. - `CancellationToken` must be at the end of the argument list like standard conventions. ## Duplex Pipe Usage @@ -130,6 +125,8 @@ Each session is assigned a unique hub instance, ensuring that data is not shared - Multiple transports and easy extensibility. - Server <-> Client communication - Cancellable Invocations + - Streaming byte data via `INexusDuplexPipe` + - Streaming classes/structs data via `NexusChannel` - Proxies can return: - void for "fire and forget" invocation situations such as notifications. - ValueTask whcih waiting for invocation completion. @@ -140,7 +137,7 @@ Each session is assigned a unique hub instance, ensuring that data is not shared - Ping system to detect timeouts from cline tand server side. - No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. - Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. -- Minimal package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) +- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) ## Transports Supported - Unix Domain Sockets (UDS) @@ -156,7 +153,4 @@ Each session is assigned a unique hub instance, ensuring that data is not shared **QUIC (UDP)** s a UDP protocol which guarantees packet transmission, order and survives a connection IP and port change such as a connection switching from WiFi to celular. It requires the `libmsquic` library which can be installed on linux/unix based systems via the local app pacakge manager. Ubuntu: `sudo apt install libmsquic`. Must install the `NexNet.Quic` Nuget package to add the Quic transport. -Additional transports can be added easily as long as the transports guarantees order and transmission. - -## Notes -This project is in development and is subject to significant change. +Additional transports can be added easily as long as the transports guarantees order and transmission. \ No newline at end of file From fb93c0e34d047eb0cdd3ad5f38deb2000f3d7d61 Mon Sep 17 00:00:00 2001 From: DJGosnell Date: Sun, 17 Sep 2023 01:51:55 -0400 Subject: [PATCH 2/4] Added readme for each nuget package. Added NuGet description for Quic package. --- src/NexNet.Generator/README.md | 39 ++++++++++++++++++++++++++++++ src/NexNet.Quic/NexNet.Quic.csproj | 3 ++- src/NexNet.Quic/README.md | 39 ++++++++++++++++++++++++++++++ src/NexNet.props | 2 ++ src/NexNet/NexNet.csproj | 2 +- src/NexNet/README.md | 39 ++++++++++++++++++++++++++++++ 6 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 src/NexNet.Generator/README.md create mode 100644 src/NexNet.Quic/README.md create mode 100644 src/NexNet/README.md diff --git a/src/NexNet.Generator/README.md b/src/NexNet.Generator/README.md new file mode 100644 index 0000000..32d7c9d --- /dev/null +++ b/src/NexNet.Generator/README.md @@ -0,0 +1,39 @@ +This package is the NexNet source code generator for all client and server Nexus classes. + +NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional event-driven functionality into their applications. This framework streamlines the transmission of updates bidirectionally between server-side code and connected clients with resilient communication channels. + +## Features +- Automatic reconnection upon timeout or socket losing connection. +- High performance Socket and Pipeline usage. +- Multiple transports and easy extensibility. +- Server <-> Client communication + - Cancellable Invocations + - Streaming byte data via `INexusDuplexPipe` + - Streaming classes/structs data via `NexusChannel` + - Proxies can return: + - void for "fire and forget" invocation situations such as notifications. + - ValueTask whcih waiting for invocation completion. + - ValueTask 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 cline tand server side. +- No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. +- Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. +- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) + +## Transports Supported +- Unix Domain Sockets (UDS) +- TCP +- TLS over TCP +- QUIC (UDP) + +**Unix Domain Sockets** are the most efficient as they encounter the least overhead and is a good candidate for inter process communication. + +**TCP** allows for network and internet communication. Fastest option next to a UDS. + +**TLS over TCP** allows for TLS encryption provided by the SslStream on both the server and client. This is still fast, but not as fast as either prior options as it creates a Socket, wrapped by a Network stream wrapped by a SslStream. + +**QUIC (UDP)** s a UDP protocol which guarantees packet transmission, order and survives a connection IP and port change such as a connection switching from WiFi to celular. It requires the `libmsquic` library which can be installed on linux/unix based systems via the local app pacakge manager. Ubuntu: `sudo apt install libmsquic`. Must install the `NexNet.Quic` Nuget package to add the Quic transport. + +Additional transports can be added easily as long as the transports guarantees order and transmission. \ No newline at end of file diff --git a/src/NexNet.Quic/NexNet.Quic.csproj b/src/NexNet.Quic/NexNet.Quic.csproj index 5993a18..acc6cfa 100644 --- a/src/NexNet.Quic/NexNet.Quic.csproj +++ b/src/NexNet.Quic/NexNet.Quic.csproj @@ -1,6 +1,7 @@ - + + Quic transport protocol for NexNet. true diff --git a/src/NexNet.Quic/README.md b/src/NexNet.Quic/README.md new file mode 100644 index 0000000..5a6668b --- /dev/null +++ b/src/NexNet.Quic/README.md @@ -0,0 +1,39 @@ +This package adds the Quic transport protocol to NexNet. + +NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional event-driven functionality into their applications. This framework streamlines the transmission of updates bidirectionally between server-side code and connected clients with resilient communication channels. + +## Features +- Automatic reconnection upon timeout or socket losing connection. +- High performance Socket and Pipeline usage. +- Multiple transports and easy extensibility. +- Server <-> Client communication + - Cancellable Invocations + - Streaming byte data via `INexusDuplexPipe` + - Streaming classes/structs data via `NexusChannel` + - Proxies can return: + - void for "fire and forget" invocation situations such as notifications. + - ValueTask whcih waiting for invocation completion. + - ValueTask 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 cline tand server side. +- No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. +- Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. +- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) + +## Transports Supported +- Unix Domain Sockets (UDS) +- TCP +- TLS over TCP +- QUIC (UDP) + +**Unix Domain Sockets** are the most efficient as they encounter the least overhead and is a good candidate for inter process communication. + +**TCP** allows for network and internet communication. Fastest option next to a UDS. + +**TLS over TCP** allows for TLS encryption provided by the SslStream on both the server and client. This is still fast, but not as fast as either prior options as it creates a Socket, wrapped by a Network stream wrapped by a SslStream. + +**QUIC (UDP)** s a UDP protocol which guarantees packet transmission, order and survives a connection IP and port change such as a connection switching from WiFi to celular. It requires the `libmsquic` library which can be installed on linux/unix based systems via the local app pacakge manager. Ubuntu: `sudo apt install libmsquic`. Must install the `NexNet.Quic` Nuget package to add the Quic transport. + +Additional transports can be added easily as long as the transports guarantees order and transmission. \ No newline at end of file diff --git a/src/NexNet.props b/src/NexNet.props index 80c9fc2..548d0a5 100644 --- a/src/NexNet.props +++ b/src/NexNet.props @@ -16,8 +16,10 @@ true rpc sockets uds tcp tls quic secure source generator logo-128.png + README.md + \ No newline at end of file diff --git a/src/NexNet/NexNet.csproj b/src/NexNet/NexNet.csproj index 4fe09b4..10b50a6 100644 --- a/src/NexNet/NexNet.csproj +++ b/src/NexNet/NexNet.csproj @@ -5,7 +5,7 @@ enable $(DefineConstants);SOCKET_STREAM_BUFFERS;RANGES true - Communication system to two way communication between a single server and multiple clients. + A real-time asynchronous networking library that provides bidirectional communication between a server and multiple clients. diff --git a/src/NexNet/README.md b/src/NexNet/README.md new file mode 100644 index 0000000..15d625a --- /dev/null +++ b/src/NexNet/README.md @@ -0,0 +1,39 @@ +This package is the core functionality for NexNet. + +NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional event-driven functionality into their applications. This framework streamlines the transmission of updates bidirectionally between server-side code and connected clients with resilient communication channels. + +## Features +- Automatic reconnection upon timeout or socket losing connection. +- High performance Socket and Pipeline usage. +- Multiple transports and easy extensibility. +- Server <-> Client communication + - Cancellable Invocations + - Streaming byte data via `INexusDuplexPipe` + - Streaming classes/structs data via `NexusChannel` + - Proxies can return: + - void for "fire and forget" invocation situations such as notifications. + - ValueTask whcih waiting for invocation completion. + - ValueTask 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 cline tand server side. +- No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. +- Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. +- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) + +## Transports Supported +- Unix Domain Sockets (UDS) +- TCP +- TLS over TCP +- QUIC (UDP) + +**Unix Domain Sockets** are the most efficient as they encounter the least overhead and is a good candidate for inter process communication. + +**TCP** allows for network and internet communication. Fastest option next to a UDS. + +**TLS over TCP** allows for TLS encryption provided by the SslStream on both the server and client. This is still fast, but not as fast as either prior options as it creates a Socket, wrapped by a Network stream wrapped by a SslStream. + +**QUIC (UDP)** s a UDP protocol which guarantees packet transmission, order and survives a connection IP and port change such as a connection switching from WiFi to celular. It requires the `libmsquic` library which can be installed on linux/unix based systems via the local app pacakge manager. Ubuntu: `sudo apt install libmsquic`. Must install the `NexNet.Quic` Nuget package to add the Quic transport. + +Additional transports can be added easily as long as the transports guarantees order and transmission. \ No newline at end of file From c2d915d5eb08387aeee7c1d7e4d4161d1dff8443 Mon Sep 17 00:00:00 2001 From: DJGosnell Date: Sun, 17 Sep 2023 02:14:13 -0400 Subject: [PATCH 3/4] Added more documentation and reorder for clarity. --- README.md | 47 ++++++++++++++++++---------------- src/NexNet.Generator/README.md | 2 +- src/NexNet.Quic/README.md | 2 +- src/NexNet/README.md | 2 +- 4 files changed, 28 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index aff49c5..06ddc45 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,25 @@ NexNet is a .NET real-time asynchronous networking library, providing developers with the capability to seamlessly incorporate server and client bidirectional event-driven functionality into their applications. This framework streamlines the transmission of updates bidirectionally between server-side code and connected clients with resilient communication channels. -Depends upon [MemoryPack](https://github.com/Cysharp/MemoryPack) for message serialization. Internally packages Marc Gravell's [Pipelines.Sockets.Unofficial](https://github.com/Dtronix/Pipelines.Sockets.Unofficial/tree/nexnet-v1) with additional performance modifications for Pipeline socket transports. +## Features +- Automatic reconnection upon timeout or socket losing connection. +- High performance Socket and Pipeline usage. +- Multiple transports and easy extensibility. +- Server <-> Client communication + - Cancellable Invocations + - Streaming byte data via `INexusDuplexPipe` with built-in congestion control. + - Streaming classes/structs data via `NexusChannel` + - Proxies can return: + - void for "fire and forget" invocation situations such as notifications. + - ValueTask whcih waiting for invocation completion. + - ValueTask 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 cline tand server side. +- No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. +- Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. +- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) ## Usage @@ -119,26 +137,6 @@ New hub instances are created for each session that connects to the hub. The hub Each session is assigned a unique hub instance, ensuring that data is not shared between different sessions. This design guarantees that each session is independently handled, providing a secure and efficient communication mechanism between the client and server. -## Features -- Automatic reconnection upon timeout or socket losing connection. -- High performance Socket and Pipeline usage. -- Multiple transports and easy extensibility. -- Server <-> Client communication - - Cancellable Invocations - - Streaming byte data via `INexusDuplexPipe` - - Streaming classes/structs data via `NexusChannel` - - Proxies can return: - - void for "fire and forget" invocation situations such as notifications. - - ValueTask whcih waiting for invocation completion. - - ValueTask 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 cline tand server side. -- No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. -- Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. -- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) - ## Transports Supported - Unix Domain Sockets (UDS) - TCP @@ -153,4 +151,9 @@ Each session is assigned a unique hub instance, ensuring that data is not shared **QUIC (UDP)** s a UDP protocol which guarantees packet transmission, order and survives a connection IP and port change such as a connection switching from WiFi to celular. It requires the `libmsquic` library which can be installed on linux/unix based systems via the local app pacakge manager. Ubuntu: `sudo apt install libmsquic`. Must install the `NexNet.Quic` Nuget package to add the Quic transport. -Additional transports can be added easily as long as the transports guarantees order and transmission. \ No newline at end of file +## Dependencies +- [MemoryPack](https://github.com/Cysharp/MemoryPack) for message serialization. +- Internally packages Marc Gravell's [Pipelines.Sockets.Unofficial](https://github.com/Dtronix/Pipelines.Sockets.Unofficial/tree/nexnet-v1) with additional performance modifications for Pipeline socket transports. +- Quic protocol requires `libmsquic` on *nix based systems. [Windows Support](https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/quic/quic-overview) + +Additional transports can be added easily as long as the new transport guarantees order and transmission. \ No newline at end of file diff --git a/src/NexNet.Generator/README.md b/src/NexNet.Generator/README.md index 32d7c9d..4173cb7 100644 --- a/src/NexNet.Generator/README.md +++ b/src/NexNet.Generator/README.md @@ -8,7 +8,7 @@ NexNet is a .NET real-time asynchronous networking library, providing developers - Multiple transports and easy extensibility. - Server <-> Client communication - Cancellable Invocations - - Streaming byte data via `INexusDuplexPipe` + - Streaming byte data via `INexusDuplexPipe` with built-in congestion control. - Streaming classes/structs data via `NexusChannel` - Proxies can return: - void for "fire and forget" invocation situations such as notifications. diff --git a/src/NexNet.Quic/README.md b/src/NexNet.Quic/README.md index 5a6668b..a8c6a15 100644 --- a/src/NexNet.Quic/README.md +++ b/src/NexNet.Quic/README.md @@ -8,7 +8,7 @@ NexNet is a .NET real-time asynchronous networking library, providing developers - Multiple transports and easy extensibility. - Server <-> Client communication - Cancellable Invocations - - Streaming byte data via `INexusDuplexPipe` + - Streaming byte data via `INexusDuplexPipe` with built-in congestion control. - Streaming classes/structs data via `NexusChannel` - Proxies can return: - void for "fire and forget" invocation situations such as notifications. diff --git a/src/NexNet/README.md b/src/NexNet/README.md index 15d625a..fbc19f4 100644 --- a/src/NexNet/README.md +++ b/src/NexNet/README.md @@ -8,7 +8,7 @@ NexNet is a .NET real-time asynchronous networking library, providing developers - Multiple transports and easy extensibility. - Server <-> Client communication - Cancellable Invocations - - Streaming byte data via `INexusDuplexPipe` + - Streaming byte data via `INexusDuplexPipe` with built-in congestion control. - Streaming classes/structs data via `NexusChannel` - Proxies can return: - void for "fire and forget" invocation situations such as notifications. From 53eb2048e5c6771cda76c46daa1a719433b9e0fa Mon Sep 17 00:00:00 2001 From: DJGosnell Date: Sun, 17 Sep 2023 02:15:20 -0400 Subject: [PATCH 4/4] Removed duplicate info. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 06ddc45..e4fe7a7 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ NexNet is a .NET real-time asynchronous networking library, providing developers - Ping system to detect timeouts from cline tand server side. - No reflection. All hubs and proxies are created by the NexNet.Generator project. This allows for fast execution and easier tracing of bugs. - Full asynchronous TPL useage throughout socket reading/writing, processing and execution of invocations and their return values. -- Minimal external package requirements. [MemoryPack](https://github.com/Cysharp/MemoryPack) +- Minimal external package requirements. ## Usage