Network Module

🌐 Core network I/O operations with timeout support More...

Files
file	frame_validator.c
	Frame validation implementation for IMAGE_FRAME packets.
file	client.c
	🌐 HTTPS client with BearSSL for fetching public keys from GitHub/GitLab with CA validation
file	network.c
	🌐 Cross-platform socket I/O with timeout management and connection handling
file	callback_timing.c
	WebSocket callback timing instrumentation implementation.
file	server.c
	WebSocket server implementation.
file	protocol.h
	Server packet processing and protocol implementation.
file	protocol.h
	ascii-chat Binary Network Protocol (complete system including ACIP discovery service)
file	dns.h
	🌐 DNS resolution utilities
file	frame_validator.h
	Frame validation utilities for IMAGE_FRAME packets.
file	client.h
	Simple HTTPS client for fetching public keys from GitHub/GitLab.
file	network.h
	🌐 Core network I/O operations with timeout support
file	parallel_connect.h
	Parallel IPv4/IPv6 connection with race-to-connect semantics.
file	tailscale.h
	Tailscale host identity helpers.
file	update_checker.h
	🔄 Update checker for GitHub releases with DNS connectivity test and cache
file	callback_timing.h
	WebSocket callback timing instrumentation.
file	internal.h
	Internal WebSocket implementation types shared between transport.c and server.c.
file	server.h
	WebSocket server for accepting browser client connections.

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...
struct	update_check_result_t
	update check result keeps the values that move through the subsystem: update_available, last_check_time, dismissed_until, check_succeeded. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself. 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.
#define	NETWORK_UPDATE_CHECKER_LATEST_VERSION_BUFFER_SIZE   64
#define	NETWORK_UPDATE_CHECKER_LATEST_SHA_BUFFER_SIZE   41
#define	NETWORK_UPDATE_CHECKER_CURRENT_VERSION_BUFFER_SIZE   64
#define	NETWORK_UPDATE_CHECKER_CURRENT_SHA_BUFFER_SIZE   41
#define	NETWORK_UPDATE_CHECKER_RELEASE_URL_BUFFER_SIZE   512

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...
enum	install_method_t {   INSTALL_METHOD_HOMEBREW , INSTALL_METHOD_SCOOP , INSTALL_METHOD_ARCH_AUR , INSTALL_METHOD_INSTALLER ,   INSTALL_METHOD_GITHUB , INSTALL_METHOD_UNKNOWN }
	Installation method for suggesting upgrade command. More...

Functions
bool	dns_test_connectivity (const char *hostname)
	Test DNS connectivity by resolving a hostname.
asciichat_error_t	frame_validate_legacy (size_t len, size_t expected_rgb_size)
	Validate legacy frame format.
asciichat_error_t	frame_validate_new (void *data, size_t len, bool *out_compressed, uint32_t *out_data_size)
	Validate new frame format with optional compression.
asciichat_error_t	frame_check_size_overflow (size_t header_size, size_t data_size)
	Check for overflow when adding header to data.
void	frame_extract_dimensions (const void *data, uint32_t *width, uint32_t *height)
	Extract width and height from frame header.
void	frame_extract_new_header (const void *data, uint32_t *compressed, uint32_t *data_size)
	Extract compressed flag and data size from new format header.
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.
asciichat_error_t	update_check_perform (update_check_result_t *result)
	Check for updates from GitHub releases API.
asciichat_error_t	update_check_load_cache (update_check_result_t *result)
	Load cached update check result.
asciichat_error_t	update_check_save_cache (const update_check_result_t *result)
	Save update check result to cache.
void	update_check_dismiss_for_a_week (update_check_result_t *result)
bool	update_check_is_dismissed (const update_check_result_t *result)
bool	update_check_is_cache_fresh (const update_check_result_t *result)
	Check if cache is fresh (< 7 days old).
bool	update_check_try_fresh_cache (update_check_result_t *result)
install_method_t	update_check_detect_install_method (void)
	Detect installation method.
void	update_check_get_upgrade_suggestion (install_method_t method, const char *latest_version, char *buffer, size_t buffer_size)
	Get upgrade suggestion string.
const char *	update_check_get_aur_helper (void)
void	update_check_format_notification (const update_check_result_t *result, char *buffer, size_t buffer_size)
	Format update notification message.
asciichat_error_t	update_check_startup (update_check_result_t *result)
	Perform startup update check with caching.

HTTPS Client
char *	https_get (const char *hostname, const char *path)
	Perform HTTPS GET request.

Socket I/O Operations
ssize_t	send_with_timeout (socket_t sockfd, const void *data, size_t len, uint64_t timeout_ns)
	Send data with timeout using chunked transmission.
ssize_t	recv_with_timeout (socket_t sockfd, void *buf, size_t len, uint64_t timeout_ns)
	Receive data with timeout.
int	accept_with_timeout (socket_t listenfd, struct sockaddr *addr, socklen_t *addrlen, uint64_t timeout_ns)
	Accept connection with timeout.
bool	connect_with_timeout (socket_t sockfd, const struct sockaddr *addr, socklen_t addrlen, int timeout_seconds)
	Connect to server with timeout.

Socket Configuration Functions
asciichat_error_t	set_socket_timeout (socket_t sockfd, uint64_t timeout_ns)
	Set socket timeout for send/receive operations.
asciichat_error_t	set_socket_keepalive (socket_t sockfd)
	Enable TCP keepalive on socket.
asciichat_error_t	set_socket_nonblocking (socket_t sockfd)
	Set socket to non-blocking mode.
asciichat_error_t	socket_configure_buffers (socket_t sockfd)
	Configure socket buffers and TCP_NODELAY for optimal performance.

Error Reporting Functions
const char *	network_error_string ()
	Get human-readable error string for network errors.

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.
asciichat_error_t	packet_decrypt_envelope (packet_envelope_t *envelope, void *crypto_ctx)
	Decrypt a PACKET_TYPE_ENCRYPTED envelope and extract inner packet.
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)

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).
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.
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.

Network Timeout Constants
Timeout values tuned for real-time video streaming. All timeouts are specified in seconds.
#define	CONNECT_TIMEOUT   3
	Connection timeout in seconds (3 seconds).
#define	SEND_TIMEOUT   1
	Send timeout in seconds (5 seconds).
#define	RECV_TIMEOUT   1
	Receive timeout in seconds (1 second).
#define	ACCEPT_TIMEOUT   1
	Accept timeout in seconds (1 second).

Test Environment Detection
#define	network_is_test_environment()
	Check if we're in a test environment.

Socket Keepalive Settings
Keepalive settings to detect dead connections. TCP keepalive probes are sent when connection is idle to detect broken connections.
#define	KEEPALIVE_IDLE   60
	Keepalive idle time in seconds (60 seconds).
#define	KEEPALIVE_INTERVAL   10
	Keepalive interval in seconds (10 seconds).
#define	KEEPALIVE_COUNT   8
	Keepalive probe count (8 probes).

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.

Detailed Description

🌐 Core network I/O operations with timeout support

Provides DNS resolution and connectivity testing utilities.

Author

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

Date

February 2026

This module provides basic HTTPS GET functionality using BearSSL for TLS. It's designed specifically for fetching SSH/GPG public keys from GitHub and GitLab.

Note

TLS library: Uses BearSSL for TLS connections. BearSSL is a minimal TLS implementation with system CA certificate support.

Security: Uses system CA certificates for trust validation (20-year longevity). Validates server certificates against system trust store.

Key fetching: Fetches keys from GitHub/GitLab endpoints:

• GitHub SSH keys: https://github.com/username.keys
• GitHub GPG keys: https://github.com/username.gpg
• GitLab SSH keys: https://gitlab.com/username.keys
• GitLab GPG keys: https://gitlab.com/username.gpg

Key fetching functions: fetch_github_ssh_keys, fetch_gitlab_ssh_keys, fetch_github_gpg_keys, and fetch_gitlab_gpg_keys are in crypto/keys/https_keys.h. They properly belong in the keys module.

Author

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

Date

October 2025

This module provides fundamental network I/O operations including socket management, timeout handling, and basic send/receive operations. All operations support configurable timeouts to prevent indefinite blocking, critical for real-time video streaming applications.

CORE RESPONSIBILITIES:

1. Socket I/O operations with timeout support
2. Connection management (connect, accept) with timeouts
3. Socket configuration (keepalive, non-blocking, timeouts)
4. Chunked transmission for large data transfers
5. Error reporting and diagnostics

ARCHITECTURAL OVERVIEW:

TIMEOUT SYSTEM:

• All I/O operations support configurable timeouts
• Timeouts are tuned for real-time video streaming requirements
• Chunked transmission prevents large data from blocking indefinitely
• Platform-specific timeout implementation (select/poll/epoll)

SOCKET CONFIGURATION:

• Keepalive settings to detect dead connections
• Non-blocking mode support for asynchronous I/O
• Socket-level timeout configuration
• Platform abstraction for cross-platform compatibility

ERROR HANDLING:

• Comprehensive error reporting with human-readable messages
• Platform-specific error code translation
• Network error string utilities

INTEGRATION WITH OTHER MODULES:

• platform/socket.h: Uses platform socket abstraction
• Used by packet.h for packet transmission
• Used by av.h for media packet sending
• Used by handshake.c for crypto handshake operations

PERFORMANCE CHARACTERISTICS:

• Chunked transmission enables progressive sending of large frames
• Timeout handling prevents indefinite blocking
• Keepalive settings detect dead connections efficiently
• Platform-specific optimizations where available

Note

Timeout values are tuned for real-time video streaming. Adjust CONNECT_TIMEOUT, SEND_TIMEOUT, and RECV_TIMEOUT if needed for different network conditions.

Chunked transmission is used automatically for large data to prevent timeouts and enable progress tracking.

Warning

Timeout values that are too short may cause false positives on slow networks. Values that are too long may delay error detection unnecessarily.

Author

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

Date

September 2025

Version

2.0 (Post-Modularization)

This module provides comprehensive packet protocol implementation including packet verification, CRC validation, protocol compliance checking, encryption support, and compression integration. It serves as the core network protocol layer for ascii-chat's communication system.

CORE RESPONSIBILITIES:

1. Packet header validation and CRC32 checksum verification
2. Secure packet transmission with encryption support
3. Secure packet reception with decryption and validation
4. Protocol compliance checking and error handling
5. Integration with cryptographic and compression subsystems

ARCHITECTURAL OVERVIEW:

PACKET STRUCTURE:

• Header: Magic number, type, length, CRC32, client ID
• Payload: Variable-length data (may be encrypted/compressed)
• Validation: CRC32 checksum for integrity verification

ENCRYPTION INTEGRATION:

• Automatic encryption/decryption when crypto context provided
• Handshake packets always sent unencrypted (plaintext)
• Session packets encrypted after handshake completion
• Encryption policy enforcement (require/optional encryption)

COMPRESSION INTEGRATION:

• Automatic compression for large packets (frames, audio)
• Compression threshold-based decision making
• Decompression on receive path

PROTOCOL VALIDATION:

• Magic number validation to detect corruption
• CRC32 checksum verification for integrity
• Packet size validation to prevent attacks
• Type validation for protocol compliance

INTEGRATION WITH OTHER MODULES:

• crypto/crypto.h: Encryption/decryption operations
• compression.h: Compression/decompression support
• network/network.h: Socket I/O operations

PERFORMANCE CHARACTERISTICS:

• Zero-copy operation when possible
• Automatic memory management for packet buffers
• Efficient CRC32 validation (hardware-accelerated when available)
• Compression reduces bandwidth for large frames

Note

All packet functions handle encryption automatically when crypto context is provided. Plaintext packets are used for handshake.

Compression is automatically applied to large packets (frames, audio batches) based on size thresholds.

Warning

Packet buffers are allocated by receive functions and must be freed by caller using the allocated_buffer pointer.

Author

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

Date

September 2025

Version

2.0 (Post-Modularization)

Provides automatic and manual update checking against GitHub releases API.

• Checks once per week automatically at startup
• Manual check via –check-update flag
• DNS connectivity test before attempting HTTP request
• Compares semantic versions to detect updates
• Caches results in ~/.config/ascii-chat/last_update_check
• Detects installation method (Homebrew, Arch AUR, GitHub)

Author

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

Date

February 2026

Packet Queues

Queues own their nodes and payload references. Use packet_queue_push_copy() for a borrowed view, packet_queue_push_take() to move a buffer without copying, or packet_queue_push_shared() for immutable fan-out. Successful take clears the caller pointer; rejection preserves it. All operations return contextual asciichat_error_t errors.

Every queue has both a packet-count limit and a byte limit. The default overflow policy rejects new packets. DROP_OLDEST must be explicitly selected for independently discardable media such as raw frames or audio blocks. Do not select it for dependency-bearing encoded video without recovery logic.

One queue mutex protects admission, list mutation, accounting and reclamation. Nodes use the shared buffer API; there is no independent node allocator. Dequeue transfers the existing node without another allocation. Release with packet_queue_free_packet(). Dequeued packets can outlive their queue.

Stop rejects new admissions and hides queued data from consumers. Clear and destroy still drain stopped queues. Join queue users before destruction. Queued storage is released automatically; already dequeued packets remain owned by their consumers.

Macro Definition Documentation

ACCEPT_TIMEOUT

#define ACCEPT_TIMEOUT   1

#include <include/ascii-chat/network/network.h>

Accept timeout in seconds (1 second).

Maximum time to wait for incoming connections. Balanced between responsiveness and CPU usage. Status screen updates independently in its own thread at target FPS.

Definition at line 142 of file network/network.h.

ACIP_CRYPTO_AUTH

#define ACIP_CRYPTO_AUTH   0x02

#include <include/ascii-chat/network/packet/packet.h>

Authentication only (no payload encryption).

Definition at line 1140 of file packet.h.

Referenced by crypto_policy_resolve(), and network_connection_establish().

ACIP_CRYPTO_ENCRYPT

#define ACIP_CRYPTO_ENCRYPT   0x01

#include <include/ascii-chat/network/packet/packet.h>

Encryption only (no identity verification).

Definition at line 1139 of file packet.h.

Referenced by client_connection_create(), and crypto_policy_resolve().

ACIP_CRYPTO_FULL

#define ACIP_CRYPTO_FULL   0x03

#include <include/ascii-chat/network/packet/packet.h>

Full crypto: encryption + authentication.

Definition at line 1141 of file packet.h.

Referenced by acip_security_receive(), acip_security_start(), crypto_policy_check_mode(), and network_client_negotiate().

ACIP_CRYPTO_HAS_AUTH

#define ACIP_CRYPTO_HAS_AUTH

(

mode

)

#include <include/ascii-chat/network/packet/packet.h>

Value:

(((mode) & ACIP_CRYPTO_AUTH) != 0)

Check if crypto mode includes authentication.

Parameters

mode	Crypto mode bitmask (ACIP_CRYPTO_*)

Returns

true if authentication is enabled, false otherwise

Definition at line 1155 of file packet.h.

Referenced by acip_security_receive(), client_handshake_receive(), crypto_policy_check_mode(), and peer_crypto_receive().

ACIP_CRYPTO_HAS_ENCRYPT

#define ACIP_CRYPTO_HAS_ENCRYPT

(

mode

)

#include <include/ascii-chat/network/packet/packet.h>

Value:

(((mode) & ACIP_CRYPTO_ENCRYPT) != 0)

Check if crypto mode includes payload encryption.

Parameters

mode	Crypto mode bitmask (ACIP_CRYPTO_*)

Returns

true if payload encryption is enabled, false otherwise

Definition at line 1148 of file packet.h.

Referenced by acip_security_init_options(), acip_security_receive(), acip_security_start(), client_acds_handshake_begin(), client_handshake_begin(), client_handshake_receive(), crypto_policy_check_mode(), handle_protocol_version_packet(), network_client_negotiate(), network_negotiation_receive(), peer_crypto_quic_begin(), peer_crypto_receive(), and peer_crypto_tick().

ACIP_CRYPTO_NONE

#define ACIP_CRYPTO_NONE   0x00

#include <include/ascii-chat/network/packet/packet.h>

No encryption, no authentication (plaintext only).

Definition at line 1138 of file packet.h.

Referenced by acip_security_receive(), client_handshake_receive(), and network_negotiation_receive().

ACIP_OPUS_BATCH_HEADER_SIZE

#define ACIP_OPUS_BATCH_HEADER_SIZE   16

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 81 of file packet.h.

Referenced by acip_send_audio_opus_batch().

ASCIICHAT_DEFAULT_DISPLAY_NAME

#define ASCIICHAT_DEFAULT_DISPLAY_NAME   "AsciiChatter"

#include <include/ascii-chat/network/packet/packet.h>

Default display name for clients without a custom name.

Used when a client connects without specifying a display name.

Definition at line 664 of file packet.h.

AUDIO_BATCH_COUNT

#define AUDIO_BATCH_COUNT   32

#include <include/ascii-chat/network/packet/packet.h>

Number of audio chunks per batch (4 chunks).

Number of audio chunks aggregated into a single batch packet for efficiency.

Definition at line 221 of file packet.h.

AUDIO_BATCH_MS

#define AUDIO_BATCH_MS   186

#include <include/ascii-chat/network/packet/packet.h>

Audio batch duration in milliseconds (~186ms).

Approximate duration of audio batch at 44.1kHz sample rate.

Definition at line 240 of file packet.h.

AUDIO_BATCH_SAMPLES

#define AUDIO_BATCH_SAMPLES   (AUDIO_SAMPLES_PER_PACKET * AUDIO_BATCH_COUNT)

#include <include/ascii-chat/network/packet/packet.h>

Total samples in audio batch (8192 samples).

Total audio samples across all chunks in a batch. At 44.1kHz, this equals ~185.8ms of audio.

Definition at line 231 of file packet.h.

Referenced by handle_audio_batch_packet().

AUDIO_SAMPLES_PER_PACKET

#define AUDIO_SAMPLES_PER_PACKET   256

#include <include/ascii-chat/network/packet/packet.h>

Samples per audio packet (256 samples).

Number of audio samples in a single audio packet. Smaller packets provide lower latency at the cost of increased packet overhead.

Definition at line 250 of file packet.h.

Referenced by handle_audio_packet().

AUTH_ALGO_ED25519

#define AUTH_ALGO_ED25519   0x01

#include <include/ascii-chat/network/packet/packet.h>

Ed25519 authentication (Edwards-curve signatures).

Definition at line 1121 of file packet.h.

Referenced by client_handshake_receive(), crypto_handshake_server_send_parameters(), and peer_crypto_receive().

AUTH_ALGO_NONE

#define AUTH_ALGO_NONE   0x00

#include <include/ascii-chat/network/packet/packet.h>

No authentication (plaintext mode).

Definition at line 1122 of file packet.h.

Referenced by client_handshake_receive(), crypto_handshake_server_send_parameters(), and peer_crypto_receive().

BASE_SEND_TIMEOUT

#define BASE_SEND_TIMEOUT   (5LL * NS_PER_SEC_INT)

#include <include/ascii-chat/network/packet/packet.h>

Base send timeout in nanoseconds (5 seconds).

Default timeout for sending packets. Used as base value for calculating timeouts for large packets.

Definition at line 170 of file packet.h.

CIPHER_ALGO_NONE

#define CIPHER_ALGO_NONE   0x00

#include <include/ascii-chat/network/packet/packet.h>

No encryption (plaintext mode).

Definition at line 1124 of file packet.h.

Referenced by acds_handshake_receive(), client_handshake_receive(), crypto_handshake_server_send_parameters(), crypto_handshake_set_parameters(), and peer_crypto_receive().

CIPHER_ALGO_XSALSA20_POLY1305

#define CIPHER_ALGO_XSALSA20_POLY1305   0x01

#include <include/ascii-chat/network/packet/packet.h>

XSalsa20-Poly1305 authenticated encryption.

Definition at line 1123 of file packet.h.

Referenced by client_handshake_receive(), crypto_handshake_server_send_parameters(), and peer_crypto_receive().

CLIENT_CAP_AUDIO

#define CLIENT_CAP_AUDIO   0x02

#include <include/ascii-chat/network/packet/packet.h>

Client can send/receive audio.

Definition at line 980 of file packet.h.

Referenced by handle_client_join_packet().

CLIENT_CAP_COLOR

#define CLIENT_CAP_COLOR   0x04

#include <include/ascii-chat/network/packet/packet.h>

Client supports color rendering.

