client.h File Reference

Go to the source code of this file.

Data Structures
struct	tcp_client
	TCP client connection state (network-layer only) More...

Typedefs
typedef struct tcp_client	tcp_client_t
	TCP client connection state (network-layer only)

Functions
tcp_client_t *	tcp_client_create (void)
	Create and initialize a TCP client instance.
void	tcp_client_destroy (tcp_client_t **client_ptr)
	Destroy TCP client and free all resources.
bool	tcp_client_is_active (const tcp_client_t *client)
	Check if connection is currently active.
bool	tcp_client_is_lost (const tcp_client_t *client)
	Check if connection was lost.
socket_t	tcp_client_get_socket (const tcp_client_t *client)
	Get current socket descriptor.
uint32_t	tcp_client_get_id (const tcp_client_t *client)
	Get client ID assigned by server.
void	tcp_client_signal_lost (tcp_client_t *client)
	Signal that connection was lost (triggers reconnection)
void	tcp_client_close (tcp_client_t *client)
	Close connection gracefully.
void	tcp_client_shutdown (tcp_client_t *client)
	Shutdown connection forcefully (for signal handlers)
int	tcp_client_connect (tcp_client_t *client, const char *address, int port, int reconnect_attempt, bool first_connection, bool has_ever_connected)
	Establish TCP connection to server.
int	tcp_client_send_packet (tcp_client_t *client, packet_type_t type, const void *data, size_t len)
	Send packet with thread-safe mutex protection.
int	tcp_client_send_ping (tcp_client_t *client)
	Send ping packet.
int	tcp_client_send_pong (tcp_client_t *client)
	Send pong packet.

Typedef Documentation

tcp_client_t

typedef struct tcp_client tcp_client_t

TCP client connection state (network-layer only)

Encapsulates network-specific state for a single TCP client connection:

• Socket file descriptor
• Server address information
• Connection state flags
• Send mutex for thread-safe packet transmission
• Encryption flag

Application-layer state (audio, threads, display, crypto) is now in app_client_t (network/client.h) to enable transport-agnostic design.

Ownership Model

• Created by tcp_client_create() in main thread
• Owned by connection management layer
• Destroyed after network I/O is complete

Thread Safety

• Atomic fields: Safe for concurrent read/write without locks
• Mutex-protected fields: Acquire send_mutex before socket writes
• Immutable after init: server_ip is set once, then read-only

See also

app_client_t For application-layer state

websocket_client_t For WebSocket transport equivalent

Function Documentation

tcp_client_close()

void tcp_client_close

(

tcp_client_t *

client

)

Close connection gracefully.

Parameters

client

TCP client instance

Definition at line 216 of file lib/network/tcp/client.c.

                                            {
  if (!client)
    return;
 
  log_debug("Closing client connection");
 
  // Mark connection as inactive
  atomic_store_bool(&client->connection_active, false);
 
  // Close socket
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Reset client ID
  client->my_client_id = 0;
}

References atomic_store_bool(), INVALID_SOCKET_VALUE, log_debug, and socket_is_valid().

tcp_client_connect()

int tcp_client_connect	(	tcp_client_t *	client,
		const char *	address,
		int	port,
		int	reconnect_attempt,
		bool	first_connection,
		bool	has_ever_connected
	)

Establish TCP connection to server.

Performs full connection lifecycle including DNS resolution, socket creation, connection with timeout, and socket configuration. Does NOT perform crypto handshake or send initial packets - those are application responsibilities.

Parameters

client	TCP client instance
address	Server hostname or IP address
port	Server port number
reconnect_attempt	Current reconnection attempt (0 for first, 1+ for retries)
first_connection	True if this is the very first connection since program start
has_ever_connected	True if client has successfully connected at least once

Returns

0 on success, negative on error

Performs full connection lifecycle:

• DNS resolution with IPv4/IPv6 dual-stack support
• Socket creation and connection with timeout
• Crypto handshake (if enabled)
• Initial capability exchange
• Client ID assignment from local port

Parameters

client	TCP client instance
address	Server hostname or IP address
port	Server port number
reconnect_attempt	Current reconnection attempt (0 for first, 1+ for retries)
first_connection	True if this is the very first connection since program start
has_ever_connected	True if client has successfully connected at least once

Returns

0 on success, negative on error

