If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/zaphoyd/websocketpp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 5d ago
• 19 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live zaphoyd/websocketpp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/zaphoyd/websocketpp.

What it runs against: a local clone of zaphoyd/websocketpp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in zaphoyd/websocketpp | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of zaphoyd/websocketpp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zaphoyd/websocketpp.git
#   cd websocketpp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of zaphoyd/websocketpp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "zaphoyd/websocketpp(\\.git)?\\b" \\
  && ok "origin remote is zaphoyd/websocketpp" \\
  || miss "origin remote is not zaphoyd/websocketpp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "websocketpp/websocketpp.hpp" \\
  && ok "websocketpp/websocketpp.hpp" \\
  || miss "missing critical file: websocketpp/websocketpp.hpp"
test -f "websocketpp/endpoint.hpp" \\
  && ok "websocketpp/endpoint.hpp" \\
  || miss "missing critical file: websocketpp/endpoint.hpp"
test -f "websocketpp/connection.hpp" \\
  && ok "websocketpp/connection.hpp" \\
  || miss "missing critical file: websocketpp/connection.hpp"
test -f "websocketpp/transport/transport.hpp" \\
  && ok "websocketpp/transport/transport.hpp" \\
  || miss "missing critical file: websocketpp/transport/transport.hpp"
test -f "websocketpp/processor/processor.hpp" \\
  && ok "websocketpp/processor/processor.hpp" \\
  || miss "missing critical file: websocketpp/processor/processor.hpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/zaphoyd/websocketpp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

WebSocket++ is a header-only C++ library implementing RFC6455 WebSocket protocol for building real-time bidirectional client/server applications. It provides message-based networking with support for secure TLS connections, IPv6, proxies, and multiple pluggable transport backends (raw sockets, iostream, Asio/Boost). Header-only library structure: top-level includes/ contains public API, examples/ provides runnable reference implementations (echo_server/, broadcast_server/, debug_client/), docs/ has Doxygen configuration and tutorials, CMakeLists.txt and SConstruct support multiple build systems.

C++ systems engineers and backend developers building real-time applications (trading systems, gaming servers, IoT platforms, live dashboards) who need production-grade WebSocket support without external runtime dependencies.

Mature and stable: version 0.8.2, implements RFC6455 fully with partial legacy protocol support, includes comprehensive examples (echo_server, broadcast_server, debug_client), has CI via Travis CI, and header-only design reduces deployment friction. Active development but stable API.

Low operational risk due to header-only design and minimal runtime dependencies, but single maintainer (Peter Thorson) creates long-term maintenance exposure. No visible test directory in file list suggests testing may be light. Requires careful version pinning of optional Boost/Asio dependencies if used.

Repository shows active maintenance (changelog.md present, .travis.yml CI configured) with examples for both HTTP and HTTPS WebSocket servers (echo_server_both/, echo_server_tls/). Recent additions include associative_storage example for managing client state, indicating focus on production patterns.

git clone https://github.com/zaphoyd/websocketpp.git && cd websocketpp && mkdir build && cd build && cmake .. && make. Examples are pre-built in examples/ subdirectories with individual CMakeLists.txt files.

Daily commands: Build examples individually: cd examples/echo_server && mkdir build && cd build && cmake .. && make. Run: ./echo_server (default listens on 0.0.0.0:9002). Connect via examples/echo_client. For TLS: echo_server_tls uses server.pem certificate.

• websocketpp/websocketpp.hpp — Main include header that exports the entire library API; all projects depend on understanding this entry point
• websocketpp/endpoint.hpp — Core endpoint class managing server/client lifecycle and connection handling; foundational to all use cases
• websocketpp/connection.hpp — Connection abstraction managing WebSocket state, message buffering, and protocol frame handling
• websocketpp/transport/transport.hpp — Transport layer abstraction defining interchangeable network modules (raw, iostream, Asio)
• websocketpp/processor/processor.hpp — Protocol processor implementing RFC6455 frame parsing and serialization logic
• CMakeLists.txt — Build configuration defining header-only compilation, dependencies (Boost/Asio), and test targets