Definition at line 981 of file packet.h.

Referenced by handle_client_join_packet().

CLIENT_CAP_STRETCH

#define CLIENT_CAP_STRETCH   0x08

#include <include/ascii-chat/network/packet/packet.h>

Client can stretch frames to fill terminal.

Definition at line 982 of file packet.h.

Referenced by handle_client_join_packet().

CLIENT_CAP_VIDEO

#define CLIENT_CAP_VIDEO   0x01

#include <include/ascii-chat/network/packet/packet.h>

Client can send/receive video.

Definition at line 979 of file packet.h.

Referenced by handle_client_join_packet().

CONNECT_TIMEOUT

#define CONNECT_TIMEOUT   3

#include <include/ascii-chat/network/network.h>

Connection timeout in seconds (3 seconds).

Maximum time to wait for connection establishment. Reduced from default for faster connection attempts and quicker failure detection.

Definition at line 98 of file network/network.h.

FEATURE_DELTA_FRAMES

#define FEATURE_DELTA_FRAMES   0x02

#include <include/ascii-chat/network/packet/packet.h>

Delta frame encoding (future).

Definition at line 843 of file packet.h.

FEATURE_RLE_ENCODING

#define FEATURE_RLE_ENCODING   0x01

#include <include/ascii-chat/network/packet/packet.h>

Feature flags for protocol_version_packet_t.

Bitmask values for optional protocol features. Used in protocol negotiation to enable advanced capabilities.

Run-length encoding support

Definition at line 842 of file packet.h.

KEEPALIVE_COUNT

#define KEEPALIVE_COUNT   8

#include <include/ascii-chat/network/network.h>

Keepalive probe count (8 probes).

Number of keepalive probes to send before considering connection dead.

Definition at line 201 of file network/network.h.

Referenced by set_socket_keepalive().

KEEPALIVE_IDLE

#define KEEPALIVE_IDLE   60

#include <include/ascii-chat/network/network.h>

Keepalive idle time in seconds (60 seconds).

Time to wait before sending first keepalive probe after connection becomes idle.

Definition at line 183 of file network/network.h.

Referenced by set_socket_keepalive().

KEEPALIVE_INTERVAL

#define KEEPALIVE_INTERVAL   10

#include <include/ascii-chat/network/network.h>

Keepalive interval in seconds (10 seconds).

Interval between subsequent keepalive probes.

Definition at line 192 of file network/network.h.

Referenced by set_socket_keepalive().

KEX_ALGO_X25519

#define KEX_ALGO_X25519   0x01

#include <include/ascii-chat/network/packet/packet.h>

X25519 key exchange (Curve25519).

Definition at line 1120 of file packet.h.

Referenced by client_handshake_receive(), crypto_handshake_server_send_parameters(), and peer_crypto_receive().

LARGE_PACKET_EXTRA_TIMEOUT_PER_MB

#define LARGE_PACKET_EXTRA_TIMEOUT_PER_MB   (800LL * NS_PER_MS_INT)

#include <include/ascii-chat/network/packet/packet.h>

Extra timeout per MB for large packets (0.8 seconds per MB).

Additional timeout added per MB for large packets to prevent premature timeout failures.

Definition at line 180 of file packet.h.

Referenced by packet_send_timeout_ns().

LARGE_PACKET_THRESHOLD

#define LARGE_PACKET_THRESHOLD   (100 * 1024)

#include <include/ascii-chat/network/packet/packet.h>

Large packet size threshold (100KB).

Packets larger than this threshold are considered "large" and may receive extended timeouts or compression treatment.

Definition at line 120 of file packet.h.

Referenced by packet_send_timeout_ns().

MAX_CLIENT_TIMEOUT

#define MAX_CLIENT_TIMEOUT   (60LL * NS_PER_SEC_INT)

#include <include/ascii-chat/network/packet/packet.h>

Maximum client timeout in nanoseconds (60 seconds).

Maximum timeout value for client operations. Prevents excessively long waits for dead connections.

Definition at line 200 of file packet.h.

Referenced by packet_send_timeout_ns().

MAX_ERROR_MESSAGE_LENGTH

#define MAX_ERROR_MESSAGE_LENGTH   4096

#include <include/ascii-chat/network/packet/packet.h>

Maximum error message length (512 bytes).

Error packets include a message payload. This defines the maximum number of bytes allowed in the message portion to prevent excessive allocations and potential abuse.

Definition at line 139 of file packet.h.

Referenced by acip_send_error(), network_error_decode(), packet_parse_error_message(), and packet_send_error().

MAX_PACKET_SIZE

#define MAX_PACKET_SIZE   ((size_t)5 * 1024 * 1024)

#include <include/ascii-chat/network/packet/packet.h>

Maximum packet size (5MB).

Absolute maximum size for any packet. Packets larger than this are rejected to prevent memory exhaustion attacks.

Definition at line 130 of file packet.h.

Referenced by acip_send_audio_batch(), acip_send_audio_opus_batch(), packet_decoder_feed(), packet_header_build(), packet_send(), packet_validate(), receive_packet_secure_with_timeout(), and send_packet_secure().

MAX_REMOTE_LOG_MESSAGE_LENGTH

#define MAX_REMOTE_LOG_MESSAGE_LENGTH   512

#include <include/ascii-chat/network/packet/packet.h>

Maximum remote log message length (512 bytes).

Remote logging packets mirror the error packet structure but are intended for diagnostic log forwarding between client and server. Limiting the payload size keeps allocations predictable and prevents log flooding over the network.

Definition at line 149 of file packet.h.

Referenced by handle_remote_log_packet_from_client(), packet_parse_remote_log(), and packet_send_remote_log().

MIN_CLIENT_TIMEOUT

#define MIN_CLIENT_TIMEOUT   (10LL * NS_PER_SEC_INT)

#include <include/ascii-chat/network/packet/packet.h>

Minimum client timeout in nanoseconds (10 seconds).

Minimum timeout value for client operations. Set to server timeout plus buffer for reliable operation.

Definition at line 190 of file packet.h.

Referenced by packet_send_timeout_ns().

network_is_test_environment

#define network_is_test_environment

(

)

#include <include/ascii-chat/network/network.h>

Value:

((int)is_test_environment())

Check if we're in a test environment.

Compatibility macro that calls is_test_environment() from tests/test_env.h. Used to adjust timeouts for faster test execution.

Returns

1 if test environment, 0 otherwise

Definition at line 162 of file network/network.h.

Referenced by send_with_timeout().

NETWORK_PACKET_COLORTERM_BUFFER_SIZE

#define NETWORK_PACKET_COLORTERM_BUFFER_SIZE   32

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 77 of file packet.h.

NETWORK_PACKET_PALETTE_CUSTOM_BUFFER_SIZE

#define NETWORK_PACKET_PALETTE_CUSTOM_BUFFER_SIZE   64

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 78 of file packet.h.

NETWORK_PACKET_TERM_TYPE_BUFFER_SIZE

#define NETWORK_PACKET_TERM_TYPE_BUFFER_SIZE   32

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 76 of file packet.h.

NETWORK_UPDATE_CHECKER_CURRENT_SHA_BUFFER_SIZE

#define NETWORK_UPDATE_CHECKER_CURRENT_SHA_BUFFER_SIZE   41

#include <include/ascii-chat/network/update_checker.h>

Definition at line 26 of file update_checker.h.

NETWORK_UPDATE_CHECKER_CURRENT_VERSION_BUFFER_SIZE

#define NETWORK_UPDATE_CHECKER_CURRENT_VERSION_BUFFER_SIZE   64

#include <include/ascii-chat/network/update_checker.h>

Definition at line 25 of file update_checker.h.

NETWORK_UPDATE_CHECKER_LATEST_SHA_BUFFER_SIZE

#define NETWORK_UPDATE_CHECKER_LATEST_SHA_BUFFER_SIZE   41

#include <include/ascii-chat/network/update_checker.h>

Definition at line 24 of file update_checker.h.

NETWORK_UPDATE_CHECKER_LATEST_VERSION_BUFFER_SIZE

#define NETWORK_UPDATE_CHECKER_LATEST_VERSION_BUFFER_SIZE   64

#include <include/ascii-chat/network/update_checker.h>

Definition at line 23 of file update_checker.h.

NETWORK_UPDATE_CHECKER_RELEASE_URL_BUFFER_SIZE

#define NETWORK_UPDATE_CHECKER_RELEASE_URL_BUFFER_SIZE   512

#include <include/ascii-chat/network/update_checker.h>

Definition at line 27 of file update_checker.h.

Referenced by update_check_perform().

PACKET_MAGIC

#define PACKET_MAGIC   MAGIC_PACKET_VALID

#include <include/ascii-chat/network/packet/packet.h>

Packet magic number (alias for MAGIC_PACKET_VALID).

Magic number used in packet headers for packet validation. Defined once in util/magic.h (0xA5C11C4A1 = "ASCIICHAT" in hex) and imported here for use in packet validation.

See also

MAGIC_PACKET_VALID

Definition at line 270 of file packet.h.

Referenced by acds_receive_packet(), packet_decoder_feed(), packet_header_build(), packet_queue_validate_packet(), packet_send(), packet_validate(), and receive_packet_secure_with_timeout().

PROTOCOL_FEATURE_IDENTITY_SET

#define PROTOCOL_FEATURE_IDENTITY_SET   0x08

#include <include/ascii-chat/network/packet/packet.h>

CLIENT_HELLO accepts a bounded set of pinned Ed25519 keys

Definition at line 845 of file packet.h.

PROTOCOL_FEATURE_RECOVERABLE_ERRORS

#define PROTOCOL_FEATURE_RECOVERABLE_ERRORS   0x04

#include <include/ascii-chat/network/packet/packet.h>

Peer accepts nonfatal audio error notifications

Definition at line 844 of file packet.h.

Referenced by handle_protocol_version_packet().

RECV_TIMEOUT

#define RECV_TIMEOUT   1

#include <include/ascii-chat/network/network.h>

Receive timeout in seconds (1 second).

Reduced to 1 second to allow snapshot mode to check elapsed time frequently and exit cleanly when snapshot_delay expires. With the longer 30-second timeout, clients in snapshot mode would block waiting for data and miss their snapshot window. The 1-second timeout balances responsiveness with network latency tolerance.

Definition at line 127 of file network/network.h.

Referenced by packet_receive(), and receive_packet_secure().

REMOTE_LOG_FLAG_TRUNCATED

#define REMOTE_LOG_FLAG_TRUNCATED   0x0001U

#include <include/ascii-chat/network/packet/packet.h>

Remote log packet flag definitions.

Message payload was truncated to fit the maximum length

Definition at line 776 of file packet.h.

Referenced by handle_remote_log_packet_from_client(), and packet_send_remote_log().

SEND_TIMEOUT

#define SEND_TIMEOUT   1

#include <include/ascii-chat/network/network.h>

Send timeout in seconds (5 seconds).

Maximum time to wait for data transmission. Video frames need timely delivery to maintain real-time performance.

Definition at line 111 of file network/network.h.

Referenced by packet_send_timeout_ns().

STREAM_TYPE_AUDIO

#define STREAM_TYPE_AUDIO   0x02

#include <include/ascii-chat/network/packet/packet.h>

Audio stream.

Definition at line 994 of file packet.h.

Referenced by client_protocol_start(), handle_stream_start_packet(), and handle_stream_stop_packet().

STREAM_TYPE_VIDEO

#define STREAM_TYPE_VIDEO   0x01

#include <include/ascii-chat/network/packet/packet.h>

Video stream.

Definition at line 993 of file packet.h.

Referenced by client_protocol_start(), handle_stream_start_packet(), and handle_stream_stop_packet().

Enumeration Type Documentation

auth_failure_reason_t

enum auth_failure_reason_t

#include <include/ascii-chat/network/packet/packet.h>

Authentication failure reason flags.

Bitmask enumeration for authentication failure reasons. Multiple flags can be combined to indicate multiple failure causes.

Enumerator
AUTH_FAIL_PASSWORD_REQUIRED	Server requires password but client didn't provide one.
AUTH_FAIL_PASSWORD_INCORRECT	Password verification failed (incorrect password).
AUTH_FAIL_CLIENT_KEY_REQUIRED	Server requires client key but client didn't provide one.
AUTH_FAIL_CLIENT_KEY_REJECTED	Client key not in whitelist (access denied).
AUTH_FAIL_SIGNATURE_INVALID	Client signature verification failed (invalid signature).

Definition at line 801 of file packet.h.

             {
  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
} auth_failure_reason_t;

install_method_t

enum install_method_t

#include <include/ascii-chat/network/update_checker.h>

Installation method for suggesting upgrade command.

Enumerator
INSTALL_METHOD_HOMEBREW	Installed via Homebrew.
INSTALL_METHOD_SCOOP	Installed via Scoop.
INSTALL_METHOD_ARCH_AUR	Installed via Arch AUR (paru/yay).
INSTALL_METHOD_INSTALLER	Installed by ascii-chat.com installer.
INSTALL_METHOD_GITHUB	Manual install from GitHub releases.
INSTALL_METHOD_UNKNOWN	Unknown installation method.

Definition at line 53 of file update_checker.h.

             {
  INSTALL_METHOD_HOMEBREW,  
  INSTALL_METHOD_SCOOP,     
  INSTALL_METHOD_ARCH_AUR,  
  INSTALL_METHOD_INSTALLER, 
  INSTALL_METHOD_GITHUB,    
  INSTALL_METHOD_UNKNOWN,   
} install_method_t;

packet_recv_result_t

enum packet_recv_result_t

#include <include/ascii-chat/network/packet/packet.h>

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.

Packet reception result codes

Result codes for packet reception operations. Negative values indicate errors, zero indicates success.

Enumerator
PACKET_RECV_SUCCESS	Packet received successfully.
PACKET_RECV_EOF	Connection closed (EOF).
PACKET_RECV_ERROR	Network error occurred.
PACKET_RECV_SECURITY_VIOLATION	Encryption policy violation (e.g., unencrypted packet when encryption required).

Definition at line 1210 of file packet.h.

             {
  PACKET_RECV_SUCCESS = 0,
  PACKET_RECV_EOF = -1,
  PACKET_RECV_ERROR = -2,
  PACKET_RECV_SECURITY_VIOLATION = -3
} packet_recv_result_t;

packet_type_t

enum packet_type_t

#include <include/ascii-chat/network/packet/packet.h>

Network protocol packet type enumeration.

Defines all packet types used in the ascii-chat network protocol. Packet types are organized by priority: protocol negotiation, then all cryptographic operations, then media, control, audio, and messages.

PACKET CATEGORIES (with expansion room):

• 1: Protocol negotiation
• 2-1001: Cryptographic operations (1000 space reserved)
  • 2: Client hello (expansion room: 3-101)
  • 102-201: Handshake/exchange (expansion room: 113-201)
  • 202-301: Rekeying (expansion room: 205-301)
• 1002-2001: Message packets (1000 space reserved)
• 2002-3001: Media frame packets (1000 space reserved)
• 3002-4001: Audio packets (1000 space reserved)
• 4002-5001: Control/state packets (1000 space reserved)
• 6001+: Discovery/ACIP protocol

Note

Crypto handshake packets (2-12) and rekey packets (14-16) are ALWAYS sent unencrypted. Use packet_is_handshake_type() to check.

PACKET_TYPE_ENCRYPTED (13) is used for encrypted session packets after handshake completion.

Enumerator
PACKET_TYPE_PROTOCOL_VERSION	Protocol version and capabilities negotiation.
PACKET_TYPE_CRYPTO_CLIENT_HELLO	Client -> Server: Expected server key fingerprint for multi-key selection (UNENCRYPTED).
PACKET_TYPE_CRYPTO_CAPABILITIES	Client -> Server: Supported crypto algorithms (UNENCRYPTED).
PACKET_TYPE_CRYPTO_PARAMETERS	Server -> Client: Chosen algorithms + data sizes (UNENCRYPTED).
PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT	Server -> Client: {server_pubkey[32]} (UNENCRYPTED).
PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP	Client -> Server: {client_pubkey[32]} (UNENCRYPTED).
PACKET_TYPE_CRYPTO_AUTH_CHALLENGE	Server -> Client: {nonce[32]} (UNENCRYPTED).
PACKET_TYPE_CRYPTO_AUTH_RESPONSE	Client -> Server: {HMAC[32]} (UNENCRYPTED).
PACKET_TYPE_CRYPTO_AUTH_FAILED	Server -> Client: "authentication failed" (UNENCRYPTED).
PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP	Server -> Client: {HMAC[32]} server proves knowledge (UNENCRYPTED).
PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE	Server -> Client: "encryption ready" (UNENCRYPTED).
PACKET_TYPE_CRYPTO_NO_ENCRYPTION	Client -> Server: "I want to proceed without encryption" (UNENCRYPTED).
PACKET_TYPE_QUIC_READY	Internal authenticated readiness barrier for ACIP over QUIC.
PACKET_TYPE_QUIC_KEYFRAME_REQUEST	Internal authenticated request for a QUIC encoded-video keyframe.
PACKET_TYPE_CRYPTO_EPOCH_MARKER
PACKET_TYPE_CRYPTO_REKEY_NEEDED
PACKET_TYPE_CRYPTO_EPOCH_ACK
PACKET_TYPE_ENCRYPTED	Encrypted packet (after handshake completion).
PACKET_TYPE_CRYPTO_REKEY_REQUEST	Initiator -> Responder: {new_ephemeral_pk[32]} (UNENCRYPTED during rekey).
PACKET_TYPE_CRYPTO_REKEY_RESPONSE	Responder -> Initiator: {new_ephemeral_pk[32]} (UNENCRYPTED during rekey).
PACKET_TYPE_CRYPTO_REKEY_COMPLETE	Initiator -> Responder: Empty (encrypted with NEW key, but still handshake).
PACKET_TYPE_SIZE_MESSAGE	Terminal size message.
PACKET_TYPE_AUDIO_MESSAGE	Audio message.
PACKET_TYPE_TEXT_MESSAGE	Text message.
PACKET_TYPE_ERROR_MESSAGE	Error packet with asciichat_error_t code and human-readable message.
PACKET_TYPE_REMOTE_LOG	Bidirectional remote logging packet.
PACKET_TYPE_ASCII_FRAME	Complete ASCII frame with all metadata.
PACKET_TYPE_IMAGE_FRAME	Complete RGB image with dimensions.
PACKET_TYPE_IMAGE_FRAME_H265	H.265-encoded frame from client (HEVC/H.265 codec).
PACKET_TYPE_IMAGE_FRAME_H264	H.264 Annex B access unit: flags:u8, width:u16be, height:u16be, data.
PACKET_TYPE_AUDIO_BATCH	Batched audio packets for efficiency.
PACKET_TYPE_AUDIO_OPUS_BATCH	Batched Opus-encoded audio frames.
PACKET_TYPE_CLIENT_CAPABILITIES	Client reports terminal capabilities.
PACKET_TYPE_PING	Keepalive ping packet.
PACKET_TYPE_PONG	Keepalive pong response.
PACKET_TYPE_CLIENT_JOIN	Client announces capability to send media.
PACKET_TYPE_CLIENT_LEAVE	Clean disconnect notification.
PACKET_TYPE_STREAM_START	Client requests to start sending video/audio.
PACKET_TYPE_STREAM_STOP	Client stops sending media.
PACKET_TYPE_CLEAR_CONSOLE	Server tells client to clear console.
PACKET_TYPE_SERVER_STATE	Server sends current state to clients.
PACKET_TYPE_ACIP_SESSION_CREATE	Create new session (Client -> Discovery Server).
PACKET_TYPE_ACIP_SESSION_CREATED	Session created response (Discovery Server -> Client).
PACKET_TYPE_ACIP_SESSION_LOOKUP	Lookup session by string (Client -> Discovery Server).
PACKET_TYPE_ACIP_SESSION_INFO	Session info response (Discovery Server -> Client).
PACKET_TYPE_ACIP_SESSION_JOIN	Join existing session (Client -> Discovery Server).
PACKET_TYPE_ACIP_SESSION_JOINED	Session joined response (Discovery Server -> Client).
PACKET_TYPE_ACIP_SESSION_LEAVE	Leave session (Client -> Discovery Server).
PACKET_TYPE_ACIP_SESSION_END	End session (Host -> Discovery Server).
PACKET_TYPE_ACIP_SESSION_RECONNECT	Reconnect to session (Client -> Discovery Server).
PACKET_TYPE_ACIP_WEBRTC_SDP	WebRTC SDP offer/answer (bidirectional).
PACKET_TYPE_ACIP_WEBRTC_ICE	WebRTC ICE candidate (bidirectional).
PACKET_TYPE_ACIP_STRING_RESERVE	Reserve session string (Client -> Discovery Server).
PACKET_TYPE_ACIP_STRING_RESERVED	String reserved response (Discovery Server -> Client).
PACKET_TYPE_ACIP_STRING_RENEW	Renew string reservation (Client -> Discovery Server).
PACKET_TYPE_ACIP_STRING_RELEASE	Release string reservation (Client -> Discovery Server).
PACKET_TYPE_ACIP_PARTICIPANT_LIST	Participant list with ring order (ACDS -> Participants).
PACKET_TYPE_ACIP_RING_COLLECT	Ring collect request (Participant -> Next Participant).
PACKET_TYPE_ACIP_NETWORK_QUALITY	NETWORK_QUALITY exchange (unified packet for all quality metrics).
PACKET_TYPE_ACIP_HOST_ANNOUNCEMENT	Host announcement (Participant -> ACDS, "I won negotiation").
PACKET_TYPE_ACIP_HOST_DESIGNATED	Host designated (ACDS -> All Participants).
PACKET_TYPE_ACIP_SETTINGS_SYNC	Settings sync (Initiator -> Host -> All Participants).
PACKET_TYPE_ACIP_SETTINGS_ACK	Settings acknowledgment (Participant -> Initiator).
PACKET_TYPE_ACIP_HOST_LOST	Host lost notification - lightweight (Participant -> ACDS).
PACKET_TYPE_ACIP_FUTURE_HOST_ELECTED	Future host elected announcement (Quorum Leader -> ACDS -> All Participants).
PACKET_TYPE_ACIP_PARTICIPANT_JOINED	Participant joined notification (ACDS -> Existing Participants).
PACKET_TYPE_ACIP_PARTICIPANT_LEFT	Participant left notification (ACDS -> Remaining Participants).
PACKET_TYPE_ACIP_BANDWIDTH_TEST	Bandwidth test request (Client -> ACDS).
PACKET_TYPE_ACIP_BANDWIDTH_RESULT	Bandwidth test results (ACDS -> Client).
PACKET_TYPE_ACIP_BROADCAST_ACK	Broadcast acknowledgment for reliable delivery.
PACKET_TYPE_RING_MEMBERS	Ring member list announcement (ACDS -> All Participants).
PACKET_TYPE_STATS_COLLECTION_START	Start statistics collection phase (Coordinator -> All Participants).
PACKET_TYPE_STATS_UPDATE	Statistics update during collection phase (Participant -> Next Participant).
PACKET_TYPE_RING_ELECTION_RESULT	Final election result (Quorum Leader -> All Participants).
PACKET_TYPE_STATS_ACK	Acknowledgment of statistics update (Participant -> Sender).
PACKET_TYPE_ACIP_DISCOVERY_PING	Discovery server ping (keepalive).
PACKET_TYPE_ACIP_ERROR	Generic error response (Discovery Server -> Client).

