3.0 KiB
lulchat protocol
Welcome to lulchat's protocol documentation. Here you will find everything you need to know if you want to create your own lulchat server or client.
Please take notice that references to webRTC in this guide should be ignored at the moment, as video and voice calls are not yet implemented.
Preface
lulchat relies on HTTP, webRTC and websocket technologies. We use this in order to bypass firewall restrictions in certain areas like universities, 4G networks, CGNAT and the like. To initiate a connection to lulchat, you will at least need a capable HTTP client coupled with something that can allow you to send and receive websocket messages. webRTC support in your client not required, although recommended. However, it is required if you want to do video and voice calls.
When we refer to data types, always assume that they are being sent over the wire in network-byte order (big endian).
Usernames
Usernames must only contain alphanumeric characters, numbers, and underscores. Must contain between 1 and 21 characters. The following RegexP validates all usernames:
^[A-Za-z0-9_]{1,21}$
Websocket
This section will teach you how to connect and commit actions on the websocket server.
Handshake
-
Initiate an HTTP connection to
/ws
using a capable websocket client. Most hosts will require SSL.In the
Sec-WebSocket-Protocol
header, include the following extensions:lulchat; permessage-deflate
Absence of either of those extensions will result in a failed handshake, as they are required.
permessage-deflate
enforces the use of thedeflate
compression algorithm for each message. -
Send a websocket
connect
message. Failing to send this message within 7 seconds will abort the connection. The only thing you can send at this point is a clientconnect
message. Sending anything else, including a websocket ping, will abort the connection. Failing to authenticate using a valid username or key will abort the connection. Specifying an invalid protocol version may abort the connection.If the server closes the connection, a
server_message
is sent, followed by a websocket1001
close sequence.On success, the client will receive a
connect_ack
.The user is now authenticated.
Server messages format specification
Server opcodes
0 server_message
1 connect_ack
2 channel_subscribe
3 channel_unsubscribe
4 channel_message
5 channel_message_edit
6 channel_message_delete
7 channel_server_message
8 channel_usertyping
9 channel_join
10 channel_leave
11 channel_setting_update
12 channel_message_clear
Server message format
server_message:
<uChar> 0
<uChar> Message title strlen
<String> Message title
<String> Message
connect_ack:
<uChar> 1
Client messages format specification
Client opcodes
0 connect
Client message format
connect:
<uChar> 0
<uShort> Client version. "100" translates to "1.0.0"
<uChar> Client name strlen
<String> Client name
<uChar> Username strlen
<String> Username
<String> PGP key