BOOST 1.88 Compatibility Issue

[olxgdm]

Build Failure: Boost 1.88 API Compatibility Issues

Summary

Vix.cpp fails to build with Boost 1.88 due to breaking API changes in boost::asio. The build errors occur in the core module during compilation of session and server components.

This affects fresh clones of the repository on systems with Boost 1.88 (current Ubuntu 26.04 / Debian testing).

---

Environment

Component	Version / Details
OS	Ubuntu 26.04 (Plucky Puffin)
Boost	1.88.0-1.4ubuntu1
Compiler	GCC 12.5.0 / GCC 15.2.0
CMake	3.31.6
Build Type	Release
Vix.cpp Commit	0de8931 (main branch, Jan 5 2026)

All system dependencies installed:

sudo apt install -y g++-12 cmake make git \
  libboost-all-dev nlohmann-json3-dev libspdlog-dev

---

Steps to Reproduce

1. Clone repository (fresh install):

   git clone https://github.com/vixcpp/vix.git
   cd vix
   git submodule update --init --recursive

2. Configure build:

   cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

   ✅ CMake configuration succeeds

3. Attempt build:

   cmake --build build -j$(nproc)

   ❌ Build fails with compilation errors

---

Build Errors

Error 1: boost::asio::socket_base::max_connections not found

File: modules/core/src/server/HTTPServer.cpp:115

error: 'max_connections' is not a member of 'boost::asio::socket_base'
  115 |         acceptor_->listen(boost::asio::socket_base::max_connections, ec);
      |                                                     ^~~~~~~~~~~~~~~

Root Cause:
The boost::asio::socket_base::max_connections constant was removed in Boost 1.88. It should be replaced with boost::asio::socket_base::max_listen_connections or a numeric constant.

Reference:

• Boost.Asio 1.88.0 Release Notes
• Deprecated in Boost 1.86, removed in 1.88

---

Error 2: timer->cancel(ec) signature mismatch

File: modules/core/src/session/Session.cpp:73

error: no matching function for call to 'boost::asio::basic_waitable_timer<std::chrono::_V2::steady_clock>::cancel(boost::system::error_code&)'
   73 |             timer_->cancel(ec);
      |             ~~~~~~~~~~~~~~^~~~

Available Candidate:

std::size_t cancel()  // No error_code parameter

Root Cause:
In Boost 1.88, cancel() no longer accepts an error_code& parameter. The error-code overload was removed. The method now returns std::size_t (number of cancelled operations) and throws on error instead of returning error codes.

Reference:

• Boost.Asio Timer API Changes

---

Expected Behavior

• ✅ Build succeeds on systems with Boost 1.88
• ✅ Backward compatibility maintained for Boost 1.83–1.87 (if feasible)
• ✅ CI/CD tests against multiple Boost versions

---

Current Workarounds

Workaround 1: Downgrade Boost (not recommended)

# Requires removing Boost 1.88 and manually installing older version
# May break other system packages

Workaround 2: Apply manual patches (temporary)

Users can manually fix the source files (see "Proposed Solution" below).

---

Proposed Solution

Fix 1: Replace max_connections constant

File: modules/core/src/server/HTTPServer.cpp

- acceptor_->listen(boost::asio::socket_base::max_connections, ec);
+ acceptor_->listen(boost::asio::socket_base::max_listen_connections, ec);

Or use CMake version detection:

#if BOOST_VERSION >= 108800  // Boost 1.88.0+
    acceptor_->listen(boost::asio::socket_base::max_listen_connections, ec);
#else
    acceptor_->listen(boost::asio::socket_base::max_connections, ec);
#endif

---

Fix 2: Update cancel() call signature

File: modules/core/src/session/Session.cpp

Option A: Remove error_code parameter (simplest):

- timer_->cancel(ec);
+ timer_->cancel();

Option B: Catch exceptions for error handling:

try {
    timer_->cancel();
} catch (const boost::system::system_error& e) {
    // Handle error if needed
}

Option C: Use version-aware code:

#if BOOST_VERSION >= 108800
    timer_->cancel();  // Boost 1.88+
#else
    boost::system::error_code ec;
    timer_->cancel(ec);  // Boost < 1.88
#endif

---

Additional Context

Impact Scope

• Severity: High — Build completely fails, no workaround without source modification
• Affected Users: Anyone using Ubuntu 26.04, Debian testing, or manually installed Boost 1.88
• Modules Affected: vix_core (HTTPServer, Session)
• Related Modules: Potentially vix_websocket if using similar patterns

CI/CD Considerations

The project's CI currently uses libboost-all-dev (line 16 in .github/workflows/SECURITY_CI.yml), which installs the default Boost version. As Ubuntu 26.04 and newer Debian releases become the CI default, this issue will affect automated builds.

Recommendation:

• Add Boost version matrix testing in CI (e.g., test against 1.83, 1.86, 1.88)
• Document minimum and maximum supported Boost versions in build documentation

---

Related Issues / PRs

None found. This is the first reported instance of Boost 1.88 incompatibility.