Definition at line 301 of file packet.h.

             {
  PACKET_TYPE_PROTOCOL_VERSION = 1,
 
  // ============================================================================
  // Cryptographic Operations (Types 1000-1999)
  // ============================================================================
 
  // ============================================================================
  // Cryptographic Client Hello (Types 1000-1099)
  // ============================================================================

  PACKET_TYPE_CRYPTO_CLIENT_HELLO = 1000,
 
  // ============================================================================
  // Cryptographic Handshake (Types 1100-1199)
  // ============================================================================
  // ALWAYS UNENCRYPTED (except ENCRYPTED which wraps encrypted data)

  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,
 
  // ============================================================================
  // Cryptographic Rekeying (Types 1200-1299)
  // ============================================================================
  // ALWAYS UNENCRYPTED during rekey phase

  PACKET_TYPE_ENCRYPTED = 1200,
  PACKET_TYPE_CRYPTO_REKEY_REQUEST = 1201,
  PACKET_TYPE_CRYPTO_REKEY_RESPONSE = 1202,
  PACKET_TYPE_CRYPTO_REKEY_COMPLETE = 1203,
 
  // ============================================================================
  // Message Packets (Types 2000-2999)
  // ============================================================================

  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,
 
  // ============================================================================
  // Media Frames (Types 3000-3999)
  // ============================================================================

  PACKET_TYPE_ASCII_FRAME = 3000,
  PACKET_TYPE_IMAGE_FRAME = 3001,
  PACKET_TYPE_IMAGE_FRAME_H265 = 3002,
  PACKET_TYPE_IMAGE_FRAME_H264 = 3003,
 
  // ============================================================================
  // Audio Packets (Types 4000-4999)
  // ============================================================================

  PACKET_TYPE_AUDIO_BATCH = 4000,
  PACKET_TYPE_AUDIO_OPUS_BATCH = 4001,
 
  // ============================================================================
  // Control/State Packets (Types 5000-5999)
  // ============================================================================

  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,
 
  // ============================================================================
  // Discovery Service Protocol (ACDS) (Types 6000+)
  // ============================================================================
  // ACIP packets use range 6000+ for discovery mode operations
  // See network/acip/protocol.h for protocol overview and utility functions
  // See network/acip/acds.h for ACDS message structures and detailed documentation

  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,
 
  // ============================================================================
  // Ring Consensus Protocol (6050-6051)
  // ============================================================================
  // Used for proactive future host election every 5 minutes

  PACKET_TYPE_ACIP_PARTICIPANT_LIST = 6050,
  PACKET_TYPE_ACIP_RING_COLLECT = 6051,
 
  // ============================================================================
  // Host Negotiation & Migration Protocol (6060-6069)
  // ============================================================================
  // Used by discovery mode for dynamic host selection and failover

  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,
 
  // ============================================================================
  // Bandwidth Testing (6070-6071)
  // ============================================================================
  // Used for measuring network bandwidth during NAT quality detection

  PACKET_TYPE_ACIP_BANDWIDTH_TEST = 6070,
  PACKET_TYPE_ACIP_BANDWIDTH_RESULT = 6071,

  PACKET_TYPE_ACIP_BROADCAST_ACK = 6075,
 
  // ============================================================================
  // Ring Consensus Protocol (6100-6104)
  // ============================================================================
  // Used for collecting statistics and coordinating ring-based consensus

  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,
 
  // ============================================================================
  // Discovery Service Keepalive (6190-6199)
  // ============================================================================

  PACKET_TYPE_ACIP_DISCOVERY_PING = 6190,
  PACKET_TYPE_ACIP_ERROR = 6199
} packet_type_t;

Function Documentation

accept_with_timeout()

int accept_with_timeout	(	socket_t	listenfd,
		struct sockaddr *	addr,
		socklen_t *	addrlen,
		uint64_t	timeout_ns )

#include <include/ascii-chat/network/network.h>

Accept connection with timeout.

Parameters

listenfd	Listening socket file descriptor
addr	Output: Client address structure (can be NULL)
addrlen	Input/output: Length of address structure
timeout_ns	Timeout in nanoseconds

Returns

Client socket file descriptor on success, -1 on error

Accepts incoming connection with timeout support. Waits up to timeout_ns for incoming connection.

Note

If addr is NULL, client address information is not returned.

addrlen must point to initialized value containing size of addr buffer. On return, contains actual size of address.

Parameters

listenfd	Listening socket
addr	Client address structure
addrlen	Length of address structure
timeout_seconds	Timeout in seconds

Returns

Client socket, or -1 on error

Definition at line 283 of file network/network.c.

                                                                                                           {
  // Set up poll for accept timeout (in nanoseconds)
  struct pollfd pfd;
  pfd.fd = listenfd;
  pfd.events = POLLIN;
  pfd.revents = 0;
 
  int result = socket_poll(&pfd, 1, (int64_t)timeout_ns);
 
  if (result <= 0) {
    if (result == 0) {
      // Timeout is expected behavior for server waiting for connections
      errno_set_with_system_error(ERROR_NETWORK_TIMEOUT, __FILE__, __LINE__, __func__, ETIMEDOUT);
      return -1;
    }
 
    if (network_handle_select_error(result)) {
      return -1; // Don't retry for accept
    }
    return -1;
  }
 
  // Check if socket is ready
  if (!(pfd.revents & POLLIN)) {
    errno_set_with_system_error(ERROR_NETWORK_TIMEOUT, __FILE__, __LINE__, __func__, ETIMEDOUT);
    return -1;
  }
 
  // Check if socket is still valid before attempting accept
  if (listenfd == INVALID_SOCKET_VALUE) {
    SET_ERRNO(ERROR_NETWORK, "listening socket is closed");
    return -1;
  }
 
  socket_t accept_result = socket_accept(listenfd, addr, addrlen, "connection");
 
  if (accept_result == INVALID_SOCKET_VALUE) {
    // Check if this is a socket closed error (common during shutdown)
    int error_code = socket_get_last_error();
 
    if (socket_is_invalid_socket_error(error_code)) {
      // During shutdown, don't log this as an error since it's expected behavior
      SET_ERRNO(ERROR_NETWORK, "Network operation failed");
    } else {
      SET_ERRNO_SYS(ERROR_NETWORK_BIND, "accept failed: %s", socket_get_error_string());
    }
    return -1;
  }
 
  return (int)accept_result;
}

References errno_set_with_system_error(), ERROR_NETWORK, ERROR_NETWORK_BIND, ERROR_NETWORK_TIMEOUT, ETIMEDOUT, SET_ERRNO, and SET_ERRNO_SYS.

av_send_audio_opus_batch()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Send Opus-encoded audio batch packet with encryption support.

Parameters

sockfd	Socket file descriptor
opus_data	Opus-encoded audio data buffer
opus_size	Size of Opus-encoded data in bytes
frame_sizes	Array of frame sizes (one per Opus frame)
sample_rate	Sample rate in Hz (e.g., 48000)
frame_duration	Frame duration in milliseconds (e.g., 20)
frame_count	Number of Opus frames in batch
crypto_ctx	Cryptographic context for encryption (NULL for plaintext)

Returns

ASCIICHAT_OK on success, error code on failure

Sends PACKET_TYPE_AUDIO_OPUS_BATCH with multiple Opus-encoded frames. Opus provides better compression than raw audio (30-100 bytes per 20ms frame).

Note

Opus packets are NOT compressed again (already compressed by Opus codec).

Encryption is applied automatically when crypto_ctx is provided.

Definition at line 1000 of file packet.c.

                                                                                          {
  if (!opus_data || opus_size == 0 || !frame_sizes || sample_rate <= 0 || frame_duration <= 0 || frame_count <= 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "Invalid Opus batch parameters: opus_data=%p, opus_size=%zu, frame_sizes=%p, sample_rate=%d, "
                     "frame_duration=%d, frame_count=%d",
                     (const void *)opus_data, opus_size, (const void *)frame_sizes, sample_rate, frame_duration,
                     frame_count);
  }
 
  // Validate frame_count to prevent integer overflow in size calculations
  // Max reasonable frames per batch: ~1 second of 10ms frames = 100 frames
  if (frame_count > 1000) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Too many Opus frames: %d (max 1000)", frame_count);
  }
 
  // Allocate buffer for header + frame sizes + encoded data
  size_t header_size = 16; // sample_rate (4), frame_duration (4), frame_count (4), reserved (4)
  size_t frame_sizes_bytes = (size_t)frame_count * sizeof(uint16_t);
  size_t total_size = header_size + frame_sizes_bytes + opus_size;
  void *packet_data = buffer_alloc(NULL, total_size);
  if (!packet_data) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for Opus batch packet: %zu bytes", total_size);
  }
 
  // Write header (network byte order for cross-platform compatibility)
  uint8_t *buf = (uint8_t *)packet_data;
  uint32_t sr = HOST_TO_NET_U32((uint32_t)sample_rate);
  uint32_t fd = HOST_TO_NET_U32((uint32_t)frame_duration);
  uint32_t fc = HOST_TO_NET_U32((uint32_t)frame_count);
  memcpy(buf, &sr, 4);
  memcpy(buf + 4, &fd, 4);
  memcpy(buf + 8, &fc, 4);
  memset(buf + 12, 0, 4); // Reserved
 
  // Write frame sizes array (convert each to network byte order)
  uint16_t *frame_sizes_out = (uint16_t *)(buf + header_size);
  for (int i = 0; i < frame_count; i++) {
    frame_sizes_out[i] = HOST_TO_NET_U16(frame_sizes[i]);
  }
 
  // Copy Opus data
  memcpy(buf + header_size + frame_sizes_bytes, opus_data, opus_size);
 
  // Send packet (with encryption support)
  asciichat_error_t result =
      send_packet_secure(sockfd, PACKET_TYPE_AUDIO_OPUS_BATCH, packet_data, total_size, crypto_ctx);
 
  // Clean up
  buffer_release(packet_data);
 
  return result;
}

References buffer_alloc(), buffer_release, ERROR_INVALID_PARAM, ERROR_MEMORY, HOST_TO_NET_U16, HOST_TO_NET_U32, PACKET_TYPE_AUDIO_OPUS_BATCH, send_packet_secure(), and SET_ERRNO.

connect_with_timeout()

bool connect_with_timeout	(	socket_t	sockfd,
		const struct sockaddr *	addr,
		socklen_t	addrlen,
		int	timeout_seconds )

#include <include/ascii-chat/network/network.h>

Connect to server with timeout.

Parameters

sockfd	Socket file descriptor
addr	Server address structure
addrlen	Address structure length
timeout_seconds	Timeout in seconds

Returns

true on success, false on failure

Establishes connection to server with timeout support. Waits up to timeout_seconds for connection to complete.

Note

Uses platform-specific connection timeout mechanism (select/poll).

Returns false on timeout or connection failure. Use network_error_string() to get human-readable error description.

Connect to server with timeout.

Parameters

sockfd	Socket file descriptor
addr	Address to connect to
addrlen	Address length
timeout_seconds	Timeout in seconds

Returns

true on success, false on failure

Definition at line 466 of file network/network.c.

                                                                                                                {
  if (sockfd == INVALID_SOCKET_VALUE) {
    errno = EBADF;
    return false;
  }
 
  // Set socket to non-blocking for timeout control
  if (set_socket_nonblocking(sockfd) != ASCIICHAT_OK) {
    return false;
  }
 
  // Attempt connection
  int result = connect(sockfd, addr, addrlen);
 
  if (result == 0) {
    // Connected immediately
    if (socket_set_blocking(sockfd) != 0) {
      return false;
    }
    return true;
  }
 
  // Check if connection is in progress (expected for non-blocking sockets)
  int error = socket_get_last_error();
  if (!socket_is_in_progress_error(error) && !socket_is_would_block_error(error)) {
    log_warn("TCP connection could not start (socket error %d)", error);
    return false;
  }
 
  // Use select to wait for connection with timeout
  fd_set write_fds;
  struct timeval timeout;
 
  socket_fd_zero(&write_fds);
  socket_fd_set(sockfd, &write_fds);
 
  timeout.tv_sec = timeout_seconds;
  timeout.tv_usec = 0;
 
  result = socket_select(sockfd, NULL, &write_fds, NULL, &timeout);
 
  if (result <= 0) {
    log_warn("TCP connection wait failed (result %d, socket error %d)", result,
             result == 0 ? 0 : socket_get_last_error());
    return false; // Timeout or error
  }
 
  if (!socket_fd_isset(sockfd, &write_fds)) {
    return false; // Socket not ready
  }
 
  // Check if connection was successful
  int error_code = 0;
  socklen_t error_len = sizeof(error_code);
 
  if (socket_getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &error_code, &error_len) != 0) {
    return false;
  }
 
  if (error_code != 0) {
    log_warn("TCP connection failed (socket error %d)", error_code);
    return false;
  }
 
  // Connection successful - restore blocking mode
  if (socket_set_blocking(sockfd) != 0) {
    log_warn("Failed to restore socket to blocking mode after connect");
    // Continue anyway - non-blocking mode works but may cause issues with send/recv
  }
 
  return true;
}

References ASCIICHAT_OK, EBADF, errno, log_warn, and set_socket_nonblocking().

dns_test_connectivity()

bool dns_test_connectivity

(

const char *

hostname

)

#include <include/ascii-chat/network/dns.h>

Test DNS connectivity by resolving a hostname.

Attempts to resolve the given hostname to verify DNS connectivity. Uses a short timeout to avoid blocking.

Parameters

hostname

Hostname to resolve (e.g., "api.github.com")

Returns

true if DNS resolution succeeds, false otherwise

Note

Logs warnings on failure

IPv4 resolution only (AF_INET)

