# socket-signal

> Signal abstraction to create WebRTC connections through sockets.

Latest version **10.3.2** (published 2022-02-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install socket-signal
pnpm add socket-signal
yarn add socket-signal
bun add socket-signal
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 10.3.2 |
| Published | 2022-02-20 |
| First published | 2020-03-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 9 |
| Unpacked size | 36.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | GEUT |
| Maintainers | tinchoz49 |
| Keywords | socket-signal, webrtc, signal, signal-client, signal-server, simple-peer |

## Links

- npm: https://www.npmjs.com/package/socket-signal
- Repository: https://github.com/geut/socket-signal
- Homepage: https://github.com/geut/socket-signal#readme
- Issues: https://github.com/geut/socket-signal/issues
- npm.io page: https://npm.io/package/socket-signal

## Dependencies (9)

- [debug](https://npm.io/package/debug.md) ^4.1.1
- [fastq](https://npm.io/package/fastq.md) ^1.11.1
- [p-limit](https://npm.io/package/p-limit.md) ^3.0.2
- [nanoerror](https://npm.io/package/nanoerror.md) ^1.0.0
- [simple-peer](https://npm.io/package/simple-peer.md) ^9.11.0
- [end-of-stream](https://npm.io/package/end-of-stream.md) ^1.4.4
- [nanomessage-rpc](https://npm.io/package/nanomessage-rpc.md) ^5.0.0
- [nanocustomassert](https://npm.io/package/nanocustomassert.md) ^1.0.0
- [nanoresource-promise](https://npm.io/package/nanoresource-promise.md) ^3.0.2

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 10.3.2 (latest) — 2022-02-20
- 4.0.2 (old-version) — 2020-05-26
- 10.3.1 — 2021-10-28
- 10.3.0 — 2021-10-20
- 10.2.2 — 2021-10-20
- 10.2.1 — 2021-10-20
- 10.2.0 — 2021-10-20
- 10.1.1 — 2021-08-20
- 10.1.0 — 2021-08-20
- 10.0.0 — 2021-08-04
- 9.2.1 — 2021-03-22
- 9.2.0 — 2021-02-04
- 9.1.0 — 2021-01-27
- 9.0.0 — 2020-08-21
- 8.1.0 — 2020-08-19
- … 26 more at https://npm.io/package/socket-signal/versions

## README

# socket-signal

[![Build Status](https://travis-ci.com/geut/socket-signal.svg?branch=master)](https://travis-ci.com/geut/socket-signal)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

> 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](https://github.com/geut/socket-signal-websocket).

## <a name="install"></a> Install

```
$ npm install socket-signal
```

## <a name="usage"></a> 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).

```javascript
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

```javascript
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](lib/server-map.js).

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

## <a name="issues"></a> Issues

:bug: If you found an issue we encourage you to report it on [github](https://github.com/geut/socket-signal/issues). Please specify your OS and the actions to reproduce it.

## <a name="contribute"></a> Contributing

:busts_in_silhouette: Ideas and contributions to the project are welcome. You must follow this [guideline](https://github.com/geut/socket-signal/blob/master/CONTRIBUTING.md).

## License

MIT © A [**GEUT**](http://geutstudio.com/) project

---
_Source: https://npm.io/package/socket-signal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._