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

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

• Windows
• Linux
• MacOS

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.

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).

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:

Example:

{
  "type": "create",
  "size": 10
}

{
  "type": "create"
}

Response:

Example:

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

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:

Example:

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

Response:

Example:

{
  "type": "join",
  "size": 4
}

{
  "type": "join"
}

Indicates that a client has left a room.

Response:

Example:

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

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:

Example:

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

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.

Cubic
A multiplayer WebGL voxel sandbox game.

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

Chat
A simple chat application.

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.