Add a new transport module

1. Create a new transport policy header in websocketpp/transport/your_transport/ implementing the transport interface (async_read, async_write, set_handle_init, etc.) (websocketpp/transport/your_transport/connection.hpp)
2. Define a config trait specialization selecting your transport in your application or config header (e.g., typedef websocketpp::config::asio_client_tls config;) (websocketpp/common/config.hpp (for reference))
3. Test with echo_server/echo_client examples to verify handshake and frame exchange work correctly (examples/echo_server/echo_server.cpp (as template))

Add a new message handler (application logic)

1. Register a handler callback in endpoint::set_message_handler() or on_message binding. Define your callback to inspect opcode, payload, and connection context. (examples/broadcast_server/broadcast_server.cpp (see on_message binding))
2. Access connection metadata via the connection_hdl parameter to route messages or maintain session state. (websocketpp/connection.hpp (connection_hdl and get_con_from_hdl))
3. Send replies via connection->send() or endpoint->send(hdl, msg) for synchronous or asynchronous dispatch. (examples/echo_server/echo_handler.hpp (example echo implementation))

Enable TLS/secure WebSockets

1. Select an Asio TLS config (asio_tls_client, asio_tls_server) instead of the plain Asio config when instantiating endpoint. (examples/echo_server_tls/echo_server_tls.cpp (full TLS server example))
2. In your endpoint initialization, set the TLS context via set_tls_init_handler() with certificate and key paths. (examples/echo_server_tls/echo_server_tls.cpp (see on_tls_init))
3. Verify client connections receive frames over encrypted transport; test with print_client_tls example. (examples/print_client_tls/print_client_tls.cpp)

Add custom logging/debugging

1. Implement the logger interface by creating a struct with access(level, channel, message) method. (websocketpp/logger/logger.hpp (interface definition))
2. Wire your logger into the config trait (config::logger_type = your_logger) and set endpoint::set_access_channels() / set_error_channels() to enable output. (examples/debug_server/debug_server.cpp (uses debug logger))
3. Compile with logging enabled and test against broadcast or echo examples to observe handshake, frame, and protocol messages. (examples/debug_client/debug_client.cpp)

• Header-only C++ library — Simplifies integration into any project; zero runtime linking cost; enables template specialization for config traits (client/server, transport, logger, concurrency)
• Asio (Boost or standalone) — Provides cross-platform async I/O abstraction for sockets, TLS, and event handling; eliminates platform-specific code (Windows IOCP, Linux epoll, etc.)
• Policy-based design (traits, templates) — Allows zero-overhead selection of transport (raw, iostream, Asio), concurrency (sync, stand_alone, boost threads), and dependencies at compile time
• RFC6455 protocol implementation — Ensures full WebSocket interoperability; handles frame masking, handshake negotiation, opcode dispatch, and fragmentation

• Header-only library

  • Why: Avoids binary compatibility issues and linker dependencies across projects
  • Consequence: Template instantiation increases compile time; larger binary footprint per translation unit; harder to debug template errors

• Asio as primary transport

  • Why: Single unified async I/O abstraction reduces code duplication and maintenance burden
  • Consequence: Dependency on Boost or standalone Asio; users must understand async/coroutine patterns; alternative transports (raw, iostream) are simpler but less efficient

• Pluggable config traits over inheritance

  • Why: Compile-time polymorphism yields zero-overhead abstractions and eliminates virtual dispatch
  • Consequence: Steep learning curve; configuration mistakes are compile-time errors; less runtime flexibility than dynamic polymorphism

• Message-based interface (not streaming)

  • Why: Simplifies application logic; frames are atomically assembled before on_message callback fires
  • Consequence: Large fragmented messages consume memory buffering; not ideal for streaming use cases (e.g., video feeds); opcode (text vs binary) must be manually checked

