packet.h File Reference

Go to the source code of this file.

Data Structures
struct	packet_header_t
	Fixed prefix shared by every ACIP packet on the wire. More...
struct	size_packet_t
	Terminal size update packet. More...
struct	client_info_packet_t
	Client information packet structure. More...
struct	stream_header_t
	Stream header packet structure. More...
struct	client_list_packet_t
	Snapshot of the clients currently known to the server. More...
struct	server_state_packet_t
	Server state packet structure. More...
struct	error_packet_t
	Error packet structure carrying error code and textual description. More...
struct	remote_log_packet_t
	Remote log packet structure carrying log level and message text. More...
struct	auth_failure_packet_t
	Authentication failure packet structure. More...
struct	protocol_version_packet_t
	Protocol version negotiation packet structure (Packet Type 1). More...
struct	ascii_frame_packet_t
	The wire metadata for one rendered ASCII frame. width and height describe the terminal grid, original_size and compressed_size bound the encoded text, and checksum detects corruption; flags carry frame-specific options. The variable text follows this fixed prefix and is owned by the packet storage until decoding completes. More...
struct	image_frame_packet_t
	Describes one compressed image sent through ACIP. width, height, and pixel_format tell the decoder how to interpret the payload; compressed_size bounds the following bytes, and checksum plus timestamp support validation and frame ordering. The packet header is fixed-size, but the image bytes are variable-length and owned by the packet buffer. More...
struct	audio_batch_packet_t
	The metadata prefix for a batch of encoded audio samples. batch_count, total_samples, sample_rate, and channels let the receiver allocate or route the batch correctly before it touches the encoded payload. The header is serialized with the packet; the audio bytes remain in the enclosing packet buffer. More...
struct	crypto_capabilities_packet_t
	Crypto capabilities packet structure (Packet Type 14). More...
struct	crypto_parameters_packet_t
	Crypto parameters packet structure (Packet Type 15). More...
struct	terminal_capabilities_packet_t
	Terminal capabilities packet structure (Packet Type 5). More...
struct	packet_envelope_t
	Packet envelope containing received packet data. More...

Macros
#define	NETWORK_PACKET_TERM_TYPE_BUFFER_SIZE   32
#define	NETWORK_PACKET_COLORTERM_BUFFER_SIZE   32
#define	NETWORK_PACKET_PALETTE_CUSTOM_BUFFER_SIZE   64
#define	ACIP_OPUS_BATCH_HEADER_SIZE   16
#define	REMOTE_LOG_FLAG_TRUNCATED   0x0001U
	Remote log packet flag definitions.
Network Protocol Constants
Announces the key-exchange, authentication, and cipher algorithms an endpoint is willing to use. The supported-algorithm fields are capability bitmasks or lists, while the preferred values guide selection; the receiver uses this packet to build the later crypto-parameters message rather than keeping it as session state. Fixed prefix shared by every ACIP packet on the wire The first ACIP negotiation packet exchanged by two peers. Its protocol version and revision fields establish wire compatibility, while the encryption, compression, and feature flags tell the receiver which later packet paths are safe to use. It is assembled for transmission and parsed into host-sized values on receipt. Terminal size update packet When code needs to work with server state packet, it keeps connected_client_count, active_client_count here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields. For stream header, this is the live record that ties client_id, stream_type, timestamp together. The owning code creates it, updates it while work is active, and releases its handles and pointed-to storage before freeing the record. The ACIP packet sent when a terminal announces what it can render. capabilities and color_level describe feature support, while width, height, and render_mode let the peer choose a compatible output format. The packed fields are serialized directly; do not treat this as a long-lived heap object.
#define	LARGE_PACKET_THRESHOLD   (100 * 1024)
	Large packet size threshold (100KB).
#define	MAX_PACKET_SIZE   ((size_t)5 * 1024 * 1024)
	Maximum packet size (5MB).
#define	MAX_ERROR_MESSAGE_LENGTH   4096
	Maximum error message length (512 bytes).
#define	MAX_REMOTE_LOG_MESSAGE_LENGTH   512
	Maximum remote log message length (512 bytes).
Timeout Configuration Constants
Timeout constants for handling packets of different sizes. Large packets require extended timeouts for successful transmission.
#define	BASE_SEND_TIMEOUT   (5LL * NS_PER_SEC_INT)
	Base send timeout in nanoseconds (5 seconds).
