client.h File Reference

WebSocket client abstraction for ascii-chat connections. More...

Go to the source code of this file.

Data Structures
struct	websocket_client
	WebSocket client connection state. More...

Typedefs
typedef struct websocket_client	websocket_client_t
	WebSocket client connection state.

Functions
websocket_client_t *	websocket_client_create (const char *name)
	Create and initialize a named WebSocket client instance.
void	websocket_client_destroy (websocket_client_t **client_ptr)
	Destroy WebSocket client and free all resources.
bool	websocket_client_is_active (const websocket_client_t *client)
	Check if connection is currently active.
bool	websocket_client_is_lost (const websocket_client_t *client)
	Check if connection was lost.
bool	websocket_client_should_reconnect (const websocket_client_t *client)
	Check if reconnection should be attempted.
void	websocket_client_signal_lost (websocket_client_t *client)
	Signal that connection was lost (triggers reconnection)
void	websocket_client_signal_reconnect (websocket_client_t *client)
	Signal that reconnection should be attempted.
void	websocket_client_clear_reconnect_flag (websocket_client_t *client)
	Clear reconnection flag (called after successful reconnect)
bool	websocket_client_is_encryption_enabled (const websocket_client_t *client)
	Check if encryption is enabled.
void	websocket_client_enable_encryption (websocket_client_t *client)
	Enable encryption for this connection.
void	websocket_client_disable_encryption (websocket_client_t *client)
	Disable encryption for this connection.
void	websocket_client_close (websocket_client_t *client)
	Close connection gracefully.
void	websocket_client_shutdown (websocket_client_t *client)
	Shutdown connection forcefully (for signal handlers)
acip_transport_t *	websocket_client_connect (websocket_client_t *client, const char *url, struct crypto_context_t *crypto_ctx)
	Establish WebSocket connection to server.
acip_transport_t *	websocket_client_get_transport (const websocket_client_t *client)
	Get active transport instance.
int	websocket_client_send_packet (websocket_client_t *client, packet_type_t type, const void *data, size_t len)
	Send a packet through WebSocket connection (thread-safe)
int	websocket_client_send_ping (websocket_client_t *client)
	Send ping frame (keepalive heartbeat)
int	websocket_client_send_pong (websocket_client_t *client)
	Send pong frame (keepalive response)
uint32_t	websocket_client_get_id (const websocket_client_t *client)
	Get the client's unique ID.
bool	websocket_client_is_encrypted (const websocket_client_t *client)
	Check if encryption is enabled for this connection.

Detailed Description

WebSocket client abstraction for ascii-chat connections.

This module provides a reusable WebSocket client implementation that parallels tcp_client.h, enabling WebSocket connections as a transport alternative to TCP.

Architecture

The websocket_client module encapsulates WebSocket-specific connection state, mirroring the structure of tcp_client_t:

• Connection lifecycle management (create, connect, destroy)
• Connection state tracking (active, lost, signals)
• Transport abstraction (returns acip_transport_t for protocol agnostic use)

Unlike tcp_client_t, this module does NOT contain:

• Audio/video thread management (handled by client_context_t)
• Capture threads (handled by client_context_t)
• Protocol-specific packet builders (handled by application)

Usage Pattern

// Create WebSocket client
websocket_client_t *ws_client = websocket_client_create();
 
// Connect to server
acip_transport_t *transport = websocket_client_connect(ws_client, "ws://localhost:27226", crypto_ctx);
if (!transport) {
  log_error("Connection failed");
  websocket_client_destroy(&ws_client);
  return;
}
 
// Use transport with ACIP protocol handlers
acip_send_packet(transport, packet_type, data, len);
 
// Check connection state
if (!websocket_client_is_active(ws_client)) {
  log_warn("Connection lost");
}
 
// Cleanup when done
websocket_client_close(ws_client);
websocket_client_destroy(&ws_client);

Comparison with tcp_client_t

