README.md
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