feat: Document message handlers subsystem

- Added a new example demonstrating the creation, registration, and dispatch of message handlers in the irsol framework.
- Refactored handler context to use `std::shared_ptr` for better memory management.
- Updated various handler implementations to accommodate the new context structure.

Author: deldoc

src/examples/00-logging-and-asserting/README.md

@@ -76,7 +76,7 @@ Different sinks are configured to have a different _runtime_ log level by defaul
 
 | Compilation mode | Debug   | Release |
 | ---------------- | ------- | ------- |
-| Console logger   | `debug` | `info`  |
+| Console logger   | `trace` | `info`  |
 | File logger      | `trace` | `info`  |
 
 

src/examples/04-message-handlers/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.13.0)
+
+project(04-message-handlers)
+
+add_executable(
+    ${PROJECT_NAME}
+    main.cpp
+)
+target_compile_definitions(${PROJECT_NAME} PRIVATE PROGRAM_NAME="${PROJECT_NAME}")
+
+target_link_libraries(${PROJECT_NAME}
+    irsol::core
+)

src/examples/04-message-handlers/README.md

@@ -0,0 +1,48 @@
+# 04-message-handlers {#message_handlers}
+@see examples/04-message-handlers/main.cpp
+
+Welcome to the `irsol::server::handlers` subsystem!  
+This guide introduces you to the core concepts and practical usage of **handlers** and the **message-handler** system in the irsol framework.
+
+## What are Handlers?
+
+Handlers are the building blocks that connect protocol messages (such as commands, assignments, and inquiries) to your application logic. Each handler is responsible for processing a specific type of protocol message and producing an appropriate response.
+
+Handlers are typically implemented as C++ classes (deriving from a base handler template @ref irsol::server::handlers::internal::HandlerBase), but can also be defined as lambda functions for rapid prototyping or simple use cases.
+
+## What is a MessageHandler?
+
+The @ref irsol::server::handlers::MessageHandler is a central registry and dispatcher. It:
+
+- Receives parsed protocol messages and forwards them to the correct handler.
+- Allows you to register, replace, or remove handlers at runtime.
+
+## Typical Workflow
+
+1. **Implement a Handler**  
+   Create a handler class (or lambda) that processes a specific protocol message.
+
+2. **Register the Handler**  
+   Register your handler with a `MessageHandler` instance, associating it with a message identifier.
+
+3. **Dispatch Messages**  
+   When a protocol message is received, the `MessageHandler` looks up the handler for its identifier and invokes it, passing the message and client context.
+
+## Example
+@see examples/04-message-handlers/main.cpp
+See the `main` file in this folder for a complete example showing:
+
+- How to define a custom handler.
+- How to register it with a `MessageHandler`.
+- How to dispatch messages and verify handler invocation.
+
+## When to Use `Lambda` Handlers
+
+For simple or one-off logic, you can use a lambda handler instead of a full class. This is especially useful for:
+
+- Prototyping new features.
+- Writing test or mock handlers.
+- Reducing boilerplate for trivial message processing.
+
+
+For more details, see the documentation in @ref irsol/server/handlers/base.hpp and @ref irsol/server/handlers/lambda_handler.hpp, and the API reference.

src/examples/04-message-handlers/main.cpp

@@ -0,0 +1,106 @@
+/// @file examples/04-message-handlers/main.cpp
+/// @brief Demonstrates creation, registration, and dispatch of handlers using
+/// @ref irsol::server::handlers::MessageHandler.
+
+#include "irsol/irsol.hpp"
+
+#include <memory>
+#include <string>
+#include <vector>
+
+/// @brief Returns the program name, typically used for logging.
+/// If `PROGRAM_NAME` is not defined at compile time, returns `"message-handlers-demo"`.
+const std::string
+getProgramName()
+{
+#ifndef PROGRAM_NAME
+#define PROGRAM_NAME "message-handlers-demo"
+#endif
+  return PROGRAM_NAME;
+}
+
+/// @brief Example custom handler for Assignment messages.
+class MyAssignmentHandler : public irsol::server::handlers::AssignmentHandler
+{
+public:
+  MyAssignmentHandler(std::shared_ptr<irsol::server::handlers::Context> ctx)
+    : irsol::server::handlers::AssignmentHandler(ctx)
+  {}
+
+  /// Overrides the base operator() as we skip the collection of the client's Session
+  /// in this demo, which is the behavior of the base class.
+  std::vector<irsol::server::handlers::out_message_t> operator()(
+    IRSOL_MAYBE_UNUSED const irsol::types::client_id_t& clientId,
+    irsol::protocol::Assignment&&                       message) override
+  {
+    return process(nullptr, std::move(message));
+  }
+
+protected:
+  std::vector<irsol::server::handlers::out_message_t> process(
+    IRSOL_MAYBE_UNUSED std::shared_ptr<irsol::server::ClientSession> client,
+    irsol::protocol::Assignment&&                                    message) override
+  {
+    IRSOL_LOG_INFO("[MyAssignmentHandler] Called with {}.", message.toString());
+    // Respond with a Success message
+    // Due to move-only semantics of `Success`, we must create the response vector
+    // in this way. Using brace-initialization like `return
+    // {irsol::protocol::Success::from(message)};` would not work here.
+    std::vector<irsol::server::handlers::out_message_t> result;
+    result.emplace_back(irsol::protocol::Success::from(message));
+    return result;
+  }
+};
+
+/// @brief Demonstrates handler creation, registration, and dispatch.
+void
+demoHandlers()
+{
+  // Don't pass a Context, as we don't need it in this demo
+  std::shared_ptr<irsol::server::handlers::Context> ctx = nullptr;
+
+  // Create a MessageHandler instance
+  irsol::server::handlers::MessageHandler msgHandler;
+
+  // Create and register a custom Assignment handler for "foo" identifier.
+  msgHandler.registerHandler<irsol::protocol::Assignment>(
+    "foo", irsol::server::handlers::makeHandler<MyAssignmentHandler>(ctx));
+
+  // Simulate a session and client id
+  irsol::types::client_id_t clientId = irsol::utils::uuid();
+
+  // Dispatch messages to the MessageHandler
+
+  // Create test Assignment messages
+  irsol::protocol::Assignment fooMsg("foo", 42);
+  IRSOL_LOG_INFO("Dispatching {}...", fooMsg.toString());
+  auto fooResult = msgHandler.handle(clientId, std::move(fooMsg));
+  IRSOL_LOG_INFO("fooResult size: {}", fooResult.size());
+  for(const auto& msg : fooResult) {
+    IRSOL_LOG_INFO("Response: {}", irsol::protocol::toString(msg));
+  }
+
+  // Try dispatching an unregistered identifier
+  irsol::protocol::Assignment unknownMsg("baz", 0);
+  IRSOL_LOG_INFO("Dispatching {} (should not find handler)...", unknownMsg.toString());
+  auto unknownResult = msgHandler.handle(clientId, std::move(unknownMsg));
+  IRSOL_LOG_INFO("unknownResult size: {}", unknownResult.size());
+  for(const auto& msg : unknownResult) {
+    IRSOL_LOG_INFO("Response: {}", irsol::protocol::toString(msg));
+  }
+}
+
+/// @brief Main entry point for the handler demo application.
+int
+main()
+{
+  // Construct log file path based on program name
+  std::string logPath = "logs/" + getProgramName() + ".log";
+  irsol::initLogging(logPath.c_str());
+
+  // Enable custom assertion handler
+  irsol::initAssertHandler();
+
+  demoHandlers();
+  return 0;
+}