Definition at line 325 of file lib/network/tcp/client.c.

                                                                       {
  (void)first_connection;   // Currently unused
  (void)has_ever_connected; // Currently unused
 
  if (!client || !address || port <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid client, address, or port");
  }
 
  // Close any existing connection
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Apply reconnection delay if this is a retry
  if (reconnect_attempt > 0) {
    uint64_t delay_ns = get_reconnect_delay(reconnect_attempt);
    platform_sleep_ns(delay_ns);
  }
 
  // Resolve server address using getaddrinfo() for IPv4/IPv6 support
  // Special handling for localhost: ensure we try both IPv6 (::1) and IPv4 (127.0.0.1)
  bool is_localhost = (strcmp(address, "localhost") == 0 || is_localhost_ipv4(address) || is_localhost_ipv6(address));
 
  struct addrinfo hints, *res = NULL, *addr_iter;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_UNSPEC; // Allow IPv4 or IPv6
  hints.ai_socktype = SOCK_STREAM;
  if (is_localhost) {
    hints.ai_flags = AI_NUMERICSERV; // Optimize for localhost
  }
 
  char port_str[16];
  SAFE_SNPRINTF(port_str, sizeof(port_str), "%d", port);
 
  // For localhost, try IPv6 loopback (::1) first, then fall back to IPv4
  if (is_localhost) {
    log_debug("Localhost detected - trying IPv6 loopback [::1]:%s first...", port_str);
    hints.ai_family = AF_INET6;
    hints.ai_flags = AI_NUMERICHOST | AI_NUMERICSERV;
 
    int ipv6_result = getaddrinfo("::1", port_str, &hints, &res);
    if (ipv6_result == 0 && res != NULL) {
      // Try IPv6 loopback connection
      client->sockfd = socket_create("client_ipv6", res->ai_family, res->ai_socktype, res->ai_protocol);
      if (client->sockfd != INVALID_SOCKET_VALUE) {
        log_debug("Trying IPv6 loopback connection to [::1]:%s...", port_str);
        if (connect_with_timeout(client->sockfd, res->ai_addr, res->ai_addrlen, CONNECT_TIMEOUT)) {
          log_debug("Connection successful using IPv6 loopback");
          SAFE_STRNCPY(client->server_ip, "::1", sizeof(client->server_ip));
          freeaddrinfo(res);
          res = NULL; // Prevent double-free at connection_success label
          goto connection_success;
        }
        close_socket_safe(client->sockfd);
        client->sockfd = INVALID_SOCKET_VALUE;
      }
      freeaddrinfo(res);
      res = NULL;
    }
 
    // IPv6 failed, try IPv4 loopback (127.0.0.1)
    log_debug("IPv6 failed, trying IPv4 loopback 127.0.0.1:%s...", port_str);
    hints.ai_family = AF_INET;
 
    int ipv4_result = getaddrinfo("127.0.0.1", port_str, &hints, &res);
    if (ipv4_result == 0 && res != NULL) {
      client->sockfd = socket_create("client_ipv4", res->ai_family, res->ai_socktype, res->ai_protocol);
      if (client->sockfd != INVALID_SOCKET_VALUE) {
        log_debug("Trying IPv4 loopback connection to 127.0.0.1:%s...", port_str);
        if (connect_with_timeout(client->sockfd, res->ai_addr, res->ai_addrlen, CONNECT_TIMEOUT)) {
          log_debug("Connection successful using IPv4 loopback");
          SAFE_STRNCPY(client->server_ip, "127.0.0.1", sizeof(client->server_ip));
          freeaddrinfo(res);
          res = NULL;
          goto connection_success;
        }
        close_socket_safe(client->sockfd);
        client->sockfd = INVALID_SOCKET_VALUE;
      }
      freeaddrinfo(res);
      res = NULL;
    }
 
    // Both IPv6 and IPv4 loopback failed for localhost
    log_warn("Could not connect to localhost using either IPv6 or IPv4 loopback");
    return -1;
  }
 
  // For non-localhost addresses, use standard resolution
  log_debug("Resolving server address '%s' port %s...", address, port_str);
  hints.ai_family = AF_UNSPEC;
  hints.ai_flags = 0;
  int getaddr_result = getaddrinfo(address, port_str, &hints, &res);
  if (getaddr_result != 0) {
    log_error("Failed to resolve server address '%s': %s", address, gai_strerror(getaddr_result));
    return -1;
  }
 
  // Try each address returned by getaddrinfo() - prefer IPv6, fall back to IPv4
  for (int address_family = AF_INET6; address_family >= AF_INET; address_family -= (AF_INET6 - AF_INET)) {
    for (addr_iter = res; addr_iter != NULL; addr_iter = addr_iter->ai_next) {
      if (addr_iter->ai_family != address_family) {
        continue;
      }
 
      const char *socket_name = (addr_iter->ai_family == AF_INET6) ? "client_server_ipv6" : "client_server_ipv4";
      client->sockfd = socket_create(socket_name, addr_iter->ai_family, addr_iter->ai_socktype, addr_iter->ai_protocol);
      if (client->sockfd == INVALID_SOCKET_VALUE) {
        continue;
      }
 
      if (addr_iter->ai_family == AF_INET) {
        log_debug("Trying IPv4 connection...");
      } else if (addr_iter->ai_family == AF_INET6) {
        log_debug("Trying IPv6 connection...");
      }
 
      if (connect_with_timeout(client->sockfd, addr_iter->ai_addr, addr_iter->ai_addrlen, CONNECT_TIMEOUT)) {
        log_debug("Connection successful using %s", addr_iter->ai_family == AF_INET    ? "IPv4"
                                                    : addr_iter->ai_family == AF_INET6 ? "IPv6"
                                                                                       : "unknown protocol");
 
        // Extract server IP address for known_hosts
        if (format_ip_address(addr_iter->ai_family, addr_iter->ai_addr, client->server_ip, sizeof(client->server_ip)) ==
            ASCIICHAT_OK) {
          log_debug("Resolved server IP: %s", client->server_ip);
        } else {
          log_warn("Failed to format server IP address");
        }
 
        goto connection_success;
      }
 
      close_socket_safe(client->sockfd);
      client->sockfd = INVALID_SOCKET_VALUE;
    }
  }
 
connection_success:
 
  if (res) {
    freeaddrinfo(res);
  }
 
  // If we exhausted all addresses without success, fail
  if (client->sockfd == INVALID_SOCKET_VALUE) {
    log_warn("Could not connect to server %s:%d (tried all addresses)", address, port);
    return -1;
  }
 
  // Extract local port for client ID
  struct sockaddr_storage local_addr = {0};
  socklen_t addr_len = sizeof(local_addr);
  if (getsockname(client->sockfd, (struct sockaddr *)&local_addr, &addr_len) == -1) {
    log_error("Failed to get local socket address: %s", network_error_string());
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
 
  // Extract port from either IPv4 or IPv6 address
  int local_port = 0;
  if (((struct sockaddr *)&local_addr)->sa_family == AF_INET) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in *)&local_addr)->sin_port);
  } else if (((struct sockaddr *)&local_addr)->sa_family == AF_INET6) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in6 *)&local_addr)->sin6_port);
  }
  client->my_client_id = (uint32_t)local_port;
 
  // Update registration name now that we have a client ID
  {
    char client_name[64];
    SAFE_SNPRINTF(client_name, sizeof(client_name), "tcp_client_%u", client->my_client_id);
    named_update_name((uintptr_t)client, client_name);
  }
 
  // Mark connection as active
  atomic_store_bool(&client->connection_active, true);
  atomic_store_bool(&client->connection_lost, false);
  atomic_store_bool(&client->should_reconnect, false);
 
  // Initialize crypto (application must set crypto_initialized flag)
  // This is done outside this function by calling client_crypto_init()
 
  // Configure socket options
  if (socket_set_keepalive(client->sockfd, true) < 0) {
    log_warn("Failed to set socket keepalive: %s", network_error_string());
  }
 
  asciichat_error_t sock_config_result = socket_configure_buffers(client->sockfd);
  if (sock_config_result != ASCIICHAT_OK) {
    log_warn("Failed to configure socket: %s", network_error_string());
  }
 
  log_debug("Connection established successfully to %s:%d (client_id=%u)", address, port, client->my_client_id);
  return 0;
}

