Membrane
A robust, minimal-server-interaction API for peer routing in the browser
Install / Use
/learn @Elijah-Bodden/MembraneREADME
What's this?
Membrane is a protocol that takes WebRTC signalling to the browser with living peer networks. With minimal server-based bootstrapping, it makes self-sufficient peer-to-peer networks that can operate without servers. Any member browser can create a connection to any other by signaling across its peers, avoiding clumsy, centralized signaling servers. The network automatically stabilizes its topology and coordinates using broadcast "gossip".
Designed to be agnostic and easy to use, membrane is ideal for web clients for distributed chat, hosting, torrenting, computing, and so much more!
| 
|
|:--:|
| Membranexus.com, built using Membrane. After a first-contact server signal, clients never need to interact with a server again - all network functions can happen on the peer level. |
Membrane leverages RTCPeerConnection's agnosticism about signalling. You could just as well communicate ICE connection data through smoke signals or quantum teleportation as through a standard signalling server. In many cases, signaling servers are an unreliable and vulnerable approach. Membrane attempts to implement a better alternative protocol. With each membrane network acting as a giant, decentralized router, unconnected members on opposite sides of the earth can exchange arbitrary data in milliseconds, with no clumsy intermediary server or risk of downtime.
Of course, this approach isn't perfect. The benefits of decentralization are ultimately also the fatal flaw. What it gains in robustness and decentralization, it loses in making spoofing and manipulation easier. A public key ledger for cryptographic signing is WIP, which should largely remedy these issues (it will likely be served up by the signaling server on initial connectioen, which isn't a problem, since new peers can only be added when the server's up). And for non trust-critical operations, the existing implementation should be good enough.
Installation and Integation
Installing the Demo or Building From Source
Prerequisites
npmnpxnode.js
Paste the following commands into a terminal to build a complete directory structure and initialize the demo on 127.0.0.1:8000 anywhere with the prerequisities installed.
wget Membrane-current.tar.gz https://github.com/Elijah-Bodden/Membrane/tarball/v2.1.1
tar xfv Membrane-current.tar.gz --transform 's!^[^/]\+\($\|/\)!Membrane-current\1!'
cd Membrane-current/src/source/frontend
npm install
cd ../server
npm install
npm run deploy
rm ../../../../Membrane-current.tar.gz
To kill the pm2 instance this creates, run npm run kill. To re-spawn it, run npm run deploy in /src/source/server.
Deploying a New First-Contact Signalling Server
Installing the pre-made server from /src/source/server/index.noStatic.js is a piece of cake! Just run npm i membrane-server at the root of your node project, sit back, and relax while it installs.
To deploy the server on pm2, run npm explore membrane-server -- npm run deploy. To kill the pm2 instance, run npx pm2 kill. Now just remember to replace the websocket addresses in your client's config with your new server's.
You will likely also want to set up coturn TURN and STUN servers and replace the addresses in the frontend's defaultConfig with those. And since this is a standalone signaling server, you'll have to serve your frontend (in the demo's case, /src/source/frontend/dist) separately.
Build Your Own App!
Using the library for your own use-case is relatively simple. Here's a typical integration process. Find the delivery method you like below, then head down below to the general next steps
| Delivery Method | Instructions |
---- | ----
| npm + Webpack | Run npm install @elijah-bodden/membrane \| cd node-modules/elijah-bodden/membrane in the root of your webpack project |
| HTML script tag | Go to the directory you serve static files from and find where you want to save the script. Run wget https://raw.githubusercontent.com/Elijah-Bodden/Membrane/main/lib/index.js -o membrane.js, and finally paste <script src="/path/to/membrane.js"/> into your HTML head. |
| Jsdelivr CDN (recommended) | Simply paste this tag into your HTML head: <script src="https://cdn.jsdelivr.net/npm/@elijah-bodden/membrane@2.1.4/index.js"></scrípt> |
Now comes the fun part - building the thing! You'll likely want to set up your own first-contact signaling server (like this) and host it publicly so people can use your app from all different networks. Don't forget to edit the websocket urls in CONFIG.serverLink to point to it (or pass a config loader into init and do that without editing the source - how to do that next)!
The library has lots of things to play with, but here are some of the most useful for high-level apps. Read the docs to find out how to use them!: init, gossipTransport.addType, gossipTransport.addParser, *.addGossip, networkMap.nodes, livePeers, authPeers, CONFIG, deauthPeer, onAuthRejected, onServerError, onNewAuthPeer, onNewPeer, onLostAuthPeer, onLostPeer, sendConsumable, onAuth, makeConnection, onNetworkMapUpdate, onConsumable
Custom App Demo
Here's a small demo that shows off how to build an app on membrane. It's a tiny distributed self-hosting platform, where clients can publish resources (for example websites) and advertise them to the rest of the network through a custom gossip transport. If a peer wants a resource, it creates an auth route to the target, and the two use an ad-hoc consumable formatting method to handle request and response. Notably this is all peer-to-peer - aside from a tiny signaling server (which is only needed for adding new members), it should be able to scale infinitely without hardware overhead. The actual structure of the network is screened off from the user, so as far as they're concerned, they're directly connected to every single node. It runs on vanilla Membrane with a standard signalling server. With redundant hosting, this could be fleshed out into a pretty usable p2p version of the web or a social media. Here's the demo in action:
And here's the code
// index.js
var selfHostingTransport
var resourceLocations = {}
var myResources = {}
document.addEventListener("DOMContentLoaded", function() {
resourceList = document.getElementById("resource-list")
resourceDisplay = document.getElementById("resource-display")
})
async function configLoadFunction() {
return {
"serverLink.initBindURL": "ws://localhost:8777/bind?originatingSDP=*",
"serverLink.reconnectURL": "ws://localhost:8777/reconnect",
"communication.publicAlias": "Random person",
}
}
// Can only add gossip transports after init
init(configLoadFunction).then(async () => {
// This transport will broadcast each peer's content list
selfHostingTransport = gossipTransport.addType("contentList");
// When we get gossip about content lists, edit our content list
gossipTransport.addParser(
"contentList",
// Means we use the default pre-parser. Automatically handles passing gossip along for us
true,
// block = all gossip; commitable = all gossip, but only the "constantParameter" fields - ones that the transport uses to decide if goss
