fix: route separator bug, stale docs, integration test regression

- Fix missing '/' between api_prefix and route pattern in
  PluginManager::register_routes (produced /api/v1apps/... instead
  of /api/v1/apps/...)
- Fix integration test expecting plaintext 'pong' after demo plugin
  was changed to return JSON
- Update plugin-system.rst, server.rst, troubleshooting.rst, and
  linux_introspection design doc to reference new get_routes() API
  instead of removed register_routes()
- Update documented API version from 4 to 5
- Remove dead code get_all_route_info() (zero callers)
- Add unit test verifying PluginManager route wrapping end-to-end

Author: bburda

docs/config/server.rst

@@ -564,7 +564,7 @@ Plugin loading lifecycle:
 4. Provider interfaces are queried via ``extern "C"`` functions
 5. ``configure()`` is called with per-plugin config
 6. ``set_context()`` passes the gateway context to the plugin
-7. ``register_routes()`` allows the plugin to add custom REST endpoints
+7. ``get_routes()`` returns custom REST endpoint definitions as ``vector<PluginRoute>``
 
 Error isolation: if a plugin throws during any lifecycle call, it is disabled
 without crashing the gateway. Other plugins continue to operate normally.

docs/troubleshooting.rst

@@ -254,7 +254,7 @@ ros2_medkit is currently suitable for development and testing. For production:
 **Q: Can I extend ros2_medkit with custom endpoints?**
 
 Yes. The gateway plugin framework allows you to add custom REST endpoints via
-``GatewayPlugin::register_routes()``. Create a shared library (``.so``) that
+``GatewayPlugin::get_routes()``. Create a shared library (``.so``) that
 implements the ``GatewayPlugin`` base class and configure it in ``gateway_params.yaml``.
 See :doc:`/config/server` for plugin configuration details.
 

docs/tutorials/plugin-system.rst

@@ -157,7 +157,6 @@ A self-contained plugin implementing UpdateProvider (copy-paste starting point):
    #include "ros2_medkit_gateway/plugins/plugin_types.hpp"
    #include "ros2_medkit_gateway/providers/update_provider.hpp"
 
-   #include <httplib.h>
    #include <nlohmann/json.hpp>
 
    using namespace ros2_medkit_gateway;
@@ -228,7 +227,7 @@ Plugin Lifecycle
 4. Provider interfaces are queried via ``get_update_provider()`` / ``get_introspection_provider()`` / ``get_log_provider()`` / ``get_script_provider()``
 5. ``configure()`` is called with per-plugin JSON config
 6. ``set_context()`` provides ``PluginContext`` with ROS 2 node, entity cache, faults, and HTTP utilities
-7. ``register_routes()`` allows registering custom REST endpoints
+7. ``get_routes()`` returns custom REST endpoint definitions as ``vector<PluginRoute>``
 8. Runtime: subsystem managers call provider methods as needed
 9. ``shutdown()`` is called before the plugin is destroyed
 
@@ -242,8 +241,14 @@ providing access to gateway data and utilities:
 - ``get_entity(id)`` - look up any entity (area, component, app, function) from the discovery cache
 - ``list_entity_faults(entity_id)`` - query faults for an entity
 - ``validate_entity_for_route(req, res, entity_id)`` - validate entity exists and matches the route type, auto-sending SOVD errors on failure
-- ``send_error()`` / ``send_json()`` - SOVD-compliant HTTP response helpers (static methods)
 - ``register_capability()`` / ``register_entity_capability()`` - register custom capabilities on entities
+
+.. note::
+
+   SOVD-compliant HTTP response helpers (``send_json()``, ``send_error()``) are instance
+   methods on ``PluginResponse``, not static methods on ``PluginContext``. Use
+   ``res.send_json(data)`` and ``res.send_error(status, code, msg)`` inside route handlers.
+
 - ``check_lock(entity_id, client_id, collection)`` - verify lock access before mutating operations; returns ``LockAccessResult`` with ``allowed`` flag and denial details
 - ``acquire_lock()`` / ``release_lock()`` - acquire and release entity locks with optional scope and TTL
 - ``get_entity_snapshot()`` - returns an ``IntrospectionInput`` populated from the current entity cache
