Think Distributed: Babel P2P Chat

Who it's for

This demo is for students, researchers, and engineers who want to understand — and start building — peer-to-peer and distributed systems, without first wrestling with sockets, threads, timeouts, and failure handling by hand. You write ordinary Java; Babel gives you protocols, events, and timers as clean composition units, and this chat shows them wired together end-to-end in a few hundred readable, heavily commented lines.

It's the software-only companion to our Babel IoT examples for Raspberry Pi: the same Babel runtime, but no hardware required. The membership, gossip, and discovery you see here are the very same building blocks that scale up to real distributed behaviour — and the ones ParadigmShift uses to build robust, self-managed, secure systems in production.

Read it, run it, fork it, and build your own protocols on top. If that's you, we'd love to hear what you make.

What it is

A peer-to-peer group chat built from three small Babel protocols. There is no central server: every participant runs the same program, the nodes form a peer mesh, and messages travel directly between them. It's deliberately minimal — the spirit of classic mIRC without the cruft (no accounts, no servers to configure) — so the interesting part is the distributed systems machinery, laid out plainly and heavily commented for you to read and modify.

If you've wanted to try building distributed systems in Java but didn't want to wrestle with sockets, threads, and failure handling by hand, this is a gentle on-ramp: Babel gives you protocols, events, and timers as clean building blocks, and this demo shows them composed end-to-end.

What it looks like

Start it with a nickname; type to talk to everyone, or use commands for private messages and presence:

*** babel-demo — connected as alice. Type /help for commands.
*** bob has joined the chat
[14:32] <bob> hi everyone
[14:32] <alice> hey bob
*** carol has joined the chat
[14:33] -> (carol) see you in 5      // a private message you sent
[14:33] <- (bob) sounds good          // a private message you received
*** bob has left the chat

Commands: /msg <nick> <text> (private message), /who (who's here), /help, /quit. Anything else you type goes to the whole channel.

How it works

Three cooperating Babel protocols — the same layering our real platform uses, minus the hardware:

• Membership (with auto-discovery). A gossip-based full-membership protocol keeps each node connected to the others. It bootstraps using Babel's DiscoverableProtocol: by default a node announces and probes the LAN by multicast, and the runtime introduces it to whoever answers (the bundled config switches this on with babel.discovery). Where multicast isn't available (VPNs, segmented networks), you pass membership.contact=<host>:<port> to seed from an existing node instead.
• Broadcast. A neighbour-aware flood disseminates each message to every peer the membership knows, exactly once — that's the global channel and the join/leave announcements.
• Chat application. Tracks who's in the chat (a nickname roster driven by a presence handshake and the membership's neighbour-up/down events), and sends private messages directly to a specific peer. The terminal UI is built with JLine.

The three protocols never call each other directly — they cooperate through the reusable babel-protocols-common abstractions (broadcast request/delivery, neighbour up/down, the discoverable-channel announcement), the very same building blocks our production protocols use. That's the lesson the demo is built to teach.

Run it (build from source)

Java 17 + Maven. Build the runnable JAR, then start a node per terminal or machine:

mvn package
java -jar target/babel-demo.jar nick=alice
java -jar target/babel-demo.jar nick=bob       # another terminal / machine — they auto-connect

Omit nick= and you'll be asked for one at startup. Every node prints, on startup, exactly which network interface and IP it bound and how it intends to find peers — so it's obvious at a glance what's going on:

  babel-demo — node 'alice'
  network     : en0  →  192.168.1.20   (auto-detected sole interface en0)
  listen      : 192.168.1.20:6000  (TCP chat)
  discovery   : multicast 233.138.122.123:1025  ·  unicast :1026
  bootstrap   : auto-discovery — I announce + probe the LAN and connect to whoever answers

To run several nodes on one machine, give each a distinct chat port and a distinct discovery socket port — the per-node discovery port (default 1026) can't be shared, so a second node would otherwise fail with BindException: Address already in use:

java -jar target/babel-demo.jar nick=alice babel.discovery.unicast.port=1026
java -jar target/babel-demo.jar nick=bob   babel.port=6001 babel.discovery.unicast.port=1027

If two local nodes don't find each other (some systems don't loop multicast back between local processes), pin both to loopback and seed the second from the first: add babel.address=127.0.0.1 to each, start the first with membership.contact=none, and the second with membership.contact=127.0.0.1:6000.

Source & credits

• Source code: github.com/ParadigmShift-PT/babel-demo (downloadable release coming soon)
• This demo's API docs: paradigmshift-pt.github.io/babel-demo (published from the repo on GitHub Pages; live once the first build runs)
• The framework libraries: Open Source · javadoc.paradigmshift.pt

Built on the ParadigmShift fork of Babel-Swarm and modelled on the upstream babel-example. Babel-Swarm was produced by the TaRDIS European project, in the Computer Systems Group of NOVA LINCS at NOVA FCT; ParadigmShift's version is provided and evolved independently of that original work. Babel is described in: P. Fouto, P. Á. Costa, N. Preguiça and J. Leitão, “Babel: A Framework for Developing Performant and Dependable Distributed Protocols,” 2022 41st International Symposium on Reliable Distributed Systems (SRDS), Vienna, Austria, 2022, pp. 146–155, doi: 10.1109/SRDS55811.2022.00022.