Peer2Peer Connector Overview

Peer2Peer Connector is a WebSocket server designed to establish and manage real-time, low-latency connections between clients. It is the core component for enabling seamless peer-to-peer interactions and room management, making it an ideal solution for applications that require real-time data exchange and collaboration.

Key Features

1. Client Connection Management

• Peer2Peer Connector allows multiple clients to connect and communicate with each other in real-time. Upon connection, each client receives a unique identifier, which is used to manage and route messages between peers.
• This unique identifier ensures that messages are accurately directed, whether the communication is between two clients or within a group or room.

2. Room Management

• Peer2Peer Connector supports the creation and management of virtual rooms, where clients can dynamically join, leave, or be removed from rooms.
• Each room is identified by a unique room ID, allowing clients to join rooms based on their needs. This feature is ideal for applications like chat rooms, collaborative workspaces, or multiplayer games.

3. WebRTC Connection Establishment

• Peer2Peer Connector is specifically designed to facilitate the establishment of WebRTC (Web Real-Time Communication) connections between clients. WebRTC enables direct peer-to-peer communication, allowing for high-quality video, audio, and data sharing without intermediaries.
• The server acts as a signaling channel, enabling clients to exchange the necessary signaling data (such as SDP and ICE candidates) required to set up a WebRTC connection seamlessly.

4. Message Routing and Error Handling

• Peer2Peer Connector efficiently routes messages between clients, ensuring accurate and timely delivery of data. It supports various message types, including offers, answers, candidates, and general messages.
• In addition to message routing, Peer2Peer Connector offers robust error handling. If a client attempts to send a message to a non-existent peer or fails to provide the necessary data for a WebRTC connection, the server responds with clear error messages, guiding the client in resolving the issue.

Use Cases

• Real-Time Communication Applications: Ideal for chat applications, video conferencing tools, and collaborative workspaces that require instant communication and data sharing between users.
• Gaming: Facilitates the creation of multiplayer games where players can connect, communicate, and interact in real-time.
• IoT and Smart Devices: Can be used in scenarios where multiple devices need to communicate and coordinate actions in real-time.

Quick usuage

events supported

• Connect: Used to initiate a connection with another client. This message should include data such as the SDP and candidate information.
• Offer: Part of the WebRTC connection process, sent by a client to initiate a peer-to-peer connection.
• Answer: Sent in response to an Offer, completing the WebRTC connection setup.
• Candidate: Contains ICE candidate information necessary for establishing the WebRTC connection.
• Message: General-purpose message type for sending data between connected clients.
• Create_Room: Used to create a new room. The message should include the room and optionally the name of the room, inside data field.
• Join_Room: Used to join a room. The message should include the room inside data field.
• Leave_Room: Used to leave a room. The message should include the room inside data field.
• End_Room: Used to end a room. The message should include the room inside data field.

Notes

• Above mentioned events should be passed to event field.
• Other necessary data should be passed inside data field.

Example

WebSocket Connection

Initial Server Response

let webSocket = new WebSocket("wss://peer2peerconnector.shankarammai.com.np");

When a client successfully connects to the server, the server will send an initial message containing details about the connected client.

Message Structure example

{
    "type": "info",
    "event": "Client_Details",
    "data": {
        "id": "mqCCxD96EcRYmv5sop4YQL"
    },
    "timestamp": "2024-08-15T20:16:08.3438515+01:00",
    "message_id": "eed9d84c-2c88-4428-80eb-84aa35222aa6"
}

Fields Description

• type: (string) The type of the message. For the initial connection message, this will be info.
• event: (string) The event message. In this case, it’s Client_Details, indicating that the message contains information about the connected client.
• data: (object) An object containing specific data related to the message.
  • id: (string) The unique identifier for the connected client. This ID is generated by the server and is used to track the client during the session.
• timestamp: (string) The timestamp indicating when the message was generated by the server, in ISO 8601 format.
• message_id: (string) A unique identifier for the message. This ID is generated by the server and can be used to track and reference this specific message.

Notes

