PeerBasket

README

PeerBasket

A hassle-free, lobby-based PeerJS discovery server.

---

The Problem

WebRTC enables two browsers to connect directly, but only after they exchange Peer IDs. WebRTC has no built-in way for peers to find each other in the first place, forcing developers to configure stateful signaling servers or databases just to bootstrap a connection.

The Solution

PeerBasket solves this with a stateless, zero-configuration HTTP API. You POST your Peer ID to a room name (a basket), and receive a list of other active Peer IDs currently in it. These IDs are then passed to PeerJS to establish direct WebRTC connections.

Key Features

• Zero Config: No signups, databases, or room setups. Just call the API endpoint.
• Auto-Pruning: Inactive peer heartbeats are automatically purged after 30 seconds to clean up empty lobbies.
• Hosted Public Node: A free public instance runs at https://peerbasket.bittu.dev.

For full rate limits, security details, and API schemas, refer to the API Documentation.

---

Quickstart

Register your Peer ID and fetch other active peers in a basket with one POST request:

const response = await fetch('https://peerbasket.bittu.dev/basket/my-room-id', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ peer_id: 'my-peerjs-id' })
});
const { peers } = await response.json();

// Connect to everyone else in the room
peers
  .filter(id => id !== 'my-peerjs-id')
  .forEach(id => peer.connect(id));

To see client integrations, check out the Examples Directory:

---

Self-Hosting

Requires Redis (running locally or accessible via REDIS_ADDR environment variable).

Option A: Using Release Binaries (Recommended)

1. Download the pre-compiled binary for your system from the Releases Page.
2. Create a .env file in the same directory:

   PORT=8080
   GIN_MODE=release
   REDIS_ADDR=127.0.0.1:6379
   

3. Run the binary:
   • Linux / macOS:

     chmod +x peerbasket-linux-amd64 && ./peerbasket-linux-amd64
     

   • Windows:

     .\peerbasket-windows-amd64.exe
     

Option B: Building from Source

1. Prerequisite: Install Go 1.26+.
2. Clone, install dependencies, and run:

   git clone https://github.com/Bittu5134/PeerBasket.git
   cd PeerBasket
   go mod tidy
   go run .
   

---

Support & Sponsorship

If PeerBasket helps your project, please consider supporting development costs:

• Patreon: Support directly via Patreon.
• Community: Join discussions on Discord.

---

License

Distributed under the MIT License. See LICENSE for details.