ws_async_internal.h File Reference

Private wiring between the app layer (C1M upgrade path) and the reactor-driven WebSocket implementation in websocket_async.c. More...

#include <cwist/net/websocket/websocket_async.h>
#include <cwist/sys/io/reactor.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for ws_async_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	cwist_websocket_async_attach (int fd, cwist_reactor_t *reactor, cwist_ws_on_message_t on_message, void *user_data, const uint8_t *initial, size_t initial_len)
	Take ownership of a connected, upgraded fd and drive it reactively.
cwist_websocket_async *	cwist_websocket_async_attach_ex (int fd, cwist_reactor_t *reactor, cwist_ws_on_message_t on_message, cwist_ws_on_close_t on_close, void *user_data, const uint8_t *initial, size_t initial_len)
	Attach variant that reports the connection handle and teardown.
void	cwist_websocket_async_close_code (cwist_websocket_async *ws, uint16_t code)
	Initiate the WebSocket close handshake with a CLOSE frame carrying a status code.

Detailed Description

Private wiring between the app layer (C1M upgrade path) and the reactor-driven WebSocket implementation in websocket_async.c.

Not part of the public API; native-only (pulls in reactor.h / sockets).

Definition in file ws_async_internal.h.

Function Documentation

cwist_websocket_async_attach()

bool cwist_websocket_async_attach	(	int	fd,
		cwist_reactor_t *	reactor,
		cwist_ws_on_message_t	on_message,
		void *	user_data,
		const uint8_t *	initial,
		size_t	initial_len
	)

Take ownership of a connected, upgraded fd and drive it reactively.

Registers a one-shot read slot with the reactor and returns. From then on the reactor drains the socket without blocking and delivers each complete message through on_message. The HTTP layer must not touch the fd after a successful attach (it returns CWIST_ASYNC_DETACH).

Parameters

fd	Connected, upgraded client socket (set non-blocking here).
reactor	Owning reactor.
on_message	Per-message callback.
user_data	Opaque pointer forwarded to the callback.
initial	Bytes already read past the upgrade request (conn->rbuf); fed through the frame parser before the first reactor wait.
initial_len	Number of valid bytes at initial (0 when none).

Returns

true when the fd was handed to the reactor path, false on failure (fd is closed and all state freed before returning).

Take ownership of a connected, upgraded fd and drive it reactively.

Thin boolean wrapper around cwist_websocket_async_attach_ex().

Parameters

fd	Upgraded socket fd (owned by the new connection on success).
reactor	Reactor to register the fd with.
on_message	Callback invoked per complete message. Must not be NULL.
user_data	Opaque pointer passed back to the callback.
initial	Bytes already read past the upgrade request; may be NULL.
initial_len	Number of bytes in initial.

Return values

true	The connection was attached and the read slot armed.
false	Invalid arguments or failure (fd is closed).

Definition at line 1211 of file websocket_async.c.

References cap, and cwist_websocket_async_attach_ex().

cwist_websocket_async_attach_ex()

cwist_websocket_async * cwist_websocket_async_attach_ex	(	int	fd,
		cwist_reactor_t *	reactor,
		cwist_ws_on_message_t	on_message,
		cwist_ws_on_close_t	on_close,
		void *	user_data,
		const uint8_t *	initial,
		size_t	initial_len
	)

Attach variant that reports the connection handle and teardown.

Identical to cwist_websocket_async_attach() plus an optional on_close hook invoked exactly once on the reactor thread at final teardown (before the connection state is freed), and a return value exposing the handle to the caller.

Returns

Connection handle on success, NULL on failure (fd closed and all state freed before returning).

Attach variant that reports the connection handle and teardown.

Sets the fd non-blocking, feeds any bytes already read past the upgrade request through the parser (delivery can happen inline here, including a close from the on_message callback), arms the one-shot read slot, and joins the reactor's idle sweep. On any failure the fd is closed and all state is freed; on_close does not fire because the attach itself failed.

Parameters

fd	Upgraded socket fd (owned by the new connection on success).
reactor	Reactor to register the fd with.
on_message	Callback invoked per complete message; takes ownership of the delivered frame. Must not be NULL.
on_close	Optional callback invoked exactly once during teardown.
user_data	Opaque pointer passed back to both callbacks.
initial	Bytes already read past the upgrade request; may be NULL.
initial_len	Number of bytes in initial.

Returns

The new async connection, or NULL on invalid arguments or failure (fd is closed in the latter case).

Definition at line 1116 of file websocket_async.c.

References cap, cwist_alloc(), cwist_fast_monotonic_sec(), cwist_free(), cwist_reactor_add(), and CWIST_WS_FRAME_CONTINUATION.

Referenced by cwist_graphql_ws_attach(), and cwist_websocket_async_attach().

cwist_websocket_async_close_code()

void cwist_websocket_async_close_code	(	cwist_websocket_async *	ws,
		uint16_t	code
	)

Initiate the WebSocket close handshake with a CLOSE frame carrying a status code.

Close with a specific status code (e.g. graphql-ws 4400-4429 range) on the wire, mirroring cwist_websocket_async_close() teardown semantics.

The 2-byte big-endian status code is echoed to the peer. Idempotent: calling again on a connection already closing is a no-op. The connection is torn down once the CLOSE frame has drained or, on queueing failure, via a deferred termination.

Parameters

ws	Async connection to close. Safe to call with NULL.
code	RFC 6455 close status code (big-endian on the wire).

Definition at line 754 of file websocket_async.c.

References cap, and CWIST_WS_FRAME_CLOSE.