• Ensure that your client application handles the Client_Details message correctly and stores the id for future communication with the server.
• The timestamp is in UTC time and may need to be converted to the client’s local timezone if necessary.

Connecting with another peer

To initiate a WebRTC connection with another peer, you can send a Connect request to the server. The server acts as an intermediary, facilitating the exchange of necessary signaling information between clients.

How to Establish a WebRTC Connection??

While the server itself doesn’t directly connect two clients via WebRTC, it plays a crucial role in enabling the connection. Clients must handle specific events such as Offer, Answer, Candidate, and Message —to successfully establish and manage the WebRTC connection. The proper handling of these messages by the client is essential for a successful peer-to-peer connection.

Example

{
  "event": "Connect",
  "to": "<clientId>",
  "data": {
    "sdp": "sdp",
    "candidate": "candidate"
  }
}

Fields Description

• event (string) "Connect" to initiate a WebRTC connection.
• to: (string, required) The client ID of the peer.
• data: (object, required) Connection details:
  • sdp:(string, required) Session Description Protocol.
  • sdp: (string, required) ICE candidate information

Error Handling

If a client tries to send a message to a peer that does not exist (i.e., the peer with the specified to client ID is not connected), the server will respond with an error message.

Error Message Structure

{
  "type": "error",
  "event": "Not_Found",
  "data": {
    "message": "Client with given 7KjNqESrhhTkEfXgFuaGWJ not found"
  },
  "timestamp": "2024-08-10T13:03:53.4821935+01:00",
  "message_id": "2007f6e7-34e5-4968-8470-f3dee63ce1b1"
}

Fields Description

• type: (string) The type of the message. For errors, this will be "error".
• event: (string) A brief title describing the error. In this case, it is "Not_Found".
• data: (object) An object containing additional details about the error.
  • message: (string) A description of the error, specifically noting that the client with the specified ID could not be found.
• timestamp: (string) The timestamp when the error occurred, in ISO 8601 format.
• message_id: (string) A unique identifier for the error message, generated by the server.

Notes

• Ensure that the to field contains a valid client ID of an active peer.
• Ensure that the data field contains sdp and candidate.
• Handle the "error" type messages in your client application to gracefully manage scenarios where the intended recipient is not available.

Sending Other requests to another client

Clients can communicate with other peers by sending data using a specific message structure. The WebSocket server supports various message types, including offer, answer, candidate, and message. Below is the structure and an explanation of how to send and receive messages between peers.

To establish a WebRTC connection, clients must use the appropriate event. By sending the correct message such as an Offer, Answer, or Candidate the Peer2Peer Connector server will facilitate the connection between peers. It’s essential that clients handle these messages correctly to ensure a successful connection. The Peer2Peer Connector acts as the intermediary, guiding the connection process and ensuring smooth communication between peers.

Sending a message to another client

To send data to another peer, the client needs to send a message in the following format:

Example

To send a simple text message to another peer with the client ID DFPsXj9pygjNDcj2VyGzqQ, the client would send the following message:

{
  "event": "Message",
  "to": "DFPsXj9pygjNDcj2VyGzqQ",
  "data": "hellow world"
}

Fields Description

• event: (string) Event name. This field is an ENUM and can have one of the following values: "Offer", "Answer", "Candidate", "Message".
• to: (string, required) The client ID of the peer to whom the message is being sent.
• data: (object) The content of the message. This can be any string data, object, such as a SIP detail, text message, or other relevant information for your application.

Received Message

When a client sends message to another peer using websocket it receives a message from server, the WebSocket server will send a message with the following structure:

Example

If a peer with the client ID 7TCqx3LCqPux3gQ9auwrH6 sends a message, the receiving client would receive:

{
  "data": "data",
  "from": "7TCqx3LCqPux3gQ9auwrH6",
  "event": "Message"
}

Fields Description

• data: (object) The content of the message that was sent by the other peer.
• from: (string) The client ID of the peer who sent the message.
• event: (string) Event title. For peer-to-peer messages, this will typically be "Offer", "Answer", "Candidate", "Message".

Error Handling

