Vix.cpp P2P Module

Peer-to-peer engine for Vix.cpp.

The P2P module provides the networking and replication foundation used to build offline-first, local-first, and distributed C++ systems with peer discovery, secure handshakes, message framing, transport abstraction, routing, WAL replication, and safe sync.

Documentation

Full documentation will be available here:

https://docs.vixcpp.com/modules/p2p/

API reference:

https://docs.vixcpp.com/modules/p2p/api-reference

What P2P provides

• Peer discovery
• LAN discovery
• Registry-based bootstrap
• Secure handshake
• Message framing
• Protocol envelopes
• Message dispatch
• Transport abstraction
• Peer routing
• WAL replication
• Outbox synchronization
• Offline-first sync
• Failure-tolerant replication model

Public headers

#include <vix/p2p.hpp>

Or include specific headers when needed:

#include <vix/p2p/discovery.hpp>
#include <vix/p2p/framing.hpp>
#include <vix/p2p/envelope.hpp>
#include <vix/p2p/dispatch.hpp>
#include <vix/p2p/router.hpp>
#include <vix/p2p/sync.hpp>

Basic idea

local write
  -> WAL
  -> envelope
  -> framing
  -> transport
  -> peer
  -> apply
  -> ack
  -> retry until convergence

The network is not required for local correctness. Nodes can continue working offline and synchronize when connectivity returns.

Protocol architecture

Discovery
  -> finds peers

Transport
  -> sends bytes

Framing
  -> splits byte streams into messages

Envelope
  -> wraps protocol messages

Dispatch
  -> routes message types

EdgeSync
  -> WAL replication and outbox sync

Router
  -> optional peer routing

Message flow

encode(message)
  -> envelope
  -> framing
  -> transport
  -> network
  -> decode
  -> dispatch
  -> handler

Handshake model

A -> Hello
B -> HelloAck
A -> HelloFinish

After the handshake, the peer session can become connected and start exchanging protocol messages.

Offline sync model

local operation
  -> append to WAL
  -> push WAL batch
  -> peer applies operation
  -> peer sends acknowledgement
  -> retry pending operations until convergence

Examples

Envelope and framing

vix run examples/p2p/01_envelope_and_framing_basic.cpp

Handshake messages

vix run examples/p2p/02_hello_handshake_messages.cpp

Discovery announce JSON

vix run examples/p2p/03_discovery_announce_json.cpp

Router

vix run examples/p2p/04_router_memory_basic.cpp

Secure envelope

vix run examples/p2p/05_pack_secure_envelope.cpp

Dispatch

vix run examples/p2p/06_dispatch_decode_basic.cpp

WAL sync

vix run examples/p2p/07_wal_push_and_ack.cpp

Runtime examples

Manual TCP connection

Terminal 1:

vix run examples/p2p/08_runtime_manual_connect.cpp --run server

Terminal 2:

vix run examples/p2p/08_runtime_manual_connect.cpp --run client 127.0.0.1 9101

UDP discovery

Terminal 1:

vix run examples/p2p/09_udp_discovery_basic.cpp --run node-a 9201

Terminal 2:

vix run examples/p2p/09_udp_discovery_basic.cpp --run node-b 9202

HTTP bootstrap

vix run examples/p2p/10_bootstrap_http_basic.cpp --run http://127.0.0.1:8080/peers

CLI usage

You can also run a P2P node directly from the Vix CLI:

vix p2p --id A --listen 9001

Connect another node:

vix p2p --id B --listen 9002 --connect 127.0.0.1:9001

Runtime arguments

When using vix run, keep this rule:

--     = compiler or linker flags
--run  = runtime arguments passed to the program

Example:

vix run examples/p2p/08_runtime_manual_connect.cpp --run client 127.0.0.1 9101

Build

Contributors should use the Vix CLI to build this module.

Vix wraps the C++ build workflow with project detection, presets, Ninja builds, clean logs, caching, and focused diagnostics. This keeps the contributor workflow consistent and helps avoid hidden C++ build issues.

Build the project

git clone https://github.com/vixcpp/vix.git
cd vix
vix build

Build all targets

Use this before running the full test suite, install workflows, or release checks:

vix build --build-target all

Clean rebuild

Use this when the local CMake cache or build directory may be stale:

vix build --clean

Release build

vix build --preset release

Tests

Build all targets first, then run tests:

vix build --build-target all
vix tests

Before opening a pull request, use:

vix fmt --check
vix build --build-target all
vix tests

Useful links

• P2P documentation: https://docs.vixcpp.com/modules/p2p/
• P2P API reference: https://docs.vixcpp.com/modules/p2p/api-reference
• P2P CLI command: https://docs.vixcpp.com/cli/p2p
• Build command: https://docs.vixcpp.com/cli/build
• Tests command: https://docs.vixcpp.com/cli/tests
• Documentation: https://docs.vixcpp.com/
• Engineering notes: https://blog.vixcpp.com/
• Registry: https://registry.vixcpp.com/
• GitHub: https://github.com/vixcpp/vix

License

MIT License.

See LICENSE for details.