• Real-time database or state synchronization (library manages connections only; application supplies logic)
• Authentication or authorization (TLS mutual auth supported; session/role management is application concern)
• Automatic reconnection (client must implement retry logic in on_fail / on_close handlers)
• Compression beyond RFC7692 negotiation (library negotiates; actual compression is transport responsibility)
• Browser compatibility (library is C++ server/client; not a JavaScript runtime)

Header-only library means longer compile times and binary bloat if not using precompiled headers. Template-heavy error messages can be cryptic. Asio backend requires careful platform-specific configuration (Windows IOCP vs EPOLL on Linux). No default secure random source hardcoded—production use must seed properly. Header installation location varies by build method (cmake install vs manual include path management).

• RFC6455 WebSocket Handshake & Frame Protocol — Core responsibility of library—understanding the HTTP upgrade mechanism, frame structure (FIN bit, opcode, masking, payload length encoding) is essential to using this library correctly
• Policy-Based Class Design — WebSocket++ uses compile-time template policies for transport selection (raw/iostream/Asio) and connection handlers—you must understand template specialization to extend or configure behavior
• Header-Only Libraries — Entire implementation in headers means no separate compilation step but requires careful template instantiation and can cause bloated binaries without precompiled headers
• Asio Proactor Pattern — WebSocket++ can use Asio for async I/O—understanding proactor (async completion-driven) vs reactor (readiness-driven) models helps configure transport correctly
• TLS/SSL Encryption for WebSockets (WSS) — Library supports secure WebSockets via OpenSSL integration—production deployments require understanding certificate pinning, cipher suites, and transport-layer security configuration
• Message Framing & UTF-8 Validation — WebSocket protocol requires text frames to be valid UTF-8 and handles partial messages across multiple frames—library handles this but you must understand fragmentation semantics
• Connection State Machine & Handler Callbacks — WebSocket++ uses event-driven callbacks (on_open, on_message, on_close) that must respect strict ordering and threading guarantees—misunderstanding callback contexts causes deadlocks or race conditions

• uNetworking/uWebSockets — Alternative high-performance WebSocket library in C++ with similar RFC6455 compliance but emphasizes lower latency and throughput
• warmcat/libwebsockets — C library WebSocket implementation with broader platform support and embedded system focus, different design philosophy from C++-centric WebSocket++
• boost-ext/asio — Standalone Asio networking library that WebSocket++ uses as optional transport backend for async I/O primitives
• boostorg/boost — Boost collection includes optional Asio and system dependencies that WebSocket++ can use as alternative to C++11 stdlib

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow to replace .travis.yml

The repo has .travis.yml (Travis CI config) but no GitHub Actions workflows in .github/workflows/. GitHub Actions is now the standard for GitHub-hosted projects and would provide faster feedback. This involves migrating the existing Travis CI build configuration to modern GitHub Actions while maintaining test coverage across platforms.

• [ ] Create .github/workflows/build.yml with matrix builds for Linux/macOS/Windows
• [ ] Add steps to build with both CMake and SConstruct build systems
• [ ] Include compilation of examples (echo_server, broadcast_server, debug_client, etc.) to verify no regressions
• [ ] Add C++ standard version matrix testing (C++11, C++14, C++17)
• [ ] Reference and update the incomplete Build Status badge in README

Add comprehensive unit tests for RFC6455 frame parsing and message assembly

The repo has no visible test/ directory despite being a protocol implementation library. RFC6455 compliance is critical and requires rigorous testing of frame parsing, masking, payload assembly, and edge cases. This would catch regressions early and increase contributor confidence.

• [ ] Create test/ directory structure with subdirectories for frame, message, and protocol validation tests
• [ ] Add tests for RFC6455 frame format parsing (FIN bit, opcode, mask, payload length)
• [ ] Add tests for payload masking/unmasking with various payload sizes (< 126, 126-65535, > 65535 bytes)
• [ ] Add tests for message assembly across multiple fragmented frames
• [ ] Add tests for invalid frame detection (reserved bits, invalid opcodes, incorrect masks)
• [ ] Integrate tests into CMakeLists.txt and SConstruct build configurations