#define	LARGE_PACKET_EXTRA_TIMEOUT_PER_MB   (800LL * NS_PER_MS_INT)
	Extra timeout per MB for large packets (0.8 seconds per MB).
#define	MIN_CLIENT_TIMEOUT   (10LL * NS_PER_SEC_INT)
	Minimum client timeout in nanoseconds (10 seconds).
#define	MAX_CLIENT_TIMEOUT   (60LL * NS_PER_SEC_INT)
	Maximum client timeout in nanoseconds (60 seconds).
Audio Batching Constants
Audio batching configuration for efficient audio transmission. Batched audio reduces packet overhead and improves bandwidth usage.
#define	AUDIO_BATCH_COUNT   32
	Number of audio chunks per batch (4 chunks).
#define	AUDIO_BATCH_SAMPLES   (AUDIO_SAMPLES_PER_PACKET * AUDIO_BATCH_COUNT)
	Total samples in audio batch (8192 samples).
#define	AUDIO_BATCH_MS   186
	Audio batch duration in milliseconds (~186ms).
#define	AUDIO_SAMPLES_PER_PACKET   256
	Samples per audio packet (256 samples).
Protocol Constants
#define	PACKET_MAGIC   MAGIC_PACKET_VALID
	Packet magic number (alias for MAGIC_PACKET_VALID).
Multi-User Protocol Constants
#define	ASCIICHAT_DEFAULT_DISPLAY_NAME   "AsciiChatter"
	Default display name for clients without a custom name.
Protocol Negotiation Constants
#define	FEATURE_RLE_ENCODING   0x01
	Feature flags for protocol_version_packet_t.
#define	FEATURE_DELTA_FRAMES   0x02
	Delta frame encoding (future).
#define	PROTOCOL_FEATURE_RECOVERABLE_ERRORS   0x04
#define	PROTOCOL_FEATURE_IDENTITY_SET   0x08
Client Capability Flags
Bitmask flags for client capabilities in multi-user protocol.
#define	CLIENT_CAP_VIDEO   0x01
	Client can send/receive video.
#define	CLIENT_CAP_AUDIO   0x02
	Client can send/receive audio.
#define	CLIENT_CAP_COLOR   0x04
	Client supports color rendering.
#define	CLIENT_CAP_STRETCH   0x08
	Client can stretch frames to fill terminal.
Stream Type Flags
Bitmask flags for stream types in multi-user protocol.
#define	STREAM_TYPE_VIDEO   0x01
	Video stream.
#define	STREAM_TYPE_AUDIO   0x02
	Audio stream.
Crypto Algorithm Constants
Algorithm identifiers for key exchange, authentication, and encryption. Used in crypto handshake packet negotiation.
#define	KEX_ALGO_X25519   0x01
	X25519 key exchange (Curve25519).
#define	AUTH_ALGO_ED25519   0x01
	Ed25519 authentication (Edwards-curve signatures).
#define	AUTH_ALGO_NONE   0x00
	No authentication (plaintext mode).
#define	CIPHER_ALGO_XSALSA20_POLY1305   0x01
	XSalsa20-Poly1305 authenticated encryption.
#define	CIPHER_ALGO_NONE   0x00
	No encryption (plaintext mode).
Crypto Mode Bitmasks
2-bit bitmask for encryption and authentication modes These constants define all valid combinations of encryption and authentication in the crypto protocol. The supports_encryption field in protocol_version_packet_t uses these values to negotiate capabilities: Bit 0 (0x01): ACIP_CRYPTO_ENCRYPT - payload encryption enabled Bit 1 (0x02): ACIP_CRYPTO_AUTH - identity authentication enabled
#define	ACIP_CRYPTO_NONE   0x00
	No encryption, no authentication (plaintext only).
#define	ACIP_CRYPTO_ENCRYPT   0x01
	Encryption only (no identity verification).
#define	ACIP_CRYPTO_AUTH   0x02
	Authentication only (no payload encryption).
#define	ACIP_CRYPTO_FULL   0x03
	Full crypto: encryption + authentication.
#define	ACIP_CRYPTO_HAS_ENCRYPT(mode)
	Check if crypto mode includes payload encryption.
#define	ACIP_CRYPTO_HAS_AUTH(mode)
	Check if crypto mode includes authentication.

