socket-signal

socket-signal

Signal abstraction to create WebRTC connections through sockets.

This module provides a common interface (for the client and server) to build your own signal.

If you want to use a ready to use implementation check: socket-signal-websocket.

Install

$ npm install socket-signal

Usage

Client

The client interface provides almost everything that you need to start a basic signal client (most of the times you won't need to add more features).

const { SocketSignalClient } = require('socket-signal')

class YourClient extends SocketSignalClient {
  async _open() {
    await super._open()
  }

  async _close() {
    await super._close()
  }

  async _onOffer(data) {
    // data.offer
  }

  async _onAnswer(data) {
    // data.answer
  }

  async _onIncomingPeer(peer) {
    if (validPeer(peer)) return
    throw new Error('invalid peer')
  }
}

const client = new YourClient(socket, opts)

;(async () => {
  // open the client
  await client.open()

  // join the swarm for the given topic and get the current peers for that topic
  const peersAvailable = await client.join(topic)

  // request a connection to a specific peer
  const remotePeer = client.connect(topic, peersAvailable[0])

  // optional, use the signal to listen for incoming media streams
  remotePeer.subscribeMediaStream = true

  try {
    // wait until the connection is established
    await remotePeer.ready()
    console.log(remotePeer.stream)
    // SimplePeer connected
  } catch(err) {
    // SimplePeer rejected
  }
})()

Server

const { SocketSignalServer } = require('socket-signal')

class YourServer extends SocketSignalServer {
  async _onDisconnect (rpc) {
    // onDisconnect a peer socket
  }

  async _onJoin (rpc, msg) {
    // msg.id, msg.topic
  }

  async _onLeave (rpc, msg) {
    // msg.id, msg.topic
  }

  async _onLookup (rpc, msg) {
    // msg.topic
  }

  /**
   * request signal offer
   */
  async _onOffer (rpc, msg) {
    // msg.remoteId, msg.topic, msg.data
  }

  /**
   * event signal
   *
   * this event is emitted when there is a signal candidate
   */
  async _onSignal (rpc, msg) {
    // msg.remoteId, msg.topic, msg.data
  }
}

If you want a server with a minimal implementation to handle peer connections you can use SocketSignalServerMap.

API

Client

const client = new Client(socket, options)

Creates a new client instance.

Options include:

• id: Buffer: Buffer of 32 bytes.
• requestTimeout: 15 * 1000: How long to wait for peer requests.
• concurrency: 1: How many incoming connections in concurrent can handle
• metadata: Object: Metadata to share across network.
• simplePeer: Object: SimplePeer options.

IMPORTANT: Every id and topic must be a Buffer of 32 bytes.

client.open() => Promise

Open the client.

client.close() => Promise

Close the client.

client.join(topic: Buffer) => Promise<Array<Buffer>>

Join the swarm for the given topic and do a lookup of peers available for that topic.

client.leave(topic: Buffer) => Promise

Leave the swarm for the given topic.

IMPORTANT: This will not close the current peers for that topic you should call closeConnectionsByTopic(topic)

client.closeConnectionsByTopic(topic: Buffer) => Promise

Close all the connections referenced by a topic.

client.connect(topic: Buffer, peerId: Buffer, options?: Object) => Peer

Creates a request connection for a specific topic and peerId.

options include:

• metadata: Object: Metadata to share with the other peer.
• simplePeer: Object: Specific SimplePeer options for this connection.

Peer is an object with:

• id: Buffer: ID of the peer.
• sessionId: Buffer: Unique ID for this connection.
• topic: Buffer: Topic related.
• metadata: Object: Metadata object to share with other side.
• stream: SimplePeer: The SimplePeer internal stream.
• subscribeMediaStream: boolean: Set in true if you want to use the signal to listen for incoming media streams. Default: false.

peer.ready() => Promise

Wait for the connection to be established.

peer.addStream(mediaStream) => Peer

Add a media stream.

Issues

If you found an issue we encourage you to report it on github. Please specify your OS and the actions to reproduce it.

Contributing

Ideas and contributions to the project are welcome. You must follow this guideline.

License

MIT A GEUT project