kWebSocket

kWebSocket is a small library written in Kotlin made to let you quickly build a powerfull WebSocket server. This library uses the power of Kotlin's coroutines to help you build a easily scalable software.

The whole server will run in a pool of a fixed number of thread, each coroutine will be dispatched equally inside of this pool. the server will create one coroutine for the listening socket then each accepted client will run in its own coroutine.

Please note that this library is not yet stable and therefore should not be used in production

In the future kWebsocket should be able to run on the JVM,Native and JavaScript plateforms. But I need the multi-plateform version of thekotlinx.coroutine.core library for that. This repo includes a Kotlin-pure implmentation of the JVM ByteBuffer, SHA1 and UTF8 tools too.

1. Introduction
2. The listeners
3. The messages
4. Clients
5. Interoperability

Introduction

The main class of kWebSocket is called Server. With it you can create, start and stop your server.

here is a quick exemple:

//create our server listening on locahlost, on the port 9999, the last argument is the protocol your server implement (REST,SOAP,etc...)
val server = Server("localhost",9999,null);

//start the server
server.startServer();

//wait for the server coroutine to stop, which is never if you don't use the server.stop() method
server.block();

Simple right? Now you can connect to your server but that is all you can do, to implement computation we are going to use Listeners

Listeners

Listeners are classes that will handle events. An event will be triggered if a client connects, send a message or close its connection. There is two types of Listeners possible: Synchronous Listeners and Asynchronous Listeners

With Synchronous Listeners, the server will dispatch one event at a time to the listener, meaning that will not have to worry about concurrent access and thread safe operation.

here is an exemple of Synchronous Listeners

import seekdasky.kWebSocket.Message.buildTextMessage;
class implSynchronousListener : SynchronousListener(){
    //called when a client send a message
    override fun synchronousProcessEvent(e: Event) {
        val message = buildTextMessage("echo!");
        e.client.send(message);
    }

    //called when a client close its connection
    override fun synchronousProcessClosed(e: Event) {
        println("Client gone!");
    }

    //called when a client connect to the server
    override fun synchronousProcessConnection(c: Client) {
        println("Client connected");
    }

}

To add the listener to the server use the addListener method

val listener = implSynchronousListener();
server.addListener(listener);

Now we have a server that can "echo" our client back, but only one client at a time as the listener is synchronous. Asynchronous listeners are pretty similar, only the name of the methods slightly change. With Asynchronous Listeners the server will be able to dispatch multiple event at the same time to you listener, you MUST take good care of your data to avoid coruption or concurrent modification.

here is an Asynchronous Listener

import seekdasky.kWebSocket.Message.buildTextMessage;
class implAsynchronousListener : AsynchronousListener() {

    override fun processEvent(e : Event){
        val message = buildTextMessage("écho!");
        e.client.send(message);
    }

    override fun processClosed(e : Event){
        println("aaaand now it's gone");
    }

    override fun processConnection(c : Client){
        println("Client connected");
    }
	
}

You can notice that the methods name have changed between synchronous and asynchronous listeners.

How to filter events You can optionally filter the incoming events by overriding the filter method. If the method returns true the Client is allowed to send the event, if not the event will not be dispatched to the listener

exemple

import seekdasky.kWebSocket.Message.buildTextMessage;
class implAsynchronousListener : AsynchronousListener() {

    override fun processEvent(e : Event){
        val message = buildTextMessage("écho!");
        e.client.send(message);
    }

    override fun processClosed(e : Event){
        println("aaaand now it's gone");
    }

    override fun processConnection(c : Client){
        println("Client connected");
    }

    override fun filter(c : Client) : Boolean{
        if(@checkSomething){
            return true
        }else{
            return false
        }
    }
	
}

Messages

As the listeners, there is two types of messages: Unipart Messages and Multipart Messages, but as the multipart messages implementation isn't quite finished yet I will not talk about them. Binary transfert aren't implemented yet either but will be in a close future.

Unipart Messages To use unipart messages you cah simply use the buildTextMessage function contained in the seekdasky.kWebSocket.Message package or build the message from scratch

exemple

//using the buildTextMessage function
val message = buildTextMessage("écho!");

//from scratch
val message = UnipartMessage(OpCode.TEXT);
message.add(text);

To get the string of an incoming message simply do

message.getString();

Clients

The client class is what you will need to use to send your messages to a conected client. The only method you should be using is send, others method being used for internal purposes

The Client object can be reteived in the Event object passed to the listener

exemple

override fun processEvent(e : Event){
    //print some information about the incoming message
    println("ClientInput (message: "+e.message+";length: "+e.message.getContentSize()+";memory: "+e.message.getMemoryTaken()+")");
    //build the response
    val message = buildTextMessage("echo!");
    //send the response
    e.client.send(message); 
}

Interoperability

Having a websocket server is great, but having it interact with the rest of your environnement is better and that is what all the Interop* classes are for

enabling Interop
You can enable Interop by calling the startInteropServer(listeningAddress:String,listeningPort:Int) method, this method will create a new socket that will listen to the given address on the given port. Next, as for the WebSocket part, you need to declare and bind a Listener, implement the InteropListener interface and bind your class to the server with addInteropListener. Please Note that the InteropListeners are asychronous and that you will need to take care of the concurrent data modification problems

data format
To communicate with the Interop server you will need to send your data in a specific way: The first 4 bytes will contain the size of the data you are going to send, then you send your data.

Available wrappers
A wrapper is currently available for PHP, with it you can send and receive data from the Interop server. This will give you a great way to push data to your clients browser using PHP.

You can find this wrapper here : https://git.seekdasky.ovh/SeekDaSKy/kWebSocketInterop_PHP