Fancy P2P

A simple way to discovery P2P (peer to peer) connections

Projects

• Fancy P2P Demo
• Amazons

Why

Direct connections between browsers is well supported with WebRTC, but this is difficult to set up and use.

Caveats

Devices behind strict NAT networks (roughly 8% of devices worldwide) can not create a direct peer to peer connection.

Terminology

Peer A direct connection from one browser to another

Client Another browser in the same lobby. We can become peers if we both accept

Install

yarn add @mothepro/fancy-p2p

How to Use

Include the ES module on your page.

<script type="module" src="//unpkg.com/@mothepro/fancy-p2p"></script>

Then in your application, initialize a P2P to find peers and connect with them.

const
  /** My public server running `@mothepro/signaling-lobby`. */
  address = 'wss://ws.parkshade.com:443',

  /** STUNS to useful for testing. */
  stuns = [
    "stun:stun.stunprotocol.org",
    "stun:stun.l.google.com:19302",
    "stun:stun1.l.google.com:19302",
    "stun:stun2.l.google.com:19302",
    "stun:stun3.l.google.com:19302",
    "stun:stun4.l.google.com:19302",
  ],

  /** The version of `@mothepro/signaling-lobby` the signaling server is running */
  version = '0.2.0',

  /** Only clients who use this string will be found in the lobby. */
  lobby = '[email protected]',

  /** P2P instance */
  p2p = new P2P({
    /** Name used to connect to lobby with */
    name: 'Mo',

    /** STUN servers to use to initialize P2P connections */
    stuns,

    /** Lobby ID to use for this app */
    lobby,

    /** Settings for the signaling server */
    server: {
        /** The address of the signaling server */
        address,
        
        /** The version of `@mothepro/signaling-lobby` the signaling server is running */
        version,
    },

    /** Whether to use the signaling server as a fallback when a direct connection to peer can not be established. */
    fallback: false,

    /** Number of times to attempt to make an RTC connection, if negative direct p2p connections will not be attempted. */
    retries: 1,

    /** The number of milliseconds to wait before giving up on the connection. */
    timeout: 10 * 1000,
  })

The p2p has 4 possible states represented by the following.

enum State {
  OFFLINE = 0,
  LOBBY = 1,
  LOADING = 2,
  READY = 3
}

The p2p instance exposes the following to listen for state changes.

class P2P {
  readonly state: State

  /** Activated when the state changes, Cancels when finalized, Deactivates when error is throw. */
  readonly stateChange: Listener<State>
}

Offline

No connection to server or peers. Next state will be LOBBY or to fail.

Lobby

We are now connected to the lobby. Now, listening to Clients connect and waiting to make or join a group.

interface Client {
  /** Name of this client. */
  readonly name: Name

  /** Activated when a initiating a new group. Closed when client leaves. */
  readonly proposals: Listener<{

      /** The other members in this group, including me. */
      members: Client[]

      /** Function to accept or reject the group, not present if you created the group */
      action?(accept: boolean): void

      /** Activated with the Client who just accepted the group proposal. Deactivates when someone rejects. */
      ack: Listener<Client>
  }>

  /**
   * Whether this client represents you in the lobby.
   * When false this is another client and proposals are initiated by them.
   */
  readonly isYou: boolean
}

The first client to connect is always "you".

The p2p instance provides a Listener to find new clients and a proposeGroup method which takes a list of clients to group with.

class P2P {
  /** Activated when a client joins the lobby. */
  readonly lobbyConnection: SafeListener<SimpleClient>
  
  /** Propose a group with other clients connected to this lobby. */
  proposeGroup(...members: SimpleClient[]): void

  /** Whether a group with the following memebers has been proposed or answered. */
  groupExists(...members: SimpleClient[]): boolean
}

Which can be used to find clients and monitor when they propose, accept or reject groups or leave the lobby.

async function bindClientProposals(client: Client) {
  for await (const { members, ack, action } of client.proposals) {
    const groupName =  members.map(client => client.name).join(', ') + ' & you'
    console.log('Group proposed for ', groupName)
    this.bindProposalAcks(groupName, ack)

    if (action) // not present if I created the group
      action(confirm('Want to join group with ' + groupName))
  }
  console.log(client.name, 'has left the lobby')
}

async function bindProposalAcks(groupName: string, ack: Listener<Client>) {
  try {
    for await (const client of ack)
      console.log(client.name, 'accepted invitation with', groupName)
  } catch (err) {
    if (err.client) // if present, this is the client who rejected
      console.error(err, err.client.name, 'rejected invitation to group with', groupName)
    else
      console.error(err, 'Group closed with', groupName)
  }
}

for await (const client of p2p.lobbyConnection) {
  console.log(client.name, 'has joined the lobby')
  this.bindClientProposals(client)
}

Next state will be LOADING if group is made or OFFLINE if kicked from server for inactivity.

Loading

Happens once every client accepts the group. Time to create direct P2P connections with everyone who accepted

Next state will be READY if successful or fail if a direct connection with all isn't made.

Ready

The direct connections with peers are set and we can now broadcast messages and generate random numbers together.

interface Peer<T extends string | ArrayBuffer | Blob> {
    /** Name of the new peer. */
    readonly name: Name

    /** Send data to activate the `message` listener for the peer. */
    send(data: T): void

    /** Activates when a message is received for this peer. Cancels once the connection is closed. */
    readonly message: Listener<T>

    /**
     * Whether this peer represents a "connection" to you.
     * When false this is another peer and data is sent through the wire.
     */
    readonly isYou: boolean

    /** Close the connection with this peer. */
    close(): void;
}

The peers member in the p2p instance is now a list of Peers in a random order. This order is consistent for all the peers though (Useful for turn based applications).

The p2p instance also provides the broadcast & random helper functions.

class P2P<T extends ArrayBuffer | string | Blob> {
    /** The peers who's connections are still open */
    readonly peers: Peer<T>[]

    /**
     * Generates a random number in [0,1). Same as Math.random()
     * If `isInt` is true, than a integer in range [-2 ** 31, 2 ** 31) is generated.
     *
     * This value will be the same across all the other connected peers.
     */
    random(isInt?: boolean): number

    /** Send data to all connected peers. Including you by default */
    broadcast(data: T, includeSelf?: boolean): void
}

async function bindPeerMessages(peer: Peer) {
  try {
    for await (const data of peer.message)
      console.log(peer.name, 'sent', data)
  } catch (err) {
    console.error(err)
  }
  console.log('Closed direct connection with', peer.name)
}

for (const peer of p2p.peers)
  this.bindPeerMessages(peer)

Roadmap

• Test RTC possibility before starting server connection
• Support trickle ICE
• Improve peer lib simple-peer is messes with buffer
• Undo https://github.com/mothepro/fancy-p2p/commit/527da616bf1982bac84ed66f55d3295df8074ff1 ??