ws_client.h File Reference

Minimal async WebSocket (RFC 6455) client on asio coroutines. More...

#include <neograph/api.h>
#include <asio/any_io_executor.hpp>
#include <asio/awaitable.hpp>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>

Include dependency graph for ws_client.h:

Go to the source code of this file.

Classes
class	neograph::async::WsClient
	Async WebSocket client. More...

Functions
NEOGRAPH_API asio::awaitable< std::unique_ptr< WsClient > >	neograph::async::ws_connect (asio::any_io_executor ex, std::string_view host, std::string_view port, std::string_view path, std::vector< std::pair< std::string, std::string > > headers={}, bool tls=true)
	Establish a WebSocket connection.

Detailed Description

Minimal async WebSocket (RFC 6455) client on asio coroutines.

Phase A primitive — transport only, no protocol-specific framing above RFC 6455. Target use: OpenAI Responses WebSocket mode (wss://api.openai.com/v1/responses), but the client is generic: any wss:// or ws:// endpoint that speaks vanilla RFC 6455.

Scope covered:

• HTTP/1.1 Upgrade handshake (client side) with Bearer-style custom header injection.
• Sec-WebSocket-Accept verification against the randomly-generated Sec-WebSocket-Key (SHA-1 + base64, per RFC 6455 §4.2.2).
• TLS via asio::ssl::stream (reused from http_client.cpp path — OpenSSL default trust store + SNI + hostname verification).
• Frame codec: text + binary + ping + pong + close opcodes; 7 / 16-bit / 64-bit extended payload lengths; client-to-server masking per §5.3.
• recv() auto-replies to ping with pong and surfaces close frames to the caller.
• Message reassembly across fragmented frames (FIN=0 continuation).

Scope NOT covered (deliberate — keep the primitive lean):

• Permessage-deflate / extensions.
• Subprotocol negotiation (Sec-WebSocket-Protocol is not set).
• Back-pressure beyond what asio's async_write already provides.
• Auto-reconnect / ping scheduling (caller drives recv loop).

Threading: a WsClient instance is NOT thread-safe. Run all send/recv on the same executor. Concurrent send + recv on the same instance is also unsafe — serialize at the caller.

Definition in file ws_client.h.

Function Documentation

ws_connect()

NEOGRAPH_API asio::awaitable< std::unique_ptr< WsClient > > neograph::async::ws_connect	(	asio::any_io_executor	ex,
		std::string_view	host,
		std::string_view	port,
		std::string_view	path,
		std::vector< std::pair< std::string, std::string > >	headers = {},
		bool	tls = true
	)

Establish a WebSocket connection.

Parameters

ex	Executor hosting the connection.
host	Target host (SNI + Host header + cert verification).
port	Port string ("443", "80", etc.).
path	Origin-form path starting with '/'. Query string allowed; fragment not.
headers	Extra HTTP headers injected into the Upgrade request. Typical use: {"Authorization","Bearer sk-..."}. Do NOT set Upgrade/Connection/Sec-WebSocket-* here — the client sets those itself.
tls	Use wss:// (TLS) vs ws:// (plain TCP).

Throws asio::system_error on transport failure, std::runtime_error if the server refuses the upgrade (non-101 status or bad Accept).

References neograph::async::ws_connect().

Referenced by neograph::async::ws_connect().