dotnet / WatsonTcp

WatsonTcp WatsonTcp is the fastest, easiest, most efficient way to build TCP-based clients and servers in C# with integrated framing, reliable transmission, and fast disconnect detection. **IMPORTANT** WatsonTcp provides framing to ensure message-level delivery which also dictates that you must either 1) use WatsonTcp for both the server and the client, or, 2) ensure that your client/server exchange messages with the WatsonTcp node using WatsonTcp's framing. Refer to for a reference on WatsonTcp message structure.• If you want a library that doesn't use framing, but has a similar implementation, use SuperSimpleTcp• If you want a library that doesn't use framing and provides explicit control over how much data to read, use CavemanTcp .NET Foundation This project is part of the .NET Foundation along with other projects like the .NET Runtime. Contributions Special thanks to the following people for their support and contributions to this project! @brudo @MrMikeJJ @mikkleini @pha3z @crushedice @marek-petak @ozrecsec @developervariety @NormenSchwettmann @karstennilsen @motridox @AdamFrisby @Job79 @Dijkstra-ru @playingoDEERUX @DuAell @syntacs @zsolt777 @broms95 @Antwns @MartyIX @Jyck @Memphizzz @nirajgenius @cee-sharp @jeverz @cbarraco @DenisBalan @Markonius @Ahmed310 @markashleybell @thechosensausage @JVemon @eatyouroats @bendablegears @Laiteux @fisherman6v6 @wesoos @YorVeX @tovich37 @sancheolz @lunedis @ShayanFiroozi If you'd like to contribute, please jump right into the source code and create a pull request, or, file an issue with your enhancement request. New in v6.1.0 Performance• Rewrote message header parsing to eliminate O(n^2) array allocations and per-byte LINQ overhead; now uses a accumulator with direct byte comparison• Send operations now use pooling instead of allocating new buffers on every iteration Thread Safety• Consolidated from 5 independent instances to a single lock, eliminating race conditions during multi-dictionary operations ( , )• Fixed TOCTOU race in ( then indexer across separate lock acquisitions); now uses • Replaced + event-based sync response matching with in both client and server, eliminating handler registration race conditions and signal loss Bug Fixes• Fixed resource leak in (was commented out, now properly closed)• Replaced busy-wait spin loops in and with • Stale kicked/timed-out client records now automatically purged every 60 seconds (previously accumulated forever) New Features• (client and server, default 256KB) guards against memory exhaustion from oversized or malicious headers• (server, default ) actively rejects connections at capacity; set to for legacy behavior Observability• Added debug-level logging to all previously silent and catch blocks Testing• 10 new automated tests (46 total) covering MaxConnections enforcement, MaxHeaderSize validation, rapid connect/disconnect, concurrent sync requests, SSL, server stop detection, duplicate GUIDs, and send-with-offset Breaking Changes• defaults to . If you relied on accepting connections beyond , set .• All other changes are internal with identical public API and wire protocol. Previous in v6.0.x• Remove unsupported frameworks• Async version of callback• Moving usings inside namespace• Remove obsolete methods• Mark non-async APIs obsolete• Modified test projects to use async• Ensured background tasks honored cancellation tokens• Ability to specify a client's GUID before attempting to connect Architecture Refer to ARCHITECTURE.md for a detailed overview of the internal design, message flow, threading model, and key design decisions. For the wire protocol specification (header format, delimiter, payload layout), see FRAMING.md. Test Applications Test projects for both client and server are included which will help you understand and exercise the class library. The project provides -compatible xUnit tests suitable for CI/CD pipelines. SSL WatsonTcp supports data exchange with or without SSL. The server and client classes include constructors that allow you to include fields for the PFX certificate file and password. An example certificate can be found in the test projects, which has a password of 'password'. To Stream or Not To Stream... WatsonTcp allows you to receive messages using either byte arrays or streams. Set if you wish to consume a byte array, or, set if you wish to consume a stream. It is important to note the following:• When using • The message payload is read from the stream and sent to your application• The event is fired asynchronously and Watson can continue reading messages while your application processes• When using • If the message payload is smaller than , the data is read into a and sent to your application asynchronously• If the message payload is larger than , the underlying data stream is sent to your application synchronously, and WatsonTcp will wait until your application responds before continuing to read• Only one of and should be set; will be used if both are set Including Metadata with a Message Should you with to include metadata with any message, use the or method that allows you to pass in metadata ( ). Refer to the , , , and projects for a full example. Keys must be of type . Note: if you use a class instance as either the value, you'll need to deserialize on the receiving end from JSON. This is not necessary if you are using simple types (int, string, etc). Simply cast to the simple type. **IMPORTANT** Metadata is serialized into the message header as JSON, increasing header size. While v6.1.0 significantly improved header parsing performance (eliminating O(n^2) allocations), it is still recommended to keep metadata small (less than 1KB) as large metadata increases JSON serialization overhead and network transfer time. Use to control the maximum allowed header size (default 256KB). Local vs External Connections **IMPORTANT**• If you specify as the listener IP address in WatsonTcpServer, it will only be able to accept connections f…