Enumerations
enum	packet_type_t {   PACKET_TYPE_PROTOCOL_VERSION = 1 , PACKET_TYPE_CRYPTO_CLIENT_HELLO = 1000 , PACKET_TYPE_CRYPTO_CAPABILITIES = 1100 , PACKET_TYPE_CRYPTO_PARAMETERS = 1101 ,   PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT = 1102 , PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP = 1103 , PACKET_TYPE_CRYPTO_AUTH_CHALLENGE = 1104 , PACKET_TYPE_CRYPTO_AUTH_RESPONSE = 1105 ,   PACKET_TYPE_CRYPTO_AUTH_FAILED = 1106 , PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP = 1107 , PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE = 1108 , PACKET_TYPE_CRYPTO_NO_ENCRYPTION = 1109 ,   PACKET_TYPE_QUIC_READY = 1110 , PACKET_TYPE_QUIC_KEYFRAME_REQUEST = 1111 , PACKET_TYPE_CRYPTO_EPOCH_MARKER = 1112 , PACKET_TYPE_CRYPTO_REKEY_NEEDED = 1113 ,   PACKET_TYPE_CRYPTO_EPOCH_ACK = 1114 , PACKET_TYPE_ENCRYPTED = 1200 , PACKET_TYPE_CRYPTO_REKEY_REQUEST = 1201 , PACKET_TYPE_CRYPTO_REKEY_RESPONSE = 1202 ,   PACKET_TYPE_CRYPTO_REKEY_COMPLETE = 1203 , PACKET_TYPE_SIZE_MESSAGE = 2000 , PACKET_TYPE_AUDIO_MESSAGE = 2001 , PACKET_TYPE_TEXT_MESSAGE = 2002 ,   PACKET_TYPE_ERROR_MESSAGE = 2003 , PACKET_TYPE_REMOTE_LOG = 2004 , PACKET_TYPE_ASCII_FRAME = 3000 , PACKET_TYPE_IMAGE_FRAME = 3001 ,   PACKET_TYPE_IMAGE_FRAME_H265 = 3002 , PACKET_TYPE_IMAGE_FRAME_H264 = 3003 , PACKET_TYPE_AUDIO_BATCH = 4000 , PACKET_TYPE_AUDIO_OPUS_BATCH = 4001 ,   PACKET_TYPE_CLIENT_CAPABILITIES = 5000 , PACKET_TYPE_PING = 5001 , PACKET_TYPE_PONG = 5002 , PACKET_TYPE_CLIENT_JOIN = 5003 ,   PACKET_TYPE_CLIENT_LEAVE = 5004 , PACKET_TYPE_STREAM_START = 5005 , PACKET_TYPE_STREAM_STOP = 5006 , PACKET_TYPE_CLEAR_CONSOLE = 5007 ,   PACKET_TYPE_SERVER_STATE = 5008 , PACKET_TYPE_ACIP_SESSION_CREATE = 6000 , PACKET_TYPE_ACIP_SESSION_CREATED = 6001 , PACKET_TYPE_ACIP_SESSION_LOOKUP = 6002 ,   PACKET_TYPE_ACIP_SESSION_INFO = 6003 , PACKET_TYPE_ACIP_SESSION_JOIN = 6004 , PACKET_TYPE_ACIP_SESSION_JOINED = 6005 , PACKET_TYPE_ACIP_SESSION_LEAVE = 6006 ,   PACKET_TYPE_ACIP_SESSION_END = 6007 , PACKET_TYPE_ACIP_SESSION_RECONNECT = 6008 , PACKET_TYPE_ACIP_WEBRTC_SDP = 6009 , PACKET_TYPE_ACIP_WEBRTC_ICE = 6010 ,   PACKET_TYPE_ACIP_STRING_RESERVE = 6020 , PACKET_TYPE_ACIP_STRING_RESERVED = 6021 , PACKET_TYPE_ACIP_STRING_RENEW = 6022 , PACKET_TYPE_ACIP_STRING_RELEASE = 6023 ,   PACKET_TYPE_ACIP_PARTICIPANT_LIST = 6050 , PACKET_TYPE_ACIP_RING_COLLECT = 6051 , PACKET_TYPE_ACIP_NETWORK_QUALITY = 6060 , PACKET_TYPE_ACIP_HOST_ANNOUNCEMENT = 6061 ,   PACKET_TYPE_ACIP_HOST_DESIGNATED = 6062 , PACKET_TYPE_ACIP_SETTINGS_SYNC = 6063 , PACKET_TYPE_ACIP_SETTINGS_ACK = 6064 , PACKET_TYPE_ACIP_HOST_LOST = 6065 ,   PACKET_TYPE_ACIP_FUTURE_HOST_ELECTED = 6066 , PACKET_TYPE_ACIP_PARTICIPANT_JOINED = 6067 , PACKET_TYPE_ACIP_PARTICIPANT_LEFT = 6068 , PACKET_TYPE_ACIP_BANDWIDTH_TEST = 6070 ,   PACKET_TYPE_ACIP_BANDWIDTH_RESULT = 6071 , PACKET_TYPE_ACIP_BROADCAST_ACK = 6075 , PACKET_TYPE_RING_MEMBERS = 6100 , PACKET_TYPE_STATS_COLLECTION_START = 6101 ,   PACKET_TYPE_STATS_UPDATE = 6102 , PACKET_TYPE_RING_ELECTION_RESULT = 6103 , PACKET_TYPE_STATS_ACK = 6104 , PACKET_TYPE_ACIP_DISCOVERY_PING = 6190 ,   PACKET_TYPE_ACIP_ERROR = 6199 }
	Network protocol packet type enumeration. More...
