diff --git a/README.md b/README.md index 775a0b5..62494e7 100644 --- a/README.md +++ b/README.md @@ -34,19 +34,119 @@ ## What is Vix.cpp? -**Vix.cpp** is a modern **C++ runtime** designed as a serious alternative to **Node.js, Deno, and Bun** -but engineered **from day one** for: +**Vix.cpp** is a modern **C++ runtime** designed as a serious alternative to **Node.js, Deno, and Bun**, +but engineered **from day one** for real-world constraints: -- unstable networks -- offline-first environments -- peer-to-peer systems -- extreme native performance +* unstable or unreliable networks +* offline-first environments +* peer-to-peer systems +* extreme native performance -> **Run applications like Node/Deno/Bun -> with C++ speed, control, and predictability.** +> Run applications like Node/Deno/Bun +> with C++ speed, control, and predictability. Vix is not just a backend framework. -It is a **runtime layer** for real-world distributed systems. +It is a **runtime layer** for distributed, edge, and offline-capable systems. + +--- + +## The Vix Runtime Model + +Vix.cpp is **not a single server**. +It is a **multi-plane runtime** composed of **three specialized servers**, +each with a clearly defined responsibility. + +Together, they form a coherent, offline-first and P2P-ready execution model. + +--- + +### 1) HTTP Server — Control & APIs + +The HTTP server provides: + +* REST APIs +* configuration endpoints +* management and orchestration +* integration with CLIs, dashboards, and web frontends + +It is designed to be: + +* fast +* stateless +* predictable +* middleware-driven + +This server acts as the **control plane** of the runtime. + +--- + +### 2) WebSocket Server — Real-time & State Synchronization + +The WebSocket server handles: + +* real-time messaging +* rooms and channels +* presence and events +* durable message storage (SQLite + WAL) +* offline-friendly reconnection and replay + +It is optimized for: + +* chat systems +* dashboards +* IoT streams +* live collaboration + +This server is the **real-time plane** of the runtime. + +--- + +### 3) P2P Runtime — Transport & Distributed Systems + +The P2P runtime is responsible for: + +* peer discovery +* secure handshakes +* connection lifecycle management +* transport abstraction (TCP, QUIC, …) +* offline-first and edge-friendly networking + +It does **not** rely on HTTP or WebSocket for data transport. + +This is the **transport plane** of the runtime. + +--- + +### How the planes fit together + +``` + ┌───────────────┐ + │ HTTP API │ ← Control plane + │ (REST, Admin) │ + └───────┬───────┘ + │ + ┌───────▼───────┐ + │ WebSocket │ ← Real-time plane + │ (Events, RT) │ + └───────┬───────┘ + │ + ┌───────▼───────┐ + │ P2P │ ← Transport plane + │ (Peers, Mesh) │ + └───────────────┘ +``` + +Each plane is: + +* independent +* non-blocking +* explicitly scoped + +They can be combined to build: + +* offline-first backends +* distributed runtimes +* edge-native applications --- @@ -54,14 +154,17 @@ It is a **runtime layer** for real-world distributed systems. Vix.cpp is built for developers who: -- Build backend systems in **modern C++** -- Need **predictable performance** (no GC pauses) -- Target **offline-first or unreliable networks** -- Work on **edge, local, or P2P systems** -- Want a **Node/Deno-like DX**, but native +* build backend systems in **modern C++** +* need **predictable performance** (no GC pauses) +* target **offline-first or unreliable networks** +* work on **edge, local, or P2P systems** +* want a **Node/Deno-like DX**, but native -If you’ve ever thought _“I wish Node was faster and more reliable”_ -Vix is for you. +If you have ever thought: + +> “I wish Node was faster, more predictable, and worked offline” + +Vix.cpp is for you. --- @@ -69,55 +172,150 @@ Vix is for you. Most modern runtimes assume: -- stable internet -- cloud-first infrastructure -- predictable latency -- always-online connectivity +* stable internet +* cloud-first infrastructure +* predictable latency +* always-online connectivity That is **not reality** for much of the world. **Vix.cpp is built for real conditions first.** +Offline is not a fallback. +It is a first-class design constraint. + --- -## Performance is not a feature it’s a requirement +## Performance is not a feature — it is a requirement -Vix.cpp is designed to remove overhead, unpredictability, and GC pauses. +Vix.cpp is designed to remove overhead, unpredictability, and garbage-collection pauses. -### ⚡ Benchmarks (Dec 2025) +### Benchmarks (Dec 2025) -| Framework | Requests/sec | Avg Latency | -| --------------------------- | ------------ | ----------- | -| ⭐ **Vix.cpp (pinned CPU)** | **~99,000** | 7–10 ms | -| Vix.cpp (default) | ~81,400 | 9–11 ms | -| Go (Fiber) | ~81,300 | ~0.6 ms | -| Deno | ~48,800 | ~16 ms | -| Node.js (Fastify) | ~4,200 | ~16 ms | -| PHP (Slim) | ~2,800 | ~17 ms | -| FastAPI (Python) | ~750 | ~64 ms | +| Framework | Requests/sec | Avg Latency | +| ------------------------ | ------------ | ----------- | +| **Vix.cpp (pinned CPU)** | ~99,000 | 7–10 ms | +| Vix.cpp (default) | ~81,400 | 9–11 ms | +| Go (Fiber) | ~81,300 | ~0.6 ms | +| Deno | ~48,800 | ~16 ms | +| Node.js (Fastify) | ~4,200 | ~16 ms | +| PHP (Slim) | ~2,800 | ~17 ms | +| FastAPI (Python) | ~750 | ~64 ms | --- ## It really is this simple +### Minimal HTTP server + ```cpp #include using namespace vix; -int main() { - App app; +int main() +{ + App app; + + app.get("/", [](Request&, Response& res) { + res.send("Hello from Vix.cpp"); + }); + + app.run(8080); +} +``` - app.get("/", [](Request&, Response& res){ - res.send("Hello from Vix.cpp 🚀"); +### Minimal WebSocket server + +```cpp +#include + +using vix::websocket::Server; + +int main() +{ + Server ws; + + ws.on_open([](auto& session) { + session.send_json("chat.system", {"text", "Welcome"}); + }); + + ws.on_typed_message([](auto& session, + const std::string& type, + const vix::json::kvs& payload) + { + (void)session; + + if (type == "chat.message") { + session.broadcast_json("chat.message", payload); + } + }); + + ws.listen_blocking(); +} +``` + +### HTTP + WebSocket together + +```cpp +#include +#include + +using namespace vix; + +int main() +{ + vix::serve_http_and_ws([](auto& app, auto& ws) { + app.get("/", [](auto&, auto& res) { + res.json({ + "message", "Hello from Vix.cpp minimal example", + "framework", "Vix.cpp" + }); }); - app.run(8080); + ws.on_typed_message([&ws](auto& session, + const std::string& type, + const vix::json::kvs& payload) + { + (void)session; + + if (type == "chat.message") { + ws.broadcast_json("chat.message", payload); + } + }); + }); + + return 0; +} +``` + +### Minimal P2P control plane (HTTP) + +```cpp +#include +#include + +using namespace vix; + +int main() +{ + App app; + + P2PHttpOptions opt; + opt.enable_peers = true; + + install_p2p_http(app, opt); + + app.listen(5178, [](const vix::utils::ServerReadyInfo &info){ + console.info("UI API listening on", info.port); + }); + + app.wait(); } ``` --- -## Script mode Run C++ like a script +## Script mode — run C++ like a script ```bash vix run main.cpp @@ -126,32 +324,55 @@ vix dev main.cpp --- +## Included Runtimes & Modules + +Vix.cpp ships as an **umbrella runtime** composed of multiple modules: + +* **HTTP Runtime** — REST APIs and control plane +* **WebSocket Runtime** — real-time messaging and synchronization +* **P2P Runtime** — peer-to-peer networking and transport +* **p2p_http** — HTTP control plane for P2P introspection +* **ORM** — native C++ ORM with prepared statements +* **CLI** — Node-like developer experience +* **Cache, Middleware, Utils** — core building blocks + +Each module is optional and explicitly linked. + +--- + ## Documentation -- [Introduction](docs/introduction.md) -- [Quick Start](docs/quick-start.md) -- [Architecture & Modules](docs/architecture.md) -- [ORM Overview](docs/orm/overview.md) -- [Benchmarks](docs/benchmarks.md) -- [Examples](docs/examples/overview.md) -- [Build & Installation](docs/build.md) -- [CLI Options](docs/options.md) -- [CLI Reference](docs/vix-cli-help.md) - -## Module Documentation Index - -- **Core** : [docs/modules/core.md](docs/modules/core.md) -- **WebSocket** : [docs/modules/websocket.md](docs/modules/websocket.md) -- **ORM** : [docs/modules/orm.md](docs/modules/orm.md) -- **JSON** : [docs/modules/json.md](docs/modules/json.md) -- **Utils** : [docs/modules/utils.md](docs/modules/utils.md) -- **CLI** : [docs/modules/cli.md](docs/modules/cli.md) +* Introduction — `docs/introduction.md` +* Quick Start — `docs/quick-start.md` +* Architecture & Modules — `docs/architecture.md` +* HTTP Runtime — `docs/http/overview.md` +* WebSocket Runtime — `docs/websocket/overview.md` +* P2P Runtime — `docs/p2p/overview.md` +* ORM Overview — `docs/orm/overview.md` +* Benchmarks — `docs/benchmarks.md` +* Examples — `docs/examples/overview.md` +* Build & Installation — `docs/build.md` +* CLI Options — `docs/options.md` +* CLI Reference — `docs/vix-cli-help.md` +* Vix Console — `docs/console.md` --- -## ⭐ Support the project +## Support the project + +If you believe in: + +* modern C++ tooling +* offline-first systems +* peer-to-peer infrastructure +* native performance without compromise -If you believe in modern C++ tooling, offline-first systems, and native performance, please consider starring the repository. +--- + +## License + MIT License + +Copyright (c) Vix.cpp contributors diff --git a/examples/p2p/public/connect.html b/examples/p2p/public/connect.html new file mode 100644 index 0000000..3ed7eff --- /dev/null +++ b/examples/p2p/public/connect.html @@ -0,0 +1,107 @@ + + + + + + Vix · Connect peers + + + +
+
+
+
+
Vix · Connect peers
+
POST /api/p2p/connect · then open dashboard
+
+ ← Dashboard +
+
+
+ +
+
+

