{"id":28210761,"url":"https://github.com/xuset/peer-relay","last_synced_at":"2025-07-31T01:42:29.635Z","repository":{"id":57321751,"uuid":"65164101","full_name":"xuset/peer-relay","owner":"xuset","description":"Relay messages through peers in a network","archived":false,"fork":false,"pushed_at":"2017-06-09T00:19:37.000Z","size":507,"stargazers_count":68,"open_issues_count":2,"forks_count":12,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-06-11T00:41:56.720Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xuset.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-08T01:49:26.000Z","updated_at":"2025-03-28T09:44:07.000Z","dependencies_parsed_at":"2022-08-26T01:11:06.644Z","dependency_job_id":null,"html_url":"https://github.com/xuset/peer-relay","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/xuset/peer-relay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuset%2Fpeer-relay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuset%2Fpeer-relay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuset%2Fpeer-relay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuset%2Fpeer-relay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xuset","download_url":"https://codeload.github.com/xuset/peer-relay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuset%2Fpeer-relay/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267973341,"owners_count":24174401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-17T17:10:33.181Z","updated_at":"2025-07-31T01:42:29.601Z","avatar_url":"https://github.com/xuset.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# peer-relay\n\n[![Build Status](https://travis-ci.org/xuset/peer-relay.svg?branch=master)](https://travis-ci.org/xuset/peer-relay)\n[![npm version](https://badge.fury.io/js/peer-relay.svg)](https://badge.fury.io/js/peer-relay)\n\npeer-relay is a p2p message relay that works in nodejs and in the browser by supporting WebSockets and WebRTC as transports. Every peer-relay peer connects to a network of other peers. When a peer wants to send a message to another, it does not have to connect directly to the target because the message will be relayed through the network of peers. This is benificial in a few cases like sending a few messages to a lot peers. Traditionally, this would require connecting directly to every peer you needed to send a message to, but in the web browser this can be very costly because of WebRTC limitations. Instead, it may be better to relay those messages through peers you are already connected to, and this is the problem that peer-relay solves.\n\nEvery peer generates it's own unique and random id that is used to identify itself within the network. To send a message to a peer, all you need to know is the target peer's id. Peer-relay will then take care of the rest by relaying the message through intermediary peers until it reaches it's target.\n\n## How it works\n\nBefore a peer can do anything, it first must bootstrap itself onto the network by knowing the WebSocket urls of at least one peer already connected to the network. Whenever a new connection is formed, both peers exchange info about the peers they are already connected to so they can connect to more peers if they need to. When a peer does want to connect to another, which transport used depends on what both peers support. Websockets are straightforward; connect to the WebSocket url. The WebRTC transport is a little different in that the signaling information must be relayed through intermediary peers before the connection can be formed.\n\nEvery peer maintains it's own [k-bucket](https://github.com/tristanls/k-bucket) routing table of peers that it is directly connected to. The message routing used by peer-relay is largely inspired by [kademlia](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf) which is why k-bucket is used. When a peer wants to send message to another, it looks at it's routing table for the peer whose id is closest to the target's id, and sends the message to the closest peer. When the receiving peer receives the message, it repeats the same process, and eventually the message will reach it's target. The amount of hops it takes for a message to reach it's target is log(n) where n is the number of peers in the network.\n\n## API\n\n### `peer = new PeerRelay([opts])`\n\nCreates a new peer that becomes apart of the relay network\n\nThe following fields can be specified within `opts`:\n * port - The port for the web socket server to listen on. If not defined, then a websocket server is not started\n * bootstrap - an array of web socket urls to peers already connected to the network\n * wrtc - custom nodejs webrtc implementation. Check out [electron-webrtc](https://github.com/mappum/electron-webrtc) or [wrtc](https://github.com/js-platform/node-webrtc)\n\n`port` can only be specified if the peer is running nodejs since start a WebSocket server is not possible in a browser. Every peer should specify at least on bootstrap peer (unless that peer is the first/only peer in the network)\n\n### `peer.id`\n\nThe peer's id. `id` is 160 bit Buffer. This id is used to identify the peer within the network.\n\n### `peer.connect(id)`\n\nForms a direct connection with the given peer. `id` is the id of the peer to connect to and must be a Buffer.\n\nBehind the scenes: a message will be relayed to that peer asking it what transports it supports (WebSocket and/or WebRTC). Then the connection will be formed based on this info; if webrtc is chosen then additional signaling info will be relayed before the connection is formed.\n\n### `peer.disconnect(id)`\n\nDisconnect the a currently connected peer with `id`.\n\n### `peer.send(id, data)`\n\nSend `data` to the peer with the `id`. `data` can be anything that is JSON serializable. The peer does not have to be directly connected to because it will be relayed through other peers. Message delivery or order is not guaranteed.\n\n### `peer.destroy([cb])`\n\nDestroy the peer and free it's resources. An optional callback can be specified and will be called when all the resources are freed.\n\n## Events\n\n### `peer.on('message', function (data, from) {})`\n\nFired when a message addressed to the peer was received. `from` is the Buffer id of the peer that sent the message.\n\n### `peer.on('peer', function (id) {})`\n\nFired when a peer has been directly connected to\n\n## PeerRelay.Socket\n\n### `var socket = new PeerRelay.Socket([opts])`\n\nCreates a new [dgram](https://nodejs.org/api/dgram.html) like socket that uses peer-relay to send messages between peers instead of UDP. This allows for peer-relay to be used by programs that expect the dgram socket interface. This method accepts the same arguments as the PeerRelay constructor. The returned object tries to match the interface provided by dgram's [Socket](https://nodejs.org/api/dgram.html#dgram_class_dgram_socket).\n\nThere are a few differences to this socket than dgram's. Mainly, ip addresses are replaced by peer IDs.\n\n### `socket.send(buffer, offset, length, port, peerRelayID, [cb])`\n\nThis relays the given buffer to the peer with `peerRelayID` by calling `peer.send(...)`. The signature for this method is similar to dgram's socket.send except the peer's id is used instead of the ip address. Port is also ignored, but is still required for compatibility reasons.\n\n### `socket.address()`\n\nReturns the peer's id instead of ip address:\n```\n{\n  address: local peer's id\n  port: random number or whatever port socket.bind([port]) was given\n  family: a string equal to 'peer-relay'\n}\n```\n\n### `socket.close([cb])`\n\nDestroys the underlying PeerRelay instance and emits the socket's close event\n\n### `socket.bind([port], [cb])`\n\nDoesn't do anything since peer-relay doesn't have the conecept of binding and ports, but this method remains for compatibilty with dgram's socket.\n\n### `socket.peer`\n\nreferences the underlying PeerRelay instance.\n\n### `socket.on('message', function (buffer, rinfo) {})`\n\n`buffer` is the received message and `rinfo` is the same structure defined by `socket.address()` exept the sender's id is in the address field.\n\n### `socket.on('error', function (err) {})`\n\nIf peer-relay experiences an error, it is bubbled up through this event.\n\n### `socket.on('close', function () {})`\n\nEmitted when socket.close is called or when PeerRelay closes. \n\n### `socket.on('listening', function () {})`\n\nDoesn't serve any purpose other than dgram socket compatility. This event is emitted after `socket.bind()` is called.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuset%2Fpeer-relay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxuset%2Fpeer-relay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuset%2Fpeer-relay/lists"}