If a client tries to send a message to a peer that does not exist (i.e., the peer with the specified to client ID is not connected), the server will respond with an error message.

Error Message Structure

{
  "type": "error",
  "event": "Not_Found",
  "data": {
    "message": "Client with given 7KjNqESrhhTkEfXgFuaGWJ not found"
  },
  "timestamp": "2024-08-10T13:03:53.4821935+01:00",
  "message_id": "2007f6e7-34e5-4968-8470-f3dee63ce1b1"
}

Fields Description

• type: (string) The type of the message. For errors, this will be "error".
• event: (string) An event. In this case, it is "Not_Found".
• data: (object) An object containing additional details about the error.
  • message: (string) A description of the error, specifically noting that the client with the specified ID could not be found.
• timestamp: (string) The timestamp when the error occurred, in ISO 8601 format.
• message_id: (string) A unique identifier for the error message, generated by the server.

Notes

• Ensure that the to field contains a valid client ID of an active peer.
• Handle the "error" type messages in your client application to gracefully manage scenarios where the intended recipient is not available.

Rooms

This Websocket supports events for room as well. Types that can be used are given below:

• Create_Room
• Join_Room
• Leave_Room
• End_Room

Fields Description

• data: (object) Details of room
• room: (string, optional) Room Id
• name: (string, optional) name of the room
• ecent: (string,required) Type of request. This will typically be "Create_room", "Join_room", "Leave_room", "End_room".

Example of creating room

If you want to create room.

{
  "event": "Create_Room",
  "data": {
    "room": "123456",
    "name": "my room name"
  }
}

Example of creating room response

Response when you send create room request. Clients are the list of clients in the room.

{
  "type": "info",
  "event": "Room_Created",
  "data": {
    "clients": ["WMYFTzZoX778PaiwjyZd59"],
    "name": "my room name",
    "roomId": "123456"
  },
  "timestamp": "2024-08-10T17:52:10.4816503+01:00",
  "message_id": "6e7ca893-26a3-420d-812d-98ea85a896cd"
}

Example of joining room

If you want to join room.

{
  "event": "Join_Room",
  "data": {
    "room": "123456",
  }
}

Example response of joining room

{
  "type": "update",
  "event": "Client_Added",
  "data": {
    "clients": [
      "UnVTfeUbHtbMH4cDoqKaCe",
      "L5RsWjtGXkHTG888LJoa8H"
    ],
    "name": "",
    "room": "hello"
  },
  "timestamp": "2024-08-10T19:19:31.6537518+01:00",
  "message_id": "330db08c-19d3-4e5a-a6bc-d6902f82272c"
}

Example of leaving a room

If you want to leave room.

{
  "event": "Leave_Room",
  "data": {
    "room": "123456",
  }
}

Example response of leaving room to another client

{
  "type": "update",
  "event": "Client_Removed",
  "data": {
    "clients": [
      "UnVTfeUbHtbMH4cDoqKaCe"
    ],
    "name": "",
    "room": "hello"
  },
  "timestamp": "2024-08-10T19:20:07.2508094+01:00",
  "message_id": "1a58b773-68fc-4b46-89d2-fec82e452877"
}

Example response of leaving room to the client requesting the leave

{
  "type": "info",
  "event": "Room_Left",
  "data": {
    "room": "hello"
  },
  "timestamp": "2024-08-10T19:20:07.2508094+01:00",
  "message_id": "1a58b773-68fc-4b46-89d2-fec82e452877"
}

Example of ending a room

If you want to end a room. Only creator can end the room.

{
  "event": "End_Room",
  "data": {
    "room": "123456",
  }
}

Example response of leaving room to all the clients, including the requester

{
  "type": "update",
  "event": "Room_Deleted",
  "data": {
    "clients": [
      "UnVTfeUbHtbMH4cDoqKaCe"
    ],
    "name": "",
    "room": "hello"
  },
  "timestamp": "2024-08-10T19:20:07.2508094+01:00",
  "message_id": "1a58b773-68fc-4b46-89d2-fec82e452877"
}

Notes

• Empty room with no clients are deleted.
• Only creator of the room can delete the room.