References ASCIICHAT_OK, atomic_store_bool(), CONNECT_TIMEOUT, connect_with_timeout(), ERROR_INVALID_PARAM, format_ip_address(), INVALID_SOCKET_VALUE, is_localhost_ipv4(), is_localhost_ipv6(), log_debug, log_error, log_warn, named_update_name(), NET_TO_HOST_U16, network_error_string(), platform_sleep_ns(), SAFE_SNPRINTF, SAFE_STRNCPY, SET_ERRNO, socket_configure_buffers(), socket_create(), socket_is_valid(), and socket_set_keepalive().

Referenced by connection_attempt_tcp().

tcp_client_create()

tcp_client_t * tcp_client_create

(

void

)

Create and initialize a TCP client instance.

Allocates a new tcp_client_t structure and initializes all fields to safe defaults. This function must be called before starting any worker threads.

Initialization Steps

1. Allocate tcp_client_t structure
2. Zero-initialize all fields
3. Set atomic flags to initial states
4. Initialize mutexes and condition variables
5. Set socket to INVALID_SOCKET_VALUE

Error Handling

Returns NULL if allocation fails or mutex initialization fails. Check errno or use HAS_ERRNO() for detailed error information.

Returns

Pointer to initialized client, or NULL on failure

Note

Caller must call tcp_client_destroy() when done

