Switchboard | switchboard.js

This is the main entrypoint for Switchboard.js.

This class manages all connections, and abstracts away all the complex details of WebRTC + Matchmaking.

Hierarchy

Subscribable
- Switchboard

Index

Constructors

constructor

Properties

Accessors

Constructors

constructor

new Switchboard(realm: string, opts?: SBClientOptions): Switchboard

- Defined in src/switchboard.ts:228
Creates a new Switchboard matchmaker.

To start finding peers, call one of: [host, findHost, swarm].

see

SBClientOptions

Parameters
- realm: string
  
  Specify a "realm" name that is likely unique to your application to avoid cross-talk with other app's peers.
- Optional opts: SBClientOptions
  
  Extra optional config values that this instance will use.
Returns Switchboard

Properties

Private _fullID

_fullID: string | null = null

Private blacklist

blacklist: Record<string, number>

Private connected

connected: Record<string, ConnectedPeer>

Private connectionMode

connectionMode: ConnectionTypeOptions = ConnectionTypeOptions.HOST

Private Readonly cryptoKeys

cryptoKeys: SignKeyPair

Private infoHash

infoHash: string = ""

Private killed

killed: boolean = false

Private Readonly opts

opts: SBClientOptions

Private Readonly realm

realm: string

Readonly secretSeed

secretSeed: string

This is the secret ID generated for use in cryptography. You should copy and reuse this if you wish to maintain a persistent Peer ID.

Note: This should never be shared. It allows whoever owns a copy to impersonate this Peer.

If you wish to know a valid seed before running Matchmaking, you can pre-generate a Seed using makeSeed.

see: SBClientOptions.seed for assigning this value.
see: Switchboard.makeSeed for pre-generating an ID.

Private trackerOpts

trackerOpts: TrackerOptions[] = []

Private trackers

trackers: Set<TrackerConnectorInterface> = new Set()

Private wantedPeerCount

wantedPeerCount: number = 0

Private wantedSpecificID

wantedSpecificID: string | null = null

Accessors

connectedPeers

get connectedPeers(): ConnectedPeer[]

- Defined in src/switchboard.ts:468
A list of all Peers currently connected to this Switchboard instance.

Returns ConnectedPeer[]

fullID

get fullID(): string

- Defined in src/switchboard.ts:277
The current long-form ID for this peer. When connecting to a target Host, this may technically be more secure than the shortened peerID.

Returns string

peerID

get peerID(): string

- Defined in src/switchboard.ts:261
The current ID this client is using. By default, uses shorter IDs, but can be toggled with SBClientOptions.useLongIds.

see

makeID

Returns string

shortID

get shortID(): string

- Defined in src/switchboard.ts:269
The short form of the local client ID. If additional security is desired when connecting to specific IDs, use fullID.

Returns string

trackerCount

get trackerCount(): number

- Defined in src/switchboard.ts:461
Returns a count of the Trackers currently processing or connected. This will include broken trackers that have not yet timed out. For more reliable detection of tracker activity, subscribe to the emitted tracker events.

Returns number

Methods

addPeerFailure

addPeerFailure(peer: ConnectedPeer, increment?: undefined | number): void

- Defined in src/switchboard.ts:478
Increases a Peer's failure count - potentially resulting in their blacklisting. If increment is not given, the Peer will be automatically blacklisted.

Parameters
- peer: ConnectedPeer
  
  The peer to (potentially) blacklist.
- Optional increment: undefined | number
  
  The amount of failures to increment. Defaults to instantly blacklisting.
Returns void

findHost

findHost(hostID: string): Promise<void>

- Defined in src/switchboard.ts:392
Connects only to the given Host PeerID. This requires that you have exchanged in advance the Host's ID.

For this to work, the Host must call host. If the Host is not yet online, they will be located once they become available.

see

host

Parameters
- hostID: string
  
  The ID of the target host. If the Host is using long-form IDs, make sure this matches!
Returns Promise<void>

host

host(maxPeers?: undefined | number): Promise<void>

- Defined in src/switchboard.ts:377
Connect to trackers as a Host, listening for client Peers. Clients looking for a specific Host via findHost will require that this is eventually called by the Host.

see

findHost

Parameters
- Optional maxPeers: undefined | number
  
  Optionally limit the maximum concurrently connected peers.
Returns Promise<void>

Private isBlackListed

isBlackListed(peerID: string): false | true | 0

- Defined in src/switchboard.ts:452
Check if a client has retried connections enough to be "blacklisted".

Parameters
- peerID: string
Returns false | true | 0

kill

kill(error?: Error, killPeers?: undefined | false | true): void

- Defined in src/switchboard.ts:418
Kill all connections to the tracker servers, and optionally the Peers connected as well.

Parameters
- Optional error: Error
  
  The error to be emitted by this object's "kill" event, or null.
- Optional killPeers: undefined | false | true
  
  If true, also close all active Peer connections.
Returns void

Private makeConnector

makeConnector(trk: TrackerOptions): TrackerConnectorInterface