src/examples/CMakeLists.txt

@@ -16,6 +16,7 @@ add_subdirectory(00-logging-and-asserting)
 add_subdirectory(01-loading-images)
 add_subdirectory(02-interacting-with-camera-features)
 add_subdirectory(03-message-protocols)
+add_subdirectory(04-message-handlers)
 add_subdirectory(simple)
 add_subdirectory(camera_socket)
 

src/examples/README.md

@@ -18,3 +18,6 @@ These examples serve as practical references to help you get started and underst
 * @subpage message_protocols
   Covers the topic of how messages are parsed, processed and serialized back to the client in the client-server architecture implemented in the `irsol` project.
 
+* @subpage message_handlers
+  Covers the topic of how to implement and use message handlers in the `irsol` framework, including the @ref irsol::server::handlers::MessageHandler class and lambda handlers for rapid prototyping.
+

src/irsol/include/irsol/server/app.hpp

@@ -203,15 +203,17 @@ class App
    * registerLambdaHandler<protocol::Command>(
    *   "custom_cmd",
    *   ctx,
-   *   [](handlers::Context& ctx, const irsol::types::client_id_t& clientId, protocol::Command&&
-   * cmd) { return std::vector<protocol::OutMessage>{...};
+   *   [](std::shared_ptr<handlers::Context> ctx, const irsol::types::client_id_t& clientId,
+   * protocol::Command&& cmd) { return std::vector<protocol::OutMessage>{...};
    *   }
    * );
    * ```
    */
   template<typename InMessageT, typename LambdaT>
-  void
-  registerLambdaHandler(const std::string& identifier, handlers::Context& ctx, LambdaT&& lambda)
+  void registerLambdaHandler(
+    const std::string&                 identifier,
+    std::shared_ptr<handlers::Context> ctx,
+    LambdaT&&                          lambda)
   {
     auto  handler = handlers::makeLambdaHandler<InMessageT>(ctx, std::forward<LambdaT>(lambda));
     auto& messageHandler = *m_messageHandler;

src/irsol/include/irsol/server/client/session.hpp

@@ -39,12 +39,8 @@ class App;
  *
  * In addition, the session holds a reference to the central @ref irsol::server::App instance,
  * which enables it to interact with the global server context (e.g., for broadcasting).
- *
- * The class derives from `std::enable_shared_from_this` to allow safe
- * creation of `std::shared_ptr` instances to itself. This is required for
- * asynchronous operations and thread-safe lifetime management.
  */
-class ClientSession : public std::enable_shared_from_this<ClientSession>
+class ClientSession
 {
 public:
   /**

src/irsol/include/irsol/server/handlers.hpp

@@ -38,6 +38,9 @@
  * @see irsol::server::handlers::MessageHandler
  */
 
+namespace irsol {
+namespace server {
+
 /**
  * @namespace irsol::server::handlers
  * @brief Contains all logic for dispatching and implementing protocol message handlers.
@@ -61,8 +64,6 @@
  * @see irsol::server::handlers::MessageHandler
  * @see irsol::protocol
  */
-namespace irsol {
-namespace server {
 namespace handlers {}
 }
 }

src/irsol/include/irsol/server/handlers/assignment_frame_rate.hpp

@@ -28,7 +28,7 @@ class AssignmentFrameRateHandler : public AssignmentHandler
    * @brief Constructs the AssignmentFrameRateHandler.
    * @param ctx Handler context.
    */
-  AssignmentFrameRateHandler(Context ctx);
+  AssignmentFrameRateHandler(std::shared_ptr<Context> ctx);
 
 protected:
   /**