Definition at line 13 of file dns.c.

                                                 {
  ASCII_OTEL_SCOPE(DNS_TEST_CONNECTIVITY);
  if (!hostname) {
    log_warn("NULL hostname provided to DNS connectivity test");
    return false;
  }
 
  char ascii_hostname[HOSTNAME_BUFFER_SIZE];
  asciichat_error_t normalized = hostname_to_ascii(hostname, ascii_hostname, sizeof(ascii_hostname));
  if (normalized != ASCIICHAT_OK)
    return false;
  hostname = ascii_hostname;
 
  struct addrinfo hints, *result = NULL;
  memset(&hints, 0, sizeof(hints));
  /* Connectivity is not IPv4-specific.  Restricting this probe to AF_INET
   * reports a false DNS failure on IPv6-only or IPv6-preferred networks even
   * though the HTTP client can connect successfully. */
  hints.ai_family = AF_UNSPEC;
  hints.ai_socktype = SOCK_STREAM;
 
  log_debug("Testing DNS connectivity to %s...", hostname);
  log_debug("★ ABOUT TO CALL getaddrinfo for %s", hostname);
 
  /* Resolve the same service used by the update request.  Passing a NULL
   * service is rejected by some Windows resolver configurations even though
   * hostname resolution itself is healthy. */
  int ret = getaddrinfo(hostname, "443", &hints, &result);
  log_debug("★ getaddrinfo returned %d", ret);
  if (ret != 0) {
    log_warn("DNS resolution failed for %s: %s", hostname, gai_strerror(ret));
    return false;
  }
 
  if (result) {
    freeaddrinfo(result);
  }
 
  log_debug("DNS connectivity test succeeded for %s", hostname);
  return true;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, HOSTNAME_BUFFER_SIZE, hostname_to_ascii(), log_debug, and log_warn.

frame_check_size_overflow()

asciichat_error_t frame_check_size_overflow	(	size_t	header_size,
		size_t	data_size )

#include <include/ascii-chat/network/frame_validator.h>

Check for overflow when adding header to data.

Parameters

header_size	Header size in bytes
data_size	Data size in bytes

Returns

ASCIICHAT_OK if safe, ERROR_BUFFER_OVERFLOW if would overflow

Definition at line 18 of file network/frame_validator.c.

                                                                                  {
  if (data_size > SIZE_MAX - header_size) {
    char size_str[NETWORK_FRAME_VALIDATOR_SIZE_BUFFER_SIZE];
    format_bytes_pretty(data_size, size_str, sizeof(size_str));
    SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Frame size overflow: %s", size_str);
    return ERROR_BUFFER_OVERFLOW;
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_BUFFER_OVERFLOW, format_bytes_pretty(), NETWORK_FRAME_VALIDATOR_SIZE_BUFFER_SIZE, and SET_ERRNO.

Referenced by frame_validate_legacy(), frame_validate_new(), and handle_image_frame_packet().

frame_extract_dimensions()

void frame_extract_dimensions	(	const void *	data,
		uint32_t *	width,
		uint32_t *	height )

#include <include/ascii-chat/network/frame_validator.h>

Extract width and height from frame header.

Parameters

data	Packet data (must be at least 8 bytes)
width	Output: frame width
height	Output: frame height

Definition at line 89 of file network/frame_validator.c.

                                                                                   {
  uint32_t width_net, height_net;
  memcpy(&width_net, data, FRAME_HEADER_FIELD_SIZE);
  memcpy(&height_net, (char *)data + FRAME_HEADER_FIELD_SIZE, FRAME_HEADER_FIELD_SIZE);
  *width = NET_TO_HOST_U32(width_net);
  *height = NET_TO_HOST_U32(height_net);
}

References FRAME_HEADER_FIELD_SIZE, height, NET_TO_HOST_U32, and width.

frame_extract_new_header()

void frame_extract_new_header	(	const void *	data,
		uint32_t *	compressed,
		uint32_t *	data_size )

#include <include/ascii-chat/network/frame_validator.h>

Extract compressed flag and data size from new format header.

Parameters

data	Packet data (must be at least 16 bytes)
compressed	Output: whether data is compressed
data_size	Output: size of data field

Definition at line 97 of file network/frame_validator.c.

                                                                                           {
  uint32_t compressed_net, size_net;
  memcpy(&compressed_net, (char *)data + FRAME_HEADER_FIELD_SIZE * 2, FRAME_HEADER_FIELD_SIZE);
  memcpy(&size_net, (char *)data + FRAME_HEADER_FIELD_SIZE * 3, FRAME_HEADER_FIELD_SIZE);
  *compressed = NET_TO_HOST_U32(compressed_net);
  *data_size = NET_TO_HOST_U32(size_net);
}

References FRAME_HEADER_FIELD_SIZE, and NET_TO_HOST_U32.

Referenced by frame_validate_new().

frame_validate_legacy()

asciichat_error_t frame_validate_legacy	(	size_t	len,
		size_t	expected_rgb_size )

#include <include/ascii-chat/network/frame_validator.h>

Validate legacy frame format.

Parameters

len	Total packet length
expected_rgb_size	Expected RGB data size (width * height * 3)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 28 of file network/frame_validator.c.

                                                                              {
  // Check minimum header size
  if (len < FRAME_HEADER_SIZE_LEGACY) {
    SET_ERRNO(ERROR_INVALID_FRAME, "Legacy frame header too small: %zu bytes", len);
    return ERROR_INVALID_FRAME;
  }
 
  // Check for overflow
  asciichat_error_t err = frame_check_size_overflow(FRAME_HEADER_SIZE_LEGACY, expected_rgb_size);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  size_t expected_total = FRAME_HEADER_SIZE_LEGACY + expected_rgb_size;
  if (len != expected_total) {
    SET_ERRNO(ERROR_INVALID_FRAME, "Legacy frame length mismatch: expected %zu got %zu", expected_total, len);
    return ERROR_INVALID_FRAME;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_FRAME, frame_check_size_overflow(), FRAME_HEADER_SIZE_LEGACY, and SET_ERRNO.

Referenced by handle_image_frame_packet().

frame_validate_new()

asciichat_error_t frame_validate_new	(	void *	data,
		size_t	len,
		bool *	out_compressed,
		uint32_t *	out_data_size )

#include <include/ascii-chat/network/frame_validator.h>

Validate new frame format with optional compression.

Parameters

data	Packet data
len	Total packet length
out_compressed	Output: whether data is compressed (optional)
out_data_size	Output: size of compressed/uncompressed data (optional)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 50 of file network/frame_validator.c.

                                                                                                            {
  // Check minimum new format header size
  if (len < FRAME_HEADER_SIZE_NEW) {
    SET_ERRNO(ERROR_INVALID_FRAME, "New frame header too small: %zu bytes", len);
    return ERROR_INVALID_FRAME;
  }
 
  uint32_t compressed_flag, data_size;
  frame_extract_new_header(data, &compressed_flag, &data_size);
 
  size_t data_size_sz = (size_t)data_size;
 
  // Check data size against maximum
  if (data_size_sz > IMAGE_MAX_PIXELS_SIZE) {
    char size_str[NETWORK_FRAME_VALIDATOR_SIZE_BUFFER_SIZE];
    format_bytes_pretty(data_size_sz, size_str, sizeof(size_str));
    SET_ERRNO(ERROR_INVALID_FRAME, "Frame data too large: %s", size_str);
    return ERROR_INVALID_FRAME;
  }
 
  // Check for overflow
  asciichat_error_t err = frame_check_size_overflow(FRAME_HEADER_SIZE_NEW, data_size_sz);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  size_t expected_total = FRAME_HEADER_SIZE_NEW + data_size_sz;
  if (len != expected_total) {
    SET_ERRNO(ERROR_INVALID_FRAME, "New frame length mismatch: expected %zu got %zu", expected_total, len);
    return ERROR_INVALID_FRAME;
  }
 
  if (out_compressed)
    *out_compressed = (compressed_flag != 0);
  if (out_data_size)
    *out_data_size = data_size;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_FRAME, format_bytes_pretty(), frame_check_size_overflow(), frame_extract_new_header(), FRAME_HEADER_SIZE_NEW, IMAGE_MAX_PIXELS_SIZE, NETWORK_FRAME_VALIDATOR_SIZE_BUFFER_SIZE, and SET_ERRNO.

https_get()

char * https_get	(	const char *	hostname,
		const char *	path )

#include <include/ascii-chat/network/http/client/client.h>

Perform HTTPS GET request.

Parameters

hostname	Server hostname (e.g., "github.com", must not be NULL)
path	Resource path (e.g., "/username.keys", must not be NULL)

Returns

Allocated string containing response body (caller must free), or NULL on error

Makes a secure HTTPS connection to the specified hostname and fetches the resource at the given path. Uses system CA certificates for validation.

Note

TLS connection: Uses BearSSL for TLS connections. Validates server certificate against system CA certificates.

Memory management: Returns allocated string that caller must free. Use SAFE_FREE() to free the returned string.

Error handling: Returns NULL on error (network error, TLS error, etc.). Error messages are logged via logging system.

Hostname format: Hostname should be domain name only (no "https://" prefix). Example: "github.com", not "https://github.com".

Path format: Path should start with "/" for absolute paths. Example: "/username.keys", not "username.keys".

Response body: Returns complete response body as null-terminated string. Response may contain multiple keys (one per line for SSH keys).

Warning

Network dependency: Requires network connectivity and valid hostname. May fail if network is unavailable or hostname is unreachable.

Memory leak: Caller must free returned string using SAFE_FREE(). Function allocates memory that must be freed.

Certificate validation: Uses system CA certificates for validation. May fail if system CA certificates are missing or outdated.

Definition at line 180 of file lib/network/http/client/client.c.

                                                        {
  ASCII_OTEL_SCOPE(HTTP);
  ascii_otel_http(&otel_scope, hostname, path);
  char *body = NULL;
  if (!hostname || !path) {
    log_error("Invalid arguments");
    return NULL;
  }
 
  char ascii_hostname[HOSTNAME_BUFFER_SIZE];
  asciichat_error_t normalized = hostname_to_ascii(hostname, ascii_hostname, sizeof(ascii_hostname));
  if (normalized != ASCIICHAT_OK)
    return NULL;
  hostname = ascii_hostname;
 
  log_info("HTTPS GET https://%s%s", hostname, path);
 
  // Load system CA certificates
  char *pem_data = NULL;
  size_t pem_size = 0;
  if (platform_load_system_ca_certs(&pem_data, &pem_size) != 0) {
    log_error("Failed to load system CA certificates");
    return NULL;
  }
 
  // Parse PEM certificates into BearSSL trust anchors
  anchor_list anchors = ANCHOR_LIST_INIT;
  defer(free_http_anchors(&anchors));
  size_t num_anchors = read_trust_anchors_from_memory(&anchors, (unsigned char *)pem_data, pem_size);
  SAFE_FREE(pem_data);
 
  if (num_anchors == 0) {
    log_error("No trust anchors loaded");
    return NULL;
  }
  log_info("Loaded %zu trust anchors", num_anchors);
 
  // Resolve hostname using getaddrinfo (modern, non-deprecated API)
  struct addrinfo hints, *result;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_INET; // IPv4
  hints.ai_socktype = SOCK_STREAM;
  hints.ai_protocol = IPPROTO_TCP;
 
  int dns_result;
  {
    ASCII_OTEL_SCOPE(DNS_RESOLVE);
    if (otel_scope.retained)
      gotel_attr_string(&otel_scope.scope, "dns.question.name", hostname);
    dns_result = getaddrinfo(hostname, "443", &hints, &result);
    if (dns_result && otel_scope.retained)
      gotel_error(&otel_scope.scope, "dns.error", "DNS lookup failed");
  }
  if (dns_result != 0) {
    log_error("Failed to resolve hostname: %s", hostname);
    return NULL;
  }
 
  defer(if (result) freeaddrinfo(result));
 
  // Create TCP socket
  socket_t sock = socket(result->ai_family, result->ai_socktype, result->ai_protocol);
  if (sock == INVALID_SOCKET_VALUE) {
    log_error("Failed to create socket");
    return NULL;
  }
 
  defer(if (sock != INVALID_SOCKET_VALUE) socket_close(sock));
 
  // Set socket timeouts to avoid blocking indefinitely on stalled connections.
  // Windows expects a DWORD timeout in milliseconds, while POSIX expects a
  // struct timeval. Passing timeval to Winsock makes the timeout effectively
  // a few milliseconds and commonly aborts the TLS handshake.
#ifdef _WIN32
  DWORD timeout_ms = 5000;
  setsockopt(sock, SOL_SOCKET, SO_RCVTIMEO, (const char *)&timeout_ms, sizeof(timeout_ms));
  setsockopt(sock, SOL_SOCKET, SO_SNDTIMEO, (const char *)&timeout_ms, sizeof(timeout_ms));
#else
  struct timeval timeout = {.tv_sec = 5, .tv_usec = 0};
  setsockopt(sock, SOL_SOCKET, SO_RCVTIMEO, (const char *)&timeout, sizeof(timeout));
  setsockopt(sock, SOL_SOCKET, SO_SNDTIMEO, (const char *)&timeout, sizeof(timeout));
#endif
 
  // Connect to server
  if (connect(sock, result->ai_addr, (int)result->ai_addrlen) != 0) {
    log_error("Failed to connect to %s:443", hostname);
    return NULL;
  }
 
  freeaddrinfo(result);
  result = NULL;
 
  log_info("Connected to %s:443", hostname);
 
  // Initialize BearSSL X.509 minimal validator
  br_x509_minimal_context xc;
  br_x509_minimal_init(&xc, &br_sha256_vtable, anchors.buf, anchors.ptr);
 
  // Initialize BearSSL client context
  br_ssl_client_context sc;
  br_ssl_client_init_full(&sc, &xc, anchors.buf, anchors.ptr);
 
  // Set I/O buffer
  const size_t iobuf_size = BR_SSL_BUFSIZE_BIDI;
  SAFE_MALLOC_DEFER_FREE(iobuf, iobuf_size, unsigned char *);
  br_ssl_engine_set_buffer(&sc.eng, iobuf, BR_SSL_BUFSIZE_BIDI, 1);
 
  // Initialize I/O context
  br_sslio_context ioc;
  br_sslio_init(&ioc, &sc.eng, sock_read, &sock, sock_write, &sock);
 
  // Start TLS handshake
  br_ssl_client_reset(&sc, hostname, 0);
 
  log_info("Starting TLS handshake with %s", hostname);
 
  // Build HTTP request
  char request[BUFFER_SIZE_LARGE];
  int request_len = safe_snprintf(request, sizeof(request),
                                  "GET %s HTTP/1.1\r\n"
                                  "Host: %s\r\n"
                                  "Connection: close\r\n"
                                  "User-Agent: ascii-chat/" ASCII_CHAT_VERSION_STRING "\r\n"
                                  "\r\n",
                                  path, hostname);
 
  // Send HTTP request over TLS
  if (br_sslio_write_all(&ioc, request, (size_t)request_len) != 0) {
    log_error("Failed to send HTTP request");
    return NULL;
  }
 
  br_sslio_flush(&ioc);
  log_info("Sent HTTP request");
 
  // Read HTTP response
  size_t response_capacity = 8192;
  size_t response_len = 0;
  SAFE_MALLOC_DEFER_FREE(response_buf, response_capacity, char *);
 
  while (1) {
    // Ensure we have space to read
    if (response_len + 1024 > response_capacity) {
      response_capacity *= 2;
      if (response_capacity > HTTPS_MAX_RESPONSE_SIZE) {
        log_error("Response exceeds maximum size (%d bytes)", HTTPS_MAX_RESPONSE_SIZE);
        return NULL;
      }
      response_buf = SAFE_REALLOC(response_buf, response_capacity, char *);
    }
 
    // Read data (reserve 1 byte for null terminator)
    int n = br_sslio_read(&ioc, response_buf + response_len, response_capacity - response_len - 1);
    if (n < 0) {
      // Check for TLS errors
      int err = br_ssl_engine_last_error(&sc.eng);
      if (err != BR_ERR_OK) {
        log_error("TLS error: %d", err);
        return NULL;
      }
      // EOF or connection closed
      break;
    }
    if (n == 0) {
      break; // EOF
    }
 
    response_len += (size_t)n;
  }
 
  response_buf[response_len] = '\0';
  log_info("Received %zu bytes", response_len);
 
  // Close connection
  br_sslio_close(&ioc);
  socket_close(sock);
  sock = INVALID_SOCKET_VALUE;
 
  // Parse HTTP response
  int code = parse_http_status(response_buf, response_len);
  if (code >= 0 && otel_scope.retained)
    gotel_http_attributes(&otel_scope.scope, "GET", code);
  if (code != 200) {
    if (code < 0)
      SET_ERRNO(ERROR_NETWORK, "Invalid HTTP response: %s", response_buf);
    else
      SET_ERRNO(ERROR_NETWORK, "HTTP request failed: %.50s", response_buf);
    return NULL;
  }
 
  body = extract_http_body(response_buf, response_len);
  if (body)
    ascii_otel_http_status(&otel_scope, 200);
 
  return body;
}

References ANCHOR_LIST_INIT, ascii_otel_http(), ascii_otel_http_status(), ASCII_OTEL_SCOPE, ASCIICHAT_OK, anchor_list::buf, BUFFER_SIZE_LARGE, ERROR_NETWORK, HOSTNAME_BUFFER_SIZE, hostname_to_ascii(), HTTPS_MAX_RESPONSE_SIZE, log_error, log_info, platform_load_system_ca_certs(), anchor_list::ptr, read_trust_anchors_from_memory(), SAFE_FREE, SAFE_MALLOC_DEFER_FREE, SAFE_REALLOC, safe_snprintf(), and SET_ERRNO.

Referenced by parse_public_key(), and update_check_perform().

network_error_string()

const char * network_error_string

(

)

#include <include/ascii-chat/network/network.h>

Get human-readable error string for network errors.

Returns

Error string describing last network error

Returns a human-readable description of the last network error. Useful for error logging and user-facing error messages.

Note

Error string is thread-local - each thread has its own error state.

Parameters

error_code

Error code

Returns

Error string

Definition at line 454 of file network/network.c.

                                   {
  return socket_get_error_string();
}

Referenced by socket_configure_buffers().

packet_decrypt_envelope()

asciichat_error_t packet_decrypt_envelope	(	packet_envelope_t *	envelope,
		void *	crypto_ctx )

#include <include/ascii-chat/network/packet/packet.h>

Decrypt a PACKET_TYPE_ENCRYPTED envelope and extract inner packet.

If the envelope contains PACKET_TYPE_ENCRYPTED, decrypts the payload and updates the envelope with the inner packet (type, data, length). Used by both TCP and non-socket (WebRTC) transports to handle encryption uniformly.

Parameters

envelope	Packet envelope to decrypt (will be modified if encrypted)
crypto_ctx	Crypto context for decryption (required if envelope is encrypted)

Returns

ASCIICHAT_OK on success, error code otherwise

Note

Updates envelope->type, envelope->data, envelope->len, and envelope->allocated_buffer to point to decrypted plaintext

Caller must free the updated envelope->allocated_buffer

Decrypt a PACKET_TYPE_ENCRYPTED envelope and extract inner packet.

Parameters

sockfd

Socket file descriptor

Returns

0 on success, -1 on error

Decrypt a PACKET_TYPE_ENCRYPTED envelope and extract inner packet

Shared decryption logic for both TCP (receive_packet_secure) and non-socket (WebRTC) transports. Decrypts PACKET_TYPE_ENCRYPTED envelopes and updates the envelope with the inner packet type and data.

Parameters

envelope	Packet envelope to decrypt (will be modified if encrypted)
crypto_ctx	Crypto context for decryption (required if envelope is encrypted)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 665 of file packet.c.

                                                                                         {
  if (!envelope) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid envelope");
  }
 
  // Only decrypt if this is an encrypted packet
  if (envelope->type != PACKET_TYPE_ENCRYPTED) {
    return ASCIICHAT_OK; // Not encrypted, nothing to do
  }
 
  if (!crypto_ctx) {
    return SET_ERRNO(ERROR_CRYPTO, "Received encrypted packet but no crypto context");
  }
 
  uint8_t *plaintext = NULL;
  size_t plaintext_length = 0;
  bool consumed = false;
  asciichat_error_t result =
      acip_security_decrypt(crypto_ctx, CRYPTO_RECORD_ANY_CHANNEL, CRYPTO_RECORD_RELIABLE, envelope->data,
                            envelope->len, &plaintext, &plaintext_length, NULL, &consumed);
  if (result != ASCIICHAT_OK)
    return result;
  packet_header_t header;
  memcpy(&header, plaintext, sizeof(header));
  if (envelope->allocated_buffer && buffer_is_unique(envelope->allocated_buffer) &&
      envelope->allocated_size >= plaintext_length) {
    memcpy(envelope->allocated_buffer, plaintext, plaintext_length);
    buffer_release(plaintext);
    plaintext = envelope->allocated_buffer;
  } else {
    buffer_release(envelope->allocated_buffer);
    envelope->allocated_size = buffer_capacity(plaintext);
  }
  envelope->type = NET_TO_HOST_U16(header.type);
  envelope->data = plaintext + sizeof(header);
  envelope->len = plaintext_length - sizeof(header);
  envelope->allocated_buffer = plaintext;
  envelope->was_encrypted = true;
  envelope->consumed = consumed;
  return ASCIICHAT_OK;
}

References acip_security_decrypt(), ASCIICHAT_OK, buffer_capacity(), buffer_is_unique(), buffer_release, CRYPTO_RECORD_ANY_CHANNEL, CRYPTO_RECORD_RELIABLE, ERROR_CRYPTO, ERROR_INVALID_PARAM, NET_TO_HOST_U16, PACKET_TYPE_ENCRYPTED, and SET_ERRNO.

Referenced by acds_receive_packet(), packet_receive_via_transport(), and receive_packet_secure_with_timeout().

packet_encode()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 67 of file packet.c.

                                                                                {
  if (!output || !written)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing packet output");
  *written = 0;
  if (capacity < sizeof(packet_header_t) || length > capacity - sizeof(packet_header_t))
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet output is too small");
  socket_buffer_t slice = {payload, length};
  packet_header_t header;
  asciichat_error_t result = packet_header_build(&header, type, &slice, 1, client_id);
  if (result != ASCIICHAT_OK)
    return result;
  if (length)
    memmove((uint8_t *)output + sizeof(header), payload, length);
  memcpy(output, &header, sizeof(header));
  *written = sizeof(header) + length;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, packet_header_build(), and SET_ERRNO.

Referenced by acip_security_rekey_encode().

packet_format_error_stack()

size_t packet_format_error_stack	(	char *	buffer,
		size_t	size )

#include <include/ascii-chat/network/packet/packet.h>

Format the current thread's error stack for transport to a peer.

Parameters

buffer	Destination buffer
size	Destination buffer size

Returns

Number of bytes written, excluding the null terminator

Definition at line 707 of file packet.c.

                                                            {
  if (!buffer || size == 0)
    return 0;
  buffer[0] = '\0';
  asciichat_error_context_t frames[ASCIICHAT_ERRNO_MAX_DEPTH];
  size_t frame_count = errno_snapshot(thread_current_id(), frames, ASCIICHAT_ERRNO_MAX_DEPTH).copied;
  size_t offset = 0;
  for (size_t i = 0; i < frame_count && offset < size - 1; ++i) {
    const asciichat_error_context_t *frame = &frames[i];
    const char *file = extract_project_relative_path(frame->file, ASCIICHAT_OWNED_SOURCE_DIRS);
#ifdef NDEBUG
    int written = snprintf(buffer + offset, size - offset, "%s%s (%s:%d in %s())", i ? "\n" : "",
                           frame->context_message, file, frame->line, frame->function ? frame->function : "<unknown>");
#else
    int written = snprintf(buffer + offset, size - offset, "%s%s (%s:%d in %s())\tfull-path=%s", i ? "\n" : "",
                           frame->context_message, file, frame->line, frame->function ? frame->function : "<unknown>",
                           frame->file ? frame->file : "");
#endif
    if (written < 0)
      break;
    size_t available = size - offset;
    offset += (size_t)written < available ? (size_t)written : available - 1;
  }
  return offset;
}

References ASCIICHAT_ERRNO_MAX_DEPTH, asciichat_error_context_t::context_message, asciichat_errno_snapshot_t::copied, errno_snapshot(), extract_project_relative_path(), asciichat_error_context_t::file, asciichat_error_context_t::function, and asciichat_error_context_t::line.

packet_header_build()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Shared ACIP wire codec. Headers are returned in network byte order.

Definition at line 47 of file packet.c.

                                                                        {
  if (!header || (!payload && count) || count > SOCKET_IOV_MAX)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet header arguments");
  size_t length = 0;
  uint32_t crc = 0;
  for (size_t i = 0; i < count; ++i) {
    if ((!payload[i].data && payload[i].len) || payload[i].len > MAX_PACKET_SIZE - length)
      return SET_ERRNO(ERROR_NETWORK_SIZE, "Invalid packet payload size");
    length += payload[i].len;
    crc = asciichat_crc32_update(crc, payload[i].data, payload[i].len);
  }
  *header = (packet_header_t){.magic = HOST_TO_NET_U64(PACKET_MAGIC),
                              .type = HOST_TO_NET_U16(type),
                              .length = HOST_TO_NET_U32((uint32_t)length),
                              .crc32 = HOST_TO_NET_U32(crc),
                              .client_id = HOST_TO_NET_U32(client_id)};
  return ASCIICHAT_OK;
}

References asciichat_crc32_update(), ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, HOST_TO_NET_U16, HOST_TO_NET_U32, HOST_TO_NET_U64, MAX_PACKET_SIZE, PACKET_MAGIC, and SET_ERRNO.

Referenced by acip_packet_encrypt(), packet_encode(), packet_send_via_transportv(), and send_packet_secure().

packet_parse_error_message()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Parse an error packet payload into components.

Parameters

data	Packet payload buffer
len	Payload length in bytes
out_error_code	Output pointer for asciichat_error_t value (must not be NULL)
message_buffer	Destination buffer for message string (must not be NULL)
message_buffer_size	Size of destination buffer in bytes (must be > 0)
out_message_length	Optional output for message length reported by sender

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 782 of file packet.c.

                                                                         {
  if (!data || len < sizeof(error_packet_t) || !out_error_code || !message_buffer || message_buffer_size == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "Invalid parameters: data=%p len=%zu out_error_code=%p message_buffer=%p buffer_size=%zu", data,
                     len, out_error_code, message_buffer, message_buffer_size);
  }
 
  const error_packet_t *packet = (const error_packet_t *)data;
  uint32_t raw_error_code = NET_TO_HOST_U32(packet->error_code);
  uint32_t raw_message_length = NET_TO_HOST_U32(packet->message_length);
 
  if (raw_message_length > MAX_ERROR_MESSAGE_LENGTH) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Error message length too large: %u", raw_message_length);
  }
 
  size_t total_required = sizeof(error_packet_t) + (size_t)raw_message_length;
  if (total_required > len) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Error packet truncated: expected %zu bytes, have %zu", total_required,
                     len);
  }
 
  const uint8_t *message_bytes = (const uint8_t *)data + sizeof(error_packet_t);
  size_t copy_len = raw_message_length;
  if (copy_len >= message_buffer_size) {
    copy_len = message_buffer_size - 1;
  }
 
  if (copy_len > 0) {
    memcpy(message_buffer, message_bytes, copy_len);
  }
  message_buffer[copy_len] = '\0';
 
  if (out_message_length) {
    *out_message_length = raw_message_length;
  }
 
  *out_error_code = (asciichat_error_t)raw_error_code;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, error_packet_t::error_code, ERROR_INVALID_PARAM, ERROR_NETWORK_PROTOCOL, MAX_ERROR_MESSAGE_LENGTH, error_packet_t::message_length, NET_TO_HOST_U32, and SET_ERRNO.

Referenced by network_error_decode().

packet_parse_remote_log()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Parse a remote log packet payload into components.

Parameters

data	Packet payload buffer
len	Payload length in bytes
out_level	Output pointer for log level (must not be NULL)
out_direction	Output pointer for direction (must not be NULL)
out_flags	Output pointer for flags (must not be NULL)
message_buffer	Destination buffer for message string (must not be NULL)
message_buffer_size	Size of destination buffer in bytes (must be > 0)
out_message_length	Optional output for message length reported by sender

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 881 of file packet.c.

                                                                      {
  if (!data || len < sizeof(remote_log_packet_t) || !out_level || !out_direction || !out_flags || !message_buffer ||
      message_buffer_size == 0) {
    return SET_ERRNO(
        ERROR_INVALID_PARAM,
        "Invalid parameters: data=%p len=%zu out_level=%p out_direction=%p out_flags=%p buffer=%p size=%zu", data, len,
        out_level, out_direction, out_flags, message_buffer, message_buffer_size);
  }
 
  const remote_log_packet_t *packet = (const remote_log_packet_t *)data;
  uint8_t raw_level = packet->log_level;
  if (raw_level > LOG_FATAL) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid remote log level: %u", raw_level);
  }
  *out_level = (log_level_t)raw_level;
 
  uint8_t raw_direction = packet->direction;
  if (raw_direction > REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER) {
    raw_direction = REMOTE_LOG_DIRECTION_UNKNOWN;
  }
  *out_direction = (remote_log_direction_t)raw_direction;
 
  uint16_t raw_flags = NET_TO_HOST_U16(packet->flags);
  *out_flags = raw_flags;
 
  uint32_t raw_message_length = NET_TO_HOST_U32(packet->message_length);
  if (raw_message_length > MAX_REMOTE_LOG_MESSAGE_LENGTH) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Remote log message length too large: %u", raw_message_length);
  }
 
  size_t total_required = sizeof(remote_log_packet_t) + (size_t)raw_message_length;
  if (total_required > len) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Remote log packet truncated: expected %zu bytes, have %zu",
                     total_required, len);
  }
 
  const uint8_t *message_bytes = (const uint8_t *)data + sizeof(remote_log_packet_t);
  size_t copy_len = raw_message_length;
  if (copy_len >= message_buffer_size) {
    copy_len = message_buffer_size - 1;
  }
 
  if (copy_len > 0) {
    memcpy(message_buffer, message_bytes, copy_len);
  }
  message_buffer[copy_len] = '\0';
 
  if (out_message_length) {
    *out_message_length = raw_message_length;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, remote_log_packet_t::direction, ERROR_INVALID_PARAM, ERROR_NETWORK_PROTOCOL, remote_log_packet_t::flags, LOG_FATAL, remote_log_packet_t::log_level, MAX_REMOTE_LOG_MESSAGE_LENGTH, remote_log_packet_t::message_length, NET_TO_HOST_U16, NET_TO_HOST_U32, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER, REMOTE_LOG_DIRECTION_UNKNOWN, and SET_ERRNO.

Referenced by handle_remote_log_packet_from_client().

packet_receive()

asciichat_error_t packet_receive	(	socket_t	sockfd,
		packet_type_t *	type,
		void **	data,
		size_t *	len )

#include <include/ascii-chat/network/packet/packet.h>

Receive a packet with header validation and CRC32 checking.

Parameters

sockfd	Socket file descriptor
type	Output: Packet type
data	Output: Packet payload data (allocated by function, freed by caller)
len	Output: Payload data length in bytes

Returns

ASCIICHAT_OK on success, error code on failure

Receives a complete packet, validates header, and verifies CRC32 checksum. Allocates buffer for payload data which must be freed by caller.

Note

Allocates buffer for payload data - caller must free when done.

Validates magic number and CRC32 checksum before returning data.

Warning

Allocated data buffer must be freed by caller to prevent memory leaks.

Receive a packet with header validation and CRC32 checking.

Parameters

sockfd	Socket file descriptor
type	Output: packet type
data	Output: packet data (allocated by caller, freed by caller)
len	Output: data length

Returns

0 on success, -1 on error

Definition at line 407 of file packet.c.

                                                                                                 {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
  }
  if (!type || !data || !len) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: type=%p, data=%p, len=%p", type, data, len);
  }
 
  // Read packet header into memory from network socket
  packet_header_t header;
  uint64_t header_timeout_ns = RECV_TIMEOUT * NS_PER_SEC_INT;
  ssize_t received = recv_with_timeout(sockfd, &header, sizeof(header), header_timeout_ns);
  if (received < 0) {
    // Error context is already set by recv_with_timeout
    return ERROR_NETWORK;
  }
  if ((size_t)received != sizeof(header)) {
    if (received == 0) {
      log_warn("Connection closed while reading packet header");
      return SET_ERRNO(ERROR_NETWORK, "Connection closed by peer while reading packet header");
    }
 
    return SET_ERRNO(ERROR_NETWORK, "Partial packet header received: %zd/%zu bytes", received, sizeof(header));
  }
 
  // Validate packet header
  uint16_t pkt_type;
  uint32_t pkt_len;
  uint32_t expected_crc;
  if (packet_validate_header(&header, &pkt_type, &pkt_len, &expected_crc) != ASCIICHAT_OK) {
    // Error context is already set by packet_validate_header
    return ERROR_NETWORK_PROTOCOL;
  }
 
  // Allocate buffer for payload
  void *payload = NULL;
  defer_named(release_payload, buffer_release(payload));
  if (pkt_len > 0) {
    payload = buffer_alloc(
        packet_is_handshake_type(pkt_type) || pkt_type == PACKET_TYPE_ERROR_MESSAGE ? buffer_control_domain() : NULL,
        pkt_len);
    if (!payload)
      return SET_ERRNO(ERROR_MEMORY, "Packet payload exceeds buffer budget");
 
    // Use adaptive timeout for large packets
    uint64_t recv_timeout = packet_send_timeout_ns(pkt_len);
    received = recv_with_timeout(sockfd, payload, pkt_len, recv_timeout);
    if (received < 0) {
      return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to receive packet payload");
    }
    if (received != (ssize_t)pkt_len) {
      return SET_ERRNO(ERROR_NETWORK, "Partial packet payload received: %zd/%u bytes", received, pkt_len);
    }
 
    // Validate CRC32
    if (packet_validate_crc32(payload, pkt_len, expected_crc) != ASCIICHAT_OK) {
      // Error context is already set by packet_validate_crc32
      return ERROR_NETWORK_PROTOCOL;
    }
  }
 
  // Return results
  *type = (packet_type_t)pkt_type;
  *data = payload;
  defer_cancel(release_payload);
  *len = pkt_len;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_alloc(), buffer_control_domain(), buffer_release, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, log_warn, NS_PER_SEC_INT, packet_send_timeout_ns(), PACKET_TYPE_ERROR_MESSAGE, RECV_TIMEOUT, recv_with_timeout(), SET_ERRNO, and SET_ERRNO_SYS.

