Parlance

A decentralized P2P messaging application.

Demo

Overview

Parlance is a functional P2P messaging application that works both on local networks and across the internet. It uses UDP multicast for local peer discovery and a lightweight bootstrap server for internet-scale discovery. All messaging happens directly peer-to-peer.

Current State

Working:

• Local discovery: UDP multicast for automatic LAN peer discovery
• Internet discovery: WebSocket-based bootstrap server for cross-network discovery
• Mode selection: Choose local or internet discovery
• Direct TCP messaging between discovered peers
• Multiple instances on the same machine (SO_REUSEPORT)

Limitations:

• No NAT traversal yet (requires direct connectivity or port forwarding)
• No encryption (cleartext over TCP)
• No message persistence
• No group chat (only 1-to-1 messaging)

Architecture

Local Discovery (UDP Multicast):

• Multicast group: 239.255.255.250:6789
• JSON-serialized discovery messages

Internet Discovery (Bootstrap Server):

• WebSocket-based signaling server
• Maintains registry of online peers

Messaging Layer (TCP):

• Each peer listens on a dynamically assigned port
• Direct socket connections for message delivery
• Line-delimited JSON over TCP
• Concurrent connection handling via Tokio

Building

Requires Rust 1.70 or later.

# Build everything
cargo build --workspace

Usage

Local Network Mode (Default)

Start multiple instances on the same network:

# Terminal 1
cargo run -p parlance -- --nickname alice

# Terminal 2
cargo run -p parlance -- --nickname bob

Discovery happens automatically via UDP multicast. After a few seconds, peers will appear in each other's peer lists.

Internet Mode

Step 1: Start the bootstrap server:

# Terminal 1
cargo run -p bootstrap-server -- --host 0.0.0.0 --port 8080

Step 2: Start clients with --mode internet:

# Terminal 2
cargo run -p parlance -- --nickname alice --mode internet

# Terminal 3 (can be on a different network!)
cargo run -p parlance -- --nickname bob --mode internet

The clients will automatically connect to the bootstrap server and discover each other.

Configuration

Edit parlance-client/parlance.toml to configure discovery mode:

[network]
mode = "local"  # Options: local | internet
bootstrap_server = "ws://localhost:8080"

• local: Use UDP multicast (LAN only, default)
• internet: Use bootstrap server (cross-network)

Commands:

• /peers - Show discovered peers
• /send <nickname> <message> - Send a message
• /quit - Exit
• /help - Show help

Example:

/peers
/send bob hey, testing this out

Messages appear in the recipient's terminal with a timestamp.

Protocol Details

Discovery Protocol

Peers send periodic announcements to 239.255.255.250:6789:

{
  "type": "announce",
  "nickname": "alice",
  "tcp_port": 54321
}

The peer registry maintains a list of all recently-seen peers. Peers are removed if they haven't announced in 15 seconds.

Messaging Protocol

Messages are sent over TCP as line-delimited JSON:

{
  "from": "alice",
  "content": "message text",
  "timestamp": 1699123456
}

Each peer maintains a TCP listener. To send a message, a peer:

1. Looks up the recipient in the peer registry
2. Opens a TCP connection to their address
3. Sends the JSON message followed by \n
4. Closes the connection

This is inefficient but simple.