1# WebSocketServer
2
3Class `WebSocketServer` represents:
4* Server endpoint accepting new `WebSocket` connections,
5* Single connection with client, encapsulated in `WebSocketBase` class.
6
7All operations operations of the class (e.g. accepting new connection or receiving new messages) are blocking. Hence typical usage cases imply initializing server and starting a distinct _server thread_, which will:
8* Call `AcceptNewConnection` when there is no active connection;
9* Until the connection is ended in loop call `Decode`, handle the incoming message and reply with `SendReply`.
10
11The connection might terminate either from client side or by call to `CloseConnection` (gracefully closes connection according to specification) or `Close` (will close both endpoint and active connection).
12
13Interface is designed with trade safety, and all _external threads_ are able to call `SendReply`, `CloseConnection` and `Close`. Note that `SendReply` from an _external thread_ might happen concurrently with `CloseConnection` and `AcceptNewConnection`, so the message might be send to the new connection. To prevent such unexpected behavior, the _external thread_ can set callbacks to be triggered before the connection is finally closed, which is done with `SetCloseConnectionCallback` and `SetFailConnectionCallback` methods.
14
15The following diagram sums up separation of concerns between server and external threads:
16
17```mermaid
18sequenceDiagram
19    participant ExternalThread
20    participant ServerThread
21    participant WebSocketServer
22    participant RemoteClient
23
24    ExternalThread->>WebSocketServer: InitUnixWebSocket()
25    ExternalThread->>ServerThread: spawn
26    par While server thread running
27        ServerThread->>WebSocketServer: AcceptNewConnection()
28        RemoteClient->>WebSocketServer: accept()
29        loop while connected
30            ServerThread->>WebSocketServer: Decode()
31            RemoteClient->>WebSocketServer: recv()
32            alt Successful recv
33                alt Close frame
34                    WebSocketServer->>WebSocketServer: CloseConnection()
35                else Data Frame
36                    ServerThread->>ServerThread: DoHandlingLogic()
37                    ServerThread->>WebSocketServer: SendReply()
38                    WebSocketServer->>RemoteClient: send()
39                end
40            else Failed recv
41                WebSocketServer->>WebSocketServer: CloseConnection()
42            end
43        end
44    and While external thread running
45        loop On event
46            ExternalThread->>WebSocketServer: SendReply()
47            WebSocketServer->>RemoteClient: send()
48        end
49        ExternalThread->>WebSocketServer: Close()
50        WebSocketServer->>WebSocketServer: stop accepting, wait if active Connecting state
51        WebSocketServer->>WebSocketServer: CloseConnection()
52    end
53```
54
55## Connection
56
57`WebSocketServer` incapsulates an active connection with a client. Methods `Decode`, `SendReply`, `CloseConnection` relate to a currently active connection (if any presents). Class maintains connection's state according to RFC6455:
58
59```mermaid
60stateDiagram-v2
61    state Connecting
62    state Open
63    state Closing
64    state Closed
65
66    Closed --> Connecting : call AcceptNewConnection()
67    Connecting --> Open : HttpHandShake() success
68    Connecting --> Closed : HttpHandShake() failure
69    Open --> Closing : call CloseConnection()
70    Closing --> Closed : call CloseConnectionSocket()
71```
72