p2p_http: add live logs sink and document P2P HTTP usage

Author: GaspardKirira

README.md

@@ -108,54 +108,113 @@ Validation rules:
 
 ---
 
-## Usage Example
+## Minimal P2P example (no HTTP)
+
+This example starts two P2P nodes and connects one to the other over TCP.
+### Node A (listener)
 
 ```cpp
 #include <vix.hpp>
 #include <vix/console.hpp>
 #include <vix/p2p/Node.hpp>
 #include <vix/p2p/P2P.hpp>
-#include <vix/p2p_http/P2PHttp.hpp>
 
 using namespace vix;
 
 int main()
 {
-  App app;
-
   vix::p2p::NodeConfig cfg;
-  cfg.node_id = "A";
+  cfg.node_id = "node-A";
   cfg.listen_port = 9001;
 
+  cfg.on_log = [](std::string_view s) {
+    console.info(std::string(s));
+  };
+
   auto node = vix::p2p::make_tcp_node(cfg);
   vix::p2p::P2PRuntime runtime(node);
+
   runtime.start();
 
-  vix::p2p_http::P2PHttpOptions opt;
-  opt.prefix = "/api/p2p";
-  opt.enable_ping = true;
-  opt.enable_status = true;
-  opt.enable_peers = true;
-  opt.enable_logs = true;
-  opt.enable_live_logs = true;
-  opt.stats_every_ms = 250;
+  console.info("Node A running on port 9001");
+  runtime.wait(); // blocks
+
+  return 0;
+}
+```
+### Node B (connects to A)
+
+```cpp
+#include <vix.hpp>
+#include <vix/console.hpp>
+#include <vix/p2p/Node.hpp>
+#include <vix/p2p/P2P.hpp>
+
+using namespace vix;
+
+int main()
+{
+  vix::p2p::NodeConfig cfg;
+  cfg.node_id = "node-B";
+
+  cfg.on_log = [](std::string_view s) {
+    console.info(std::string(s));
+  };
 
-  vix::p2p_http::registerRoutes(app, runtime, opt);
+  auto node = vix::p2p::make_tcp_node(cfg);
+  vix::p2p::P2PRuntime runtime(node);
 
-  app.static_dir("./public");
-  app.get("/", [](Request &, Response &res)
-          { res.file("./public/index.html"); });
+  runtime.start();
+
+  vix::p2p::PeerEndpoint ep;
+  ep.host = "127.0.0.1";
+  ep.port = 9001;
+  ep.scheme = "tcp";
 
-  app.get("/connect", [](Request &, Response &res)
-          { res.file("./public/connect.html"); });
+  node->connect(ep);
 
-  app.listen(5178, [](const vix::utils::ServerReadyInfo &info)
-             { console.info("UI API listening on", info.port); });
+  console.info("Node B connecting to node A...");
+  runtime.wait(); // blocks
 
-  app.wait();
-  runtime.stop();
+  return 0;
 }
 ```
+## What this demonstrates
+
+✅ Pure P2P (no HTTP, no UI)
+✅ Asynchronous TCP transport
+✅ Secure handshake (Hello / Ack / Finish)
+✅ Heartbeats + peer lifecycle
+✅ Logs via cfg.on_log
+
+## How to run
+```bash
+# terminal 1
+vix run node_a.cpp
+
+# terminal 2
+vix run node_b.cpp
+```
+## You should see logs like:
+
+```bash
+[p2p] connect() requested: tcp://127.0.0.1:9001
+[p2p] connect() ready: peer_id=...
+[p2p] handshake completed
+```
+
+## Why this example is important
+
+- Shows the smallest useful P2P setup
+- No framework noise
+- Easy mental model
+
+Perfect starting point for:
+
+- messaging
+- replication
+- offline-first sync
+- custom protocols
 
 ---
 

include/vix/p2p_http/P2PHttp.hpp

@@ -32,6 +32,9 @@ namespace vix::p2p_http
       vix::App &app,
       vix::p2p::P2PRuntime &runtime,
       const P2PHttpOptions &opt);
+
+  void shutdown_live_logs();
+  void set_live_log_sink(std::function<void(std::string)> sink);
 }
 
 #endif // VIX_P2P_HTTP_HPP

include/vix/p2p_http/P2PHttpOptions.hpp

@@ -23,8 +23,8 @@
 namespace vix::p2p_http
 {
   using AuthHookCtx = std::function<bool(vix::mw::Context &)>;
-
   using AuthHookLegacy = std::function<bool(vix::vhttp::Request &, vix::vhttp::ResponseWrapper &)>;
+  using LogSink = std::function<void(std::string_view)>;
 
   struct P2PHttpOptions
   {
@@ -40,6 +40,8 @@ namespace vix::p2p_http
 
     AuthHookCtx auth_ctx = nullptr;
     AuthHookLegacy auth_legacy = nullptr;
+
+    LogSink log_sink = nullptr;
   };
 
 }

