server.h File Reference

ACIP server-side protocol API. More...

Go to the source code of this file.

Data Structures
struct	acip_frame_workspace_t
	Send ASCII frame to client (server → client). More...

Functions
asciichat_error_t	acip_server_receive_and_dispatch (acip_transport_t *transport, void *client_ctx, const acip_server_callbacks_t *callbacks)
	Receive packet from client and dispatch to callbacks.
void	acip_frame_workspace_destroy (acip_frame_workspace_t *workspace)
asciichat_error_t	acip_send_ascii_frame (acip_transport_t *transport, acip_frame_workspace_t *workspace, const char *frame_data, size_t frame_size, uint32_t width, uint32_t height, const char *client_id)
asciichat_error_t	acip_send_ascii_frame_contract (acip_transport_t *transport, acip_frame_workspace_t *workspace, const char *text, size_t length, uint32_t width, uint32_t height, const acip_render_settings_t *settings, uint32_t effects, const char *client_id)
asciichat_error_t	acip_send_clear_console (acip_transport_t *transport)
	Send clear console command to client (server → client).
asciichat_error_t	acip_send_server_state (acip_transport_t *transport, const server_state_packet_t *state)
	Send server state update to client (server → client).

Detailed Description

ACIP server-side protocol API.

Server-side API for ascii-chat protocol. Provides functions for:

• Receiving and dispatching packets from clients
• Sending ASCII frames to clients
• Sending server state updates
• Sending console control commands

Author

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

Date

January 2026

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

Function Documentation

acip_frame_workspace_destroy()

void acip_frame_workspace_destroy

(

acip_frame_workspace_t *

workspace

)

Definition at line 161 of file lib/network/acip/server.c.

                                                                     {
  if (!workspace)
    return;
  compression_workspace_destroy(&workspace->compression);
}

References acip_frame_workspace_t::compression, and compression_workspace_destroy().

Referenced by client_video_render_thread(), session_host_create(), and session_host_destroy().

acip_send_ascii_frame()

asciichat_error_t acip_send_ascii_frame	(	acip_transport_t *	transport,
		acip_frame_workspace_t *	workspace,
		const char *	frame_data,
		size_t	frame_size,
		uint32_t	width,
		uint32_t	height,
		const char *	client_id )

Definition at line 155 of file lib/network/acip/server.c.

                                                               {
  return acip_send_ascii_frame_contract(transport, workspace, text, length, width, height, NULL, 0, client_id);
}

References acip_send_ascii_frame_contract(), height, and width.

Referenced by session_host_broadcast_frame(), and session_host_send_frame().

acip_send_ascii_frame_contract()

asciichat_error_t acip_send_ascii_frame_contract	(	acip_transport_t *	transport,
		acip_frame_workspace_t *	workspace,
		const char *	text,
		size_t	length,
		uint32_t	width,
		uint32_t	height,
		const acip_render_settings_t *	settings,
		uint32_t	effects,
		const char *	client_id )