See also

tcp_client_destroy() For proper cleanup

Create and initialize a TCP client instance.

Allocates tcp_client_t and initializes all fields to safe defaults.

Definition at line 96 of file lib/network/tcp/client.c.

                                      {
  tcp_client_t *client = SAFE_MALLOC(sizeof(tcp_client_t), tcp_client_t *);
  if (!client) {
    log_error("Failed to allocate tcp_client_t");
    return NULL;
  }
 
  memset(client, 0, sizeof(*client));
 
  client->sockfd = INVALID_SOCKET_VALUE;
  atomic_store_bool(&client->connection_active, false);
  atomic_store_bool(&client->connection_lost, false);
  atomic_store_bool(&client->should_reconnect, false);
  client->my_client_id = 0;
  memset(client->server_ip, 0, sizeof(client->server_ip));
  client->encryption_enabled = false;
 
  if (mutex_init(&client->send_mutex, "client_send") != 0) {
    log_error("Failed to initialize send mutex");
    SAFE_FREE(client);
    return NULL;
  }
 
  NAMED_REGISTER_CLIENT(client, "client", NULL);
 
  // Register atomic fields for debug tracking - parent_key handles hierarchical naming
  NAMED_REGISTER_ATOMIC(&client->connection_active, "is_connection_active", (uintptr_t)(const void *)(client));
  NAMED_REGISTER_ATOMIC(&client->connection_lost, "has_connection_been_lost", (uintptr_t)(const void *)(client));
  NAMED_REGISTER_ATOMIC(&client->should_reconnect, "should_attempt_reconnection", (uintptr_t)(const void *)(client));
 
  log_debug("TCP client created successfully");
  return client;
}

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

Referenced by connection_attempt_tcp().

tcp_client_destroy()

void tcp_client_destroy

(

tcp_client_t **

client_ptr

)

Destroy TCP client and free all resources.

Destroys all synchronization primitives and frees the client structure. This function must be called AFTER all worker threads have been joined.

Cleanup Steps

1. Verify all threads have exited (debug builds only)
2. Destroy all mutexes and condition variables
3. Free tcp_client_t structure
4. Set pointer to NULL (via parameter)

Thread Safety

This function is NOT thread-safe. All worker threads must be joined before calling this function.

Parameters

client_ptr

Pointer to client pointer (set to NULL after free)

Warning

All threads must be stopped and joined before calling

Note

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

Destroy TCP client and free all resources.

Must be called AFTER all threads have been joined.