@@ -302,10 +307,10 @@ for the lower-level registry API.
    still required because ``plugin_api_version()`` must return the current version
    (exact-match check).
 
-PluginContext API (v4)
+PluginContext API (v5)
 ----------------------
 
-Version 4 of the plugin API introduced several new methods on ``PluginContext``.
+Version 5 of the plugin API introduced several new methods on ``PluginContext``.
 These methods have default no-op implementations, so existing plugins continue to
 compile without changes (though a rebuild is required to match the new
 ``PLUGIN_API_VERSION``).
@@ -320,7 +325,7 @@ should call this before proceeding:
 
    auto result = ctx_->check_lock(entity_id, client_id, "configurations");
    if (!result.allowed) {
-     PluginContext::send_error(res, 409, result.denied_code, result.denied_reason);
+     res.send_error(409, result.denied_code, result.denied_reason);
      return;
    }
 
@@ -378,30 +383,36 @@ API described in `Cyclic Subscription Extensions`_.
 Custom REST Endpoints
 ---------------------
 
-Any plugin can register vendor-specific endpoints via ``register_routes()``.
-Use ``PluginContext`` utilities for entity validation and SOVD-compliant responses:
+Any plugin can expose vendor-specific endpoints by overriding ``get_routes()``, which
+returns a ``vector<PluginRoute>``. Each route specifies an HTTP method, a URL pattern
+relative to the API prefix (no leading slash), and a handler. Use ``PluginRequest`` and
+``PluginResponse`` for path parameters and SOVD-compliant responses:
 
 .. code-block:: cpp
 
-   void register_routes(httplib::Server& server, const std::string& api_prefix) override {
-     // Global vendor endpoint
-     server.Get(api_prefix + "/x-myvendor/status",
-       [this](const httplib::Request&, httplib::Response& res) {
-         PluginContext::send_json(res, get_status_json());
-       });
-
-     // Entity-scoped endpoint (matches a registered capability)
-     server.Get((api_prefix + R"(/apps/([^/]+)/x-medkit-traces)").c_str(),
-       [this](const httplib::Request& req, httplib::Response& res) {
-         auto entity = ctx_->validate_entity_for_route(req, res, req.matches[1]);
-         if (!entity) return;  // Error already sent
-
-         auto faults = ctx_->list_entity_faults(entity->id);
-         PluginContext::send_json(res, {{"entity", entity->id}, {"faults", faults}});
-       });
+   std::vector<PluginRoute> get_routes() override {
+     return {
+         // Global vendor endpoint
+         {"GET", "x-myvendor/status",
+          [this](const PluginRequest& /*req*/, PluginResponse& res) {
+            res.send_json(get_status_json());
+          }},
+
+         // Entity-scoped endpoint (matches a registered capability)
+         {"GET", R"(apps/([^/]+)/x-medkit-traces)",
+          [this](const PluginRequest& req, PluginResponse& res) {
+            auto entity_id = req.path_param(1);
+            auto entity = ctx_->validate_entity_for_route(req, res, entity_id);
+            if (!entity) return;  // Error already sent
+
+            auto faults = ctx_->list_entity_faults(entity->id);
+            res.send_json({{"entity", entity->id}, {"faults", faults}});
+          }},
+     };
    }
 
-Use the ``x-`` prefix for vendor-specific endpoints per SOVD convention.
+Use the ``x-`` prefix for vendor-specific endpoints per SOVD convention. Patterns are
+relative to the API prefix and must not include a leading slash.
 
 For entity-scoped endpoints, register a matching capability via ``register_capability()``
 or ``register_entity_capability()`` in ``set_context()`` so the endpoint appears in the
@@ -750,7 +761,7 @@ Alternatively, simply do not install the ``ros2_medkit_graph_provider`` package
 Error Handling
 --------------
 
-If a plugin throws during any lifecycle method (``configure``, ``set_context``, ``register_routes``,
+If a plugin throws during any lifecycle method (``configure``, ``set_context``, ``get_routes``,
 ``shutdown``), the exception is caught and logged. The plugin is disabled but the gateway continues
 operating. A failing plugin never crashes the gateway.
 
@@ -761,7 +772,7 @@ Plugins export ``plugin_api_version()`` which must return the gateway's ``PLUGIN
 If the version does not match, the plugin is rejected with a clear error message suggesting
 a rebuild against matching gateway headers.
 
-The current API version is **4**. It is incremented when the ``PluginContext`` vtable changes
+The current API version is **5**. It is incremented when the ``PluginContext`` vtable changes
 or breaking changes are made to ``GatewayPlugin`` or provider interfaces.
 
 Build Requirements

src/ros2_medkit_discovery_plugins/ros2_medkit_linux_introspection/design/index.rst

@@ -32,7 +32,7 @@ The following diagram shows the three plugins and their shared infrastructure.
            +name(): string
            +configure(config): void
            +set_context(ctx): void
-           +register_routes(server, prefix): void
+           +get_routes(): vector~PluginRoute~
        }
 
        interface IntrospectionProvider {
@@ -43,8 +43,6 @@ The following diagram shows the three plugins and their shared infrastructure.
            +register_capability()
            +validate_entity_for_route()
            +get_child_apps()
-           +send_json()
-           +send_error()
        }
    }
 

