A lightweight and scalable asynchronous WebSocket listener
This project is considered completed. Reported bugs will be fixed, but there is no plans for new features.
@deniszykov has continued its development, adding support for other platforms in his fork deniszykov/WebSocketListener.
The WebSocketListener class provides simple methods that listen for and accept incoming WebSocket connection requests asynchronously. It is a lightweight listener with an API very similar to the System.Net.TcpListener
class. It does not use the Microsoft's System.Net.WebSockets
namespace.
It works with .NET Standard 2.0 since Version 3.0.0. Version 2.2.4 is .NET/Mono 4.5 compatible.
WebSocketListener has been designed to provide WebSocket connectivity to other applications, in the same way that System.Net.TcpListener
provides TCP connectivity. It is not a communication framework on its own and it does not provide any kind of publisher/subscriber pattern or reliable messaging beyond TCP.
wss://
(secure). More info.StreamReader
and StreamWriter
. Two different WebSocket messages, yield two different streams.Take a look on the performance and load tests on a simple 'echo' server.
This echo server example uses NGINX to serve static files and WebSocket connections through the same port, providing SSL termination for both. It uses Docker and .Net Core 2.0.
WebSocketListener is available through NuGet
PM> Install-Package vtortola.WebSocketListener
Setting up a server and start listening for clients is very similar to a TcpListener
. An listening endpoint and a WebSocket standard is the minimum needed to set up a server.
var server = new WebSocketListener(new IPEndPoint(IPAddress.Any, 8006));
server.Standards.RegisterStandard(new WebSocketFactoryRfc6455());
server.StartAsync();
The class vtortola.WebSockets.Rfc6455.WebSocketFactoryRfc6455
gives support to the RFC 6455, that is the WebSocket standard used at the moment. Future standards can be added in the same way.
Optionally, you can also:
Once the server has started, clients can be awaited asynchronously. When a client connects, a WebSocket
object will be returned:
var client = await server.AcceptWebSocketAsync(cancellationToken);
The client provides means to read and write messages. With the client, as in the underlying NetworkStream
, is possible to write and read at the same time even from different threads, but is not possible to read from two or more threads at the same time, same for writing.
AcceptWebSocketAsync
should be in a loop to continuously accept new clients, also wrapped in a try/catch
since errors in the negotiation process will be thrown here. Take a look to the simple host tutorial.
With the client we can await a message as a readonly stream:
var messageReadStream = await client.ReadMessageAsync(cancellationToken);
Messages are a stream-like objects, so is it possible to use regular .NET framework tools to work with them. The WebSocketMessageReadStream.MessageType
property indicates the kind of content the message contains, so it can be used to select a different handling approach.
The returned WebSocketMessageReadStream
object will contain information from the header, like type of message (Text or Binary) but not the message content, neither the message length, since a frame only contains the frame length rather than the total message length, therefore that information could be missleading.
A text message can be read with a simple StreamReader
. It is worth remember that according to the WebSockets specs, it always uses UTF8 for text enconding:
if(messageReadStream.MessageType == WebSocketMessageType.Text)
{
var msgContent = string.Empty;
using (var sr = new StreamReader(messageReadStream, Encoding.UTF8))
msgContent = await sr.ReadToEndAsync();
}
ReadMessageAsync
should go in a loop, to read messages continuously. Writes and read can be performed at the same time. Take a look to the simple host tutorial.
Also, a binary message can be read using regular .NET techniques:
if(messageReadStream.MessageType == WebSocketMessageType.Binary)
{
using (var ms = new MemoryStream())
{
await messageReadStream.CopyToAsync(ms);
}
}
Writing messages is also easy. The WebSocketMessageReadStream.CreateMessageWriter
method allows to create a write only message:
using (var messageWriterStream = client.CreateMessageWriter(WebSocketMessageType.Text))
Once a message writer is created, regular .NET tools can be used to write in it:
using (var sw = new StreamWriter(messageWriterStream, Encoding.UTF8))
{
await sw.WriteAsync("Hello World!");
}
Also binary messages:
using (var messageWriter = ws.CreateMessageWriter(WebSocketMessageType.Binary))
await myFileStream.CopyToAsync(messageWriter);
Take a look on the WebSocketListener samples.
Copyright (c) 2014 vtortola
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.