# WebSocket Output Options Evaluation

This document captures the evaluation and comparison of approaches to add WebSocket output to mag-usb while keeping build and dependency constraints in mind.

## Key constraint check
- Both WebSocket++ and MengRao/websocket are C++ libraries; they require a C++ compiler and C++11+ (and typically Asio/Boost). That conflicts with “keep project C11” if you mean “no C++ toolchain required.”
- “Header-only” does not mean “dependency-free.” WebSocket++ usually depends on Boost.Asio or standalone Asio, so you would still be vendoring additional headers and accepting C++ ABI/toolchain implications.

## Option 1: Directly couple a WS library
- Pros: single binary; lowest runtime plumbing; straightforward to broadcast data to multiple clients.
- Cons: drags in C++ toolchain + Asio/Boost; changes build surface area; complicates CMake and portability; blurs C11 guarantee; harder to keep the core tiny.
- Fit with constraints: poor.

## Option 2: Directly couple behind a build flag
- Pros: best of both worlds for users; core can still be “C-only” builds; optional feature for advanced setups.
- Cons: still adds C++/Asio complexity for the optional path; dual build/test matrix; more maintenance.
- Fit with constraints: acceptable only if you are willing to support a C++ toolchain in the optional build.

## Option 3: Separate small WS bridge (websocketd-style)
- Pros: preserves C11 core; no C++ dependency in mag-usb; simple piping (stdout/pipe); easiest to keep versioning isolated; can be swapped/replaced without touching core.
- Cons: extra process; needs IPC (pipe/stdio); you must handle reconnection/backpressure in the bridge; packaging two binaries.
- Fit with constraints: best match if “C11 core” is a hard requirement.

## Library choice implications
- WebSocket++: header-only but C++11+ and Asio/Boost; good maturity, but heavyweight for your goals.
- MengRao/websocket: also C++-based; still violates C11-only goal.
- Net: neither meets “C11-only” unless you accept a C++ optional component.

## Recommended direction
- If C11 purity is non-negotiable: choose Option 3 and build a minimal WS bridge (could be in C++ if you are fine with that in the separate tool, or in C if you want everything C-only). This keeps mag-usb simple and stable while still enabling WS.
- If you can tolerate optional C++: choose Option 2 with a build flag and keep WS in a separate module. Users who do not want C++ just build without it.

## Alternative worth considering
- A small C-based embedded server library (e.g., Mongoose) can be vendored as C source rather than a C++ dependency. That would allow Option 1 or 2 without a C++ toolchain, but introduces a third-party C library and licensing considerations.

---

## Follow-up request and responses

User request:
"I am willing to sacrifice the 'C11 purity' constraint,  but I don't want ASIO/Boost involved. I would like to pursue the option 2 using the meng/rao library. I want that library vendored into the project.  This can all bive behind a build flag.  I will need test cases and a test harness to explore the results."

Assistant response:
"Added optional WebSocket output behind `-DENABLE_WEBSOCKET=ON`, vendored MengRao/websocket under `third_party/`, and wired runtime config + CLI flags (`-W`, `-w`, `-a`) so mag-usb can broadcast each JSON line to connected WS clients. I also added a basic test (`websocket-tests`) and a small `ws-client` harness for manual exploration; docs and the requirements spec now reflect the new capability.

Details and touch points
- Build flag and targets: `CMakeLists.txt` adds `ENABLE_WEBSOCKET`, `ws-client`, and `websocket-tests`
- Runtime integration: `src/main.c` polls the WS server in the output loop and broadcasts the JSON line
- Configuration + CLI: `src/config.c`, `src/config.toml`, `src/cmdmgr.c`, `src/main.h`
- Wrapper and tooling: `src/ws_bridge.h`, `src/ws_bridge.cpp`, `tools/ws_client.cpp`, `tests/test_websocket.cpp`
- Docs/reqs: `docs/Configuration.md`, `docs/Getting-Started.md`, `docs/Requirements.md`, `README.md`
- `third_party/mengrao-websocket/`

Tests not run.

If you want to verify:
```
cmake -S . -B build -DENABLE_WEBSOCKET=ON
cmake --build build --target mag-usb ws-client
cmake --build build --target websocket-tests
(cd build && ctest --output-on-failure)
```

To try the harness:
```
./build/mag-usb -W -w 8765 -a 0.0.0.0
./build/ws-client 127.0.0.1 8765 /
```

If you want adjustments (port defaults, max connections, or a dedicated WS thread), tell me which behavior you prefer."