Definition at line 135 of file lib/network/tcp/client.c.

                                                   {
  if (!client_ptr || !*client_ptr) {
    return;
  }
 
  tcp_client_t *client = *client_ptr;
 
  if (socket_is_valid(client->sockfd)) {
    close_socket_safe(client->sockfd);
    client->sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Unregister atomic fields
  NAMED_UNREGISTER(&client->connection_active);
  NAMED_UNREGISTER(&client->connection_lost);
  NAMED_UNREGISTER(&client->should_reconnect);
 
  NAMED_UNREGISTER(client);
  mutex_destroy(&client->send_mutex);
  SAFE_FREE(*client_ptr);
 
  log_debug("TCP client destroyed");
}

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

Referenced by connection_attempt_tcp().

tcp_client_get_id()

uint32_t tcp_client_get_id

(

const tcp_client_t *

client

)

Get client ID assigned by server.

Parameters

client

TCP client instance

Returns

Client ID (from local port) or 0 if not connected

Definition at line 191 of file lib/network/tcp/client.c.

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

tcp_client_get_socket()

socket_t tcp_client_get_socket

(

const tcp_client_t *

client

)

Get current socket descriptor.

Parameters

client

TCP client instance

Returns

Socket descriptor or INVALID_SOCKET_VALUE if not connected

Definition at line 184 of file lib/network/tcp/client.c.

                                                           {
  return client ? client->sockfd : INVALID_SOCKET_VALUE;
}

References INVALID_SOCKET_VALUE.

Referenced by connection_attempt_tcp().

tcp_client_is_active()

bool tcp_client_is_active

(

const tcp_client_t *

client

)

Check if connection is currently active.

Parameters

client

TCP client instance

Returns

true if connection is active, false otherwise

Definition at line 166 of file lib/network/tcp/client.c.

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

References atomic_load_bool().

tcp_client_is_lost()

bool tcp_client_is_lost

(

const tcp_client_t *

client

)

Check if connection was lost.

Parameters

client

TCP client instance

Returns

true if connection loss was detected, false otherwise

Definition at line 175 of file lib/network/tcp/client.c.

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

References atomic_load_bool().

tcp_client_send_packet()

int tcp_client_send_packet	(	tcp_client_t *	client,
		packet_type_t	type,
		const void *	data,
		size_t	len
	)

Send packet with thread-safe mutex protection.

All packet transmission goes through this function to ensure packets aren't interleaved on the wire. Automatically handles encryption if crypto context is ready.

Parameters

client	TCP client instance
type	Packet type identifier
data	Packet payload
len	Payload length

Returns

0 on success, negative on error

All packet transmission goes through this function to ensure packets aren't interleaved on the wire.

Definition at line 260 of file lib/network/tcp/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");
  }
 
  // Acquire send mutex for thread-safe transmission
  mutex_lock(&client->send_mutex);
 
  // Send packet without encryption (crypto is handled at app_client layer)
  asciichat_error_t result = (asciichat_error_t)send_packet(client->sockfd, type, data, len);
 
  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, send_packet(), and SET_ERRNO.

Referenced by tcp_client_send_ping(), and tcp_client_send_pong().

tcp_client_send_ping()

int tcp_client_send_ping

(

tcp_client_t *

client

)

Send ping packet.

Parameters

client

TCP client instance

Returns

0 on success, negative on error

Definition at line 288 of file lib/network/tcp/client.c.

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

References PACKET_TYPE_PING, and tcp_client_send_packet().

tcp_client_send_pong()

int tcp_client_send_pong

(

tcp_client_t *

client

)

Send pong packet.

Parameters

client

TCP client instance

Returns

0 on success, negative on error

Definition at line 297 of file lib/network/tcp/client.c.

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

References PACKET_TYPE_PONG, and tcp_client_send_packet().

tcp_client_shutdown()

void tcp_client_shutdown

(

tcp_client_t *

client

)

Shutdown connection forcefully (for signal handlers)

Parameters

client

TCP client instance

Definition at line 238 of file lib/network/tcp/client.c.

                                               {
  if (!client)
    return;
 
  atomic_store_bool(&client->connection_active, false);
 
  // Shutdown socket for reading/writing to interrupt blocking calls
  if (socket_is_valid(client->sockfd)) {
    socket_shutdown(client->sockfd, SHUT_RDWR);
  }
}

References atomic_store_bool(), socket_is_valid(), and socket_shutdown().

tcp_client_signal_lost()

void tcp_client_signal_lost

(

tcp_client_t *

client

)

Signal that connection was lost (triggers reconnection)

Parameters

client

TCP client instance

Definition at line 202 of file lib/network/tcp/client.c.

                                                  {
  if (!client)
    return;
 
  if (!atomic_load_bool(&client->connection_lost)) {
    atomic_store_bool(&client->connection_lost, true);
    atomic_store_bool(&client->connection_active, false);
    log_info("Connection lost signaled");
  }
}

References atomic_load_bool(), atomic_store_bool(), and log_info.