Add a peer endpoint

+
Example: host=127.0.0.1 port=9002 scheme=tcp
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ +
+ + +
+ +
ready
+
+
+ + + + diff --git a/examples/p2p/public/index.html b/examples/p2p/public/index.html new file mode 100644 index 0000000..b12de35 --- /dev/null +++ b/examples/p2p/public/index.html @@ -0,0 +1,1010 @@ + + + + + + Vix · P2P Dashboard + + + + + +
+
+
+ +
+

Vix · P2P Dashboard

+
Runtime status · multi-peer · CLI parity
+
+
+ +
+
+ + offline + · — ms +
+ +
+ refresh + +
+ +
+ filter + +
+ + + + + + + connect + + +
+
+
+ +
+ +
+
+

Runtime

+
last: —
+
+ +
+
+
Peers total
+
—
+
tracked
+
+ +
+
Peers connected
+
—
+
active links
+
+ +
+
Handshakes
+
—
+
started · completed
+
+ +
+
Connect attempts
+
—
+
deduped · failures
+
+ +
+
Backoff skips
+
—
+
guarded retries
+
+ +
+
Tracked endpoints
+
—
+
connect table
+
+
+ +
+
+ + +
+ +
+
+
+

Peers

+
—
+
+ +
+ + + + + + + + + + + + +
PeerEndpointStateSecure
Waiting for peers…
+
+ +
+ Tip: click a peer row to see details. +
+
+ +
+
+