Referenced by receive_packet().

packet_send()

asciichat_error_t packet_send	(	socket_t	sockfd,
		packet_type_t	type,
		const void *	data,
		size_t	len )

#include <include/ascii-chat/network/packet/packet.h>

Send a packet with header and CRC32 checksum.

Parameters

sockfd	Socket file descriptor
type	Packet type (from packet_types.h)
data	Packet payload data (can be NULL for header-only packets)
len	Payload data length in bytes

Returns

ASCIICHAT_OK on success, error code on failure

Sends a complete packet with header (magic, type, length, CRC32) and optional payload. CRC32 is computed automatically and included in header.

Note

Packet header is constructed with all required fields including magic number, type, length, CRC32, and client ID.

CRC32 is computed over payload data (or zero if data is NULL).

Send a packet with header and CRC32 checksum.

Parameters

sockfd	Socket file descriptor
type	Packet type
data	Packet data
len	Data length

Returns

0 on success, -1 on error

Definition at line 366 of file packet.c.

                                                                                                 {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
  }
 
  if (len > MAX_PACKET_SIZE) {
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: %zu > %d", len, MAX_PACKET_SIZE);
  }
 
  if (len && !data)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing packet payload");
  packet_header_t header = {.magic = HOST_TO_NET_U64(PACKET_MAGIC),
                            .type = HOST_TO_NET_U16((uint16_t)type),
                            .length = HOST_TO_NET_U32((uint32_t)len),
                            .crc32 = HOST_TO_NET_U32(len > 0 ? asciichat_crc32(data, len) : 0),
                            .client_id = HOST_TO_NET_U32(0)}; // Always initialize client_id to 0 in network byte order
 
  // Calculate timeout based on packet size (in nanoseconds)
  uint64_t timeout = packet_send_timeout_ns(len);
 
  socket_buffer_t slices[] = {{&header, sizeof(header)}, {data, len}};
  asciichat_error_t result = socket_sendv_all(sockfd, slices, 2, timeout);
  if (result != ASCIICHAT_OK)
    return result;
 
#ifdef DEBUG_NETWORK
  log_debug_every(US_PER_SEC_INT, "Sent packet type=%d, len=%zu, errno=%d (%s)", type, len, errno,
                  SAFE_STRERROR(errno));
#endif
 
  return 0;
}

References asciichat_crc32, ASCIICHAT_OK, errno, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, HOST_TO_NET_U16, HOST_TO_NET_U32, HOST_TO_NET_U64, log_debug_every, MAX_PACKET_SIZE, PACKET_MAGIC, packet_send_timeout_ns(), SAFE_STRERROR, SET_ERRNO, and US_PER_SEC_INT.

Referenced by packet_send_error(), packet_send_remote_log(), send_image_frame_packet(), send_packet(), and send_packet_secure().

packet_send_error()

asciichat_error_t packet_send_error	(	socket_t	sockfd,
		const crypto_context_t *	crypto_ctx,
		asciichat_error_t	error_code,
		const char *	message )

#include <include/ascii-chat/network/packet/packet.h>

Send an error packet with optional encryption context.

Parameters

sockfd	Socket file descriptor
crypto_ctx	Crypto context for encryption (NULL or not ready sends plaintext)
error_code	Error code from asciichat_error_t enumeration
message	Legacy argument; fixed public text is sent for the allowlisted error code

Returns

ASCIICHAT_OK on success, error code otherwise

When the crypto context is ready, the packet is encrypted automatically. During the handshake (or when encryption is disabled), the packet is sent in plaintext so protocol errors can be delivered before encryption is active.

Definition at line 733 of file packet.c.

                                                         {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
  }
 
  error_code = network_error_public_code(error_code);
  // This packet is valid before peer authentication, so use only the public
  // error description rather than contextual errno data.
  (void)message;
  message = asciichat_error_string(error_code);
 
  size_t message_len = strnlen(message, MAX_ERROR_MESSAGE_LENGTH);
  if (message_len == MAX_ERROR_MESSAGE_LENGTH) {
    log_warn("Error message truncated to %zu bytes", (size_t)MAX_ERROR_MESSAGE_LENGTH);
  }
 
  size_t payload_len = sizeof(error_packet_t) + message_len;
  uint8_t *payload = SAFE_MALLOC(payload_len, uint8_t *);
  if (!payload) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate %zu bytes for error packet", payload_len);
  }
 
  error_packet_t *packet = (error_packet_t *)payload;
  packet->error_code = HOST_TO_NET_U32((uint32_t)error_code);
  packet->message_length = HOST_TO_NET_U32((uint32_t)message_len);
 
  if (message_len > 0) {
    memcpy(payload + sizeof(error_packet_t), message, message_len);
  }
 
  bool encryption_ready = crypto_ctx && crypto_ctx->encrypt_data && crypto_is_ready(crypto_ctx);
  asciichat_error_t send_result;
 
  if (encryption_ready) {
    send_result =
        send_packet_secure(sockfd, PACKET_TYPE_ERROR_MESSAGE, payload, payload_len, (crypto_context_t *)crypto_ctx);
  } else {
    send_result = packet_send(sockfd, PACKET_TYPE_ERROR_MESSAGE, payload, payload_len);
  }
  SAFE_FREE(payload);
 
  if (send_result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to send error packet: %s", asciichat_error_string(send_result));
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, crypto_is_ready(), crypto_context_t::encrypt_data, error_packet_t::error_code, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, HOST_TO_NET_U32, log_warn, MAX_ERROR_MESSAGE_LENGTH, error_packet_t::message_length, network_error_public_code(), packet_send(), PACKET_TYPE_ERROR_MESSAGE, SAFE_FREE, SAFE_MALLOC, send_packet_secure(), and SET_ERRNO.

packet_send_remote_log()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Send a remote log packet with optional encryption context.

Parameters

sockfd	Socket file descriptor
crypto_ctx	Crypto context for encryption (NULL or not ready sends plaintext)
level	Log level to transmit
direction	Direction flag (REMOTE_LOG_DIRECTION_*)
flags	Additional flags (REMOTE_LOG_FLAG_*)
message	Log message text

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 824 of file packet.c.

                                                                                                                {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
  }
 
  if (level < LOG_DEV || level > LOG_FATAL) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid log level: %d", level);
  }
 
  const char *safe_message = message ? message : "";
  bool truncated = false;
  size_t message_len = strnlen(safe_message, MAX_REMOTE_LOG_MESSAGE_LENGTH);
  if (message_len == MAX_REMOTE_LOG_MESSAGE_LENGTH && safe_message[message_len] != '\0') {
    truncated = true;
  }
 
  size_t payload_len = sizeof(remote_log_packet_t) + message_len;
  uint8_t *payload = SAFE_MALLOC(payload_len, uint8_t *);
  if (!payload) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate %zu bytes for remote log packet", payload_len);
  }
 
  remote_log_packet_t *packet = (remote_log_packet_t *)payload;
  packet->log_level = (uint8_t)level;
  packet->direction = (uint8_t)direction;
  uint16_t final_flags = flags;
  if (truncated) {
    final_flags |= REMOTE_LOG_FLAG_TRUNCATED;
  }
  packet->flags = HOST_TO_NET_U16(final_flags);
  packet->message_length = HOST_TO_NET_U32((uint32_t)message_len);
 
  if (message_len > 0) {
    memcpy(payload + sizeof(remote_log_packet_t), safe_message, message_len);
  }
 
  bool encryption_ready = crypto_ctx && crypto_ctx->encrypt_data && crypto_is_ready(crypto_ctx);
  asciichat_error_t send_result;
 
  if (encryption_ready) {
    int secure_result =
        send_packet_secure(sockfd, PACKET_TYPE_REMOTE_LOG, payload, payload_len, (crypto_context_t *)crypto_ctx);
    send_result = secure_result == 0 ? ASCIICHAT_OK : ERROR_NETWORK;
  } else {
    send_result = packet_send(sockfd, PACKET_TYPE_REMOTE_LOG, payload, payload_len);
  }
 
  SAFE_FREE(payload);
 
  if (send_result != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to send remote log packet: %d", send_result);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, crypto_is_ready(), remote_log_packet_t::direction, crypto_context_t::encrypt_data, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, remote_log_packet_t::flags, HOST_TO_NET_U16, HOST_TO_NET_U32, LOG_FATAL, remote_log_packet_t::log_level, MAX_REMOTE_LOG_MESSAGE_LENGTH, remote_log_packet_t::message_length, packet_send(), PACKET_TYPE_REMOTE_LOG, REMOTE_LOG_FLAG_TRUNCATED, SAFE_FREE, SAFE_MALLOC, send_packet_secure(), and SET_ERRNO.

packet_validate()

asciichat_error_t packet_validate	(	const void *	packet,
		size_t	length,
		size_t	limit,
		packet_header_t *	header )

#include <include/ascii-chat/network/packet/packet.h>

Validate exactly one complete packet, including the empty-payload checksum. A zero limit uses MAX_PACKET_SIZE. The optional header output is a copy.

Definition at line 86 of file packet.c.

                                                                                                            {
  if (!packet || length < sizeof(packet_header_t))
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Incomplete packet header");
  packet_header_t header;
  memcpy(&header, packet, sizeof(header));
  size_t payload = length - sizeof(header);
  if (NET_TO_HOST_U64(header.magic) != PACKET_MAGIC || NET_TO_HOST_U32(header.length) != payload ||
      payload > (limit ? limit : MAX_PACKET_SIZE))
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid packet framing or size");
  if (asciichat_crc32((const uint8_t *)packet + sizeof(header), payload) != NET_TO_HOST_U32(header.crc32))
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Packet CRC mismatch");
  if (output)
    *output = header;
  return ASCIICHAT_OK;
}

References asciichat_crc32, ASCIICHAT_OK, ERROR_NETWORK_PROTOCOL, MAX_PACKET_SIZE, NET_TO_HOST_U32, NET_TO_HOST_U64, PACKET_MAGIC, and SET_ERRNO.

Referenced by acip_packet_open_sequence(), acip_security_open(), acip_security_rekey_receive(), packet_decoder_feed(), packet_receive_via_transport(), peer_crypto_receive(), and receive_packet_secure_with_timeout().

protocol_version_packet_init()

void protocol_version_packet_init	(	protocol_version_packet_t *	version,
		uint8_t	supports_encryption )

#include <include/ascii-chat/network/packet/packet.h>

Initialize a protocol version packet with the current wire version.

Parameters

version	Packet to initialize.
supports_encryption	ACIP encryption/authentication capability mask.

Definition at line 37 of file packet.c.

                                                                                                   {
  if (!version)
    return;
  memset(version, 0, sizeof(*version));
  version->protocol_version = HOST_TO_NET_U16(PROTOCOL_VERSION_MAJOR);
  version->protocol_revision = HOST_TO_NET_U16(PROTOCOL_VERSION_MINOR);
  version->protocol_patch = HOST_TO_NET_U16(PROTOCOL_VERSION_PATCH);
  version->supports_encryption = supports_encryption;
}

References HOST_TO_NET_U16, protocol_version_packet_t::protocol_patch, protocol_version_packet_t::protocol_revision, protocol_version_packet_t::protocol_version, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, PROTOCOL_VERSION_PATCH, and protocol_version_packet_t::supports_encryption.

Referenced by acds_handshake_begin(), and acip_security_start().

receive_packet()

int receive_packet	(	socket_t	sockfd,
		packet_type_t *	type,
		void **	data,
		size_t *	len )

#include <include/ascii-chat/network/packet/packet.h>

Receive a basic packet without encryption.

Parameters

sockfd	Socket file descriptor
type	Output: Packet type
data	Output: Packet payload data (allocated by function)
len	Output: Payload data length in bytes

Returns

0 on success, -1 on error

Receives a plaintext packet without decryption. Allocates buffer for payload data which must be freed by caller.

Note

Use receive_packet_secure() if decryption support is needed.

Warning

Allocated data buffer must be freed by caller.

Parameters

sockfd	Socket file descriptor
type	Output: packet type
data	Output: packet data
len	Output: data length

Returns

0 on success, -1 on error

Definition at line 620 of file packet.c.

                                                                                   {
  asciichat_error_t result = packet_receive(sockfd, type, data, len);
  return result == ASCIICHAT_OK ? 0 : -1;
}

References ASCIICHAT_OK, and packet_receive().

receive_packet_secure()

packet_recv_result_t receive_packet_secure	(	socket_t	sockfd,
		void *	crypto_ctx,
		bool	enforce_encryption,
		packet_envelope_t *	envelope )

#include <include/ascii-chat/network/packet/packet.h>

Receive a packet with decryption and decompression support.

Parameters

sockfd	Socket file descriptor
crypto_ctx	Cryptographic context for decryption (NULL for plaintext)
enforce_encryption	If true, reject unencrypted packets (except handshake)
envelope	Output: Received packet envelope with all metadata

Returns

PACKET_RECV_SUCCESS on success, error code on failure

Receives a packet with automatic decryption (if encrypted) and decompression (if compressed). Validates encryption policy and packet integrity.

Note

Decryption is applied automatically when packet is encrypted and crypto_ctx is provided.

Decompression is applied automatically when packet is compressed.

If enforce_encryption is true, unencrypted packets (except handshake packets) cause PACKET_RECV_SECURITY_VIOLATION.

Warning

Envelope's allocated_buffer must be freed by caller to prevent memory leaks.

Parameters

sockfd	Socket file descriptor
crypto_ctx	Crypto context for decryption
enforce_encryption	Whether to require encryption
envelope	Output: received packet envelope

Returns

Packet receive result

Definition at line 587 of file packet.c.

                                                                        {
  return receive_packet_secure_with_timeout(sockfd, crypto_ctx, enforce_encryption, envelope,
                                            RECV_TIMEOUT * NS_PER_SEC_INT);
}

References NS_PER_SEC_INT, receive_packet_secure_with_timeout(), and RECV_TIMEOUT.

receive_packet_secure_with_timeout()

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 )

