fix(server): build cpprestsdk against libc++ >= 16 via overlay port

[Ansh-Karnwal]

Fixes #1438

Problem

The C++ engine links against a vendored copy of cpprestsdk (archived by Microsoft, frozen at 2.10.19). On any host with a modern libc++ (>= 16), the engine link step fails:

error: implicit instantiation of undefined template 'std::char_traits<unsigned char>'

This blocks the build on recent distros (Fedora 40+, Ubuntu 24.04) and on clang/libc++ 16 through 22. The Linux engine build uses -stdlib=libc++, so it is exposed.

Root cause

Value2StringFormatter<uint8_t> in Release/include/cpprest/streams.h returns std::basic_string<uint8_t>. Since uint8_t is unsigned char, that type needs std::char_traits<unsigned char>. libc++ 16 removed the non-standard char_traits specializations for unsigned char (and friends), so the type can no longer be instantiated. libstdc++ still provides the extension, which is why only libc++ builds break.

Note that cpprestsdk already defines its own char_traits<unsigned char>, but that one lives in the Concurrency::streams namespace and does not satisfy std::basic_string, so it does not help here.

Change

Add a vcpkg overlay port for cpprestsdk under packages/server/cmake/ports/cpprestsdk/, following the existing overlay-port pattern in this repo (e.g. tinyxml2, breakpad). The overlay is a copy of the stock vcpkg 2026.04.27 port (cpprestsdk 2.10.19, commit 411a109) and its patch set, with one extra patch layered on top:

• fix-libcxx16-char-traits.patch reintroduces a minimal, standard-conforming std::char_traits<unsigned char> in astreambuf.h (a header streams.h already includes).
• The specialization is guarded by #if defined(_LIBCPP_VERSION) && _LIBCPP_VERSION >= 160000, so it is a no-op on libstdc++ and on libc++ < 16. Those still ship the extension, and defining it there would be a redefinition. The <string> include is placed before the guard so _LIBCPP_VERSION is defined when the guard is evaluated.

This is the overlay-port approach suggested in the issue. Migrating off cpprestsdk entirely is the longer-term path and is tracked separately in #1468.

Verification

Reproduced and verified locally with clang/libc++ 22 (the failure exists for any libc++ >= 16):

• Compiling the real cpprest/streams.h without the patch fails with the exact char_traits<unsigned char> error at two sites in <string>.
• Compiling the same header with the patch produces zero errors under -fsyntax-only.
• The guard was checked on both toolchains: under clang/libc++ the specialization is defined and std::basic_string<uint8_t> compiles and runs; under gcc/libstdc++ the block is skipped and there is no redefinition. Also confirmed under -std=c++14 and -std=c++17.
• git apply --check confirms the patch applies cleanly against a fresh 2.10.19 checkout.

The final engine link against a full libc++ build is left to CI, which builds the port through vcpkg on the pinned toolchain.

Notes for reviewers

• When the pinned vcpkg version is bumped, portfile.cmake, vcpkg.json, and the stock .patch files should be re-synced from upstream and this patch re-verified. This is noted in the port's README.md.
• No public contract (node/SDK/protocol surface) changes, so no co-located docs are affected.

Summary by CodeRabbit

• New Features
  • Packaged CppRestSDK v2.10.19 integration with configurable compression and WebSocket support.
• Bug Fixes
  • Improved compatibility with newer Boost.Asio APIs, OpenSSL detection, Clang DLL export/import handling, libc++ 16+ builds, and MSVC/UWP compiler behavior.
  • Prevented build issues from missing OpenSSL locations and narrowing/switch mismatches; updated Asio networking and SSL hostname verification.
• Documentation
  • Added/updated port documentation describing the overlay, mirrored upstream commit, and applied patch details.

[github-actions]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 77ba8d7f-5a4d-4abe-b695-8abbe06eeca7

📥 Commits

Reviewing files that changed from the base of the PR and between 3ff5ee9 and be8e0d7.

📒 Files selected for processing (1)

• packages/server/cmake/ports/cpprestsdk/fix-libcxx16-char-traits.patch

---

📝 Walkthrough

Walkthrough

Adds a vcpkg overlay port for cpprestsdk, pins its upstream source, applies Boost.Asio and toolchain compatibility patches, configures platform features, and packages the resulting library with CMake metadata and license files.

Changes

cpprestsdk overlay port

