From 44c4ab342dc6651ab5453e4cf86e1377b91e8dd7 Mon Sep 17 00:00:00 2001
From: Gaspard Kirira <gaspardkirira9@gmail.com>
Date: Mon, 2 Feb 2026 15:33:09 +0300
Subject: [PATCH] v1.27.0: OpenAPI docs for HTTP & WebSocket + improved
 WebSocket example

---
 examples/websocket/advanced/CMakeLists.txt    |  18 +-
 .../websocket/advanced/advanced_chat.html     |  31 +--
 examples/websocket/advanced/src/client.cpp    | 188 +++++++++---------
 examples/websocket/advanced/src/server.cpp    |  35 +---
 modules/core                                  |   2 +-
 modules/websocket                             |   2 +-
 6 files changed, 118 insertions(+), 158 deletions(-)

diff --git a/examples/websocket/advanced/CMakeLists.txt b/examples/websocket/advanced/CMakeLists.txt
index 4f10754..3eb4ee7 100644
--- a/examples/websocket/advanced/CMakeLists.txt
+++ b/examples/websocket/advanced/CMakeLists.txt
@@ -1,5 +1,15 @@
 # ------------------------------------------------------------------------------
-#  CMakeLists.txt — Advanced WebSocket Examples for Vix.cpp
+#  @file CMakeLists.cpp
+#  @author Gaspard Kirira
+#
+#  Copyright 2025, Gaspard Kirira.  All rights reserved.
+#  https://github.com/vixcpp/vix
+#  Use of this source code is governed by a MIT license
+#  that can be found in the License file.
+#
+#  Vix.cpp
+#
+#  Advanced WebSocket Examples for Vix.cpp
 #
 #  This CMake file builds two advanced demonstration executables showcasing
 #  production-style usage of the Vix.cpp WebSocket module:
@@ -30,10 +40,7 @@ project(vix_ws_advanced LANGUAGES CXX)
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-# ------------------------------------------------------------------------------
 #  Advanced WebSocket Server
-# ------------------------------------------------------------------------------
-
 add_executable(vix-ws-advanced-server
     src/server.cpp
 )
@@ -43,10 +50,7 @@ target_link_libraries(vix-ws-advanced-server
         vix::websocket
 )
 
-# ------------------------------------------------------------------------------
 #  Advanced WebSocket Client
-# ------------------------------------------------------------------------------
-
 add_executable(vix-ws-advanced-client
     src/client.cpp
 )