#include <include/ascii-chat/network/packet/packet.h>

Definition at line 1114 of file packet.c.

                                                                                                          {
  if (!envelope) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Missing packet envelope");
    return PACKET_RECV_ERROR;
  }
  *envelope = (packet_envelope_t){0};
  packet_header_t header;
  ssize_t received = recv_with_timeout(sockfd, &header, sizeof(header), timeout_ns);
  if (!received)
    return PACKET_RECV_EOF;
  if (received != (ssize_t)sizeof(header))
    return PACKET_RECV_ERROR;
  size_t payload_length = NET_TO_HOST_U32(header.length);
  if (NET_TO_HOST_U64(header.magic) != PACKET_MAGIC || payload_length > MAX_PACKET_SIZE) {
    SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid packet header");
    return PACKET_RECV_ERROR;
  }
  size_t length = sizeof(header) + payload_length;
  uint8_t *packet = buffer_alloc(NULL, length);
  if (!packet) {
    SET_ERRNO(ERROR_MEMORY, "Cannot allocate received packet");
    return PACKET_RECV_ERROR;
  }
  memcpy(packet, &header, sizeof(header));
  if (payload_length &&
      recv_with_timeout(sockfd, packet + sizeof(header), payload_length,
                        MAX(timeout_ns, packet_send_timeout_ns(payload_length))) != (ssize_t)payload_length) {
    buffer_release(packet);
    // The header has already been consumed, so even an idle payload timeout
    // leaves the byte stream out of sync and must close the connection.
    SET_ERRNO(ERROR_NETWORK, "Incomplete packet payload after receiving header");
    return PACKET_RECV_ERROR;
  }
  asciichat_error_t result = packet_validate(packet, length, MAX_PACKET_SIZE, NULL);
  packet_type_t type = NET_TO_HOST_U16(header.type);
  if (result == ASCIICHAT_OK && enforce_encryption && type != PACKET_TYPE_ENCRYPTED &&
      !packet_is_initial_handshake_type(type))
    result = SET_ERRNO(ERROR_CRYPTO, "Unencrypted packet in encrypted session");
  if (result != ASCIICHAT_OK) {
    buffer_release(packet);
    return PACKET_RECV_ERROR;
  }
  *envelope = (packet_envelope_t){
      .type = type, .data = packet, .len = length, .allocated_buffer = packet, .allocated_size = length};
  if (type == PACKET_TYPE_ENCRYPTED) {
    envelope->data = packet + sizeof(header);
    envelope->len = payload_length;
    result = packet_decrypt_envelope(envelope, crypto_ctx);
    if (result != ASCIICHAT_OK) {
      buffer_release(envelope->allocated_buffer);
      *envelope = (packet_envelope_t){0};
      return PACKET_RECV_ERROR;
    }
  }
  return PACKET_RECV_SUCCESS;
}

References ASCIICHAT_OK, buffer_alloc(), buffer_release, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, MAX, MAX_PACKET_SIZE, NET_TO_HOST_U16, NET_TO_HOST_U32, NET_TO_HOST_U64, packet_decrypt_envelope(), PACKET_MAGIC, PACKET_RECV_EOF, PACKET_RECV_ERROR, PACKET_RECV_SUCCESS, packet_send_timeout_ns(), PACKET_TYPE_ENCRYPTED, packet_validate(), recv_with_timeout(), and SET_ERRNO.

Referenced by receive_packet_secure().

recv_with_timeout()

ssize_t recv_with_timeout	(	socket_t	sockfd,
		void *	buf,
		size_t	len,
		uint64_t	timeout_ns )

#include <include/ascii-chat/network/network.h>

Receive data with timeout.

Parameters

sockfd	Socket file descriptor
buf	Buffer to receive data
len	Length of buffer in bytes
timeout_ns	Timeout in nanoseconds

Returns

Number of bytes received on success, -1 on error

Receives data from socket with timeout support. Waits up to timeout_ns for data to arrive.

Note

Partial receives are possible - function returns number of bytes actually received.

Returns -1 on timeout or error. Use network_error_string() to get human-readable error description.

Parameters

sockfd	Socket file descriptor
buf	Buffer to receive data
len	Length of buffer
timeout_seconds	Timeout in seconds

Returns

Number of bytes received, or -1 on error

Definition at line 178 of file network/network.c.

                                                                                       {
  if (sockfd == INVALID_SOCKET_VALUE) {
    errno = EBADF;
    return -1;
  }
 
  ssize_t total_received = 0;
  char *data = (char *)buf;
  uint64_t receive_start = time_get_ns();
 
  while (total_received < (ssize_t)len) {
    // Set up poll for read timeout (in nanoseconds)
    struct pollfd pfd;
    pfd.fd = sockfd;
    pfd.events = POLLIN;
    pfd.revents = 0;
 
    // Use provided timeout for recv() calls - don't artificially limit data packets in test mode
    // Timeouts should only apply to initial handshake, not to receiving data on active connections
    uint64_t elapsed = time_get_ns() - receive_start;
    if (elapsed >= timeout_ns) {
      SET_ERRNO(total_received ? ERROR_NETWORK : ERROR_NETWORK_TIMEOUT, "Receive deadline expired");
      return -1;
    }
    int result = socket_poll(&pfd, 1, (int64_t)(timeout_ns - elapsed));
    if (result <= 0) {
      if (result == 0) {
        /* A read timeout is the ordinary idle state for signaling sockets.
         * Do not emit an error on every polling interval. */
        errno_set_with_system_error(ERROR_NETWORK_TIMEOUT, __FILE__, __LINE__, __func__, ETIMEDOUT);
        if (total_received > 0)
          SET_ERRNO(ERROR_NETWORK, "Receive timed out after consuming %zd/%zu bytes", total_received, len);
        return -1;
      }
      if (network_handle_select_error(result)) {
        continue; // Retry
      }
      return -1; // Fatal error
    }
 
    // Poll can return readiness for a hangup or socket error without POLLIN.
    // Treat those as terminal network errors so callers tear down the dead
    // connection instead of retrying it as an idle timeout in a tight loop.
    // Linux zerocopy completions also raise POLLERR with SO_ERROR == 0.
    // The serialized sender owns the error queue and will consume those events.
    if ((pfd.revents & POLLERR) && !(pfd.revents & (POLLHUP | POLLNVAL))) {
      int socket_error = 0;
      socklen_t error_len = sizeof(socket_error);
      if (socket_getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &socket_error, &error_len) == 0 && !socket_error) {
        pfd.revents &= (short)~POLLERR;
        if (!(pfd.revents & POLLIN)) {
          platform_sleep_ns(NS_PER_MS_INT);
          continue;
        }
      }
    }
    if (pfd.revents & (POLLERR | POLLNVAL)) {
      SET_ERRNO(ERROR_NETWORK, "poll reported socket flags 0x%x", pfd.revents);
      return -1;
    }
    // A drained asynchronous writer may close while readable bytes remain.
    // Consume POLLIN before treating POLLHUP as EOF (notably WSAPoll).
    if ((pfd.revents & POLLHUP) && !(pfd.revents & POLLIN))
      return total_received;
 
    // Other readiness flags without POLLIN are an ordinary no-data result.
    if (!(pfd.revents & POLLIN)) {
      errno_set_with_system_error(ERROR_NETWORK_TIMEOUT, __FILE__, __LINE__, __func__, ETIMEDOUT);
      if (total_received > 0)
        SET_ERRNO(ERROR_NETWORK, "Receive stalled after consuming %zd/%zu bytes", total_received, len);
      return -1;
    }
 
    // Calculate how much we still need to receive
    size_t bytes_to_recv = len - (size_t)total_received;
    ssize_t received = socket_recv(sockfd, data + total_received, bytes_to_recv, 0);
 
    if (received < 0) {
      int error = errno;
      if (network_handle_recv_error(error)) {
        continue; // Retry
      }
      return -1; // Fatal error
    }
 
    if (received == 0) {
      // Connection closed by peer
      log_debug("Connection closed by peer during recv");
      return total_received; // Return what we got so far
    }
 
    total_received += received;
  }
 
  return total_received;
}

References EBADF, errno, errno_set_with_system_error(), ERROR_NETWORK, ERROR_NETWORK_TIMEOUT, ETIMEDOUT, log_debug, NS_PER_MS_INT, and SET_ERRNO.

Referenced by packet_receive(), and receive_packet_secure_with_timeout().

send_crypto_capabilities_packet()

int send_crypto_capabilities_packet	(	socket_t	sockfd,
		const crypto_capabilities_packet_t *	caps )

#include <include/ascii-chat/network/packet/packet.h>

Send crypto capabilities packet.

Parameters

sockfd	Socket file descriptor
caps	Crypto capabilities packet structure

Returns

0 on success, -1 on error

Sends a PACKET_TYPE_CRYPTO_CAPABILITIES packet to advertise supported cryptographic algorithms (key exchange, authentication, cipher).

Note

Crypto capabilities packets are always sent unencrypted (handshake packets).

Parameters

sockfd	Socket file descriptor
caps	Crypto capabilities packet

Returns

0 on success, -1 on error

Definition at line 958 of file packet.c.

                                                                                               {
  if (!caps) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: caps=%p", caps);
    return -1;
  }
  return send_packet(sockfd, PACKET_TYPE_CRYPTO_CAPABILITIES, caps, sizeof(*caps));
}

References ERROR_INVALID_PARAM, PACKET_TYPE_CRYPTO_CAPABILITIES, send_packet(), and SET_ERRNO.

send_crypto_parameters_packet()

int send_crypto_parameters_packet	(	socket_t	sockfd,
		const crypto_parameters_packet_t *	params )

#include <include/ascii-chat/network/packet/packet.h>

Send crypto parameters packet.

Parameters

sockfd	Socket file descriptor
params	Crypto parameters packet structure

Returns

0 on success, -1 on error

Sends a PACKET_TYPE_CRYPTO_PARAMETERS packet containing chosen cryptographic algorithms and data sizes for handshake continuation.

Note

Crypto parameters packets are always sent unencrypted (handshake packets).

Parameters

sockfd	Socket file descriptor
params	Crypto parameters packet

Returns

0 on success, -1 on error

Definition at line 972 of file packet.c.

                                                                                             {
  if (!params) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: params=%p", params);
    return -1;
  }
 
  // Create a copy and convert uint16_t fields to network byte order
  crypto_parameters_packet_t net_params = *params;
  log_debug("NETWORK_DEBUG: Before htons: kex=%u, auth=%u, sig=%u, secret=%u", params->kex_public_key_size,
            params->auth_public_key_size, params->signature_size, params->shared_secret_size);
  net_params.kex_public_key_size = HOST_TO_NET_U16(params->kex_public_key_size);
  net_params.auth_public_key_size = HOST_TO_NET_U16(params->auth_public_key_size);
  net_params.signature_size = HOST_TO_NET_U16(params->signature_size);
  net_params.shared_secret_size = HOST_TO_NET_U16(params->shared_secret_size);
  log_debug("NETWORK_DEBUG: After htons: kex=%u, auth=%u, sig=%u, secret=%u", net_params.kex_public_key_size,
            net_params.auth_public_key_size, net_params.signature_size, net_params.shared_secret_size);
 
  return send_packet(sockfd, PACKET_TYPE_CRYPTO_PARAMETERS, &net_params, sizeof(net_params));
}

References crypto_parameters_packet_t::auth_public_key_size, ERROR_INVALID_PARAM, HOST_TO_NET_U16, crypto_parameters_packet_t::kex_public_key_size, log_debug, PACKET_TYPE_CRYPTO_PARAMETERS, send_packet(), SET_ERRNO, crypto_parameters_packet_t::shared_secret_size, and crypto_parameters_packet_t::signature_size.

send_image_frame_packet()

asciichat_error_t send_image_frame_packet	(	socket_t	sockfd,
		const void *	image_data,
		uint16_t	width,
		uint16_t	height,
		uint8_t	format )

#include <include/ascii-chat/network/packet/packet.h>

Send image frame packet.

Parameters

sockfd	Socket file descriptor
image_data	Image pixel data buffer
width	Image width in pixels
height	Image height in pixels
format	Pixel format (0=RGB24)

Returns

ASCIICHAT_OK on success, error code on failure

Sends PACKET_TYPE_IMAGE_FRAME with RGB image data. Used for transmitting camera frames or video input.

Note

Maximum dimensions: 4096x4096 pixels (~25MB per frame).

Pixel data must be in RGB24 format (3 bytes per pixel).

Definition at line 1055 of file packet.c.

                                                          {
  if (!image_data || width == 0 || height == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: image_data=%p, width=%u, height=%u", image_data, width,
                     height);
  }
 
  // Validate dimensions to prevent integer overflow
  // Max reasonable dimensions: 4K (3840x2160) = ~25MB per frame
  if (width > 4096 || height > 4096) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Image dimensions too large: %ux%u (max 4096x4096)", width, height);
  }
 
  // Create image frame packet
  image_frame_packet_t packet;
  packet.width = HOST_TO_NET_U32(width);
  packet.height = HOST_TO_NET_U32(height);
  packet.pixel_format = HOST_TO_NET_U32(format);
  packet.compressed_size = 0;
  packet.checksum = 0;
  packet.timestamp = 0; // Will be set by receiver
 
  // Calculate total packet size
  // Cast to size_t before multiplication to prevent integer overflow
  // Use overflow-checked multiplication
  size_t width_times_height;
  if (checked_size_mul((size_t)width, (size_t)height, &width_times_height) != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Image dimensions too large: %d x %d", width, height);
  }
 
  size_t frame_size;
  if (checked_size_mul(width_times_height, 3u, &frame_size) != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Frame size overflow for RGB format");
  }
 
  size_t total_size;
  if (checked_size_add(sizeof(image_frame_packet_t), frame_size, &total_size) != ASCIICHAT_OK) {
    return SET_ERRNO(ERROR_BUFFER_OVERFLOW, "Total packet size overflow");
  }
 
  // Allocate buffer for complete packet
  void *packet_data = buffer_alloc(NULL, total_size);
  if (!packet_data) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for image frame packet: %zu bytes", total_size);
  }
 
  // Copy packet header and image data
  memcpy(packet_data, &packet, sizeof(image_frame_packet_t));
  memcpy((char *)packet_data + sizeof(image_frame_packet_t), image_data, frame_size);
 
  // Send packet
  asciichat_error_t result = packet_send(sockfd, PACKET_TYPE_IMAGE_FRAME, packet_data, total_size);
 
  // Clean up
  buffer_release(packet_data);
 
  return result;
}

References ASCIICHAT_OK, buffer_alloc(), buffer_release, image_frame_packet_t::checksum, image_frame_packet_t::compressed_size, ERROR_BUFFER_OVERFLOW, ERROR_INVALID_PARAM, ERROR_MEMORY, height, image_frame_packet_t::height, HOST_TO_NET_U32, packet_send(), PACKET_TYPE_IMAGE_FRAME, image_frame_packet_t::pixel_format, SET_ERRNO, image_frame_packet_t::timestamp, image_frame_packet_t::width, and width.

send_packet()

int send_packet	(	socket_t	sockfd,
		packet_type_t	type,
		const void *	data,
		size_t	len )

#include <include/ascii-chat/network/packet/packet.h>

Send a basic packet without encryption.

Parameters

sockfd	Socket file descriptor
type	Packet type (from packet_types.h)
data	Packet payload data
len	Payload data length in bytes

Returns

0 on success, -1 on error

Sends a plaintext packet without encryption. Equivalent to packet_send() but returns int instead of asciichat_error_t for compatibility.

Note

Use send_packet_secure() if encryption support is needed.

Parameters

sockfd	Socket file descriptor
type	Packet type
data	Packet data
len	Data length

Returns

0 on success, -1 on error

Definition at line 607 of file packet.c.

                                                                                   {
  asciichat_error_t result = packet_send(sockfd, type, data, len);
  return result == ASCIICHAT_OK ? 0 : -1;
}

References ASCIICHAT_OK, and packet_send().