enum	auth_failure_reason_t {   AUTH_FAIL_PASSWORD_REQUIRED = 0x01 , AUTH_FAIL_PASSWORD_INCORRECT = 0x02 , AUTH_FAIL_CLIENT_KEY_REQUIRED = 0x04 , AUTH_FAIL_CLIENT_KEY_REJECTED = 0x08 ,   AUTH_FAIL_SIGNATURE_INVALID = 0x10 }
	Authentication failure reason flags. More...
enum	packet_recv_result_t { PACKET_RECV_SUCCESS = 0 , PACKET_RECV_EOF = -1 , PACKET_RECV_ERROR = -2 , PACKET_RECV_SECURITY_VIOLATION = -3 }
	packet envelope is intentionally a small, concrete record. Fields such as type, data, len, was_encrypted give callers the identity and current value they need. It is normally borrowed from, or owned by, the surrounding subsystem—not independently managed. More...

Functions
asciichat_error_t	packet_header_build (packet_header_t *header, packet_type_t type, const socket_buffer_t *payload, size_t count, uint32_t client_id)
asciichat_error_t	packet_encode (packet_type_t type, const void *payload, size_t length, uint32_t client_id, void *output, size_t capacity, size_t *written)
asciichat_error_t	packet_validate (const void *packet, size_t length, size_t limit, packet_header_t *header)
void	protocol_version_packet_init (protocol_version_packet_t *version, uint8_t supports_encryption)
	Initialize a protocol version packet with the current wire version.
uint64_t	packet_send_timeout_ns (size_t packet_size)
Basic Packet I/O Functions
asciichat_error_t	packet_send (socket_t sockfd, packet_type_t type, const void *data, size_t len)
	Send a packet with header and CRC32 checksum.
asciichat_error_t	packet_receive (socket_t sockfd, packet_type_t *type, void **data, size_t *len)
	Receive a packet with header validation and CRC32 checking.
Secure Packet I/O Functions
asciichat_error_t	send_packet_secure (socket_t sockfd, packet_type_t type, const void *data, size_t len, crypto_context_t *crypto_ctx)
	Send a packet with encryption and compression support.
packet_recv_result_t	receive_packet_secure (socket_t sockfd, void *crypto_ctx, bool enforce_encryption, packet_envelope_t *envelope)
	Receive a packet with decryption and decompression support.
packet_recv_result_t	receive_packet_secure_with_timeout (socket_t sockfd, void *crypto_ctx, bool enforce_encryption, packet_envelope_t *envelope, uint64_t timeout_ns)
asciichat_error_t	packet_decrypt_envelope (packet_envelope_t *envelope, void *crypto_ctx)
	Decrypt a PACKET_TYPE_ENCRYPTED envelope and extract inner packet.
Legacy Packet I/O Functions
These functions provide basic packet I/O without encryption support. Use send_packet_secure() and receive_packet_secure() for encryption support.
int	send_packet (socket_t sockfd, packet_type_t type, const void *data, size_t len)
	Send a basic packet without encryption.