Definition at line 93 of file lib/network/acip/server.c.

                                                                                          {
  ASCII_OTEL_SCOPE(ACIP_SEND_ASCII_FRAME_CONTRACT);
  if (!transport || !frame_data || !workspace) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or frame_data");
  }
 
  if (frame_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Empty frame data");
  }
 
  if (frame_size > UINT32_MAX) {
    return SET_ERRNO(ERROR_NETWORK_SIZE, "ASCII frame is too large: %zu bytes", frame_size);
  }
 
  log_dev("SEND_ASCII_FRAME: client_id=%s, width=%u, height=%u, frame_size=%zu bytes", client_id, width, height,
          frame_size);
 
  // Calculate CRC32 checksum of frame data for integrity verification
  uint32_t checksum_value = asciichat_crc32(frame_data, frame_size);
  log_debug("★ SEND_ASCII_FRAME: CRC32 checksum calculated: 0x%08x for %zu bytes", checksum_value, frame_size);
 
  // Compress ANSI text before sending it. Native and browser clients decode zstd frames.
  const void *payload_data = frame_data;
  size_t payload_size = frame_size;
  bool is_compressed = false;
  if (frame_size >= COMPRESSION_MIN_SIZE &&
      compress_workspace(&workspace->compression, frame_data, frame_size, 1) == ASCIICHAT_OK &&
      should_compress(frame_size, workspace->compression.output.length)) {
    payload_data = workspace->compression.output.data;
    payload_size = workspace->compression.output.length;
    is_compressed = true;
  }
 
  // Create ASCII frame packet header
  ascii_frame_packet_t header;
  header.width = HOST_TO_NET_U32(width);
  header.height = HOST_TO_NET_U32(height);
  header.original_size = HOST_TO_NET_U32((uint32_t)frame_size);
  header.compressed_size = HOST_TO_NET_U32(is_compressed ? (uint32_t)payload_size : 0);
  header.checksum = HOST_TO_NET_U32(checksum_value);
  uint8_t contract[FRAME_RENDER_CONTRACT_MAX];
  size_t contract_length = 0;
  if (settings) {
    asciichat_error_t encoded = frame_render_contract_encode(settings, effects, contract, &contract_length);
    if (encoded != ASCIICHAT_OK)
      return encoded;
  }
  header.flags =
      HOST_TO_NET_U32((is_compressed ? FRAME_FLAG_IS_COMPRESSED : 0) | (settings ? FRAME_FLAG_RENDER_CONTRACT : 0));
 
  socket_buffer_t slices[3] = {{&header, sizeof(header)}};
  size_t count = 1;
  if (contract_length)
    slices[count++] = (socket_buffer_t){contract, contract_length};
  slices[count++] = (socket_buffer_t){payload_data, payload_size};
  asciichat_error_t result = packet_send_via_transportv(transport, PACKET_TYPE_ASCII_FRAME, slices, count, 0);
  return result;
}

References ASCII_OTEL_SCOPE, asciichat_crc32, ASCIICHAT_OK, compress_workspace(), acip_frame_workspace_t::compression, COMPRESSION_MIN_SIZE, buffer_workspace_t::data, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, FRAME_FLAG_IS_COMPRESSED, FRAME_FLAG_RENDER_CONTRACT, frame_render_contract_encode(), FRAME_RENDER_CONTRACT_MAX, height, HOST_TO_NET_U32, buffer_workspace_t::length, log_debug, log_dev, compression_workspace_t::output, packet_send_via_transportv(), PACKET_TYPE_ASCII_FRAME, SET_ERRNO, should_compress(), ascii_frame_packet_t::width, and width.

Referenced by acip_send_ascii_frame(), and server_send_video().

acip_send_clear_console()

asciichat_error_t acip_send_clear_console

(

acip_transport_t *

transport

)

Send clear console command to client (server → client).

Instructs client to clear the terminal/console.

Parameters

transport

Transport instance

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 167 of file lib/network/acip/server.c.

                                                                       {
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport");
  }
 
  return packet_send_via_transport(transport, PACKET_TYPE_CLEAR_CONSOLE, NULL, 0, 0);
}

References ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_CLEAR_CONSOLE, and SET_ERRNO.

Referenced by server_send_video().

acip_send_server_state()

asciichat_error_t acip_send_server_state	(	acip_transport_t *	transport,
		const server_state_packet_t *	state )

Send server state update to client (server → client).

Notifies client of server state changes (client count, grid layout, etc.)

Parameters

transport	Transport instance
state	Server state structure

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 175 of file lib/network/acip/server.c.

                                                                                                          {
  ASCII_OTEL_SCOPE(ACIP_SEND_SERVER_STATE);
  if (!transport || !state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport or state");
  }
 
  return packet_send_via_transport(transport, PACKET_TYPE_SERVER_STATE, state, sizeof(*state), 0);
}