- Defined in src/switchboard.ts:340
Parameters
- trk: TrackerOptions
Returns TrackerConnectorInterface

Private makeSigPacket

makeSigPacket(localSdp: string): Uint8Array

- Defined in src/switchboard.ts:558
Builds a binary buffer, containing the current public key & a validation signature from the matching private key.

see

verifyPacket

Parameters
- localSdp: string
Returns Uint8Array

on

on(event: "connected", callback: (openTrackers: TrackerConnector[]) => void): () => void
on(event: "peer", callback: (peer: ConnectedPeer) => void): () => void
on(event: "peer-error", callback: (err: Error) => void): () => void
on(event: "peer-seen", callback: (peerID: string) => void): () => void
on(event: "peer-blacklisted", callback: (peer: ConnectedPeer) => void): () => void
on(event: "warn", callback: (err: Error) => void): () => void
on(event: "kill", callback: (err: Error | null) => void): () => void
on(event: "tracker-connect", callback: (tracker: TrackerOptions) => void): () => void

Overrides Subscribable.on
- Defined in src/switchboard.ts:133
Emitted when all possible trackers have connected. If all trackers fail, this is not emitted.

For potential ease of debugging, the internally-used array of connected TrackerConnectors will be provided with this event. It is not advisable to manipulate these.

You should not wait for this event. Peers may come in from faster trackers before they are all connected.

Parameters
- event: "connected"
- callback: (openTrackers: TrackerConnector[]) => void
  
  A function which can accept an array of the internal TrackerConnectors.
  - - (openTrackers: TrackerConnector[]): void
    - Parameters
      - openTrackers: TrackerConnector[]
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:142
Emitted after a new Peer object is located, connected, and authenticated. You should always subscribe to this event, because all Peers will be returned via this emitter.

Parameters
- event: "peer"
- callback: (peer: ConnectedPeer) => void
  - - (peer: ConnectedPeer): void
    - Parameters
      - peer: ConnectedPeer
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:151
Emitted when any connected Peer has an error. You can catch these at a more granular level by subscribing directly to the Peer's on('error') emitter instead.

Parameters
- event: "peer-error"
- callback: (err: Error) => void
  
  A function that can receive the Error, if any, that caused termination.
  - - (err: Error): void
    - Parameters
      - err: Error
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:159
Emitted when a PeerID is offered by a Tracker. The Peer may not actually connect.

Parameters
- event: "peer-seen"
- callback: (peerID: string) => void
  
  A function that can receive the Peer ID.
  - - (peerID: string): void
    - Parameters
      - peerID: string
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:168
Emitted whenever a Peer ID is blacklisted. The emitted Peer will be valid until the callback has run (synchronously), then it will be disconnected.

Parameters
- event: "peer-blacklisted"
- callback: (peer: ConnectedPeer) => void
  
  A function that can receive the PeerWrapper that was blacklisted.
  - - (peer: ConnectedPeer): void
    - Parameters
      - peer: ConnectedPeer
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:176
Emitted when a non-fatal error occurs. You should not assume that the Switchboard is broken based off these.

Parameters
- event: "warn"
- callback: (err: Error) => void
  
  A function that can receive the Error, if any, that caused termination.
  - - (err: Error): void
    - Parameters
      - err: Error
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:187
Triggered when this Switchboard is unrecoverably killed.

If this is emitted, this Switchboard is dead. You should create a new one if you need to reconnect.

Parameters
- event: "kill"
- callback: (err: Error | null) => void
  
  A function that can receive the Error, if any, that caused termination.
  - - (err: Error | null): void
    - Parameters
      - err: Error | null
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void
Overrides Subscribable.on
- Defined in src/switchboard.ts:195
Emitted when each of the trackers connects.

Parameters
- event: "tracker-connect"
- callback: (tracker: TrackerOptions) => void
  
  A function that can receive the TrackerOptions.
  - - (tracker: TrackerOptions): void
    - Parameters
      - tracker: TrackerOptions
      Returns void
Returns () => void

A function to call, in order to unsubscribe.
- - (): void
  - Returns void

Private onPeer

onPeer(peer: ConnectedPeer): void

- Defined in src/switchboard.ts:500
Triggered when a Tracker finds a peer that has passed the blacklist.

This handler initializes and verifies the new Peer's identity, using a binary handshake.

Parameters
- peer: ConnectedPeer
  
  The new Peer that has connected.
Returns void

once

once(event: string, callback: Function): (Anonymous function)

Inherited from Subscribable.once
- Defined in src/subscribable.ts:35
Same as on(), but only triggers one time & automatically cleans up.

see

on for the available specific events.

Parameters
- event: string
- callback: Function
Returns (Anonymous function)

removeAllListeners

removeAllListeners(event?: undefined | string): this

Inherited from Subscribable.removeAllListeners
- Defined in src/subscribable.ts:77
Removes all non-permanent callbacks for the given event type, or every event type if none is given.

Parameters
- Optional event: undefined | string
Returns this

Private shouldBlockConnection

shouldBlockConnection(peerID: string, emitSeen?: boolean): boolean

