---

A fast and simple WebSocket relay, built in Rust, that enables a peer-to-peer-like network communication.

• Getting Started
• Protocol
  • Text Protocol
    • create packet
    • join packet
    • leave packet
    • error packet
  • Binary Protocol
• Examples
• Building

Getting Started

Binaries

To get started, you can either build or download the precompiled binaries for your platform:

• Windows
• Linux
• MacOS

Running

The following are the command-line arguments for the application:

relay <IP> <PORT> <HOST>

• <IP> is the IP address that should be bound to, for example: 127.0.0.1
• <PORT> is the port that should be bound to, for example: 8080
• <HOST> is the domain suffix of the origin request header.
  • For example, using example.com will allow requests from example.com, a.example.com, and a.b.example.com, while requests that do not match this suffix will be rejected.
  • If left blank, then the origin header is not checked, and requests from any origin are accepted.

Protocol

Relay uses the concept of rooms, which represent a list of clients that wish to send data between each other. A client can create a room and have other clients join the room. Once inside a room, data can be relayed.

• To create and join rooms, we use the text protocol.
• To send data between clients, we use the binary protocol.

The text protocol uses JSON to communicate between the client and the relay server to create and join rooms.

The binary protocol uses a single byte at the start of your data to indicate the destination (when sending) and the source (when receiving).

Example:

To use the text protocol in JavaScript, you would write:

const webSocket = new WebSocket("<URL>");
webSocket.send(`{"type": "create"}`);

To use the binary protocol in JavaScript, you would write:

const webSocket = new WebSocket("<URL>");
webSocket.send(new Uint8Array(255, 1, 2, 3));

Note: Text can still be sent using the binary protocol, it would just need to be wrapped in a Uint8Array or be sent using the binary opcode (if using a WebSocket library).

Text Protocol

create packet

Creates a new room.

• When creating a room, if an error occurs, an error packet is sent as a response.

• You cannot create a room while you are already inside another room.

Request:

Field	Type	Description
type	string	The value should be "create".
size	number | undefined	Specifies the size of the room. The minimum value is 1, the maximum value is 254, and the default value is 2.

Example:

Creating a room of size 10	Creating a room of size 2 (default)
{ "type": "create", "size": 10 }	{ "type": "create" }

Response:

Field	Type	Description
type	string	The value will be "create".
id	string	The UUID identifier of the room, which is used to join the room.

Example:

{
  "type": "create",
  "id": "f4b087df-1e2c-4482-b434-d23b723cf6d"
}

---

join packet

Joins a room.

• When joining a room, if an error occurs, an error packet is sent as a response.

• You cannot join a room while you are already inside another room.

Request:

Field	Type	Description
type	string	The value should be "join".
id	string	The UUID identifier of the room to join.

Example:

{
  "type": "join",
  "id": "f4b087df-1e2c-4482-b434-d23b723cf6d"
}

Response:

Field	Type	Description
type	string	The value will be "join".
size	number | undefined	The client that sent the "join" packet will receive the number of clients currently in the room (excluding themselves). All other clients in the room will receive the "join" packet without a size field.

Example:

Sender	Everyone else
{ "type": "join", "size": 4 }	{ "type": "join" }

---

leave packet

Indicates that a client has left a room.

Response:

Field	Type	Description
type	string	The value will be "leave".
index	number	The index of the client that has left.

Example:

{
  "type": "leave",
  "index": 0
}

---

error packet

Indicates that an error occurred when either joining or creating a room.

• You can assume that if you get this packet, then you're not in a room.

Response:

Field	Type	Description
type	string	The value will be "error".
message	"InvalidSize" | "AlreadyExists" | "DoesNotExist" | "IsFull"	"InvalidSize" The size parameter in the create packet is not valid. "AlreadyExists" The room already exists. "DoesNotExist" The room does not exist. "IsFull" The room is full.

Example:

{
  "type": "error",
  "message": "DoesNotExist"
}

Binary Protocol

0	1	2	3	...	N
Index	Data

Index:

When sending, the index byte indicates which client the packet should be sent to.

• A value of 255 indicates a broadcast, which means the packet will be sent to everyone in the room (excluding the sender).
• A value between 0 and 254 indicates the index of the client that the packet will be sent to (a client can send to itself).

When receiving, the index byte will contain the index of the sender of the packet.

• A value between 0 and 254 indicates the index of the client that sent the packet.

Data:

The data region contains N user-defined bytes, where N ≥ 0.

Examples

Cubic
A multiplayer WebGL voxel sandbox game.

Share
A real-time, peer-to-peer file transfer platform.

Chat
A simple chat application.

Building

Note: The following instructions assume that you are in a terminal (bash, cmd, etc).

1. Install Rust and Git.
2. Run git clone https://github.com/vldr/relay
3. Navigate to the cloned directory.
4. Run cargo build --release

After the build process finishes, the output executable will be located in the target/release folder.