src/P2PHttp.cpp

@@ -75,6 +75,48 @@ namespace vix::p2p_http
 
   static std::atomic<bool> g_tick_started{false};
   static std::atomic<bool> g_tick_stop{false};
+  static std::thread g_tick_thread;
+  static std::mutex g_tick_mu;
+
+  static std::function<void(std::string)> g_external_sink = nullptr;
+
+  static void p2p_http_sink(std::string line)
+  {
+    if (g_external_sink)
+    {
+      g_external_sink(std::move(line));
+      return;
+    }
+    g_logs.push(std::move(line));
+  }
+
+  void set_live_log_sink(std::function<void(std::string)> sink)
+  {
+    g_external_sink = std::move(sink);
+  }
+
+  static void push_log(const P2PHttpOptions *opt, std::string line)
+  {
+    if (opt && opt->log_sink)
+    {
+      opt->log_sink(line);
+      return;
+    }
+    g_logs.push(std::move(line));
+  }
+
+  void shutdown_live_logs()
+  {
+    std::lock_guard<std::mutex> lk(g_tick_mu);
+
+    g_tick_stop.store(true);
+
+    if (g_tick_thread.joinable())
+      g_tick_thread.join();
+
+    vix::p2p::clear_global_log_sink();
+    g_tick_started.store(false);
+  }
 
   static std::string stats_line_plain(const vix::p2p::RuntimeStats &st)
   {
@@ -202,49 +244,49 @@ namespace vix::p2p_http
   {
     const std::string base = (opt.prefix.empty() ? "/p2p" : opt.prefix);
 
-    g_logs.push("[p2p_http] routes registered");
+    push_log(&opt, "[p2p_http] routes registered");
+    vix::p2p::set_global_log_sink([](std::string_view s)
+                                  { p2p_http_sink(std::string(s)); });
 
     if (opt.enable_live_logs && opt.enable_logs)
     {
-      bool expected = false;
-      if (g_tick_started.compare_exchange_strong(expected, true))
-      {
-        g_tick_stop.store(false);
+      const int every = (opt.stats_every_ms <= 0 ? 1000 : opt.stats_every_ms);
+      auto *rt = &runtime;
+
+      std::lock_guard<std::mutex> lk(g_tick_mu);
 
-        const int every = (opt.stats_every_ms <= 0 ? 1000 : opt.stats_every_ms);
+      if (g_tick_started.load())
+        return;
 
-        auto *rt = &runtime;
+      g_tick_started.store(true);
+      g_tick_stop.store(false);
 
-        std::thread(
-            [rt, every]()
-            {
-          vix::p2p::RuntimeStats last{};
-          while (!g_tick_stop.load())
-          {
-            const auto st = rt->runtime_stats();
-
-            const bool changed =
-              (st.peers_total != last.peers_total) ||
-              (st.peers_connected != last.peers_connected) ||
-              (st.handshakes_started != last.handshakes_started) ||
-              (st.handshakes_completed != last.handshakes_completed) ||
-
-              (st.connect.connect_attempts != last.connect.connect_attempts) ||
-              (st.connect.connect_deduped != last.connect.connect_deduped) ||
-              (st.connect.connect_failures != last.connect.connect_failures) ||
-              (st.connect.backoff_skips != last.connect.backoff_skips) ||
-              (st.connect.tracked_endpoints != last.connect.tracked_endpoints);
-
-            if (changed)
-            {
-              g_logs.push(std::string("[p2p] ") + stats_line_plain(st));
-              last = st;
-            }
+      g_tick_thread = std::thread([rt, every]()
+                                  {
+      vix::p2p::RuntimeStats last{};
+      while (!g_tick_stop.load())
+      {
+        const auto st = rt->runtime_stats();
+
+        const bool changed =
+          (st.peers_total != last.peers_total) ||
+          (st.peers_connected != last.peers_connected) ||
+          (st.handshakes_started != last.handshakes_started) ||
+          (st.handshakes_completed != last.handshakes_completed) ||
+          (st.connect.connect_attempts != last.connect.connect_attempts) ||
+          (st.connect.connect_deduped != last.connect.connect_deduped) ||
+          (st.connect.connect_failures != last.connect.connect_failures) ||
+          (st.connect.backoff_skips != last.connect.backoff_skips) ||
+          (st.connect.tracked_endpoints != last.connect.tracked_endpoints);
+
+        if (changed)
+        {
+          p2p_http_sink(std::string("[p2p] ") + stats_line_plain(st));
+          last = st;
+        }
 
-            std::this_thread::sleep_for(std::chrono::milliseconds(every));
-          } })
-            .detach();
-      }
+        std::this_thread::sleep_for(std::chrono::milliseconds(every));
+      } });
     }
 
     // GET /p2p/ping