- Defined in src/switchboard.ts:433
Determine if a given PeerID can connect. Called by TrackerConnectors before a handshake is established.

Parameters
- peerID: string
- Default value emitSeen: boolean = true
Returns boolean

Private start

start(swarmID: string): Promise<void>

- Defined in src/switchboard.ts:290
Connect to all Trackers, and register event handling internally.

Parameters
- swarmID: string
  
  ID to use for the swarm. This is hashed into an InfoHash.
Returns Promise<void>

swarm

swarm(swarmID: string, maxPeers?: undefined | number): Promise<void>

- Defined in src/switchboard.ts:407
Connect to all Peers within a given "swarm ID".

This ID can be any string you'd like, though it is suggested you make it something unique in order to avoid finding unrelated peers.

Parameters
- swarmID: string
  
  The ID of the swarm to join.
- Optional maxPeers: undefined | number
  
  An optional limit on the number of unique connected Peers.
Returns Promise<void>

Static defaultTrackers

defaultTrackers(): Promise<{ uri: string }[]>

- Defined in src/switchboard.ts:682
Convenience wrapper for users who want to set their own trackers, but still want access to Switchboard's defaults.

Returns Promise<{ uri: string }[]>

Static getExtraTrackers

getExtraTrackers(): Promise<{ uri: string }[]>

- Defined in src/switchboard.ts:668
Use this to fetch a list of additional, dynamic trackers, as provided by ngosang/trackerslist. By default, this is used internally to add additional trackers unless it is disabled.

Returns Promise<{ uri: string }[]>

Static getIdFromSeed

getIdFromSeed(seedString: string, getFullID?: boolean): string

- Defined in src/switchboard.ts:647
Get the (full) ID that a given seed string will use.

Parameters
- seedString: string
  
  The string Seed, can be generated using makeSeed.
- Default value getFullID: boolean = true
  
  If the returned ID should be the full-length ID, or the short version.
Returns string

Static Private makeCryptoPair

makeCryptoPair(seedString: string): SignKeyPair

- Defined in src/switchboard.ts:660
Accepts a string "seed", and uses it to rehydrate a pair of public/private keys.

Parameters
- seedString: string
  
  The seed, as generated by makeSeed.
Returns SignKeyPair

Static Private makeFullID

makeFullID(pubKey: Uint8Array): string

- Defined in src/switchboard.ts:631
Returns the long-form ID for the given Key, not truncated.

Parameters
- pubKey: Uint8Array
Returns string

Static Private makeID

makeID(pubKey: Uint8Array): string

- Defined in src/switchboard.ts:622
Generate a (short) ID from the given Public Key.

This ID will be a shortened (20 chars) SHA-1 hash.

Parameters
- pubKey: Uint8Array
  
  The public key to hash.
Returns string

Static makeSeed

makeSeed(): string

- Defined in src/switchboard.ts:638
Generate a new "seed", which is an encoded string of 32 random bytes.

Returns string

Static Private verifyPacket

verifyPacket(peerID: string, packet: Uint8Array, wantedID: string | null, remoteSdp: string): boolean

- Defined in src/switchboard.ts:585
Attempts to verify that the given packet was signed by, and for, the given peerID.

Validates that the packet's public key matches the Peer's ID, then validates that the packet was signed by the corresponding private key.

see

makeSigPacket

Parameters
- peerID: string
  
  The (short) ID of the Peer responsible for this packet.
- packet: Uint8Array
  
  The binary packet received.
- wantedID: string | null
  
  If a specific Host ID is desired, restrict it to this.
- remoteSdp: string
  
  The value of the current SDP config from the Remote connection.
Returns boolean

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

realm: string

Optional opts: SBClientOptions

Returns Switchboard

Properties

Private _fullID

Private blacklist

Private connected

Private connectionMode

Private Readonly cryptoKeys

Private infoHash

Private killed

Private Readonly opts

Private Readonly realm

Readonly secretSeed

Private trackerOpts

Private trackers

Private wantedPeerCount

Private wantedSpecificID

Accessors

connectedPeers

Returns ConnectedPeer[]

fullID

Returns string

peerID

Returns string

shortID

Returns string

trackerCount

Returns number

Methods

addPeerFailure

Parameters

peer: ConnectedPeer

Optional increment: undefined | number

Returns void

findHost

Parameters

hostID: string

Returns Promise<void>

host

Parameters

Optional maxPeers: undefined | number

Returns Promise<void>

Private isBlackListed

Parameters

peerID: string

Returns false | true | 0

kill

Parameters

Optional error: Error

Optional killPeers: undefined | false | true

Returns void

Private makeConnector

Parameters

trk: TrackerOptions

Returns TrackerConnectorInterface

Private makeSigPacket

Parameters

localSdp: string

Returns Uint8Array

on

Parameters

event: "connected"

callback: (openTrackers: TrackerConnector[]) => void

Parameters

openTrackers: TrackerConnector[]

Returns void

Returns () => void

Returns void

Parameters

event: "peer"