The App

framework::app is the main class you will interact with. It manages the event loop, listeners, route registration, and the mesh node.

Creating an App

#include <framework.hpp>


using namespace framework;

int main() {
    framework::app app;
    // ...
    app.run();
}

You can also pass a pre-built configuration:

using namespace framework;

configuration config;
config.ports_.node_port_.store(11001);

framework::app app(config);

What You Can Do with App

Register HTTP Routes

using namespace framework;
using namespace framework::clients::http;

app.register_endpoint(
    http_verb_t::get,
    "/hello",
    handler_function
);

Start Services

// HTTP only — serves REST API endpoints
app.run_http_service(8080);

// WebSocket only — serves the binary FlatBuffers protocol
app.run_websocket_service(8081);

// Raw WebSocket with custom handler — full control over connections
app.run_raw_websocket_service(8082, [](auto conn) { });

// TCP — raw binary protocol
app.run_tcp_service(9000, [](auto session) { });

// Combined HTTP + WebSocket on the same port
// The kernel detects WebSocket upgrade requests vs regular HTTP
app.run_service(8080);

Register Custom Handlers

// Override a built-in WebSocket opcode

using namespace framework;

app.override_websocket_handler(protocol::fbs::Opcode_Ping, my_ping_handler);

// Register a custom opcode handler (opcodes 200+)
app.register_custom_handler(200, my_custom_handler);

// Register a node-to-node handler (opcode 0-255)
// These handle inter-node mesh messages with custom opcodes
app.register_node_handler(42, my_node_handler);

Custom node handlers use the nodes::handler_t signature:

using nodes::handler_t = message_offset_t (*)(const nodes::request&);
// Receives a nodes::request (state, connection, message, builder)
// Returns a FlatBuffers message offset for the response

Run the Mesh

app.run_mesh();

Accessors

// Get the inter-node mesh port
auto mesh_port = app.get_mesh_port();

// Get all active listeners
auto& listeners = app.get_listeners();
for (auto& l : listeners) {
    fmt::println("Listener on port {}", l->get_port());
}

Boot Callback

app.on_boot([](const boost::system::error_code& ec) {
    if (!ec) {
        std::cout << "App is ready!" << std::endl;
    }
});

Starting the App

app.run();            // 1 thread (default)
app.run(4);           // 4 threads

This starts the event loop and blocks until app.stop() is called or the process receives a signal.

Thread safety: With multiple threads, handler code runs concurrently on I/O threads. Access to shared state must be protected (mutexes, atomics). The framework's state::instance provides thread-safe access to registries, but your handler code is not automatically serialized.