int	receive_packet (socket_t sockfd, packet_type_t *type, void **data, size_t *len)
	Receive a basic packet without encryption.
Protocol Packet Functions
Convenience functions for sending specific protocol packets. These functions construct the appropriate packet structure and send it over the socket.
int	send_ping_packet (socket_t sockfd)
	Send a ping packet (keepalive).
int	send_pong_packet (socket_t sockfd)
	Send a pong packet (keepalive response).
asciichat_error_t	packet_send_error (socket_t sockfd, const crypto_context_t *crypto_ctx, asciichat_error_t error_code, const char *message)
	Send an error packet with optional encryption context.
size_t	packet_format_error_stack (char *buffer, size_t size)
	Format the current thread's error stack for transport to a peer.
asciichat_error_t	packet_parse_error_message (const void *data, size_t len, asciichat_error_t *out_error_code, char *message_buffer, size_t message_buffer_size, size_t *out_message_length)
	Parse an error packet payload into components.
asciichat_error_t	packet_send_remote_log (socket_t sockfd, const crypto_context_t *crypto_ctx, log_level_t level, remote_log_direction_t direction, uint16_t flags, const char *message)
	Send a remote log packet with optional encryption context.
asciichat_error_t	packet_parse_remote_log (const void *data, size_t len, log_level_t *out_level, remote_log_direction_t *out_direction, uint16_t *out_flags, char *message_buffer, size_t message_buffer_size, size_t *out_message_length)
	Parse a remote log packet payload into components.
int	send_protocol_version_packet (socket_t sockfd, const protocol_version_packet_t *version)
	Send protocol version negotiation packet.
int	send_crypto_capabilities_packet (socket_t sockfd, const crypto_capabilities_packet_t *caps)
	Send crypto capabilities packet.
int	send_crypto_parameters_packet (socket_t sockfd, const crypto_parameters_packet_t *params)
	Send crypto parameters packet.
asciichat_error_t	av_send_audio_opus_batch (socket_t sockfd, const uint8_t *opus_data, size_t opus_size, const uint16_t *frame_sizes, int sample_rate, int frame_duration, int frame_count, crypto_context_t *crypto_ctx)
	Send Opus-encoded audio batch packet with encryption support.
asciichat_error_t	send_image_frame_packet (socket_t sockfd, const void *image_data, uint16_t width, uint16_t height, uint8_t format)
	Send image frame packet.

Function Documentation

packet_send_timeout_ns()

uint64_t packet_send_timeout_ns

(

size_t

packet_size

)

Shared size-adjusted packet I/O budget, in nanoseconds.

Calculate timeout based on packet size Large packets need more time to transmit reliably

Note

Returns timeout in nanoseconds for use with send/recv APIs

Definition at line 117 of file packet.c.

                                                    {
  uint64_t base_timeout = SEND_TIMEOUT * NS_PER_SEC_INT;
 
  // For large packets, increase timeout proportionally
  if (packet_size > LARGE_PACKET_THRESHOLD) {
    // Add extra timeout per MB above the threshold
    uint64_t extra_timeout =
        (uint64_t)(((double)packet_size - LARGE_PACKET_THRESHOLD) / 1000000.0 * LARGE_PACKET_EXTRA_TIMEOUT_PER_MB) +
        NS_PER_MS_INT;
    uint64_t total_timeout = base_timeout + extra_timeout;
 
    // Ensure client timeout is longer than server's RECV_TIMEOUT (30s) to prevent deadlock
    // Add 10 seconds buffer to account for server processing delays
    if (total_timeout < MIN_CLIENT_TIMEOUT) {
      total_timeout = MIN_CLIENT_TIMEOUT;
    }
 
    // Cap at maximum timeout
    return (total_timeout > MAX_CLIENT_TIMEOUT) ? MAX_CLIENT_TIMEOUT : total_timeout;
  }
 
  return base_timeout;
}

References LARGE_PACKET_EXTRA_TIMEOUT_PER_MB, LARGE_PACKET_THRESHOLD, MAX_CLIENT_TIMEOUT, MIN_CLIENT_TIMEOUT, NS_PER_MS_INT, NS_PER_SEC_INT, and SEND_TIMEOUT.

Referenced by packet_receive(), packet_send(), receive_packet_secure_with_timeout(), and send_packet_secure().