lulchat/proto.md

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

1. 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 the deflate compression algorithm for each message.

2. 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 client connect 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 websocket 1001 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