Vix.cpp WebSocket Module

Native realtime communication for Vix.cpp.

The WebSocket module provides the runtime layer used to build realtime C++ applications with WebSocket servers, clients, sessions, typed messages, rooms, broadcasting, long-polling fallback, metrics, and message persistence.

Documentation

Full documentation is available here:

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

API reference:

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

What WebSocket provides

• Native WebSocket server
• Native WebSocket client
• Per-connection sessions
• Event routing
• Typed JSON messages
• Rooms and broadcasting
• Long-polling fallback
• HTTP bridge APIs
• Prometheus-style metrics
• Message persistence interfaces
• SQLite-backed message storage
• OpenAPI documentation helpers
• Integration with vix::App
• Shared runtime execution through RuntimeExecutor

Public header

#include<vix/websocket.hpp>

For HTTP and WebSocket together:

#include<vix.hpp>
#include<vix/websocket.hpp>

Minimal WebSocket server

#include<memory>
#include<string>
#include<vix/config/Config.hpp>
#include<vix/executor/RuntimeExecutor.hpp>
#include<vix/websocket.hpp>intmain()
{
vix::config::Config config{".env"};
auto executor =
std::make_shared<vix::executor::RuntimeExecutor>(4);
vix::websocket::Server ws{config, executor};
ws.on_message(
[](vix::websocket::Session &session, const std::string &message)
{
session.send_text("echo: " + message);
});
ws.listen_blocking();
return0;
}

Typed messages

Vix WebSocket supports a typed JSON message model:

{
"type": "chat.message",
"payload": {
"user": "Ada",
"text": "Hello"
}
}

Example handler:

ws.on_typed_message(
[&ws](vix::websocket::Session &session,
const std::string &type,
const vix::json::kvs &payload)
{
(void)session;
if (type == "chat.message")
{
ws.broadcast_json("chat.message", payload);
}
});

Rooms

ws.join_room(session.shared_from_this(), "general");
ws.broadcast_text_to_room(
"general",
"Hello room");

HTTP and WebSocket together

#include<memory>
#include<vix.hpp>
#include<vix/websocket.hpp>intmain()
{
vix::App app;
auto executor =
std::make_shared<vix::executor::RuntimeExecutor>(4);
vix::websocket::Server ws{app.config(), executor};
app.get("/", [](vix::Request &req, vix::Response &res)
{
(void)req;
res.text("HTTP + WebSocket");
});
ws.on_message(
[](vix::websocket::Session &session, const std::string &message)
{
session.send_text("echo: " + message);
});
vix::websocket::AttachedRuntime runtime{app, ws, executor};
app.run(8080);
return0;
}

WebSocket architecture

Server
-> LowLevelServer
-> Session
-> Router
-> user callbacks

For HTTP and WebSocket together:

vix::App
-> HTTP server
vix::websocket::Server
-> WebSocket server
AttachedRuntime
-> shared lifecycle
-> shared RuntimeExecutor
-> coordinated shutdown

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

• WebSocket documentation: https://docs.vixcpp.com/modules/websocket/
• WebSocket API reference: https://docs.vixcpp.com/modules/websocket/api-reference
• 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.