Layer / File(s)	Summary
Port manifest and packaging packages/server/cmake/ports/cpprestsdk/vcpkg.json, packages/server/cmake/ports/cpprestsdk/portfile.cmake	Defines cpprestsdk metadata, dependencies, features, pinned source retrieval, patch application, platform configuration, installation fixups, and package metadata.
Boost.Asio API modernization packages/server/cmake/ports/cpprestsdk/fix-asio-error.patch	Migrates threadpool, HTTP, scheduler, and WebSocket code to newer Boost.Asio context, resolver, timer, buffer, work-guard, and TLS APIs.
Platform and compiler compatibility packages/server/cmake/ports/cpprestsdk/fix-clang-dllimport.patch, packages/server/cmake/ports/cpprestsdk/fix-find-openssl.patch, packages/server/cmake/ports/cpprestsdk/fix-uwp.patch, packages/server/cmake/ports/cpprestsdk/fix-narrowing.patch, packages/server/cmake/ports/cpprestsdk/silence-stdext-checked-array-iterators-warning.patch	Updates export macros, OpenSSL path handling, UWP option scope, compiler detection, unsigned sentinel cases, and an MSVC warning definition.
libc++ compatibility documentation packages/server/cmake/ports/cpprestsdk/fix-libcxx16-char-traits.patch, packages/server/cmake/ports/cpprestsdk/README.md	Adds a guarded std::char_traits<unsigned char> specialization for libc++ 16+ and documents the overlay snapshot and compatibility patch.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant vcpkg
  participant GitHub
  participant cpprestsdk
  vcpkg->>GitHub: Fetch pinned cpprestsdk commit
  vcpkg->>cpprestsdk: Apply compatibility patches
  vcpkg->>cpprestsdk: Configure selected features and platform options
  cpprestsdk->>vcpkg: Install library, CMake files, and license

Loading

Possibly related issues

• Issue 1468: Concerns the cpprestsdk dependency and its libc++ compatibility workaround, which this PR adds through an overlay port.

Suggested reviewers: jmaionchi, rod-christensen, stepmikhaylov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly states the server cpprestsdk overlay-port fix for libc++ 16+, matching the PR's main change.
Linked Issues check	✅ Passed	The overlay port and char_traits shim directly address the libc++ ≥16 build/link failure for cpprestsdk on modern toolchains.
Out of Scope Changes check	✅ Passed	The extra patches and port metadata are all part of the cpprestsdk overlay needed for the same toolchain-compatibility fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/server/cmake/ports/cpprestsdk/fix-libcxx16-char-traits.patch`:
- Around line 17-19: Update the include list in the libc++ char-traits patch to
explicitly include <cstdio>, alongside the existing headers, so the EOF symbol
used by eof() is directly declared rather than relying on transitive inclusion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 605ee2c6-72cf-42c8-b4a4-65b854392b87

📥 Commits

Reviewing files that changed from the base of the PR and between f41afb5 and 3ff5ee9.

📒 Files selected for processing (10)

• packages/server/cmake/ports/cpprestsdk/README.md
• packages/server/cmake/ports/cpprestsdk/fix-asio-error.patch
• packages/server/cmake/ports/cpprestsdk/fix-clang-dllimport.patch
• packages/server/cmake/ports/cpprestsdk/fix-find-openssl.patch
• packages/server/cmake/ports/cpprestsdk/fix-libcxx16-char-traits.patch
• packages/server/cmake/ports/cpprestsdk/fix-uwp.patch
• packages/server/cmake/ports/cpprestsdk/fix_narrowing.patch
• packages/server/cmake/ports/cpprestsdk/portfile.cmake
• packages/server/cmake/ports/cpprestsdk/silence-stdext-checked-array-iterators-warning.patch
• packages/server/cmake/ports/cpprestsdk/vcpkg.json

[Ansh-Karnwal]

Addressed the CodeRabbit review in be8e0d7: added an explicit #include so EOF is directly declared rather than relying on transitive includes. Regenerated the patch and re-verified that the real cpprest/streams.h still compiles clean under libc++.

[Ansh-Karnwal]

The macOS (ARM64) build failed and I traced it to the char-traits patch. Pushed a fix in 0fe143d.

Root cause: macOS compiles cpprestsdk with -std=gnu++11 (visible in the build log), and a constexpr function returning void is ill-formed before C++14, since void is not a literal type there. Apple clang hard-errored on the injected char_traits<unsigned char>::assign(char_type&, const char_type&). Once that overload was ill-formed it dropped out of the overload set, so libc++'s <string> could not find the two-argument assign and reported "too few arguments, expected 3" against the remaining three-argument overload. Both log errors come from that one member.

The Linux/libc++>=16 job passed because it builds at C++14 or newer, where constexpr void is fine, and Windows never enters the guard.

Fix: drop constexpr from that one assign. CharTraits does not require it to be constexpr, and libc++ itself only marks it constexpr since C++17, so this stays valid on the C++11 macOS build and correct on the Linux build. The other members return literal types and remain valid constexpr under C++11, so they are unchanged.

[Ansh-Karnwal]

@asclearuc when you have a moment, could you approve the workflow run for 0fe143d? It is the macOS char-traits fix from above, and since this is a fork PR the run is waiting on approval before it can start. Thanks for kicking off the last one.

[asclearuc]

Thanks a lot for your contribution — really appreciate you taking the time to put this together! 🙏

I'm going to put this on hold for now. There's an open question on our side about whether we want to keep cpprestsdk or remove it going forward, and this PR touches that directly. Once that decision is made, I'll circle back here — if we decide to keep it, we can move ahead with your changes.

Thanks again for your patience, and sorry for the wait in the meantime!