References ASCII_OTEL_SCOPE, ERROR_INVALID_PARAM, packet_send_via_transport(), PACKET_TYPE_SERVER_STATE, and SET_ERRNO.

Referenced by send_server_state_to_client(), server_send_state(), and session_host_set_client_transport().

acip_server_receive_and_dispatch()

asciichat_error_t acip_server_receive_and_dispatch	(	acip_transport_t *	transport,
		void *	client_ctx,
		const acip_server_callbacks_t *	callbacks )

Receive packet from client and dispatch to callbacks.

High-level receive function for server side. Receives a single packet from the transport, handles decryption, and dispatches to appropriate callback handler.

Parameters

transport	Transport instance
client_ctx	Client context pointer (passed to callbacks)
callbacks	Callback structure for handling received packets

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 33 of file lib/network/acip/server.c.

                                                                                             {
  ASCII_OTEL_SCOPE(ACIP_SERVER_RECEIVE_AND_DISPATCH);
  uint64_t dispatch_start_ns = time_get_ns();
  log_dev_every(4500 * US_PER_MS_INT,
                "ACIP_SERVER_DISPATCH: Entry, transport=%p, client_ctx=%p, callbacks=%p, timestamp=%llu",
                (void *)transport, client_ctx, (const void *)callbacks, (unsigned long long)dispatch_start_ns);
 
  if (!transport) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport (NULL)");
  }
  if (!callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid callbacks (NULL)");
  }
 
  // Check if transport is connected
  if (!transport->methods->is_connected(transport)) {
    return SET_ERRNO(ERROR_NETWORK, "Transport not connected");
  }
 
  packet_envelope_t envelope = {0};
  asciichat_error_t received = packet_receive_via_transport(transport, &envelope.type, &envelope.data, &envelope.len,
                                                            &envelope.allocated_buffer);
  if (received != ASCIICHAT_OK)
    return received;
 
  // Dispatch packet to appropriate ACIP handler
  // Server receives packets FROM clients, so use server packet handler
  log_info("ACIP_DISPATCH_PKT: type=%d, len=%zu, client_ctx=%p", envelope.type, envelope.len, client_ctx);
  log_info("📤 [FRAME_DISPATCH] Starting handler dispatch for packet type=%d (0x%04x), payload=%zu bytes",
           envelope.type, envelope.type, envelope.len);
  uint64_t dispatch_handler_start_ns = time_get_ns();
  asciichat_error_t dispatch_result =
      acip_handle_server_packet(transport, envelope.type, envelope.data, envelope.len, client_ctx, callbacks);
  uint64_t dispatch_handler_end_ns = time_get_ns();
  char handler_duration_str[TIME_DURATION_BUFFER_SIZE];
  time_pretty((uint64_t)(dispatch_handler_end_ns - dispatch_handler_start_ns), -1, handler_duration_str,
              sizeof(handler_duration_str));
  log_info("[WS_TIMING] Handler for type=%d took %s (result=%d)", envelope.type, handler_duration_str, dispatch_result);
 
  if (dispatch_result != ASCIICHAT_OK) {
    log_error("❌ [FRAME_DISPATCH_FAILED] Handler returned error for type=%d: %s", envelope.type,
              asciichat_error_format(NULL, dispatch_result));
  } else {
    log_info("✅ [FRAME_DISPATCH_SUCCESS] Handler completed successfully for type=%d", envelope.type);
  }
 
  // Always free the allocated buffer (even if handler failed)
  if (envelope.allocated_buffer) {
    buffer_release(envelope.allocated_buffer);
  }
 
  // Return handler result
  return dispatch_result;
}

References acip_handle_server_packet(), ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, buffer_release, ERROR_INVALID_PARAM, ERROR_NETWORK, acip_transport_methods_t::is_connected, log_dev_every, log_error, log_info, acip_transport::methods, packet_receive_via_transport(), SET_ERRNO, TIME_DURATION_BUFFER_SIZE, time_pretty(), and US_PER_MS_INT.