Referenced by acip_server_send_error(), send_crypto_capabilities_packet(), send_crypto_parameters_packet(), send_error_packet_message(), send_ping_packet(), send_pong_packet(), and send_protocol_version_packet().

send_packet_secure()

asciichat_error_t send_packet_secure	(	socket_t	sockfd,
		packet_type_t	type,
		const void *	data,
		size_t	len,
		crypto_context_t *	crypto_ctx )

#include <include/ascii-chat/network/packet/packet.h>

Send a packet with encryption and compression support.

Parameters

sockfd	Socket file descriptor
type	Packet type (from packet_types.h)
data	Packet payload data
len	Payload data length in bytes
crypto_ctx	Cryptographic context for encryption (NULL for plaintext)

Returns

0 on success, negative on error

Sends a packet with automatic encryption (if crypto context provided) and compression (if packet is large enough). Handshake packets are never encrypted.

Note

Encryption is applied automatically when crypto_ctx is provided and packet type is not a handshake packet.

Compression is applied automatically to large packets based on size thresholds and compression ratios.

Handshake packets (packet_is_handshake_type(type) == true) are always sent unencrypted, even when crypto_ctx is provided.

Parameters

sockfd	Socket file descriptor
type	Packet type
data	Packet data
len	Data length
crypto_ctx	Crypto context for encryption

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 492 of file packet.c.

                                                                   {
  if (sockfd == INVALID_SOCKET_VALUE)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid packet socket");
  if (len > MAX_PACKET_SIZE) {
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: %zu > %d", len, MAX_PACKET_SIZE);
  }
 
  if (!data && len > 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Packet payload is NULL with nonzero length");
  }
 
  // Handshake packets are ALWAYS sent unencrypted
  if (packet_is_initial_handshake_type(type)) {
    return packet_send(sockfd, type, data, len);
  }
 
  // Apply compression if beneficial for large packets
  const void *final_data = data;
  size_t final_len = len;
  void *compressed_data = NULL;
 
  // Skip compression for pre-compressed data (Opus audio) or if --no-compress flag is set
  bool should_skip_compression = packet_is_precompressed(type) || GET_OPTION(no_compress);
  if (!should_skip_compression && len > COMPRESSION_MIN_SIZE && should_compress(len, len)) {
    void *temp_compressed = NULL;
    size_t compressed_size = 0;
 
    // Use configured compression level from options (default: 1 for fastest compression)
    int compression_level = (GET_OPTION(compression_level) > 0) ? GET_OPTION(compression_level) : 1;
    asciichat_error_t compress_result = compress_data(data, len, &temp_compressed, &compressed_size, compression_level);
    if (compress_result == ASCIICHAT_OK) {
      double ratio = (double)compressed_size / (double)len;
      if (ratio < COMPRESSION_RATIO_THRESHOLD) {
        final_data = temp_compressed;
        final_len = compressed_size;
        compressed_data = temp_compressed;
        log_debug_every(US_PER_SEC_INT, "Compressed packet: %zu -> %zu bytes (%.1f%%)", len, compressed_size,
                        ratio * 100.0);
      } else {
        buffer_release(temp_compressed);
      }
    }
  }
 
  // If no crypto context or crypto not ready, send unencrypted
  bool ready = crypto_ctx ? crypto_is_ready(crypto_ctx) : false;
  if (!crypto_ctx || !ready || !crypto_ctx->encrypt_data) {
    log_warn_every(LOG_RATE_FAST, "CRYPTO_DEBUG: Sending packet type %d UNENCRYPTED (crypto_ctx=%p, ready=%d)", type,
                   (void *)crypto_ctx, ready);
    asciichat_error_t result = packet_send(sockfd, type, final_data, final_len);
    if (compressed_data) {
      buffer_release(compressed_data);
    }
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send packet: %s", asciichat_error_string(result));
    }
    return result;
  }
 
  socket_buffer_t payload = {final_data, final_len};
  packet_header_t header;
  asciichat_error_t result = packet_header_build(&header, type, &payload, 1, 0);
  socket_buffer_t slices[] = {{&header, sizeof(header)}, payload};
  acip_packet_plan_t plan;
  if (result == ASCIICHAT_OK)
    result = acip_packet_plan(crypto_ctx, slices, 2, &plan);
  uint8_t *ciphertext = NULL;
  if (result == ASCIICHAT_OK) {
    ciphertext = buffer_alloc(plan.domain, plan.ciphertext_capacity);
    if (!ciphertext)
      result = SET_ERRNO(ERROR_MEMORY, "Cannot allocate packet ciphertext");
  }
  if (result == ASCIICHAT_OK) {
    packet_header_t outer;
    size_t length = 0;
    result = acip_packet_encrypt(crypto_ctx, &plan, plan.domain, ciphertext, plan.ciphertext_capacity, &outer, &length);
    if (result == ASCIICHAT_OK) {
      socket_buffer_t wire[] = {{&outer, sizeof(outer)}, {ciphertext, length}};
      result = socket_sendv_all(sockfd, wire, 2, packet_send_timeout_ns(sizeof(outer) + length));
    }
  }
  buffer_release(ciphertext);
  buffer_release(compressed_data);
  return result;
}

References acip_packet_encrypt(), acip_packet_plan(), ASCIICHAT_OK, buffer_alloc(), buffer_release, acip_packet_plan_t::ciphertext_capacity, compress_data(), COMPRESSION_MIN_SIZE, COMPRESSION_RATIO_THRESHOLD, crypto_is_ready(), acip_packet_plan_t::domain, crypto_context_t::encrypt_data, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_SIZE, GET_OPTION, log_debug_every, LOG_RATE_FAST, log_warn_every, MAX_PACKET_SIZE, packet_header_build(), packet_send(), packet_send_timeout_ns(), SET_ERRNO, should_compress(), and US_PER_SEC_INT.

Referenced by av_send_audio_opus_batch(), packet_send_error(), and packet_send_remote_log().

send_ping_packet()

int send_ping_packet

(

socket_t

sockfd

)

#include <include/ascii-chat/network/packet/packet.h>

Send a ping packet (keepalive).

Parameters

sockfd

Socket file descriptor

Returns

0 on success, -1 on error

Sends a PACKET_TYPE_PING packet to keep connection alive. Server/client responds with PACKET_TYPE_PONG.

Note

Ping packets are always sent unencrypted (handshake packets).

Send a ping packet (keepalive).

Parameters

sockfd

Socket file descriptor

Returns

0 on success, -1 on error

Definition at line 636 of file packet.c.

                                      {
  return send_packet(sockfd, PACKET_TYPE_PING, NULL, 0);
}

References PACKET_TYPE_PING, and send_packet().

send_pong_packet()

int send_pong_packet

(

socket_t

sockfd

)

#include <include/ascii-chat/network/packet/packet.h>

Send a pong packet (keepalive response).

Parameters

sockfd

Socket file descriptor

Returns

0 on success, -1 on error

Sends a PACKET_TYPE_PONG packet in response to PACKET_TYPE_PING. Indicates that connection is alive and responsive.

Note

Pong packets are always sent unencrypted (handshake packets).

Send a pong packet (keepalive response).

Parameters

sockfd

Socket file descriptor

Returns

0 on success, -1 on error

Definition at line 645 of file packet.c.

                                      {
  return send_packet(sockfd, PACKET_TYPE_PONG, NULL, 0);
}

References PACKET_TYPE_PONG, and send_packet().

send_protocol_version_packet()

int send_protocol_version_packet	(	socket_t	sockfd,
		const protocol_version_packet_t *	version )

#include <include/ascii-chat/network/packet/packet.h>

Send protocol version negotiation packet.

Parameters

sockfd	Socket file descriptor
version	Protocol version packet structure

Returns

0 on success, -1 on error

Sends a PACKET_TYPE_PROTOCOL_VERSION packet for protocol capability negotiation. Both client and server send this during handshake.

Note

Protocol version packets are always sent unencrypted (handshake packets).

Send protocol version negotiation packet.

Parameters

sockfd	Socket file descriptor
version	Protocol version packet

Returns

0 on success, -1 on error

Definition at line 944 of file packet.c.

                                                                                            {
  if (!version) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: version=%p", version);
    return -1;
  }
  return send_packet(sockfd, PACKET_TYPE_PROTOCOL_VERSION, version, sizeof(*version));
}

References ERROR_INVALID_PARAM, PACKET_TYPE_PROTOCOL_VERSION, send_packet(), and SET_ERRNO.

send_with_timeout()

ssize_t send_with_timeout	(	socket_t	sockfd,
		const void *	data,
		size_t	len,
		uint64_t	timeout_ns )

#include <include/ascii-chat/network/network.h>

Send data with timeout using chunked transmission.

Parameters

sockfd	Socket file descriptor
data	Data to send
len	Length of data in bytes
timeout_ns	Timeout in nanoseconds

Returns

Number of bytes sent on success, -1 on error

Sends data to socket with timeout support. Uses chunked transmission for large data to prevent blocking and enable progress tracking.

Note

Chunked transmission automatically handles large frames by sending in smaller chunks, preventing timeout issues.

Partial sends are handled automatically - function retries until all data is sent or timeout occurs.

Parameters

sockfd	Socket file descriptor
data	Data to send
len	Length of data
timeout_seconds	Timeout in seconds

Returns

Number of bytes sent, or -1 on error

Definition at line 109 of file network/network.c.

                                                                                              {
  if (sockfd == INVALID_SOCKET_VALUE) {
    errno = EBADF;
    return -1;
  }
 
  size_t total_sent = 0;
  const char *data_ptr = (const char *)data;
 
  while (total_sent < len) {
    // Calculate chunk size
    size_t bytes_to_send = len - total_sent;
    const size_t MAX_CHUNK_SIZE = 65536; // 64KB chunks for reliable TCP transmission
    if (bytes_to_send > MAX_CHUNK_SIZE) {
      bytes_to_send = MAX_CHUNK_SIZE;
    }
 
    // Set up poll for write timeout (in nanoseconds)
    struct pollfd pfd;
    pfd.fd = sockfd;
    pfd.events = POLLOUT;
    pfd.revents = 0;
 
    int64_t effective_timeout_ns = network_is_test_environment() ? (100LL * NS_PER_MS_INT) : (int64_t)timeout_ns;
    int result = socket_poll(&pfd, 1, effective_timeout_ns);
    if (result <= 0) {
      if (result == 0) {
        SET_ERRNO_SYS(ERROR_NETWORK_TIMEOUT, "timed out after %llu nanoseconds", (unsigned long long)timeout_ns);
        return -1;
      }
      if (network_handle_select_error(result)) {
        continue; // Retry
      }
      return -1; // Fatal error
    }
 
    // Check if socket is ready for writing
    if (!(pfd.revents & POLLOUT)) {
      SET_ERRNO_SYS(ERROR_NETWORK_TIMEOUT, "socket not ready for writing after poll");
      return -1;
    }
 
    // Use platform-specific send
    ssize_t sent = socket_send(sockfd, data_ptr + total_sent, bytes_to_send, 0);
 
    if (sent < 0) {
      int error = errno;
      if (network_handle_send_error(error)) {
        continue; // Retry
      }
      return -1; // Fatal error
    }
 
    if (sent > 0) {
      total_sent += (size_t)sent;
    }
  }
 
  return (ssize_t)total_sent;
}

References EBADF, errno, ERROR_NETWORK_TIMEOUT, network_is_test_environment, NS_PER_MS_INT, and SET_ERRNO_SYS.

set_socket_keepalive()

asciichat_error_t set_socket_keepalive

(

socket_t

sockfd

)

#include <include/ascii-chat/network/network.h>

Enable TCP keepalive on socket.

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, error code on failure

Enables TCP keepalive probes on socket using KEEPALIVE_IDLE, KEEPALIVE_INTERVAL, and KEEPALIVE_COUNT settings.

Note

Keepalive helps detect dead connections (broken network path) without application-level heartbeats.

Enable TCP keepalive on socket.

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 380 of file network/network.c.

                                                        {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket file descriptor");
  }
  int result = socket_set_keepalive_params(sockfd, true, KEEPALIVE_IDLE, KEEPALIVE_INTERVAL, KEEPALIVE_COUNT);
  if (result != 0) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to set socket keepalive parameters");
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, KEEPALIVE_COUNT, KEEPALIVE_IDLE, KEEPALIVE_INTERVAL, SET_ERRNO, and SET_ERRNO_SYS.

set_socket_nonblocking()

asciichat_error_t set_socket_nonblocking

(

socket_t

sockfd

)

#include <include/ascii-chat/network/network.h>

Set socket to non-blocking mode.

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, error code on failure

Sets socket to non-blocking mode. I/O operations return immediately with error if data is not available.

Note

Non-blocking sockets require different error handling - EAGAIN/EWOULDBLOCK indicates operation would block.

Useful for asynchronous I/O patterns with select/poll/epoll.

Set socket to non-blocking mode.

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 396 of file network/network.c.

                                                          {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket file descriptor");
  }
  int result = socket_set_nonblocking(sockfd, true);
  if (result != 0) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to set socket non-blocking mode");
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, SET_ERRNO, and SET_ERRNO_SYS.

Referenced by connect_with_timeout().

set_socket_timeout()

asciichat_error_t set_socket_timeout	(	socket_t	sockfd,
		uint64_t	timeout_ns )

#include <include/ascii-chat/network/network.h>

Set socket timeout for send/receive operations.

Parameters

sockfd	Socket file descriptor
timeout_ns	Timeout in nanoseconds (0 to disable timeout)

Returns

ASCIICHAT_OK on success, error code on failure

Configures socket-level timeout for send and receive operations. This sets SO_SNDTIMEO and SO_RCVTIMEO socket options.

Note

Socket-level timeouts work in addition to application-level timeouts in send_with_timeout() and recv_with_timeout().

Set socket timeout for send/receive operations.

Parameters

sockfd	Socket file descriptor
timeout_ns	Timeout in nanoseconds (converted to milliseconds for socket level)

Returns

ASCIICHAT_OK on success, error code on failure

Sets socket-level timeouts (SO_RCVTIMEO/SO_SNDTIMEO) as a safety net fallback. Actual precision depends on platform: milliseconds on most systems, microseconds on some. Works in conjunction with application-level timeouts via socket_poll.

Definition at line 345 of file network/network.c.

                                                                           {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket file descriptor");
  }
 
  // Convert nanoseconds to milliseconds for socket-level timeout
  // Note: socket-level timeouts have ~millisecond granularity on most platforms
  uint64_t timeout_ms = timeout_ns / (1000 * 1000);
  if (timeout_ms == 0 && timeout_ns > 0) {
    timeout_ms = 1; // Ensure at least 1ms for non-zero timeouts
  }
 
  // Set both receive and send timeouts using struct timeval
  struct timeval tv;
  tv.tv_sec = (time_t)(timeout_ms / 1000);
  tv.tv_usec = (long)((timeout_ms % 1000) * 1000);
 
  // Set receive timeout
  if (socket_setsockopt(sockfd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv)) != 0) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to set socket receive timeout");
  }
 
  // Set send timeout
  if (socket_setsockopt(sockfd, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv)) != 0) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to set socket send timeout");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, SET_ERRNO, and SET_ERRNO_SYS.

socket_configure_buffers()

asciichat_error_t socket_configure_buffers

(

socket_t

sockfd

)

#include <include/ascii-chat/network/network.h>

Configure socket buffers and TCP_NODELAY for optimal performance.

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, or ERROR_NETWORK if all options fail

Configures socket with large send/receive buffers (1MB each) and enables TCP_NODELAY for low-latency real-time video streaming.

CONFIGURATION:

