transport.h File Reference

Transport abstraction layer for ACIP protocol. More...

Go to the source code of this file.

Data Structures
struct	acip_transport_capabilities_t
	The useful part of acip transport capabilities is in independent_streams, datagrams, max_datagram_payload: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path. application data in one QUIC DATAGRAM frame on the current path, including any transport-specific envelope. Query again after path changes. More...
struct	acip_transport_methods_t
	Transport method table (virtual function table). More...
struct	acip_transport
	Transport instance structure. More...

Typedefs
typedef struct acip_websocket_runtime	acip_websocket_runtime_t

Enumerations
enum	acip_transport_type_t {   ACIP_TRANSPORT_TCP = 1 , ACIP_TRANSPORT_WEBSOCKET = 2 , ACIP_TRANSPORT_WEBRTC = 3 , ACIP_TRANSPORT_HTTP = 4 ,   ACIP_TRANSPORT_QUIC = 5 }
	Transport method table (virtual function table). More...
enum	acip_transport_ownership_t { ACIP_TRANSPORT_BORROWED , ACIP_TRANSPORT_OWNED }

Functions
void	acip_transport_destroy (acip_transport_t *transport)
	Destroy transport and free all resources.
asciichat_error_t	acip_transport_sendv (acip_transport_t *transport, const socket_buffer_t *buffers, size_t count)
	Send data through transport.
asciichat_error_t	acip_transport_sendv_ex (acip_transport_t *transport, const socket_buffer_t *buffers, size_t count, const acip_send_options_t *options)
asciichat_error_t	acip_transport_get_capabilities (acip_transport_t *transport, acip_transport_capabilities_t *out)
asciichat_error_t	acip_transport_send (acip_transport_t *transport, const void *data, size_t len)
acip_transport_t *	acip_tcp_transport_create (const char *name, socket_t sockfd, crypto_context_t *crypto_ctx)
	Create TCP transport from existing socket.
acip_transport_t *	acip_tcp_transport_create_owned (const char *name, socket_t sockfd, crypto_context_t *crypto_ctx)
	Create a TCP transport that owns its connected socket.
asciichat_error_t	acip_tcp_transport_set_zerocopy (acip_transport_t *transport, bool enabled)
asciichat_error_t	acip_websocket_transport_flush (acip_transport_t *transport, uint64_t timeout_ns)
	Create WebSocket client transport.
asciichat_error_t	acip_websocket_runtime_create (acip_websocket_runtime_t **out)
void	acip_websocket_runtime_destroy (acip_websocket_runtime_t **runtime)
acip_transport_t *	acip_websocket_client_transport_create (const char *name, const char *url, crypto_context_t *crypto_ctx)
	Create WebSocket client transport.
acip_transport_t *	acip_websocket_server_transport_create (const char *name, struct lws *wsi, crypto_context_t *crypto_ctx)
	Create WebSocket server transport from existing connection.
acip_transport_t *	acip_webrtc_transport_create (struct webrtc_peer_connection *peer_conn, struct webrtc_data_channel *data_channel, crypto_context_t *crypto_ctx)

Detailed Description

Transport abstraction layer for ACIP protocol.

Provides a transport-agnostic interface that allows ACIP protocol handlers to work with any underlying transport (TCP, WebSocket, HTTP, etc.).

Transport Layer Design

Architecture

The transport layer abstracts protocol delivery, allowing the same ACIP protocol handlers to work with multiple underlying transports:

• TCP (acip_tcp_transport_create): Raw TCP sockets, binary packet streaming
• WebSocket (acip_websocket_client_transport_create): HTTP upgrade, frame-based
• WebRTC (acip_webrtc_transport_create): P2P data channels, encryption at transport
• HTTP (reserved): Long-polling, REST-style transport slot
• QUIC: UDP-based transport with congestion control and optional datagrams

Design Principles

1. Protocol code never calls socket()/send()/recv() directly
2. Same ACIP handlers work with any transport implementation
3. Each transport handles its own connection state and reliability
4. Clean separation between protocol logic (acip_*) and transport logic

Packet Framing

Transports handle packet framing transparently:

• TCP: Uses packet_header_t (magic + type + length + CRC32 + client_id)
• WebSocket: Wraps packets in WebSocket frames
• WebRTC: Sends packets directly on data channel

Version Information

• Transport API Version: 1.0 (stable)
• Supported ACIP Version: 1.0

DESIGN GOALS:

1. Protocol code never calls socket()/send()/recv() directly
2. Same ACIP handlers work with TCP, WebSocket, WebRTC, QUIC, or another backend
3. Transport implementations handle their own connection state
4. Clean separation between protocol logic and transport logic

USAGE PATTERN:

// Create TCP transport from existing socket
acip_transport_t *tcp = acip_tcp_transport_create(sockfd, crypto_ctx);
 
// Send packet with type-specific helper
asciichat_error_t result = acip_send_ascii_frame(tcp, frame_data, frame_size, ...);
 
