fix(cmake): cap find_package(httplib) at < 0.20 and flag the multipart pin

The medkit_find_cpp_httplib pkg-config tier already masks cpp-httplib
>= 0.20 (which dropped the multipart Request::has_file API the gateway
uses), but the find_package(httplib) fallback accepted any version. A
distro shipping httplibConfig.cmake for 0.26 would resolve there and
skip the vendored fallback. Apply the same < 0.20 cap to that tier;
unversioned source-build configs still pass through.

Add FIXME(#409) markers at the multipart sites (route_registry,
response_types, bulkdata_handlers, script_handlers) that depend on the
removed httplib::MultipartFormData / req.files API, and link #409 from
the cmake pin so the vendored-header workaround stays tracked.

Author: bburda

src/ros2_medkit_cmake/cmake/ROS2MedkitCompat.cmake

@@ -85,7 +85,7 @@ endmacro()
 # On Lyrical/Resolute the system package is 0.26.x which removed the
 # multipart `Request::has_file` / `get_file_value` API used by
 # BulkDataHandlers, so we cap pkg-config at < 0.20 and fall back to the
-# vendored copy until the handler is migrated to the newer API.
+# vendored copy until the handler is migrated to the newer API (see #409).
 #
 # Creates a unified alias target `cpp_httplib_target` for consumers.
 # ---------------------------------------------------------------------------
@@ -107,9 +107,17 @@ macro(medkit_find_cpp_httplib)
     message(STATUS "[MedkitCompat] cpp-httplib: using pkg-config (${cpp_httplib_VERSION})")
   else()
     find_package(httplib QUIET)
-    if(TARGET httplib::httplib)
+    # Cap this tier at [0.14, 0.20) like the pkg-config tier above: a future
+    # distro shipping httplibConfig.cmake for 0.26 would otherwise resolve here
+    # and skip the vendored fallback, even though 0.26 dropped the multipart
+    # Request::has_file API. An unversioned config (deliberate source build) is
+    # trusted and passes through.
+    if(TARGET httplib::httplib AND DEFINED httplib_VERSION AND NOT httplib_VERSION VERSION_LESS "0.20")
+      message(STATUS "[MedkitCompat] cpp-httplib: cmake config ${httplib_VERSION} removes the multipart Request::has_file API; falling back to vendored 0.14")
+    endif()
+    if(TARGET httplib::httplib AND (NOT DEFINED httplib_VERSION OR httplib_VERSION VERSION_LESS "0.20"))
       add_library(cpp_httplib_target ALIAS httplib::httplib)
-      message(STATUS "[MedkitCompat] cpp-httplib: using cmake config (source build)")
+      message(STATUS "[MedkitCompat] cpp-httplib: using cmake config (source build, version '${httplib_VERSION}')")
     elseif(_mfch_VENDORED_DIR AND EXISTS "${_mfch_VENDORED_DIR}/httplib.h")
       add_library(cpp_httplib_vendored INTERFACE)
       target_include_directories(cpp_httplib_vendored SYSTEM INTERFACE "${_mfch_VENDORED_DIR}")

src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/response_types.hpp

@@ -56,6 +56,9 @@ struct BinaryResponse {
 struct MultipartBody {
   /// Raw parts as parsed by cpp-httplib. Each part carries name, filename,
   /// content type, and the part bytes.
+  // FIXME(#409): httplib::MultipartFormDataItems is unavailable in cpp-httplib
+  // >= 0.20 (req.form API). Replace with a gateway-owned part type to decouple
+  // handlers from the cpp-httplib struct and lift the vendored-header pin.
   httplib::MultipartFormDataItems parts;
 };
 

src/ros2_medkit_gateway/src/http/handlers/bulkdata_handlers.cpp

@@ -478,6 +478,8 @@ BulkDataHandlers::upload(const http::TypedRequest & req, const http::MultipartBo
   // every named part into MultipartBody.parts; walk the vector instead of
   // relying on `req.files` map ordering so the typed surface does not leak
   // through to the cpp-httplib shape.
+  // FIXME(#409): httplib::MultipartFormData is unavailable in cpp-httplib
+  // >= 0.20; migrate to the req.form API (tracked with the vendored-header pin).
   const httplib::MultipartFormData * file_part = nullptr;
   const httplib::MultipartFormData * description_part = nullptr;
   const httplib::MultipartFormData * metadata_part = nullptr;

src/ros2_medkit_gateway/src/http/handlers/script_handlers.cpp

@@ -210,6 +210,8 @@ ScriptHandlers::upload_script(const http::TypedRequest & req, const http::Multip
   // MultipartBody.parts; we walk the vector instead of relying on `req.files`
   // map ordering so the typed surface does not leak through to the cpp-httplib
   // shape.
+  // FIXME(#409): httplib::MultipartFormData is unavailable in cpp-httplib
+  // >= 0.20; migrate to the req.form API (tracked with the vendored-header pin).
   const httplib::MultipartFormData * file_part = nullptr;
   const httplib::MultipartFormData * metadata_part = nullptr;
   for (const auto & part : body.parts) {

src/ros2_medkit_gateway/src/openapi/route_registry.hpp

@@ -999,6 +999,9 @@ RouteEntry & RouteRegistry::multipart_upload(
     // body.parts default-constructs empty; the loop below populates it from req.files.
     // cpp-httplib exposes parsed multipart entries via `req.files`; surface
     // them through MultipartBody.parts as MultipartFormData entries.
+    // FIXME(#409): `req.files` / httplib::MultipartFormData are unavailable in
+    // cpp-httplib >= 0.20; migrate to the req.form API so the system package can
+    // be used on Lyrical/Resolute instead of the vendored 0.14.3 header.
     for (const auto & [name, file] : req.files) {
       httplib::MultipartFormData mp;
       mp.name = name;