Woof.Net.WebSockets 6.0.1

Woof.Net.WebSockets

Full featured, multi-platform high-level WebSocket client and server.

Features:

WebSocket Server, WebSocket client. You can build a WS API. A fast communication channel between any number of clients and the server. It's way faster than REST, it's almost real-time. Most online exchanges use it. The client can be used to access them. Also, the client can receive notifications from server immediately. It doesn't have to query the server all the time.

It also supports streaming. So it can stream audio, video and other data very fast. Streaming means you can request any part of the stream any time. No need to download a complete file.

Authentication is built in. Just implement IAuthenticationProvider and you can use your secure API keys, secrets and message signing. It works with real world crypto exchanges APIs.

A big part of the project will be used for a P2P library soon.

Replaces / deprecates:

Woof.WebSocket. This is the new version of the package. It's almost completely rewritten. The old package is deprecated. A huge number of bugs were fixed sice the last version. It's faster and way more reliable. It also contains some built in API to test the connection and identify the end points.

This package doesn't require the users to write their own authentication logic. The only thing that has to be implemented to make the authenticated calls work is IAuthenticationProvider. It is not built in because it would depend on the user's backend.

Requirements:

• WebSocket client and server supporting any supprotocol and API.
• Comaptible with other clients and servers.
• Built-in subprotocol for fast and reliable message exchange.
• Support for unreliable connections, servers and clients.
• Support for any kind of authentication backend.
• Fully asynchronous, modern implementation.
• Simplicity (minimal implementation is trivial).
• Performance.
• Security (secure authentication and message signing support).
• Reliability (a test bench included).

Q/A:

Q: Works on Linux?
A: Works on anything that runs .NET 5.0 or higher.

Q: Dependencies?
A: .NET 5.0, protobuf-net.

Q: Some legacy support, for like .NET Core or .NET Framework?
A: No. But feel free to port it yourself.

Q: Thread-safe?
A: Yes. Tested. Tested. Then tested some more.

Q: Asynchronous?
A: Task based. Fully asynchronous.

Q: Will the server work with clients in other environments (non .NET)?
A: Yes. WOOF codec uses compatible Google Protocol Buffer serializer available for many environments. It's relatively easy to make your own codec using JSON or any other object serializer.

Q: Why Protocol Buffers?
A: Because it efficient (small serialized size), fast (simple algorithm, fixed size reads), well established (invented by Goolge, developed by active community).

Q: Where can I find an example of a client written in language x?
A: Be the first to write it and don't forget to send a pull request.

Q: Can custom subprotocols be used with WebSocket transport?
A: Yes. Any subprotocol can be used, all it takes is to implement SubProtocolCodec abstract class. Do JSON as an excercise 😉

Q: So why use this Client and Server without a subprotocol?
A: A great deal of the transport hand-shaking already done. Tidy structure to implement. And you DO have a good WOOF subprotocol based on Protocol Buffers.

Q: Can it be done simpler?
A: No. I really tried. This is as simple as it gets.

Q: Wow, neat DI there 😉 But what if my IAuthenticationProvider implementation throws an exception? I don't see it anywhere, is it a bug?
A: No. It's a feature. Check the Exception property of the DecodeResult in your OnMessageReceived handler. It's there to be handled in your code.

Q: About the last one, isn't that dangerous? I can have non-breaking (silent) exception in authentication code.
A: You still have IsSignatureValid false and IsUnauthorized true in DecodeResult. Do use them.

Q: Will stream download block the channel?
A: Yes. Multiple messages can't be exchanged at the same time. Consider starting another server instance listening on a different end point just for streaming.

Q: AsyncEventHandler? WTF?
A: Just implement the async delagate. Await async calls inside. It will work! Avoid async void! Do not block async thread!

Q: Will there ever be a proper documentation for that package?
A: It's possible. I'm working on it.

Q: How about the code changes? Is it stable?
A: We'll see. I'll try my best to avoid it, but expect some refactoring needed when the second digit of the version will change.

Q: Why is there so many things moved to Woof.Net namespace?
A: I'm working on UDP communication. The code is meant to be reused for that purpose.

Q: Wait, what, UDP, like with "UDP hole punching", like in Skype?
A: Exactly.

Q: I found a bug in your code!
A: Please kindly add an issue on Github ASAP.

Usage:

First time: Pull the Git repository. Run the provided test bench. See the test source. There is full documentation in XMLdoc.<br/> Not first time: Just install Woof.Net.WebSockets with NuGet.

READ:

• Docs/Basics.md to understand the basics,
• Docs/API-guidelines.md file before defining your own API messages.

Disclaimer:

This package is made for pros. For now. Using it requires some experience in making network based applications and using some basic DI. It makes implementing WebSocket APIs way easier, but it's not a trivial task using ANY programming library. The goal of the package is to move the low-level protocol handling out of the way. It's meant to make things like authentication or exception handling as simple as it gets. It doesn't mean it's simple per se. Let's say with this package is as simple as using REST, or even a little easier.