// Receive packet with dispatcher
acip_client_receive_and_dispatch(tcp, &callbacks);
 
// Or create WebSocket client transport
acip_transport_t *ws = acip_websocket_client_transport_create("ws://localhost:27225", crypto_ctx);
asciichat_error_t result = acip_send_ascii_frame(ws, frame_data, frame_size, ...);
 
// Cleanup
acip_transport_destroy(tcp);
acip_transport_destroy(ws);

MEMORY OWNERSHIP:

• Transport owns its connection state (socket, pointers, etc.)
• send() does NOT take ownership of data (caller must keep it valid)
• recv() allocates buffer, caller must free via out_allocated_buffer
• destroy() cleans up all transport resources and frees transport structure

Author

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

Date

January 2026

Version

1.0 (Transport API)

Definition in file include/ascii-chat/network/acip/transport.h.

Typedef Documentation

acip_websocket_runtime_t

typedef struct acip_websocket_runtime acip_websocket_runtime_t

Application lifetime reference for libwebsockets TLS initialization. Keep it alive across connection contexts and release it after the last user.

Definition at line 462 of file include/ascii-chat/network/acip/transport.h.

Enumeration Type Documentation

acip_transport_ownership_t

enum acip_transport_ownership_t

Ownership transfers only after successful registration.

Enumerator
ACIP_TRANSPORT_BORROWED
ACIP_TRANSPORT_OWNED

Definition at line 125 of file include/ascii-chat/network/acip/transport.h.

             {
  ACIP_TRANSPORT_BORROWED,
  ACIP_TRANSPORT_OWNED,
} acip_transport_ownership_t;

acip_transport_type_t

enum acip_transport_type_t

Transport method table (virtual function table).

This is the handoff point for acip transport. Callers fill outbound, stats_peer, methods, crypto_ctx before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do.

Transport type enumeration

Identifies which transport implementation is being used. Useful for debugging and conditional logic.

Enumerator
ACIP_TRANSPORT_TCP	Raw TCP socket.
ACIP_TRANSPORT_WEBSOCKET	WebSocket over TCP.
ACIP_TRANSPORT_WEBRTC	WebRTC DataChannel (P2P).
ACIP_TRANSPORT_HTTP	HTTP long-polling (future).
ACIP_TRANSPORT_QUIC	QUIC/UDP (future).

Definition at line 98 of file include/ascii-chat/network/acip/transport.h.

             {
  ACIP_TRANSPORT_TCP = 1,       
  ACIP_TRANSPORT_WEBSOCKET = 2, 
  ACIP_TRANSPORT_WEBRTC = 3,    
  ACIP_TRANSPORT_HTTP = 4,      
  ACIP_TRANSPORT_QUIC = 5       
} acip_transport_type_t;

Function Documentation

acip_tcp_transport_create()

acip_transport_t * acip_tcp_transport_create	(	const char *	name,
		socket_t	sockfd,
		crypto_context_t *	crypto_ctx )

Create TCP transport from existing socket.

Parameters

name	Debug name for tracking this transport (required, e.g., "transport_client_5")
sockfd	Connected socket descriptor
crypto_ctx	Optional crypto context (may be NULL)

Returns

Transport instance or NULL on error

Note