diff --git a/examples/websocket/advanced/advanced_chat.html b/examples/websocket/advanced/advanced_chat.html
index 3003855..3e6cf4d 100644
--- a/examples/websocket/advanced/advanced_chat.html
+++ b/examples/websocket/advanced/advanced_chat.html
@@ -4,7 +4,6 @@
     <meta charset="UTF-8" />
     <title>Vix WebSocket Rooms Chat</title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <!-- (CSS identique à la version précédente, je le laisse intact pour garder le style) -->
     <style>
       :root {
         --bg: #050816;
@@ -547,33 +546,26 @@ <h1>Vix WebSocket Chat</h1>
     </div>
 
     <script>
-      // --- Configuration ---
-      const WS_PORT = 9091; // WebSocket port (from config.json)
-      const HTTP_PORT = 8080; // HTTP app port (vix::App)
+      const WS_PORT = 9091;
+      const HTTP_PORT = 8080;
 
-      // Base HTTP pour /ws/poll et /ws/send
-      // Si tu ouvres le fichier en file:// ou depuis un autre port,
-      // on force les appels API vers le backend Vix (8080).
       const host = window.location.hostname || "localhost";
       const HTTP_BASE =
         window.location.protocol === "https:"
           ? `https://${host}:${HTTP_PORT}`
           : `http://${host}:${HTTP_PORT}`;
 
-      // --- State ---
       let ws = null;
       let currentUser = "anonymous";
       let currentRoom = "general";
       let connectedWS = false;
-      let lpMode = false; // vrai si on est en mode LP
-      let lpActive = false; // boucle LP en cours ou pas
+      let lpMode = false;
+      let lpActive = false;
       let activityCount = 0;
 
-      // Session ID LP pour /ws/poll et /ws/send
       let lpSessionId =
         "lp-" + Math.random().toString(36).slice(2) + Date.now().toString(36);
 
-      // --- DOM ---
       const statusDot = document.getElementById("statusDot");
       const statusText = document.getElementById("statusText");
       const connectBtn = document.getElementById("connectBtn");
@@ -587,7 +579,6 @@ <h1>Vix WebSocket Chat</h1>
       const activityLog = document.getElementById("activityLog");
       const activityCounter = document.getElementById("activityCounter");
 
-      // --- Utils ---
       function formatTime(d) {
         return d.toLocaleTimeString(undefined, {
           hour: "2-digit",
@@ -626,7 +617,6 @@ <h1>Vix WebSocket Chat</h1>
         }
       }
 
-      // --- Messages UI ---
       function addMessage({ kind, type, room, user, text }) {
         const container = document.createElement("div");
         container.classList.add("message");
@@ -717,7 +707,6 @@ <h1>Vix WebSocket Chat</h1>
             handleJsonEnvelope(obj);
           }
         } catch (e) {
-          // Fallback texte brut
           addMessage({
             kind: "system",
             type: "raw",
@@ -728,7 +717,6 @@ <h1>Vix WebSocket Chat</h1>
         }
       }
 
-      // --- Envoi WebSocket / LongPolling ---
       function sendViaWS(type, payload) {
         if (!ws || ws.readyState !== WebSocket.OPEN) return;
         const message = { type, payload: payload || {} };
@@ -771,7 +759,6 @@ <h1>Vix WebSocket Chat</h1>
         }
       }
 
-      // --- LongPolling loop ---
       async function longPollLoop() {
         lpActive = true;
         appendActivity(
@@ -834,7 +821,6 @@ <h1>Vix WebSocket Chat</h1>
         updateConnectionStatus();
       }
 
-      // --- WebSocket connect ---
       function connectWS() {
         const wsHost = host || "localhost";
         const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
@@ -846,11 +832,10 @@ <h1>Vix WebSocket Chat</h1>
 
         ws.onopen = () => {
           connectedWS = true;
-          stopLP(); // on coupe LP si jamais il tournait
+          stopLP();
           updateConnectionStatus();
           appendActivity("WebSocket connection opened", true);
 
-          // join room courante
           sendViaWS("chat.join", {
             room: currentRoom,
             user: currentUser,
@@ -869,7 +854,6 @@ <h1>Vix WebSocket Chat</h1>
             false
           );
 
-          // Fallback LP
           if (!lpMode) {
             startLP();
           }
@@ -881,7 +865,6 @@ <h1>Vix WebSocket Chat</h1>
         };
       }
 
-      // --- Connexion principale ---
       function connect() {
         currentUser = userInput.value.trim() || "anonymous";
         currentRoom = roomInput.value.trim() || "general";
@@ -895,7 +878,6 @@ <h1>Vix WebSocket Chat</h1>
       function joinRoom(newRoom) {
         if (!newRoom) return;
 
-        // leave ancienne room
         sendMessage("chat.leave", {
           room: currentRoom,
           user: currentUser,
@@ -904,7 +886,6 @@ <h1>Vix WebSocket Chat</h1>
         currentRoom = newRoom;
         currentRoomLabel.textContent = currentRoom;
 
-        // join nouvelle room
         sendMessage("chat.join", {
           room: currentRoom,
           user: currentUser,
@@ -927,7 +908,6 @@ <h1>Vix WebSocket Chat</h1>
         composerInput.focus();
       }
 
-      // --- Events UI ---
       connectBtn.addEventListener("click", () => {
         if (connectedWS || lpMode) return;
         connect();
@@ -952,7 +932,6 @@ <h1>Vix WebSocket Chat</h1>
         }
       });
 
-      // Valeurs par défaut
       userInput.value = "alice";
       roomInput.value = "africa";
       currentUserLabel.textContent = "—";
diff --git a/examples/websocket/advanced/src/client.cpp b/examples/websocket/advanced/src/client.cpp
index 14a3e00..85b1dda 100644
--- a/examples/websocket/advanced/src/client.cpp
+++ b/examples/websocket/advanced/src/client.cpp
@@ -1,7 +1,7 @@
 /**
- * @file client.cpp
- * @brief Advanced interactive WebSocket client example for Vix.cpp
- * @author Gaspard Kirira
+ *
+ *  @file server.cpp
+ *  @author Gaspard Kirira
  *
  *  Copyright 2025, Gaspard Kirira.  All rights reserved.
  *  https://github.com/vixcpp/vix
@@ -9,6 +9,7 @@
  *  that can be found in the License file.
  *
  *  Vix.cpp
+ * @brief Advanced interactive WebSocket client example for Vix.cpp
  *
  * This example demonstrates how to build a fully interactive, terminal-based
  * WebSocket client using the Vix.cpp WebSocket module. It is designed to show
@@ -87,113 +88,113 @@
 
 #include <boost/system/error_code.hpp>
 
-#include <vix/websocket.hpp> // expose Client + JsonMessage
+#include <vix/websocket.hpp>
 
 namespace ws = vix::websocket;
 
 using ClientPtr = std::shared_ptr<ws::Client>;
 using Clock = std::chrono::steady_clock;
 
-// Petit helper local : starts_with
 bool starts_with(const std::string &s, const std::string &prefix)
 {
   return s.size() >= prefix.size() &&
          s.compare(0, prefix.size(), prefix) == 0;
 }
 
-/**
- * @brief Configure le client WebSocket (handlers, auto-reconnect, heartbeat).
- */
-ClientPtr create_chat_client(std::string host,
-                             std::string port,
-                             std::string path,
-                             std::string user,
-                             std::string room)
+ClientPtr create_chat_client(
+    std::string host,
+    std::string port,
+    std::string path,
+    std::string user,
+    std::string room)
 {
   using ws::JsonMessage;
 
-  auto client = ws::Client::create(std::move(host),
-                                   std::move(port),
-                                   std::move(path));
-
-  // ───────────── Handlers ─────────────
-
-  client->on_open([client, user, room]
-                  {
-                        std::cout << "[client] Connected ✅" << std::endl;
-
-                        client->send(
-                            "chat.join",
-                            {
-                                "room", room,
-                                "user", user,
-                            }); });
-
-  client->on_message([](const std::string &msg)
-                     {
-                           auto jm = JsonMessage::parse(msg);
-
-                           if (!jm)
-                           {
-                               std::cout << msg << std::endl;
-                               return;
-                           }
-
-                           const std::string &type = jm->type;
-
-                           if (type == "chat.system")
-                           {
-                               std::string text     = jm->get_string("text");
-                               std::string roomName = jm->get_string("room");
-
-                               if (!roomName.empty())
-                               {
-                                   std::cout << "[system][" << roomName << "] " << text << std::endl;
-                               }
-                               else
-                               {
-                                   std::cout << "[system] " << text << std::endl;
-                               }
-                           }
-                           else if (type == "chat.message")
-                           {
-                               std::string user     = jm->get_string("user");
-                               std::string text     = jm->get_string("text");
-                               std::string roomName = jm->get_string("room");
-
-                               if (user.empty())
-                                   user = "anonymous";
-
-                               if (!roomName.empty())
-                               {
-                                   std::cout << "[chat][" << roomName << "] " << user << ": " << text << std::endl;
-                               }
-                               else
-                               {
-                                   std::cout << "[chat] " << user << ": " << text << std::endl;
-                               }
-                           }
-                           else
-                           {
-                               std::cout << msg << std::endl;
-                           } });
-
-  client->on_close([]()
-                   { std::cout << "[client] Disconnected." << std::endl; });
-
-  client->on_error([](const boost::system::error_code &ec)
-                   { std::cerr << "[client] error: " << ec.message() << std::endl; });
-
-  // Auto-reconnect + heartbeat
+  auto client = ws::Client::create(
+      std::move(host),
+      std::move(port),
+      std::move(path));
+
+  client->on_open(
+      [client, user, room]
+      {
+        std::cout << "[client] Connected ✅" << std::endl;
+
+        client->send(
+            "chat.join",
+            {
+                "room",
+                room,
+                "user",
+                user,
+            });
+      });
+
+  client->on_message(
+      [](const std::string &msg)
+      {
+        auto jm = JsonMessage::parse(msg);
+
+        if (!jm)
+        {
+          std::cout << msg << std::endl;
+          return;
+        }
+
+        const std::string &type = jm->type;
+
+        if (type == "chat.system")
+        {
+          std::string text = jm->get_string("text");
+          std::string roomName = jm->get_string("room");
+
+          if (!roomName.empty())
+          {
+            std::cout << "[system][" << roomName << "] " << text << std::endl;
+          }
+          else
+          {
+            std::cout << "[system] " << text << std::endl;
+          }
+        }
+        else if (type == "chat.message")
+        {
+          std::string user = jm->get_string("user");
+          std::string text = jm->get_string("text");
+          std::string roomName = jm->get_string("room");
+
+          if (user.empty())
+            user = "anonymous";
+
+          if (!roomName.empty())
+          {
+            std::cout << "[chat][" << roomName << "] " << user << ": " << text << std::endl;
+          }
+          else
+          {
+            std::cout << "[chat] " << user << ": " << text << std::endl;
+          }
+        }
+        else
+        {
+          std::cout << msg << std::endl;
+        }
+      });
+
+  client->on_close(
+      []()
+      { std::cout << "[client] Disconnected." << std::endl; });
+
+  client->on_error(
+      [](const boost::system::error_code &ec)
+      { std::cerr << "[client] error: " << ec.message() << std::endl; });
+
   client->enable_auto_reconnect(true, std::chrono::seconds(3));
   client->enable_heartbeat(std::chrono::seconds(20));
 
   return client;
 }
 
-/**
- * @brief Boucle CLI : gère /join, /leave, /quit et envoie les messages.
- */
 void run_chat_cli(ClientPtr client, std::string user, std::string room)
 {
   std::cout << "Type messages, /join <room>, /leave, /quit\n";
@@ -203,7 +204,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
     if (line == "/quit")
       break;
 
-    // /join <room>
     if (starts_with(line, "/join "))
     {
       std::string newRoom = line.substr(6);
@@ -213,7 +213,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
         continue;
       }
 
-      // Leave ancienne room
       client->send(
           "chat.leave",
           {
@@ -225,7 +224,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
 
       room = newRoom;
 
-      // Join nouvelle room
       client->send(
           "chat.join",
           {
@@ -239,7 +237,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
       continue;
     }
 
-    // /leave (reste connecté, mais ne participe plus à la room)
     if (line == "/leave")
     {
       client->send(
@@ -255,7 +252,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
       continue;
     }
 
-    // Message normal → chat.message dans la room courante
     if (!line.empty())
     {
       client->send(
@@ -274,7 +270,6 @@ void run_chat_cli(ClientPtr client, std::string user, std::string room)
 
 int main()
 {
-  // ───────────── Prompt user + room ─────────────
   std::cout << "Pseudo: ";
   std::string user;
   std::getline(std::cin, user);
@@ -288,11 +283,8 @@ int main()
     room = "general";
 
   auto client = create_chat_client("localhost", "9090", "/", user, room);
-
   client->connect();
-
   run_chat_cli(client, user, room);
-
   client->close();
   return 0;
 }
diff --git a/examples/websocket/advanced/src/server.cpp b/examples/websocket/advanced/src/server.cpp
index e061f0c..0d9f0b6 100644
--- a/examples/websocket/advanced/src/server.cpp
+++ b/examples/websocket/advanced/src/server.cpp
@@ -1,7 +1,7 @@
 /**
- * @file server.cpp
- * @brief Advanced WebSocket server example for Vix.cpp
- * @author Gaspard Kirira
+ *
+ *  @file server.cpp
+ *  @author Gaspard Kirira
  *
  *  Copyright 2025, Gaspard Kirira.  All rights reserved.
  *  https://github.com/vixcpp/vix
@@ -94,7 +94,7 @@
 
 #include <nlohmann/json.hpp>
 
-#include <vix.hpp> // HTTP runtime (App, vhttp::ResponseWrapper, etc.)
+#include <vix.hpp>
 
 #include <vix/websocket.hpp>
 #include <vix/websocket/Metrics.hpp>
@@ -123,11 +123,12 @@ int main()
 
   WebSocketMetrics metrics;
 
-  std::thread metricsThread([&metrics]()
-                            { vix::websocket::run_metrics_http_exporter(
-                                  metrics,
-                                  "0.0.0.0",
-                                  9100); });
+  std::thread metricsThread(
+      [&metrics]()
+      { vix::websocket::run_metrics_http_exporter(
+            metrics,
+            "0.0.0.0",
+            9100); });
   metricsThread.detach();
 
   vix::websocket::SqliteMessageStore store{"chat_messages.db"};
@@ -309,12 +310,9 @@ int main()
         }
       });
 
-  // ─────────────────────────────────────────────
   // 7) HTTP App : /ws/poll + /ws/send (LongPolling)
-  // ─────────────────────────────────────────────
   vix::App httpApp;
 
-  // Helper local pour lire ?name=value dans la target Beast
   auto get_query_param = [](const http::request<http::string_body> &req,
                             std::string_view key) -> std::optional<std::string>
   {
@@ -351,7 +349,6 @@ int main()
     return std::nullopt;
   };
 
-  // GET /ws/poll → retourne un array JSON de JsonMessage
   httpApp.get(
       "/ws/poll",
       [lpBridge, &get_query_param](const http::request<http::string_body> &req,
@@ -378,7 +375,6 @@ int main()
           }
           catch (...)
           {
-            // on garde 50
           }
         }
 
@@ -388,7 +384,6 @@ int main()
         res.status(http::status::ok).json(body);
       });
 
-  // POST /ws/send → HTTP -> LP (et via httpToWs → WS + rooms)
   httpApp.post(
       "/ws/send",
       [lpBridge](const http::request<http::string_body> &req,
@@ -421,7 +416,6 @@ int main()
           return;
         }
 
-        // Si pas de session_id fourni :
         if (sessionId.empty())
         {
           if (!room.empty())
@@ -453,7 +447,6 @@ int main()
         });
       });
 
-  // (Optionnel) /health simple
   httpApp.get(
       "/health",
       [](auto &, vix::vhttp::ResponseWrapper &res)
@@ -464,16 +457,9 @@ int main()
         });
       });
 
-  // ─────────────────────────────────────────────
-  // 8) Lancement WS + HTTP
-  // ─────────────────────────────────────────────
-
-  // Thread dédié WebSocket
   std::thread wsThread{[&wsApp]()
                        { wsApp.run_blocking(); }};
 
-  // Hook shutdown : quand HTTP reçoit SIGINT/SIGTERM, il sort de run()
-  // et on coupe proprement le WS.
   httpApp.set_shutdown_callback([&wsApp, &wsThread]()
                                 {
         wsApp.stop();
@@ -482,7 +468,6 @@ int main()
             wsThread.join();
         } });
 
-  // HTTP bloquant sur 8080
   httpApp.run(8080);
 
   return 0;
diff --git a/modules/core b/modules/core
index ce61119..0bb8e14 160000
--- a/modules/core
+++ b/modules/core
@@ -1 +1 @@
-Subproject commit ce611199e083dc7344901e3167ae871e54421c20
+Subproject commit 0bb8e148d0766712c9f88db7c67b34626b48be69
diff --git a/modules/websocket b/modules/websocket
index dbd9a3a..d4d5d5f 160000
--- a/modules/websocket
+++ b/modules/websocket
@@ -1 +1 @@
-Subproject commit dbd9a3a888d4a92b1c639891b89282d79247016a
+Subproject commit d4d5d5f8a121924443807de58750409453520ef2