Aspect	tcp_client_t	websocket_client_t
Connection type	TCP socket	WebSocket (TCP-based)
State tracking	Yes	Yes
Audio queues	Yes (TO REMOVE)	No (in client_context)
Thread management	Yes (TO REMOVE)	No (in client_context)
Transport return	N/A	acip_transport_t*

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Version

1.0

Definition in file include/ascii-chat/network/websocket/client.h.

Typedef Documentation

websocket_client_t

typedef struct websocket_client websocket_client_t

WebSocket client connection state.

Encapsulates WebSocket-specific connection state, including:

• Connection URL and state flags
• Client ID and encryption state
• Active transport (owned by websocket_client)
• Thread-safe packet transmission mutex

This structure mirrors tcp_client_t for API compatibility. Application state (audio, threads, crypto) lives in client_context_t instead.

Thread Safety

• Atomic fields: Safe for concurrent read/write without locks
• Immutable after init: url is set once, then read-only
• Mutex: Protects concurrent packet transmission

Function Documentation

websocket_client_clear_reconnect_flag()

void websocket_client_clear_reconnect_flag

(

websocket_client_t *

client

)

Clear reconnection flag (called after successful reconnect)

Parameters

client

WebSocket client instance

websocket_client_close()

void websocket_client_close

(

websocket_client_t *

client

)

Close connection gracefully.

Parameters

client

WebSocket client instance

Definition at line 136 of file lib/network/websocket/client.c.

                                                        {
  if (!client) {
    return;
  }
 
  log_debug("Closing WebSocket client");
 
  if (client->transport) {
    acip_transport_close(client->transport);
  }
 
  atomic_store_bool(&client->connection_active, false);
}

References atomic_store_bool(), and log_debug.

websocket_client_connect()

acip_transport_t * websocket_client_connect	(	websocket_client_t *	client,
		const char *	url,
		struct crypto_context_t *	crypto_ctx
	)

Establish WebSocket connection to server.

Performs full connection lifecycle including URL resolution and WebSocket handshake. Does NOT perform crypto handshake - that's application responsibility.

Parameters

client	WebSocket client instance
url	WebSocket server URL (e.g., "ws://localhost:27226")
crypto_ctx	Cryptographic context for encrypted connections

Returns

acip_transport_t pointer on success, NULL on failure

Note

The returned transport is owned by websocket_client_t

Call websocket_client_is_active() after connecting to verify success

Delegates to acip_websocket_client_transport_create() which handles:

• URL parsing and validation
• WebSocket handshake
• Transport setup and lifecycle

Definition at line 177 of file lib/network/websocket/client.c.

                                                                                {
  if (!client || !url) {
    log_error("Invalid arguments to websocket_client_connect");
    return NULL;
  }
 
  log_info("Connecting WebSocket client to %s", url);
 
  // Store URL for reference
  SAFE_STRNCPY(client->url, url, sizeof(client->url));
 
  // Create transport using ACIP layer
  acip_transport_t *transport = acip_websocket_client_transport_create("client", url, crypto_ctx);
  if (!transport) {
    log_error("Failed to create WebSocket transport");
    atomic_store_bool(&client->connection_lost, true);
    return NULL;
  }
 
  // Derive client ID from URL hash using FNV-1a (proper implementation with 64-bit arithmetic)
  // This provides a stable, unique ID per connection URL without undefined behavior
  client->my_client_id = fnv1a_hash_string(url);
 
  // Update registration name now that we have a client ID
  {
    char client_name[64];
    SAFE_SNPRINTF(client_name, sizeof(client_name), "websocket_client_%u", client->my_client_id);
    named_update_name((uintptr_t)client, client_name);
  }
 
  // Mark encryption as enabled if crypto context provided
  client->encryption_enabled = (crypto_ctx != NULL);
 
  // Store transport and mark as active
  client->transport = transport;
  atomic_store_bool(&client->connection_active, true);
  atomic_store_bool(&client->connection_lost, false);
 
  log_info("WebSocket client connected to %s (ID: %u)", url, client->my_client_id);
 
  return transport;
}

