Core concepts

View Source

These pages explain how each piece of barrel_p2p works. They are not API references; the goal is to give you a mental model. Reach for the Reference when you need exact function signatures or configuration keys.

The concepts are mostly independent. You can read them in any order, but if it is your first pass, the order below is the natural one.

Membership and reachability

  • Cluster membership — HyParView's bounded active and passive views, joining, shuffle, failure handling.
  • Gossip broadcast — Plumtree push-lazy-push trees, the self-healing graft/prune dance.

Naming and replication

  • Service registry — the OR-Map CRDT behind register_service/2, whereis_service/1, and the eventually-consistent service catalogue.
  • Hybrid logical clocks — the timestamps the CRDT uses to merge concurrent updates.
  • Leader election — cluster-wide singletons via barrel_p2p:lead/2, with fencing tokens for safety.
  • Sharded placement — consistent hashing over a replicated live-node set; place/1 and ownership events.
  • Durable reminders — replicated, fire-at-most-once timers that survive the node that armed them.
  • Replicated maps — barrel_p2p_map, a gossiped last-write-wins key-value map for cluster-wide control-plane state.

The transport

  • Dist channel — the -proto_dist barrel_p2p shim over quic_dist, the discovery chain, the idle GC.
  • Authentication — Ed25519 mutual challenge-response between TLS handshake and Erlang dist handshake.
  • Streams — application-level multiplex over the same QUIC connection.
  • Connection migration — RFC 9000 §9 path rebind for laptops, tunnels, and CGNATs.

After the concepts

  • The Tutorials put these concepts to work in a real application.
  • The How-to guides cover operational tasks: production deployment, observability, troubleshooting, rotation, relays, testing.
  • The Reference has the API, the full configuration list, and the architecture deep dive.