src/ros2_medkit_gateway/CMakeLists.txt

@@ -778,7 +778,9 @@ endif()
 # Export include directories for downstream packages (plugins)
 install(DIRECTORY include/ DESTINATION include)
 install(DIRECTORY src/vendored/tl_expected/include/ DESTINATION include/ros2_medkit_gateway/vendored)
-install(FILES src/vendored/cpp_httplib/httplib.h DESTINATION include/ros2_medkit_gateway/vendored)
+# Note: vendored httplib.h is NOT installed to the export dir. It is only used
+# internally by the gateway via VENDORED_DIR cmake parameter. Plugins no longer
+# need httplib - they use PluginRequest/PluginResponse wrappers instead.
 ament_export_include_directories(include include/ros2_medkit_gateway/vendored)
 
 ament_package()

src/ros2_medkit_gateway/include/ros2_medkit_gateway/plugins/plugin_manager.hpp

@@ -161,14 +161,6 @@ class PluginManager {
     return context_;
   }
 
-  // ---- Route descriptions (for handle_root auto-registration) ----
-
-  /**
-   * @brief Collect route info (method, pattern) from all active plugins
-   * @return Combined (method, pattern) pairs from all plugins
-   */
-  std::vector<std::pair<std::string, std::string>> get_all_route_info() const;
-
   // ---- Info ----
   bool has_plugins() const;
   std::vector<std::string> plugin_names() const;

src/ros2_medkit_gateway/src/plugins/plugin_manager.cpp

@@ -273,7 +273,7 @@ void PluginManager::register_routes(void * server_ptr, const std::string & api_p
     try {
       auto routes = lp.load_result.plugin->get_routes();
       for (auto & route : routes) {
-        std::string full_pattern = api_prefix + route.pattern;
+        std::string full_pattern = api_prefix + "/" + route.pattern;
         auto handler_fn = route.handler;  // capture by value for lambda
         auto httplib_handler = [handler_fn](const httplib::Request & req, httplib::Response & res) {
           PluginRequest plugin_req(&req);
@@ -381,26 +381,6 @@ std::vector<std::pair<std::string, IntrospectionProvider *>> PluginManager::get_
   return result;
 }
 
-std::vector<std::pair<std::string, std::string>> PluginManager::get_all_route_info() const {
-  std::shared_lock<std::shared_mutex> lock(plugins_mutex_);
-  std::vector<std::pair<std::string, std::string>> all;
-  for (const auto & lp : plugins_) {
-    if (!lp.load_result.plugin) {
-      continue;
-    }
-    try {
-      auto routes = lp.load_result.plugin->get_routes();
-      for (const auto & route : routes) {
-        all.emplace_back(route.method, route.pattern);
-      }
-    } catch (const std::exception & e) {
-      RCLCPP_ERROR(rclcpp::get_logger("plugin_manager"), "Plugin '%s' threw in get_routes(): %s",
-                   lp.load_result.plugin->name().c_str(), e.what());
-    }
-  }
-  return all;
-}
-
 bool PluginManager::has_plugins() const {
   std::shared_lock<std::shared_mutex> lock(plugins_mutex_);
   for (const auto & lp : plugins_) {