References acip_websocket_client_transport_create(), atomic_store_bool(), log_error, log_info, named_update_name(), SAFE_SNPRINTF, and SAFE_STRNCPY.

Referenced by connection_attempt_tcp(), and connection_attempt_websocket().

websocket_client_create()

websocket_client_t * websocket_client_create

(

const char *

name

)

Create and initialize a named WebSocket client instance.

Parameters

name	Debug name for the WebSocket client

Allocates a new websocket_client_t structure and initializes all fields to safe defaults. The transport remains NULL until websocket_client_connect() is called. The client is automatically registered with the debug naming system.

Returns

Pointer to initialized client, or NULL on failure

Note

Caller must call websocket_client_destroy() when done

See also

websocket_client_destroy() For proper cleanup

Create and initialize a named WebSocket client instance.

Definition at line 27 of file lib/network/websocket/client.c.

                                                              {
  if (!name) {
    log_error("WebSocket client name is required");
    return NULL;
  }
 
  websocket_client_t *client = SAFE_MALLOC(sizeof(websocket_client_t), websocket_client_t *);
  if (!client) {
    log_error("Failed to allocate websocket_client_t");
    return NULL;
  }
 
  // Zero-initialize all fields
  memset(client, 0, sizeof(*client));
 
  // Initialize connection state
  atomic_store_bool(&client->connection_active, false);
  atomic_store_bool(&client->connection_lost, false);
  client->transport = NULL;
  client->my_client_id = 0;
  client->encryption_enabled = false;
  atomic_store_bool(&client->should_reconnect, false);
 
  // Initialize thread-safe mutex for packet transmission
  if (mutex_init(&client->send_mutex, "client_send") != 0) {
    log_error("Failed to initialize send_mutex");
    SAFE_FREE(client);
    return NULL;
  }
 
  // Register WebSocket client with debug naming system
  NAMED_REGISTER_WEBSOCKET(client, name, NULL);
 
  // Register atomic fields for sync state monitoring - descriptive names showing control purpose
  NAMED_REGISTER_ATOMIC(&client->connection_active, "connection_is_active", (uintptr_t)(const void *)(client));
  NAMED_REGISTER_ATOMIC(&client->connection_lost, "connection_was_lost", (uintptr_t)(const void *)(client));
  NAMED_REGISTER_ATOMIC(&client->should_reconnect, "needs_reconnection_attempt", (uintptr_t)(const void *)(client));
 
  log_debug("WebSocket client created");
 
  return client;
}

References atomic_store_bool(), log_debug, log_error, mutex_init(), NAMED_REGISTER_ATOMIC, NAMED_REGISTER_WEBSOCKET, SAFE_FREE, and SAFE_MALLOC.

Referenced by connection_attempt_tcp(), and connection_attempt_websocket().

websocket_client_destroy()

void websocket_client_destroy

(

websocket_client_t **

client_ptr

)

Destroy WebSocket client and free all resources.

Destroys the transport and frees the client structure. Must be called AFTER the transport is no longer in use.

Parameters

client_ptr

Pointer to client pointer (set to NULL after free)

Warning

All operations on transport must be complete before calling

Note

No-op if client_ptr is NULL or *client_ptr is NULL

Destroy WebSocket client and free all resources.

Definition at line 73 of file lib/network/websocket/client.c.

                                                               {
  if (!client_ptr || !*client_ptr) {
    return; // No-op if NULL
  }
 
  websocket_client_t *client = *client_ptr;
 
  log_debug("Destroying WebSocket client");
 
  // Note: Do NOT destroy the transport. The transport is created and owned by the
  // connection layer (acip_websocket_client_transport_create). The WebSocket client
  // is just a thin wrapper that holds a reference. The transport will be destroyed
  // by the connection context or server connection cleanup code.
  client->transport = NULL;
 
  // Unregister atomic fields
  NAMED_UNREGISTER(&client->connection_active);
  NAMED_UNREGISTER(&client->connection_lost);
  NAMED_UNREGISTER(&client->should_reconnect);
 
  NAMED_UNREGISTER(client);
 
  // Destroy mutex
  mutex_destroy(&client->send_mutex);
 
  SAFE_FREE(*client_ptr);
}