Peer details

+
none
+
+ +
+
+
Peer id
+
—
+
+
+
Endpoint
+
—
+
+
+
State
+
—
+
+
+
Secure
+
—
+
+
+
Last seen
+
—
+
+
+
Public key
+
—
+
+
+ +
+
Notes
+
Select a peer to inspect metadata.
+
+
+
+ + +
+
+

Logs

+
/api/p2p/logs
+
+ 
Waiting for logs…
+
+
+
+ +
+ Vix.cpp · P2P HTTP · dashboard demo (no frameworks) +
+ + + + diff --git a/examples/p2p/server.cpp b/examples/p2p/server.cpp new file mode 100644 index 0000000..8f9cb36 --- /dev/null +++ b/examples/p2p/server.cpp @@ -0,0 +1,47 @@ +// vix run server.cpp +// http://127.0.0.1:5178/ + +#include +#include +#include +#include +#include + +using namespace vix; + +int main() +{ + App app; + + vix::p2p::NodeConfig cfg; + cfg.node_id = "A"; + cfg.listen_port = 9001; + + 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; + + vix::p2p_http::registerRoutes(app, runtime, opt); + + app.static_dir("./public"); + app.get("/", [](Request &, Response &res) + { res.file("./public/index.html"); }); + + app.get("/connect", [](Request &, Response &res) + { res.file("./public/connect.html"); }); + + app.listen(5178, [](const vix::utils::ServerReadyInfo &info) + { console.info("UI API listening on", info.port); }); + + app.wait(); + runtime.stop(); +} diff --git a/modules/cache b/modules/cache index 9b76554..68977e8 160000 --- a/modules/cache +++ b/modules/cache @@ -1 +1 @@ -Subproject commit 9b76554627bdff0d2b28931bf0c2e6993af3a383 +Subproject commit 68977e8f4883a9ca072e82a55860fd28f5e6bcae diff --git a/modules/core b/modules/core index 5e5de28..0be4577 160000 --- a/modules/core +++ b/modules/core @@ -1 +1 @@ -Subproject commit 5e5de28264feaf7f964da768de308aacbf23daed +Subproject commit 0be4577129de06367d5c77d2c77ab902dddb3525 diff --git a/modules/middleware b/modules/middleware index 7eda882..e2adec4 160000 --- a/modules/middleware +++ b/modules/middleware @@ -1 +1 @@ -Subproject commit 7eda882964f4c33b8976404bc0dab41fd678a4e4 +Subproject commit e2adec4bedf4c1370bc682df6493a1ba23268d4d diff --git a/modules/p2p b/modules/p2p index 8953e52..87550dc 160000 --- a/modules/p2p +++ b/modules/p2p @@ -1 +1 @@ -Subproject commit 8953e52e4f28f2763c4295ee0db169faea482565 +Subproject commit 87550dc02331c8be95d7c5ceb216025232b94a67 diff --git a/modules/p2p_http b/modules/p2p_http index de501c6..0bf96b4 160000 --- a/modules/p2p_http +++ b/modules/p2p_http @@ -1 +1 @@ -Subproject commit de501c6c7512d631f92cea56b35263eb542e0579 +Subproject commit 0bf96b49880408d9834892b7129e019bbffce0f1