• Send buffer: 1MB (SO_SNDBUF)
• Receive buffer: 1MB (SO_RCVBUF)
• TCP_NODELAY: enabled (disables Nagle's algorithm)

BEHAVIOR: Attempts to set all three socket options independently. Individual failures are logged as warnings but do not prevent attempting other options. This ensures TCP_NODELAY is always set even if buffer size configuration fails (common on systems with strict limits). Only returns error if ALL options fail.

Note

Large buffers prevent packet loss during frame bursts

TCP_NODELAY ensures frames are sent immediately without buffering

Call this immediately after socket creation/connection

Parameters

sockfd

Socket file descriptor

Returns

ASCIICHAT_OK on success, ERROR_NETWORK_CONFIG on failure

Definition at line 412 of file network/network.c.

                                                            {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Invalid socket file descriptor");
  }
 
  int failed_options = 0;
 
  // Attempt to configure 1MB send buffer for optimal frame transmission
  int send_buffer_size = 1024 * 1024;
  if (socket_setsockopt(sockfd, SOL_SOCKET, SO_SNDBUF, &send_buffer_size, sizeof(send_buffer_size)) < 0) {
    log_warn("Failed to set send buffer size to 1MB: %s", network_error_string());
    failed_options++;
  }
 
  // Attempt to configure 1MB receive buffer for optimal frame reception
  int recv_buffer_size = 1024 * 1024;
  if (socket_setsockopt(sockfd, SOL_SOCKET, SO_RCVBUF, &recv_buffer_size, sizeof(recv_buffer_size)) < 0) {
    log_warn("Failed to set receive buffer size to 1MB: %s", network_error_string());
    failed_options++;
  }
 
  // Attempt to enable TCP_NODELAY to disable Nagle's algorithm for low-latency transmission
  // This must be set even if buffer configuration fails, as it's essential for real-time video.
  int tcp_nodelay = 1;
  if (socket_setsockopt(sockfd, IPPROTO_TCP, TCP_NODELAY, &tcp_nodelay, sizeof(tcp_nodelay)) < 0) {
    log_warn("Failed to set TCP_NODELAY: %s", network_error_string());
    failed_options++;
  }
 
  // Return error only if ALL options failed
  if (failed_options >= 3) {
    return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to configure all socket options");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_NETWORK, log_warn, network_error_string(), and SET_ERRNO_SYS.

update_check_detect_install_method()

install_method_t update_check_detect_install_method

(

void

)

#include <include/ascii-chat/network/update_checker.h>

Detect installation method.

Checks binary path and system files to determine how ascii-chat was installed.

Returns

Installation method enum

Definition at line 454 of file update_checker.c.

                                                          {
#if defined(ASCIICHAT_INSTALLED_BY_HOMEBREW)
  return INSTALL_METHOD_HOMEBREW;
#elif defined(ASCIICHAT_INSTALLED_BY_SCOOP)
  return INSTALL_METHOD_SCOOP;
#elif defined(ASCIICHAT_INSTALLED_BY_AUR)
  return INSTALL_METHOD_ARCH_AUR;
#elif defined(_WIN32)
  return INSTALL_METHOD_INSTALLER;
#else
  if (is_homebrew_install()) {
    return INSTALL_METHOD_HOMEBREW;
  }
 
  if (is_arch_linux()) {
    return INSTALL_METHOD_ARCH_AUR;
  }
 
  // The published Unix installer is the default outside package-managed installs.
  return INSTALL_METHOD_INSTALLER;
#endif
}

References INSTALL_METHOD_ARCH_AUR, INSTALL_METHOD_HOMEBREW, INSTALL_METHOD_INSTALLER, and INSTALL_METHOD_SCOOP.

Referenced by update_banner_install_update(), update_banner_set_result(), and update_check_format_notification().

update_check_dismiss_for_a_week()

void update_check_dismiss_for_a_week

(

update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Persist a seven-day dismissal for the currently cached release.

Definition at line 242 of file update_checker.c.

                                                                    {
  if (!result) {
    return;
  }
  result->dismissed_until = time(NULL) + UPDATE_CHECK_CACHE_MAX_AGE_SECONDS;
  (void)update_check_save_cache(result);
}

References update_check_result_t::dismissed_until, UPDATE_CHECK_CACHE_MAX_AGE_SECONDS, and update_check_save_cache().

Referenced by update_banner_show_prompt().

update_check_format_notification()

void update_check_format_notification	(	const update_check_result_t *	result,
		char *	buffer,
		size_t	buffer_size )

#include <include/ascii-chat/network/update_checker.h>

Format update notification message.

Creates human-readable update notification with version comparison and upgrade suggestion. Example: "Update available: v0.8.1 (f8dc35e1) → v0.9.0 (a1b2c3d4). Run: brew upgrade ascii-chat"

Parameters

	result	Update check result
[out]	buffer	Output buffer for formatted message
	buffer_size	Size of output buffer

Definition at line 533 of file update_checker.c.

                                                                                                             {
  if (!result || !buffer || buffer_size == 0) {
    return;
  }
 
  // Get upgrade suggestion
  install_method_t method = update_check_detect_install_method();
  char suggestion[NETWORK_UPDATE_CHECKER_SUGGESTION_BUFFER_SIZE];
  update_check_get_upgrade_suggestion(method, result->latest_version, suggestion, sizeof(suggestion));
 
  // Keep the notification useful even when it is displayed in a log line:
  // identify the versions, provide an actionable command or download URL, and
  // point to the exact GitHub release that was returned by the API.
  snprintf(buffer, buffer_size, "Update available: %s → %s. %s%s. Release notes: %s", result->current_version,
           result->latest_version,
           (method == INSTALL_METHOD_GITHUB || method == INSTALL_METHOD_UNKNOWN) ? "Download: " : "Run: ", suggestion,
           result->release_url);
}

References buffer_size, update_check_result_t::current_version, INSTALL_METHOD_GITHUB, INSTALL_METHOD_UNKNOWN, update_check_result_t::latest_version, NETWORK_UPDATE_CHECKER_SUGGESTION_BUFFER_SIZE, update_check_result_t::release_url, update_check_detect_install_method(), and update_check_get_upgrade_suggestion().

Referenced by action_check_update_immediate().

update_check_get_aur_helper()

const char * update_check_get_aur_helper

(

void

)

#include <include/ascii-chat/network/update_checker.h>

Return the detected AUR helper (paru or yay), or NULL if unavailable.

Definition at line 477 of file update_checker.c.

                                              {
  static _Atomic int cached_helper = -1;
  int helper = atomic_load(&cached_helper);
  if (helper == -1) {
    const char *paru[] = {"paru", "--version", NULL};
    const char *yay[] = {"yay", "--version", NULL};
    helper = platform_execute_subprocess("paru", paru, NULL, 0, NULL, NULL) == 0 ? 1
             : platform_execute_subprocess("yay", yay, NULL, 0, NULL, NULL) == 0 ? 2
                                                                                 : 0;
    atomic_store(&cached_helper, helper);
  }
  return helper == 1 ? "paru" : helper == 2 ? "yay" : NULL;
}

References platform_execute_subprocess().

Referenced by update_banner_install_update(), update_banner_set_result(), and update_check_get_upgrade_suggestion().

update_check_get_upgrade_suggestion()

void update_check_get_upgrade_suggestion	(	install_method_t	method,
		const char *	latest_version,
		char *	buffer,
		size_t	buffer_size )

#include <include/ascii-chat/network/update_checker.h>

Get upgrade suggestion string.

Returns appropriate upgrade command or URL based on installation method.

Parameters

	method	Installation method
	latest_version	Latest version tag for GitHub URL
[out]	buffer	Output buffer for suggestion string
	buffer_size	Size of output buffer

Definition at line 491 of file update_checker.c.

                                                             {
  if (!buffer || buffer_size == 0) {
    return;
  }
 
  switch (method) {
  case INSTALL_METHOD_HOMEBREW:
    snprintf(buffer, buffer_size, "brew upgrade ascii-chat");
    break;
 
  case INSTALL_METHOD_SCOOP:
    snprintf(buffer, buffer_size, "scoop update ascii-chat");
    break;
 
  case INSTALL_METHOD_INSTALLER:
#ifdef _WIN32
    snprintf(buffer, buffer_size, "irm https://ascii-chat.com/install.ps1 | iex");
#else
    snprintf(buffer, buffer_size, "curl -fsSL https://ascii-chat.com/install.sh | bash");
#endif
    break;
 
  case INSTALL_METHOD_ARCH_AUR: {
    const char *helper = update_check_get_aur_helper();
    if (helper) {
      snprintf(buffer, buffer_size, "%s -S ascii-chat", helper);
    } else {
      snprintf(buffer, buffer_size, "<your-aur-helper> -Ss ascii-chat");
    }
    break;
  }
 
  case INSTALL_METHOD_GITHUB:
  case INSTALL_METHOD_UNKNOWN:
  default:
    snprintf(buffer, buffer_size, "https://github.com/zfogg/ascii-chat/releases/tag/%s",
             latest_version ? latest_version : "latest");
    break;
  }
}

References buffer_size, INSTALL_METHOD_ARCH_AUR, INSTALL_METHOD_GITHUB, INSTALL_METHOD_HOMEBREW, INSTALL_METHOD_INSTALLER, INSTALL_METHOD_SCOOP, INSTALL_METHOD_UNKNOWN, and update_check_get_aur_helper().

Referenced by update_check_format_notification().

update_check_is_cache_fresh()

bool update_check_is_cache_fresh

(

const update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Check if cache is fresh (< 7 days old).

Parameters

result

Cached result to check

Returns

true if cache is < 7 days old, false otherwise

Definition at line 231 of file update_checker.c.

                                                                      {
  if (!result || result->last_check_time == 0) {
    return false;
  }
 
  time_t now = time(NULL);
  time_t age = now - result->last_check_time;
 
  return (age < UPDATE_CHECK_CACHE_MAX_AGE_SECONDS);
}

References update_check_result_t::last_check_time, and UPDATE_CHECK_CACHE_MAX_AGE_SECONDS.

Referenced by update_check_startup(), and update_check_try_fresh_cache().

update_check_is_dismissed()

bool update_check_is_dismissed

(

const update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

True when the cached available release remains dismissed.

Definition at line 250 of file update_checker.c.

                                                                    {
  return result && result->dismissed_until > time(NULL);
}

References update_check_result_t::dismissed_until.

Referenced by update_banner_show_prompt().

update_check_load_cache()

asciichat_error_t update_check_load_cache

(

update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Load cached update check result.

Reads cache file from ~/.config/ascii-chat/last_update_check. Cache format (4 lines):

• Line 1: Unix timestamp
• Line 2: Latest version tag (or empty if check failed)
• Line 3: Latest SHA (full 40 chars, or empty if check failed)
• Line 4: Exact GitHub release URL

Parameters

[out]

result

Output structure with cached results

Returns

ASCIICHAT_OK if cache valid, error if missing/corrupt

Definition at line 95 of file update_checker.c.

                                                                         {
  if (!result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL result pointer");
  }
 
  memset(result, 0, sizeof(*result));
 
  char *cache_path = get_cache_file_path();
  if (!cache_path) {
    return SET_ERRNO(ERROR_FILE_OPERATION, "Could not determine cache file path");
  }
  defer(SAFE_FREE(cache_path));
 
  /* A cache miss is expected on first launch.  Check existence through the
   * platform layer before opening so Windows does not turn the missing file
   * into a stale errno-stack notification. */
  if (platform_access(cache_path, PLATFORM_ACCESS_EXISTS) != 0)
    return ASCIICHAT_OK;
 
  FILE *f = platform_fopen("file_stream", cache_path, "r");
  if (!f) {
    const char *error_msg = file_read_error_message(cache_path);
    return SET_ERRNO(ERROR_FILE_OPERATION, "%s", error_msg);
  }
  defer(SAFE_FCLOSE(f));
 
  // Read line 1: timestamp
  char line[NETWORK_UPDATE_CHECKER_LINE_BUFFER_SIZE];
  if (!fgets(line, sizeof(line), f)) {
    return SET_ERRNO(ERROR_FILE_OPERATION, "Failed to read timestamp from cache");
  }
 
  // Parse timestamp safely with error checking
  errno = 0;
  char *endptr = NULL;
  long long timestamp_ll = strtoll(line, &endptr, 10);
  if (errno != 0 || endptr == line) {
    log_error("Failed to parse timestamp from cache: invalid value '%s'", line);
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid timestamp in cache file");
  }
  result->last_check_time = (time_t)timestamp_ll;
 
  // Read line 2: latest version (may be empty if check failed)
  if (fgets(line, sizeof(line), f)) {
    trim_line_ending(line);
    SAFE_STRNCPY(result->latest_version, line, sizeof(result->latest_version));
  }
 
  // Read line 3: latest SHA (may be empty if check failed)
  if (fgets(line, sizeof(line), f)) {
    trim_line_ending(line);
    SAFE_STRNCPY(result->latest_sha, line, sizeof(result->latest_sha));
  }
 
  // Read line 4: release URL. This field is required in the current cache
  // format; an older or partially-written cache must be refreshed.
  if (!fgets(line, sizeof(line), f)) {
    SAFE_FCLOSE(f);
    // Treat a legacy cache exactly like a missing cache. Close the file before
    // removing it so this also works on Windows, where open files cannot be
    // deleted.
    (void)remove(cache_path);
    return SET_ERRNO(ERROR_FORMAT, "Update cache format is obsolete");
  }
  trim_line_ending(line);
  SAFE_STRNCPY(result->release_url, line, sizeof(result->release_url));
 
  // Older four-line cache files remain valid; they simply have no dismissal.
  if (fgets(line, sizeof(line), f)) {
    result->dismissed_until = (time_t)strtoll(line, NULL, 10);
  }
 
  SAFE_FCLOSE(f);
 
  // Fill in current version/SHA
  SAFE_STRNCPY(result->current_version, ASCII_CHAT_VERSION_STRING, sizeof(result->current_version));
  SAFE_STRNCPY(result->current_sha, ASCII_CHAT_GIT_COMMIT_HASH, sizeof(result->current_sha));
 
  // Determine if update is available using version comparison (if we have cached data)
  if (result->latest_version[0] != '\0') {
    semantic_version_t current_ver = version_parse(result->current_version);
    semantic_version_t latest_ver = version_parse(result->latest_version);
 
    if (current_ver.valid && latest_ver.valid) {
      int cmp = version_compare(latest_ver, current_ver);
      result->update_available = (cmp > 0); // Update available if latest > current
      result->check_succeeded = true;
    } else {
      // Cache contains invalid version data - delete it
      log_warn("Update cache contains invalid version data (current:%s, latest:%s) - deleting corrupted cache",
               result->current_version, result->latest_version);
      if (remove(cache_path) != 0) {
        log_warn("Failed to delete corrupted cache file: %s", cache_path);
      }
      return SET_ERRNO(ERROR_FORMAT, "Corrupted cache file deleted");
    }
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, update_check_result_t::check_succeeded, update_check_result_t::current_sha, update_check_result_t::current_version, update_check_result_t::dismissed_until, errno, ERROR_FILE_OPERATION, ERROR_FORMAT, ERROR_INVALID_PARAM, update_check_result_t::last_check_time, update_check_result_t::latest_sha, update_check_result_t::latest_version, log_error, log_warn, NETWORK_UPDATE_CHECKER_LINE_BUFFER_SIZE, update_check_result_t::release_url, SAFE_FCLOSE, SAFE_FREE, SAFE_STRNCPY, SET_ERRNO, update_check_result_t::update_available, version_compare(), and version_parse().

update_check_perform()

asciichat_error_t update_check_perform

(

update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Check for updates from GitHub releases API.

Performs DNS connectivity test, fetches latest release from GitHub API, compares SHA with current build, and caches the result.

Parameters

[out]

result

Output structure with check results

Returns

ASCIICHAT_OK on success (check completed), error otherwise

Note

On timeout or network error, logs warning and marks as checked in cache

On DNS failure, does not update cache (will retry when online)

Timeout is 2 seconds for the entire operation

Definition at line 311 of file update_checker.c.

                                                                      {
  if (!result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL result pointer");
  }
 
  update_check_result_t cached = {0};
  bool have_cached = load_optional_cache(&cached) == ASCIICHAT_OK;
  memset(result, 0, sizeof(*result));
 
  // Fill in current version and SHA
  SAFE_STRNCPY(result->current_version, ASCII_CHAT_VERSION_STRING, sizeof(result->current_version));
  SAFE_STRNCPY(result->current_sha, ASCII_CHAT_GIT_COMMIT_HASH, sizeof(result->current_sha));
  result->last_check_time = time(NULL);
 
#ifndef NDEBUG
  // Deterministic local seam for PTY smoke coverage. Release builds never
  // consult it, and ordinary debug runs continue through the network path.
  const char *test_latest = SAFE_GETENV("ASCII_CHAT_TEST_UPDATE_LATEST_VERSION");
  if (test_latest && test_latest[0]) {
    SAFE_STRNCPY(result->latest_version, test_latest, sizeof(result->latest_version));
    const char *test_slow = SAFE_GETENV("ASCII_CHAT_TEST_UPDATE_SLOW");
    if (test_slow && strcmp(test_slow, "1") == 0)
      platform_sleep_ms(1000);
    const char *test_gate = SAFE_GETENV("ASCII_CHAT_TEST_UPDATE_GATE");
    if (test_gate && test_gate[0]) {
      uint64_t deadline = time_get_ns() + 30 * NS_PER_SEC_INT;
      while (platform_access(test_gate, PLATFORM_ACCESS_EXISTS) != 0 && time_get_ns() < deadline)
        platform_sleep_ms(10);
    }
    SAFE_STRNCPY(result->release_url, "https://github.com/zfogg/ascii-chat/releases/latest",
                 sizeof(result->release_url));
    result->check_succeeded = true;
    semantic_version_t current_ver = version_parse(result->current_version);
    semantic_version_t latest_ver = version_parse(result->latest_version);
    result->update_available = current_ver.valid && latest_ver.valid && version_compare(latest_ver, current_ver) > 0;
    if (have_cached && strcmp(cached.latest_version, result->latest_version) == 0) {
      result->dismissed_until = cached.dismissed_until;
    }
    (void)update_check_save_cache(result);
    return ASCIICHAT_OK;
  }
#endif
 
  // Fetch latest release from GitHub API
  log_info("Checking for updates from GitHub releases...");
  char *response = https_get(GITHUB_API_HOSTNAME, GITHUB_RELEASES_PATH);
  if (!response) {
    log_warn("Failed to fetch GitHub releases API (timeout or network error)");
    // Don't save cache on network failure — retry next startup
    result->check_succeeded = false;
    return SET_ERRNO(ERROR_NETWORK, "Failed to fetch GitHub releases");
  }
 
  defer(SAFE_FREE(response));
 
  // Parse JSON response
  char latest_tag[NETWORK_UPDATE_CHECKER_LATEST_TAG_BUFFER_SIZE] = {0};
  char release_url[NETWORK_UPDATE_CHECKER_RELEASE_URL_BUFFER_SIZE] = {0};
 
  if (!parse_github_release_json(response, latest_tag, sizeof(latest_tag), release_url, sizeof(release_url))) {
    log_error("Failed to parse GitHub API response");
    // Don't save cache on parse failure — retry next startup
    result->check_succeeded = false;
    return SET_ERRNO(ERROR_FORMAT, "Failed to parse GitHub API JSON");
  }
 
  // Fill in result
  SAFE_STRNCPY(result->latest_version, latest_tag, sizeof(result->latest_version));
  SAFE_STRNCPY(result->release_url, release_url, sizeof(result->release_url));
  result->latest_sha[0] = '\0';
  result->check_succeeded = true;
  if (have_cached && strcmp(cached.latest_version, result->latest_version) == 0) {
    result->dismissed_until = cached.dismissed_until;
  }
 
  // Compare versions semantically
  semantic_version_t current_ver = version_parse(result->current_version);
  semantic_version_t latest_ver = version_parse(result->latest_version);
 
  if (!current_ver.valid || !latest_ver.valid) {
    log_warn("Failed to parse version strings for comparison (current: %s, latest: %s)", result->current_version,
             result->latest_version);
    result->update_available = false;
  } else {
    int cmp = version_compare(latest_ver, current_ver);
    result->update_available = (cmp > 0); // Update available if latest > current
  }
 
  if (result->update_available) {
    log_info("Update available: %s → %s", result->current_version, result->latest_version);
  } else {
    log_info("Already on latest version: %s", result->current_version);
  }
 
  // Save to cache
  update_check_save_cache(result);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, update_check_result_t::check_succeeded, update_check_result_t::current_sha, update_check_result_t::current_version, update_check_result_t::dismissed_until, ERROR_FORMAT, ERROR_INVALID_PARAM, ERROR_NETWORK, GITHUB_API_HOSTNAME, GITHUB_RELEASES_PATH, https_get(), update_check_result_t::last_check_time, update_check_result_t::latest_sha, update_check_result_t::latest_version, log_error, log_info, log_warn, NETWORK_UPDATE_CHECKER_LATEST_TAG_BUFFER_SIZE, NETWORK_UPDATE_CHECKER_RELEASE_URL_BUFFER_SIZE, NS_PER_SEC_INT, platform_sleep_ms(), update_check_result_t::release_url, SAFE_FREE, SAFE_GETENV, SAFE_STRNCPY, SET_ERRNO, update_check_result_t::update_available, update_check_save_cache(), version_compare(), and version_parse().

Referenced by action_check_update_immediate(), and update_check_startup().

update_check_save_cache()

asciichat_error_t update_check_save_cache

(

const update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Save update check result to cache.

Writes cache file to ~/.config/ascii-chat/last_update_check.

Parameters

result

Result to cache

Returns

ASCIICHAT_OK on success, error otherwise

Definition at line 196 of file update_checker.c.

                                                                               {
  if (!result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL result pointer");
  }
 
  char *cache_path = get_cache_file_path();
  if (!cache_path) {
    return SET_ERRNO(ERROR_FILE_OPERATION, "Could not determine cache file path");
  }
  defer(SAFE_FREE(cache_path));
 
  FILE *f = platform_fopen("file_stream", cache_path, "w");
  if (!f) {
    const char *error_msg = file_write_error_message(cache_path);
    return SET_ERRNO(ERROR_FILE_OPERATION, "%s", error_msg);
  }
 
  // Write timestamp
  fprintf(f, "%lld\n", (long long)result->last_check_time);
 
  // Write version (may be empty if check failed)
  fprintf(f, "%s\n", result->latest_version);
 
  // Write SHA (may be empty if check failed)
  fprintf(f, "%s\n", result->latest_sha);
 
  // Write the release URL so cached notifications retain the exact GitHub
  // source returned by the API.
  fprintf(f, "%s\n", result->release_url);
  fprintf(f, "%lld\n", (long long)result->dismissed_until);
 
  fclose(f);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, update_check_result_t::dismissed_until, ERROR_FILE_OPERATION, ERROR_INVALID_PARAM, update_check_result_t::last_check_time, update_check_result_t::latest_sha, update_check_result_t::latest_version, update_check_result_t::release_url, SAFE_FREE, and SET_ERRNO.

Referenced by update_check_dismiss_for_a_week(), and update_check_perform().

update_check_startup()

asciichat_error_t update_check_startup

(

update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Perform startup update check with caching.

Designed for automatic startup checks. Uses cache if fresh (< 7 days), otherwise performs fresh check. Non-blocking and silent on failure.

Parameters

[out]

result

Output structure with check results (can be NULL if you only want logging)

Returns

ASCIICHAT_OK if check succeeded, error otherwise

Note

Does nothing if cache is fresh

Logs warning on network failure but does not fail

Updates cache only if check succeeds

Definition at line 552 of file update_checker.c.

                                                                      {
  update_check_result_t local_result;
  update_check_result_t *target = result ? result : &local_result;
 
  // Try to load from cache first
  asciichat_error_t cache_err = load_optional_cache(target);
  if (cache_err == ASCIICHAT_OK && update_check_is_cache_fresh(target)) {
    // Cache is fresh, use it
    log_debug("Using cached update check result (age: %.1f days)",
              (time(NULL) - target->last_check_time) / (double)SEC_PER_DAY);
    return ASCIICHAT_OK;
  }
 
  // Cache is stale or missing, perform fresh check
  log_debug("Performing automatic update check (cache %s)", cache_err == ASCIICHAT_OK ? "stale" : "missing");
  asciichat_error_t check_err = update_check_perform(target);
  if (check_err != ASCIICHAT_OK) {
    // Check failed, but don't fail startup
    log_debug("Automatic update check failed (continuing startup)");
    return check_err;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, update_check_result_t::last_check_time, log_debug, SEC_PER_DAY, update_check_is_cache_fresh(), and update_check_perform().

update_check_try_fresh_cache()

bool update_check_try_fresh_cache

(

update_check_result_t *

result

)

#include <include/ascii-chat/network/update_checker.h>

Load a fresh cached result without treating a cache miss as an error.

Definition at line 307 of file update_checker.c.

                                                                 {
  return result && load_optional_cache(result) == ASCIICHAT_OK && update_check_is_cache_fresh(result);
}

References ASCIICHAT_OK, and update_check_is_cache_fresh().