References log_debug, mutex_destroy(), NAMED_UNREGISTER, and SAFE_FREE.

Referenced by connection_attempt_tcp(), and connection_attempt_websocket().

websocket_client_disable_encryption()

void websocket_client_disable_encryption

(

websocket_client_t *

client

)

Disable encryption for this connection.

Parameters

client

WebSocket client instance

websocket_client_enable_encryption()

void websocket_client_enable_encryption

(

websocket_client_t *

client

)

Enable encryption for this connection.

Parameters

client

WebSocket client instance

websocket_client_get_id()

uint32_t websocket_client_get_id

(

const websocket_client_t *

client

)

Get the client's unique ID.

Parameters

client

WebSocket client instance

Returns

Client ID, or 0 if not set

Note

Equivalent to tcp_client_get_id() for API compatibility

Definition at line 291 of file lib/network/websocket/client.c.

                                                                   {
  return client ? client->my_client_id : 0;
}

websocket_client_get_transport()

acip_transport_t * websocket_client_get_transport

(

const websocket_client_t *

client

)

Get active transport instance.

Parameters

client

WebSocket client instance

Returns

acip_transport_t pointer or NULL if not connected

Definition at line 224 of file lib/network/websocket/client.c.

                                                                                   {
  if (!client) {
    return NULL;
  }
  return client->transport;
}

websocket_client_is_active()

bool websocket_client_is_active

(

const websocket_client_t *

client

)

Check if connection is currently active.

Parameters

client

WebSocket client instance

Returns

true if connection is active, false otherwise

Definition at line 104 of file lib/network/websocket/client.c.

                                                                  {
  if (!client) {
    return false;
  }
  return atomic_load_bool(&client->connection_active);
}

References atomic_load_bool().

websocket_client_is_encrypted()

bool websocket_client_is_encrypted

(

const websocket_client_t *

client

)

Check if encryption is enabled for this connection.

Parameters

client

WebSocket client instance

Returns

true if encryption is enabled, false otherwise

Definition at line 298 of file lib/network/websocket/client.c.

                                                                     {
  if (!client)
    return false;
  return client->encryption_enabled;
}

websocket_client_is_encryption_enabled()

bool websocket_client_is_encryption_enabled

(

const websocket_client_t *

client

)

Check if encryption is enabled.

Parameters

client

WebSocket client instance

Returns

true if encryption is enabled, false otherwise

websocket_client_is_lost()

bool websocket_client_is_lost

(

const websocket_client_t *

client

)

Check if connection was lost.

Parameters

client

WebSocket client instance

Returns

true if connection loss was detected, false otherwise

Definition at line 114 of file lib/network/websocket/client.c.

                                                                {
  if (!client) {
    return false;
  }
  return atomic_load_bool(&client->connection_lost);
}

References atomic_load_bool().

websocket_client_send_packet()

int websocket_client_send_packet	(	websocket_client_t *	client,
		packet_type_t	type,
		const void *	data,
		size_t	len
	)

Send a packet through WebSocket connection (thread-safe)

Acquires send_mutex, transmits packet, releases mutex. Checks connection state before sending.

Parameters

client	WebSocket client instance
type	Packet type to send
data	Packet payload (NULL for empty packets)
len	Payload length in bytes

Returns

0 on success, -1 on failure

Note

Equivalent to tcp_client_send_packet() for API compatibility

Thread-safe: multiple threads can call concurrently

Acquires send_mutex, transmits packet via transport, releases mutex. Checks connection state before sending.