Create specific documentation for TLS/secure WebSocket configuration

The repo has TLS examples (echo_server_tls/ with .pem files and dh.pem) and mentions TLS support in README, but docs/ folder lacks dedicated documentation on configuring TLS transport policies. Users need clear guidance on certificate setup, Asio TLS configuration, and differences between transport modules.

• [ ] Add docs/tls_configuration.dox explaining TLS setup, certificate generation, and Asio context configuration
• [ ] Document the TLS transport policy interface with before/after code examples
• [ ] Cross-reference the TLS example code (examples/echo_server_tls/echo_server_tls.cpp) in the documentation
• [ ] Add troubleshooting section for common TLS errors (certificate validation, DH parameter size, cipher negotiation)
• [ ] Update docs/getting_started.dox to mention TLS as an option alongside basic transport

• Add comprehensive unit test suite under tests/ directory covering RFC6455 frame parsing, UTF-8 validation, and handshake state machine—currently no visible test harness
• Expand docs/handlers.dox with concrete callback handler templates and lifecycle diagrams showing connection states through open→message→close
• Create examples/tls_client/ TLS client example (repo has echo_server_tls but no matching client for complete TLS workflow demonstration)

WebSocket++ is a mature C++ library with generally good security posture. The primary concern is hardcoded cryptographic materials (certificates/keys) in the repository, which is a common but serious mistake in example code. The library handles complex protocol parsing that requires continuous security review. No SQL injection or XSS risks are present (not applicable to C++ library). Main recommendations: remove hardcoded certificates, establish a security policy/vulnerability disclosure process, maintain active security auditing, and provide security hardening guidance to users. The library's age and unclear maintenance status warrant verification of ongoing security support.

• Medium · Hardcoded TLS Certificates in Repository — examples/echo_server_both/server.pem, examples/echo_server_tls/dh.pem, examples/echo_server_tls/server.pem, examples/print_client_tls/ca-chain.cert.pem. The repository contains hardcoded private key and certificate files (server.pem, dh.pem, ca-chain.cert.pem) committed to version control. These are sensitive cryptographic materials that should never be stored in source code repositories, especially in examples that may be forked or cloned. Fix: Move all certificate and key files to configuration management systems or environment variables. Generate them at deployment time. Add *.pem to .gitignore. Consider using a certificate management solution for production deployments.
• Medium · Header-Only Library Without Input Validation Documentation — websocketpp library implementation (not visible in provided structure). As a header-only C++ WebSocket library, WebSocket++ processes untrusted network input (WebSocket frames). Without visibility into implementation details and given it's a complex protocol implementation, there's a risk of buffer overflows, integer overflows, or malformed frame handling vulnerabilities. The README mentions RFC6455 support but doesn't document security hardening measures. Fix: Conduct thorough code review and fuzzing of frame parsing logic. Implement strict bounds checking and validation for all incoming WebSocket frames. Add security documentation detailing input validation and threat model. Consider maintaining a security.md or SECURITY.md file with vulnerability reporting procedures.
• Low · Missing SECURITY.md or Security Policy — Repository root. The repository does not appear to have a SECURITY.md file or documented security policy for reporting vulnerabilities. This makes it difficult for security researchers to report issues responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines and security contact information. Consider adding a .github/SECURITY.md or linking to a security page.
• Low · Outdated Version Number — README.md, version tracking. The README indicates version 0.8.2, which is relatively old. No indication of active maintenance or regular security updates is visible from the provided structure. Fix: Maintain a changelog documenting security fixes. Regularly audit dependencies and publish security updates. Consider implementing automated dependency checking with tools like Dependabot.
• Low · TLS Configuration in Examples — examples/echo_server_tls/, examples/print_client_tls/. While the examples include TLS support, there's no visible documentation about recommended TLS versions, cipher suites, or secure configuration best practices for end-users implementing this library. Fix: Add security documentation recommending TLS 1.2+ and strong cipher suites. Provide example configurations that follow current security best practices. Consider a secure_defaults.hpp or similar configuration template.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.