Websockets

2023-02-09T16:24:12Z

Andythenuge: /* Sending a message from the server */

Websockets in SocialStack use a non-allocating binary format called bolt in order to be extremely high speed and high throughput, capable of handling over a million messages per second on a single socket link without causing any problems. The server code is in the Api/WebSockets module, and the frontend code is in UI/Functions/WebSocket. Both ends can be setup to create multiple websocket clients or multiple websocket servers but of course a default project creates 1.

Note that the websocket itself does not currently directly support TLS (https), just like the web API as well. Instead that is added by a reverse proxy in front of the API service which is typically [https://www.nginx.com/ nginx] (''pronounced "Engine X"'') in most deployments.

= Sending a message from the server =

To send a custom message through the websocket, you'll need a Writer. Typically these originate from a pool such that they get reused. Here's an example:

<syntaxhighlight lang="csharp">
// Import websocket library
using Api.SocketServerLibrary;

// Get a pooled writer:
var message = Writer.GetPooled();

// Start writing to it (this is a required call). The number is opcode of the message - that's effectively the message identifier on the wire.
message.Start(15);

// Write the contents of the message. See the wiki's reccommendations for some guidance on this.
message.WriteUTF8("Hello world!");

// Write a number:
message.Write((uint)1337);

// Assuming you have a WebSocketClient object:
// WebSocketClient client;
client.Send(message);

// You can send the same message to multiple clients if you want.
// Once you have sent it and you're done, release it. This returns it back to the pool.
message.Release();

</syntaxhighlight>

== Tips on writing a message ==

* Give yourself some flexibility for making changes to the contents of the message, but you don't need too much. You can always just send a message with a different opcode as the newer version format.
* Try to avoid writing strings, particularly things like JSON, as much as possible. Building a typical string on the server is quite expensive for multiple reasons, and if you're trying to make realtime high throughput sockets then JSON is not going to fit the bill.
* However, the ToJson method inside all AutoService's is non-allocating and outputs in to a writer, so it's ok to use that or any equivalent. It internally uses generated code and custom implementations of number writing to avoid all string concatinations and intermediate allocations.
* Favour writing value types. Numbers, floats, dates and so on - are all extremely fast, as they effectively go from the stack and straight to the network buffer.
* WriteCompressed uses a fast compression scheme originally from the MySQL binary protocol which will store a long or ulong in the smallest number of bytes it reasonably can. It's of course always suggested to make your message as small as you can, but sometimes there are instances where a constant length (in bytes) number is useful, such as a length for the message itself.
* If you want to write a length for some currently unknown amount of data, first write a 0 as a fixed size value - usually that's .Write((uint)0) - then write everything you want, then measure the number of bytes written and replace the 0 with the measured size. This avoids needing to create copies of things in memory, and also avoids needing to awkwardly figure out what the length should be by adding things together.

= Receiving the message in the client =

The websocket client library exports a function, registerOpcode, which can be used to register a handler which runs when a message of the given opcode is received. Its job is to then parse the message from the given stream.

<syntaxhighlight lang="javascript">

import webSocket from 'UI/Functions/WebSocket';

...

// Registering opcode 15 sent above
webSocket.registerOpcode(15, (reader) => {

// Read the string:
var helloMessage = reader.readUtf8();

// Read the uint:
var leetNumber = reader.readUInt32();

console.log(helloMessage, leetNumber); // Hello world! and 1337

}, false);

</syntaxhighlight>

= Sending a message from the client =

Like with the server, you'll need a writer. Note that client to server messages always require a size at the start. The javascript websocket library has a Writer class available, which will also internally take care of that size for you:

<syntaxhighlight lang="javascript">

import webSocket from 'UI/Functions/WebSocket';

...

var writer = new webSocket.Writer(15);
writer.writeUtf8("Hello world!");
writer.writeUInt32(1337);

// Send it:
webSocket.send(writer);

</syntaxhighlight>

SocialStack - User contributions [en-gb]

Websockets