Module: Socket

━ What's the Objective?

Socket APIs establishes bidirectional communication b/w client & the server unlike REST APIs. Due to it being highly duplex, its suitable & reliable especially for real-time communication. Since other 3rd party networking solution being a bloatware & not as per our taste, we had to build our own lightweight socket solution. Moreover, ws by default doesn't comes in handy state out of the box & is also deprived of support to execute on local network beside remote which vNetwork's Socket API implementation tries to fulfill.

━ Modules

• Network
• Room

━ APIs

━ server.socket.create() (Shared)

@Objective: Creates a socket instance on the route.

const socket: cSocket = cServer.socket.create(
  string: route,
  object: options // (Optional)
)

options: {
  // Heartbeat options are shared
  heartbeat: {
    interval: 10000, // (Optional): Interval at which heartbeat should be executed
    timeout: 60000 // (Optional): Duration b/w each heartbeat
  },

  // Reconnection options are only available on client side
  reconnection: {
    attempts: -1, // (Optional): Number of attempts before onClientDisconnect is reached. [Note: -1 = infinite attempts]
    interval: 2500 // (Optional): Duration b/w each attempt
  }
}

---

━ server.socket.destroy() (Shared)

@Objective: Destroys an existing socket instance from route.

const bool: state = cServer.socket.destroy(
  string: route
)

---

━ server.socket.isVoid() (Shared)

@Objective: Validates whether the route is void.

const bool: isRouteVoid = cServer.socket.isVoid(
  string: route
)

---

━ server.socket.fetch() (Shared)

@Objective: Retrieves instance by route.

const socket: cSocket = cServer.socket.fetch(
  string: route
)

---

━ server.socket.fetchSockets() (Shared)

@Objective: Retrieves an object containing existing routes & their corresponding sockets.

const object: result = cServer.socket.fetchSockets()

━ Methods

━ socket.onPreHeartbeat() (Shared) (📅Event)

@Objective: Fired whenever a heartbeat is emitted.

// Client Syntax:
cSocket.onPreHeartbeat = function(
  int: id,
  int: deltaTick
) {}

// Server Syntax:
cSocket.onPreHeartbeat = function(
  string: client,
  int: id,
  int: deltaTick
) {}

---

━ socket.onHeartbeat() (Shared) (📅Event)

@Objective: Fired whenever a heartbeat is received.

// Client Syntax:
cSocket.onHeartbeat = function(
  int: id,
  int: deltaTick
) {}

// Server Syntax:
cSocket.onHeartbeat = function(
  string: client,
  int: id,
  int: deltaTick
) {}

---

━ socket.onConnectionError() (Shared) (📅Event)

@Objective: Fired whenever a connection fails.

cSocket.onConnectionError = function(
  object: error
) {}

---

━ socket.onClientConnect() (Shared) (📅Event)

@Objective: Fired whenever a client connects to socket.

cSocket.onClientConnect = function(
  string: client
) {}

---

━ socket.onClientReconnect() (Client) (📅Event)

@Objective: Fired whenever a client attempts a reconnection to socket.

cSocket.onClientReconnect = function(
  string: client,
  int: currentAttempt,
  int: maxAttempts
) {}

---

━ socket.onClientDisconnect() (Shared) (📅Event)

@Objective: Fired whenever a client disconnects from socket.

cSocket.onClientDisconnect = function(
  string: client,
  string: reason
) {}

reason: [
  "version-mismatch", // Used when client/server's version doesn't match
  "heartbeat-timeout", // Used when client/server's heartbeat gets timed-out
  "server-nonexistent", // Used when client tries to connect to a non-existing/invalid socket URL
  "server-disconnected", // Used when server shuts down
  "client-disconnected", // Used when client disconnects from server
  "client-reconnection-expired" // Used when client's reconnect attempts gets expired
]

---

━ socket.onServerConnect() (Server) (📅Event)

@Objective: Fired whenever the socket server gets connected.

cSocket.onServerConnect = function() {}

---

━ socket.onServerDisconnect() (Server) (📅Event)

@Objective: Fired whenever the socket server gets disconnected.

cSocket.onServerDisconnect = function(
  object <date>: timestamp_start, // Timestamp since when server started
  object <date>: timestamp_end, // Timestamp when the server shutdown
  int: deltaTick // Run duration
) {}

---

━ socket.isInstance() (Shared)

@Objective: Validates the socket instance.

const bool: state = cSocket.isInstance()

---

━ socket.isConnected() (Client)

@Objective: Validates socket's connectivity.

const bool: state = cSocket.isConnected(
  string: client
)

---

━ socket.isClient() (Server)

@Objective: Validates client's availability within the socket.

const bool: state = cSocket.isClient(
  string: client
)

---

━ socket.fetchClients() (Server)

@Objective: Retrieves an array of existing clients on socket.

const array: result = cSocket.fetchClients()

---

━ socket.destroy() (Shared)

@Objective: Destroys the socket instance.

const bool: state = cSocket.destroy()