Caller retains socket ownership (transport doesn't close on destroy)

Definition at line 293 of file tcp/transport.c.

                                                                                                             {
  if (!name) {
    SET_ERRNO(ERROR_INVALID_STATE, "Transport name is required");
    return NULL;
  }
 
  if (sockfd == INVALID_SOCKET_VALUE) {
    log_error("[TCP_CREATE_STATE] ❌ INVALID_SOCKET: sockfd=%d", sockfd);
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
    return NULL;
  }
 
  log_info("[TCP_CREATE_STATE] 🟢 CREATE_START: sockfd=%d, crypto=%s", sockfd, crypto_ctx ? "yes" : "no");
 
  // Allocate transport structure
  acip_transport_t *transport = SAFE_CALLOC(1, sizeof(acip_transport_t), acip_transport_t *);
  if (!transport) {
    log_error("[TCP_CREATE_STATE] ❌ ALLOC_TRANSPORT_FAILED: size=%zu", sizeof(acip_transport_t));
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate TCP transport");
    return NULL;
  }
 
  log_debug("[TCP_CREATE_STATE] 🟢 TRANSPORT_ALLOCATED: transport=%p", (void *)transport);
 
  // Allocate TCP-specific data
  tcp_transport_data_t *tcp_data = SAFE_MALLOC(sizeof(tcp_transport_data_t), tcp_transport_data_t *);
  if (!tcp_data) {
    log_error("[TCP_CREATE_STATE] ❌ ALLOC_TCP_DATA_FAILED: size=%zu", sizeof(tcp_transport_data_t));
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate TCP transport data");
    return NULL;
  }
 
  log_debug("[TCP_CREATE_STATE] 🟢 TCP_DATA_ALLOCATED: tcp_data=%p", (void *)tcp_data);
 
  // Initialize TCP data
  tcp_data->sockfd = sockfd;
  tcp_data->is_connected = true;
  tcp_data->owns_socket = false;
  tcp_data->zerocopy_disabled = false;
 
  // Initialize send mutex to protect concurrent sends from multiple threads
  int mutex_result = mutex_init(&tcp_data->send_mutex, "tcp_send");
  if (mutex_result != 0) {
    log_error("[TCP_CREATE_STATE] ❌ MUTEX_INIT_FAILED: result=%d", mutex_result);
    SAFE_FREE(tcp_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_MEMORY, "Failed to initialize send mutex");
    return NULL;
  }
 
  log_info("[TCP_CREATE_STATE] 🟢 TCP_DATA_INITIALIZED: sockfd=%d, is_connected=true, send_mutex=initialized", sockfd);
 
  // Enable TCP_NODELAY to disable Nagle's algorithm
  // This ensures small packets are sent immediately instead of being buffered
  int nodelay = 1;
  if (setsockopt(sockfd, IPPROTO_TCP, TCP_NODELAY, (const char *)&nodelay, sizeof(nodelay)) < 0) {
    log_warn("[TCP_CREATE_STATE] ⚠️  TCP_NODELAY_FAILED: sockfd=%d, %s", sockfd, SAFE_STRERROR(errno));
    // Continue anyway - this is not fatal
  } else {
    log_debug("[TCP_CREATE_STATE] 🟢 TCP_NODELAY_SET: sockfd=%d", sockfd);
  }
 
  // Initialize transport
  transport->methods = &tcp_methods;
  transport->stats_peer = stats_runtime_peer_open("TCP");
  transport->crypto_ctx = crypto_ctx;
  transport->impl_data = tcp_data;
  int send_buffer = SOCKET_STREAM_SEND_BUFFER;
  if (socket_setsockopt(sockfd, SOL_SOCKET, SO_SNDBUF, &send_buffer, sizeof(send_buffer)) != 0) {
    acip_transport_destroy(transport);
    SET_ERRNO_SYS(ERROR_NETWORK, "Cannot bound TCP send buffer");
    return NULL;
  }
 
  // Register transport and impl_data before logging so named replacements work
  NAMED_REGISTER_TRANSPORT(transport, name, NULL);
  NAMED_REGISTER(tcp_data, "impl", "tcp_impl", "0x%tx", (uintptr_t)(const void *)(transport));
 
  log_info("[TCP_CREATE_STATE] ✅ CREATE_COMPLETE: transport=%p, sockfd=%d, is_connected=true, crypto=%s",
           (void *)transport, sockfd, crypto_ctx ? "enabled" : "disabled");
 
#ifndef __EMSCRIPTEN__
  if (transport && acip_outbound_create(transport) != ASCIICHAT_OK) {
    acip_transport_destroy(transport);
    return NULL;
  }
#endif
  return transport;
}

References acip_outbound_create(), acip_transport_destroy(), ASCIICHAT_OK, acip_transport::crypto_ctx, errno, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NETWORK, acip_transport::impl_data, tcp_transport_data_t::is_connected, log_debug, log_error, log_info, log_warn, acip_transport::methods, NAMED_REGISTER, NAMED_REGISTER_TRANSPORT, tcp_transport_data_t::owns_socket, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, SAFE_STRERROR, tcp_transport_data_t::send_mutex, SET_ERRNO, SET_ERRNO_SYS, tcp_transport_data_t::sockfd, acip_transport::stats_peer, stats_runtime_peer_open(), and tcp_transport_data_t::zerocopy_disabled.

Referenced by acip_tcp_transport_create_owned().

acip_tcp_transport_create_owned()

acip_transport_t * acip_tcp_transport_create_owned	(	const char *	name,
		socket_t	sockfd,
		crypto_context_t *	crypto_ctx )

Create a TCP transport that owns its connected socket.

Parameters

name	Debug name for the transport
sockfd	Connected socket; ownership transfers only on success
crypto_ctx	Optional borrowed crypto context

Returns

Transport instance or NULL on error Closing or destroying the transport closes the socket.

Definition at line 384 of file tcp/transport.c.

                                                                                                                   {
  acip_transport_t *transport = acip_tcp_transport_create(name, sockfd, crypto_ctx);
  if (transport)
    ((tcp_transport_data_t *)transport->impl_data)->owns_socket = true;
  return transport;
}

References acip_tcp_transport_create(), and acip_transport::impl_data.

acip_tcp_transport_set_zerocopy()

asciichat_error_t acip_tcp_transport_set_zerocopy	(	acip_transport_t *	transport,
		bool	enabled )

Override the automatic kernel copy-avoidance policy for this TCP transport. Large Linux encrypted sends may pin pages; other platforms fall back to vectors. Copy avoidance is attempted automatically and disabled after copied completions.

Definition at line 112 of file tcp/transport.c.

                                                                                             {
  if (!transport || acip_transport_get_type(transport) != ACIP_TRANSPORT_TCP)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Expected TCP transport");
  tcp_transport_data_t *tcp = transport->impl_data;
  mutex_lock(&tcp->send_mutex);
  tcp->zerocopy_disabled = !enabled;
  mutex_unlock(&tcp->send_mutex);
  return ASCIICHAT_OK;
}

References ACIP_TRANSPORT_TCP, ASCIICHAT_OK, enabled, ERROR_INVALID_PARAM, acip_transport::impl_data, tcp_transport_data_t::send_mutex, SET_ERRNO, and tcp_transport_data_t::zerocopy_disabled.

acip_transport_destroy()

void acip_transport_destroy

(

acip_transport_t *

transport

)

Destroy transport and free all resources.

Parameters

transport

Transport to destroy (may be NULL)

Note

Calls close() first if still connected

Frees the transport structure itself

Safe to pass NULL

Definition at line 395 of file tcp/transport.c.

                                                         {
  if (!transport) {
    log_debug("[TRANSPORT_DESTROY] ⚠️  NULL_TRANSPORT: nothing to destroy");
    return;
  }
 
  log_debug("[TRANSPORT_DESTROY] 🔴 DESTROY_START: transport=%p, impl_data=%p", (void *)transport,
            transport->impl_data);
 
#ifndef __EMSCRIPTEN__
  acip_outbound_destroy(transport);
#endif
 
  // Get type before we destroy for logging
  acip_transport_type_t type = 0;
  if (transport->methods && transport->methods->get_type) {
    type = transport->methods->get_type(transport);
    log_debug("[TRANSPORT_DESTROY] 📋 TRANSPORT_TYPE: type=%d (1=TCP, 2=WebSocket, 3=WebRTC, ...)", type);
  }
 
  // Close if still connected
  if (transport->methods && transport->methods->close && transport->methods->is_connected &&
      transport->methods->is_connected(transport)) {
    log_debug("[TRANSPORT_DESTROY] 🔴 STILL_CONNECTED: calling close() first (type=%d)", type);
    asciichat_error_t close_result = transport->methods->close(transport);
    if (close_result != ASCIICHAT_OK)
      log_warn("Transport close during cleanup failed: %d", close_result);
    log_debug("[TRANSPORT_DESTROY] 🔴 CLOSE_CALLED: result=%d", close_result != ASCIICHAT_OK ? -1 : 0);
  } else {
    log_debug("[TRANSPORT_DESTROY] ✅ ALREADY_CLOSED: skipping close (type=%d)", type);
  }
 
  // Call custom destroy implementation if provided
  if (transport->methods && transport->methods->destroy_impl) {
    log_debug("[TRANSPORT_DESTROY] 🔧 CALLING_DESTROY_IMPL: type=%d", type);
    transport->methods->destroy_impl(transport);
    log_debug("[TRANSPORT_DESTROY] ✅ DESTROY_IMPL_COMPLETE: type=%d", type);
  } else {
    log_debug("[TRANSPORT_DESTROY] ⏭️  NO_CUSTOM_DESTROY: type=%d (using generic cleanup)", type);
  }
 
  // Free implementation data
  if (transport->impl_data) {
    log_debug("[TRANSPORT_DESTROY] 🗑️  FREEING_IMPL_DATA: %p", transport->impl_data);
    NAMED_UNREGISTER(transport->impl_data);
    SAFE_FREE(transport->impl_data);
    log_debug("[TRANSPORT_DESTROY] ✅ IMPL_DATA_FREED");
  }
 
  stats_runtime_peer_close(transport->stats_peer);
  transport->stats_peer = NULL;
 
  // Free transport structure
  log_debug("[TRANSPORT_DESTROY] 🗑️  FREEING_TRANSPORT: %p", (void *)transport);
  SAFE_FREE(transport);
 
  log_debug("[TRANSPORT_DESTROY] ✅ DESTROY_COMPLETE: type=%d", type);
}

References acip_outbound_destroy(), ASCIICHAT_OK, acip_transport_methods_t::close, acip_transport_methods_t::destroy_impl, acip_transport_methods_t::get_type, acip_transport::impl_data, acip_transport_methods_t::is_connected, log_debug, log_warn, acip_transport::methods, NAMED_UNREGISTER, SAFE_FREE, acip_transport::stats_peer, and stats_runtime_peer_close().

Referenced by acip_async_tcp_accepted_create(), acip_async_tcp_client_create(), acip_async_tcp_transport_create(), acip_tcp_transport_create(), acip_websocket_client_transport_create(), acip_websocket_server_transport_create(), network_connection_open(), and quic_release().

acip_transport_get_capabilities()

asciichat_error_t acip_transport_get_capabilities	(	acip_transport_t *	transport,
		acip_transport_capabilities_t *	out )

A backend with no capability method reports no optional capabilities. Negotiated backends can return ERROR_INVALID_STATE until negotiation finishes.

Definition at line 104 of file send.c.

                                                                                                                   {
  if (!out)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing transport capabilities output");
  *out = (acip_transport_capabilities_t){0};
  if (!transport || !transport->methods)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport capabilities query");
  return transport->methods->get_capabilities ? transport->methods->get_capabilities(transport, out) : ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, acip_transport_methods_t::get_capabilities, acip_transport::methods, out, and SET_ERRNO.

Referenced by packet_send_via_transportv().

acip_transport_send()

asciichat_error_t acip_transport_send	(	acip_transport_t *	transport,
		const void *	data,
		size_t	len )

Definition at line 150 of file send.c.

                                                                                                 {
  socket_buffer_t buffer = {data, len};
  return acip_transport_sendv(transport, &buffer, 1);
}

References acip_transport_sendv().

acip_transport_sendv()

asciichat_error_t acip_transport_sendv	(	acip_transport_t *	transport,
		const socket_buffer_t *	buffers,
		size_t	count )

Send data through transport.

Convenience wrapper around transport->methods->send().

Parameters

transport	Transport instance
data	Data to send
len	Data length

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 140 of file send.c.

                                                                                                                  {
  acip_send_options_t options = {.traffic_class = ACIP_TRAFFIC_CONTROL, .delivery = ACIP_DELIVERY_RELIABLE};
  if (buffers && count && buffers[0].data && buffers[0].len >= sizeof(packet_header_t)) {
    packet_header_t header;
    memcpy(&header, buffers[0].data, sizeof(header));
    options.traffic_class = acip_packet_traffic_class(NET_TO_HOST_U16(header.type));
  }
  return acip_transport_sendv_ex(transport, buffers, count, &options);
}

References ACIP_DELIVERY_RELIABLE, acip_packet_traffic_class(), ACIP_TRAFFIC_CONTROL, acip_transport_sendv_ex(), NET_TO_HOST_U16, and acip_send_options_t::traffic_class.

Referenced by acip_transport_send().

acip_transport_sendv_ex()

asciichat_error_t acip_transport_sendv_ex	(	acip_transport_t *	transport,
		const socket_buffer_t *	buffers,
		size_t	count,
		const acip_send_options_t *	options )

Send with explicit delivery metadata. Unsupported datagrams or deadlines return ERROR_NOT_SUPPORTED and are never silently changed into reliable delivery. A deadline uses time_get_ns()'s monotonic clock.

Definition at line 113 of file send.c.

                                                                              {
  if (!transport || !transport->methods || !buffers || !count || count > SOCKET_IOV_MAX || !options ||
      (unsigned)options->traffic_class > ACIP_TRAFFIC_VISUAL ||
      (options->delivery != ACIP_DELIVERY_RELIABLE && options->delivery != ACIP_DELIVERY_DATAGRAM))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport send options");
  if (options->delivery != ACIP_DELIVERY_RELIABLE || options->deadline_ns) {
    if (!transport->methods->sendv_ex || !transport->methods->validate_send_options)
      return SET_ERRNO(ERROR_NOT_SUPPORTED, "Datagrams and deadlines are not supported by this transport");
    asciichat_error_t result = transport->methods->validate_send_options(transport, options);
    if (result != ASCIICHAT_OK)
      return result;
  }
#ifndef __EMSCRIPTEN__
  if (transport && transport->outbound) {
    acip_admission_t admission;
    asciichat_error_t result = acip_outbound_submitv_ex(transport, buffers, count, options, &admission);
    if (result != ASCIICHAT_OK)
      return result;
    if (admission != ACIP_ADMISSION_ACCEPTED)
      return SET_ERRNO(ERROR_BUFFER_FULL, "Outbound media not admitted (%d)", admission);
    return ASCIICHAT_OK;
  }
#endif
  return transport_sendv_impl(transport, buffers, count, options);
}

References ACIP_ADMISSION_ACCEPTED, ACIP_DELIVERY_DATAGRAM, ACIP_DELIVERY_RELIABLE, acip_outbound_submitv_ex(), ACIP_TRAFFIC_VISUAL, ASCIICHAT_OK, acip_send_options_t::deadline_ns, acip_send_options_t::delivery, ERROR_BUFFER_FULL, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, acip_transport::methods, acip_transport::outbound, acip_transport_methods_t::sendv_ex, SET_ERRNO, acip_send_options_t::traffic_class, and acip_transport_methods_t::validate_send_options.

Referenced by acip_transport_sendv(), and packet_send_via_transportv().

acip_webrtc_transport_create()

acip_transport_t * acip_webrtc_transport_create	(	struct webrtc_peer_connection *	peer_conn,
		struct webrtc_data_channel *	data_channel,
		crypto_context_t *	crypto_ctx )

Definition at line 913 of file webrtc/transport.c.

                                                                             {
  return webrtc_transport_create(peer_conn, data_channel, crypto_ctx, NULL, NULL, NULL);
}

acip_websocket_client_transport_create()

acip_transport_t * acip_websocket_client_transport_create	(	const char *	name,
		const char *	url,
		crypto_context_t *	crypto_ctx )

Create WebSocket client transport.

Parameters

url	WebSocket URL (e.g., "ws://localhost:27225")
crypto_ctx	Optional encryption context (can be NULL)

Returns

Transport instance or NULL on failure

Definition at line 1537 of file websocket/transport.c.

                                                                                       {
  if (!name) {
    SET_ERRNO(ERROR_INVALID_STATE, "Transport name is required");
    return NULL;
  }
 
  if (!url) {
    SET_ERRNO(ERROR_INVALID_PARAM, "url is required");
    return NULL;
  }
 
  websocket_endpoint_t endpoint;
  if (websocket_parse_endpoint(url, &endpoint) != ASCIICHAT_OK) {
    return NULL;
  }
  const char *host = endpoint.host;
  const char *path = endpoint.path;
  int port = endpoint.port;
  bool use_ssl = endpoint.use_ssl;
 
  acip_transport_t *transport = websocket_allocate_client_transport(name);
  if (!transport) {
    return NULL;
  }
  websocket_transport_data_t *ws_data = (websocket_transport_data_t *)transport->impl_data;
 
  ws_data->context = websocket_create_client_context();
 
  if (!ws_data->context) {
    cond_destroy(&ws_data->state_cond);
    mutex_destroy(&ws_data->state_mutex);
    cond_destroy(&ws_data->recv_cond);
    mutex_destroy(&ws_data->recv_mutex);
    ringbuffer_destroy(ws_data->send_queue);
    ringbuffer_destroy(ws_data->recv_queue);
    SAFE_FREE(ws_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_NETWORK, "Failed to create libwebsockets context");
    return NULL;
  }
 
  // Initialize connection state flags BEFORE calling lws_client_connect_via_info
  // The callback might fire immediately, so all fields must be ready
  ws_data->is_connected = false;      // Will be set to true in LWS_CALLBACK_CLIENT_ESTABLISHED
  ws_data->connection_failed = false; // Set to true in LWS_CALLBACK_CLIENT_CONNECTION_ERROR
  ws_data->owns_context = true;       // Client transport owns the context
 
  // Connect to WebSocket server
  log_debug("Initiating WebSocket connection to %s:%d%s", host, port, path);
  struct lws_client_connect_info connect_info;
  memset(&connect_info, 0, sizeof(connect_info));
  connect_info.context = ws_data->context;
  connect_info.address = host;
  connect_info.port = port;
  connect_info.path = path;
  connect_info.host = host;
  connect_info.origin = host;
  // Request the ACIP subprotocol so server routes to acip_protocol handler
  // This ensures WebSocket upgrade includes Sec-WebSocket-Protocol: acip
  connect_info.local_protocol_name = "acip";
  connect_info.protocol = "acip";
  // Use SSL + skip server certificate hostname verification + allow self-signed certs (for development)
  connect_info.ssl_connection =
      use_ssl ? (LCCSCF_USE_SSL | LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK | LCCSCF_ALLOW_SELFSIGNED) : 0;
  connect_info.opaque_user_data = ws_data;
 
  log_debug("Calling lws_client_connect_via_info...");
  ws_data->wsi = lws_client_connect_via_info(&connect_info);
  log_debug("lws_client_connect_via_info returned: %p", (void *)ws_data->wsi);
  if (!ws_data->wsi) {
    lws_context_destroy(ws_data->context);
    cond_destroy(&ws_data->state_cond);
    mutex_destroy(&ws_data->state_mutex);
    cond_destroy(&ws_data->recv_cond);
    mutex_destroy(&ws_data->recv_mutex);
    ringbuffer_destroy(ws_data->send_queue);
    ringbuffer_destroy(ws_data->recv_queue);
    SAFE_FREE(ws_data);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_NETWORK, "Failed to connect to WebSocket server");
    return NULL;
  }
 
  // Initialize transport
  transport->methods = &websocket_methods;
  transport->stats_peer = stats_runtime_peer_open("WebSocket");
  transport->crypto_ctx = crypto_ctx;
  transport->impl_data = ws_data;
 
  // Start service thread immediately - it will drive TLS handshake with frequent polling
  // The service thread checks is_destroying and context validity before calling lws_service,
  // so it's safe to start it right away without delays.
  ws_data->service_running = true;
  if (platform_thread_create(&ws_data->service_thread, "ws_service", websocket_service_thread, ws_data) != 0) {
    log_error("Failed to create WebSocket service thread");
    ws_data->service_running = false;
    lws_context_destroy(ws_data->context);
    cond_destroy(&ws_data->state_cond);
    mutex_destroy(&ws_data->state_mutex);
    cond_destroy(&ws_data->recv_cond);
    mutex_destroy(&ws_data->recv_mutex);
    ringbuffer_destroy(ws_data->send_queue);
    ringbuffer_destroy(ws_data->recv_queue);
    SAFE_FREE(ws_data);
    stats_runtime_peer_close(transport->stats_peer);
    SAFE_FREE(transport);
    SET_ERRNO(ERROR_INTERNAL, "Failed to create service thread");
    return NULL;
  }
  log_debug("WebSocket service thread started");
 
  // Do NOT block the main thread waiting for connection!
  // This prevents stdin/keyboard input from being processed and causes the client to hang.
  // The service thread will establish the connection asynchronously.
  // The protocol layer (recv) will detect if connection fails and handle it there.
  // Return immediately so the main thread can respond to keyboard input.
  log_debug("WebSocket transport created, service thread will establish connection asynchronously");
 
  // Register transport
  NAMED_REGISTER_TRANSPORT(transport, name, NULL);
 
  // Register websocket implementation data with transport as parent
  (void)NAMED_REGISTER_WEBSOCKET_IMPL(ws_data, "impl", (uintptr_t)(const void *)(transport));
 
  // Return transport immediately - connection will be established by service thread
  // If connection fails, recv() will detect is_connected=false and return error
  if (transport->methods && acip_outbound_create(transport) != ASCIICHAT_OK) {
    acip_transport_destroy(transport);
    return NULL;
  }
  return transport;
}

References acip_outbound_create(), acip_transport_destroy(), ASCIICHAT_OK, websocket_transport_data_t::connection_failed, websocket_transport_data_t::context, acip_transport::crypto_ctx, ERROR_INTERNAL, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, websocket_endpoint_t::host, acip_transport::impl_data, websocket_transport_data_t::is_connected, log_debug, log_error, acip_transport::methods, NAMED_REGISTER_TRANSPORT, NAMED_REGISTER_WEBSOCKET_IMPL, websocket_transport_data_t::owns_context, websocket_endpoint_t::path, websocket_endpoint_t::port, websocket_transport_data_t::recv_cond, websocket_transport_data_t::recv_mutex, websocket_transport_data_t::recv_queue, ringbuffer_destroy(), SAFE_FREE, websocket_transport_data_t::send_queue, websocket_transport_data_t::service_running, websocket_transport_data_t::service_thread, SET_ERRNO, websocket_transport_data_t::state_cond, websocket_transport_data_t::state_mutex, acip_transport::stats_peer, stats_runtime_peer_close(), stats_runtime_peer_open(), websocket_endpoint_t::use_ssl, and websocket_transport_data_t::wsi.

Referenced by network_connection_open().

acip_websocket_runtime_create()

asciichat_error_t acip_websocket_runtime_create

(

acip_websocket_runtime_t **

out

)

Definition at line 1416 of file websocket/transport.c.

                                                                                {
  if (!out || *out)
    return SET_ERRNO(ERROR_INVALID_PARAM, "WebSocket runtime output must be empty");
  acip_websocket_runtime_t *runtime = SAFE_CALLOC(1, sizeof(*runtime), acip_websocket_runtime_t *);
  if (!runtime)
    return SET_ERRNO(ERROR_MEMORY, "Could not allocate WebSocket runtime");
  // libwebsockets 4.5 calls OPENSSL_cleanup when its last TLS context goes away.
  // An application reference prevents connection teardown from ending TLS lifetime.
  runtime->context = websocket_create_client_context();
  if (!runtime->context) {
    SAFE_FREE(runtime);
    return SET_ERRNO(ERROR_NETWORK, "Could not initialize WebSocket runtime");
  }
  *out = runtime;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, acip_websocket_runtime::context, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, out, SAFE_CALLOC, SAFE_FREE, and SET_ERRNO.

Referenced by discovery_main().

acip_websocket_runtime_destroy()

void acip_websocket_runtime_destroy

(

acip_websocket_runtime_t **

runtime

)

Definition at line 1433 of file websocket/transport.c.

                                                                        {
  if (!runtime || !*runtime)
    return;
  lws_context_destroy((*runtime)->context);
  SAFE_FREE(*runtime);
  *runtime = NULL;
}

References SAFE_FREE.

Referenced by discovery_main().

acip_websocket_server_transport_create()

acip_transport_t * acip_websocket_server_transport_create	(	const char *	name,
		struct lws *	wsi,
		crypto_context_t *	crypto_ctx )

Create WebSocket server transport from existing connection.

Wraps an already-established libwebsockets connection (from server accept). Used by websocket_server module to create transports for incoming clients.

Parameters

wsi	Established libwebsockets connection (not owned by transport)
crypto_ctx	Optional crypto context

Returns

Transport instance or NULL on error

Definition at line 1773 of file websocket/transport.c.

                                                                                       {
  if (!name) {
    SET_ERRNO(ERROR_INVALID_STATE, "Transport name is required");
    return NULL;
  }
 
  if (!wsi) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid wsi parameter");
    return NULL;
  }
 
  acip_transport_t *transport = websocket_allocate_server_transport(name);
  if (!transport) {
    return NULL;
  }
  websocket_transport_data_t *ws_data = (websocket_transport_data_t *)transport->impl_data;
 
  // Store connection info (server-side: no context ownership, connection already established)
  ws_data->wsi = wsi;
 
  ws_data->context = lws_get_context(wsi); // Get context from wsi (not owned)
  ws_data->owns_context = false;           // Server owns context, not transport
  ws_data->is_connected = true;            // Already connected (server-side)
  log_debug_every(US_PER_SEC_INT, "★★★ SERVER TRANSPORT CREATED: is_connected=true, wsi=%p, ws_data=%p", (void *)wsi,
                  (void *)ws_data);
  log_debug("Server transport created: is_connected=true, wsi=%p", (void *)wsi);
 
  // Initialize transport
  transport->methods = &websocket_methods;
  transport->stats_peer = stats_runtime_peer_open("WebSocket");
  transport->crypto_ctx = crypto_ctx;
  transport->impl_data = ws_data;
 
  log_debug_every(US_PER_SEC_INT, "Created WebSocket server transport (crypto: %s)",
                  crypto_ctx ? "enabled" : "disabled");
 
  // Register transport
  NAMED_REGISTER_TRANSPORT(transport, name, NULL);
 
  // Register websocket implementation data with transport as parent
  (void)NAMED_REGISTER_WEBSOCKET_IMPL(ws_data, "impl", (uintptr_t)(const void *)(transport));
 
  int send_buffer = SOCKET_STREAM_SEND_BUFFER;
  if (socket_setsockopt(lws_get_socket_fd(wsi), SOL_SOCKET, SO_SNDBUF, &send_buffer, sizeof(send_buffer)) != 0) {
    acip_transport_destroy(transport);
    SET_ERRNO_SYS(ERROR_NETWORK, "Cannot bound WebSocket send buffer");
    return NULL;
  }
 
  if (transport->methods && acip_outbound_create(transport) != ASCIICHAT_OK) {
    acip_transport_destroy(transport);
    return NULL;
  }
  return transport;
}

References acip_outbound_create(), acip_transport_destroy(), ASCIICHAT_OK, websocket_transport_data_t::context, acip_transport::crypto_ctx, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, acip_transport::impl_data, websocket_transport_data_t::is_connected, log_debug, log_debug_every, acip_transport::methods, NAMED_REGISTER_TRANSPORT, NAMED_REGISTER_WEBSOCKET_IMPL, websocket_transport_data_t::owns_context, SET_ERRNO, SET_ERRNO_SYS, acip_transport::stats_peer, stats_runtime_peer_open(), US_PER_SEC_INT, and websocket_transport_data_t::wsi.

acip_websocket_transport_flush()

asciichat_error_t acip_websocket_transport_flush	(	acip_transport_t *	transport,
		uint64_t	timeout_ns )

Create WebSocket client transport.

Connects to a WebSocket server at the specified URL and creates a transport for sending/receiving ACIP packets over the WebSocket connection.

Parameters

name	Debug name for tracking this transport (required, e.g., "transport_websocket_client")
url	WebSocket URL (e.g., "ws://localhost:27225" or "wss://example.com/path")
crypto_ctx	Optional encryption context (can be NULL)

Returns

Transport instance or NULL on failure

Note

The URL must include the protocol (ws:// or wss://)

Port defaults to 80 for ws:// and 443 for wss:// if not specified

Connection is established synchronously during creation Wait for queued messages to reach their writable completion callback. Call from a worker, never from the libwebsockets service thread.

Definition at line 1087 of file websocket/transport.c.

                                                                                                   {
  if (!transport || acip_transport_get_type(transport) != ACIP_TRANSPORT_WEBSOCKET)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Expected WebSocket transport");
  websocket_transport_data_t *ws_data = transport->impl_data;
  uint64_t started = time_get_ns();
  while (acip_transport_is_connected(transport)) {
    mutex_lock(&ws_data->send_mutex);
    bool drained = ringbuffer_is_empty(ws_data->send_queue) && !ws_data->inflight_buffer;
    mutex_unlock(&ws_data->send_mutex);
    if (drained)
      return ASCIICHAT_OK;
    if (time_get_ns() - started >= timeout_ns)
      return SET_ERRNO(ERROR_NETWORK_TIMEOUT, "WebSocket send queue did not drain");
    platform_sleep_us(1000);
  }
  return SET_ERRNO(ERROR_NETWORK, "WebSocket closed before send queue drained");
}

References ACIP_TRANSPORT_WEBSOCKET, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, ERROR_NETWORK_TIMEOUT, acip_transport::impl_data, websocket_transport_data_t::inflight_buffer, ringbuffer_is_empty(), websocket_transport_data_t::send_mutex, websocket_transport_data_t::send_queue, and SET_ERRNO.