Definition at line 237 of file lib/network/websocket/client.c.

                                                                                                               {
  if (!client) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL client");
  }
 
  if (!atomic_load_bool(&client->connection_active)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection not active");
  }
 
  if (!client->transport) {
    return SET_ERRNO(ERROR_NETWORK, "No active transport");
  }
 
  // Acquire send mutex for thread-safe transmission
  mutex_lock(&client->send_mutex);
 
  // Send packet through transport with client ID
  asciichat_error_t result = packet_send_via_transport(client->transport, type, data, len, client->my_client_id);
 
  mutex_unlock(&client->send_mutex);
 
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to send packet type %d: %s", type, asciichat_error_string(result));
    return -1;
  }
 
  return 0;
}

References ASCIICHAT_OK, atomic_load_bool(), ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, mutex_lock, mutex_unlock, packet_send_via_transport(), and SET_ERRNO.

Referenced by websocket_client_send_ping(), and websocket_client_send_pong().

websocket_client_send_ping()

int websocket_client_send_ping

(

websocket_client_t *

client

)

Send ping frame (keepalive heartbeat)

Routes through websocket_client_send_packet() with PACKET_TYPE_PING.

Parameters

client

WebSocket client instance

Returns

0 on success, -1 on failure

Note

Equivalent to tcp_client_send_ping() for API compatibility

Routes through websocket_client_send_packet() with PACKET_TYPE_PING.

Definition at line 271 of file lib/network/websocket/client.c.

                                                           {
  if (!client)
    return -1;
  return websocket_client_send_packet(client, PACKET_TYPE_PING, NULL, 0);
}

References PACKET_TYPE_PING, and websocket_client_send_packet().

websocket_client_send_pong()

int websocket_client_send_pong

(

websocket_client_t *

client

)

Send pong frame (keepalive response)

Routes through websocket_client_send_packet() with PACKET_TYPE_PONG.

Parameters

client

WebSocket client instance

Returns

0 on success, -1 on failure

Note

Equivalent to tcp_client_send_pong() for API compatibility

Routes through websocket_client_send_packet() with PACKET_TYPE_PONG.

Definition at line 282 of file lib/network/websocket/client.c.

                                                           {
  if (!client)
    return -1;
  return websocket_client_send_packet(client, PACKET_TYPE_PONG, NULL, 0);
}

References PACKET_TYPE_PONG, and websocket_client_send_packet().

websocket_client_should_reconnect()

bool websocket_client_should_reconnect

(

const websocket_client_t *

client

)

Check if reconnection should be attempted.

Parameters

client

WebSocket client instance

Returns

true if reconnection is needed, false otherwise

websocket_client_shutdown()

void websocket_client_shutdown

(

websocket_client_t *

client

)

Shutdown connection forcefully (for signal handlers)

Parameters

client

WebSocket client instance

Shutdown connection forcefully (for signal handlers)

Definition at line 153 of file lib/network/websocket/client.c.

                                                           {
  if (!client) {
    return;
  }
 
  log_debug("Shutting down WebSocket client");
 
  // Force close the transport
  if (client->transport) {
    acip_transport_close(client->transport);
  }
 
  atomic_store_bool(&client->connection_active, false);
  atomic_store_bool(&client->connection_lost, true);
}

References atomic_store_bool(), and log_debug.

websocket_client_signal_lost()

void websocket_client_signal_lost

(

websocket_client_t *

client

)

Signal that connection was lost (triggers reconnection)

Parameters

client

WebSocket client instance

Signal that connection was lost (triggers reconnection)

Definition at line 124 of file lib/network/websocket/client.c.

                                                              {
  if (!client) {
    return;
  }
  atomic_store_bool(&client->connection_lost, true);
  atomic_store_bool(&client->connection_active, false);
  log_debug("WebSocket connection marked as lost");
}

References atomic_store_bool(), and log_debug.

websocket_client_signal_reconnect()

void websocket_client_signal_reconnect

(

websocket_client_t *

client

)

Signal that reconnection should be attempted.

Parameters

client

WebSocket client instance