Network Module

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

Files
file	frame_validator.c
	Frame validation implementation for IMAGE_FRAME packets.
file	http_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	http_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
	Network packet header structure. 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
	Client list packet structure. 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
	ASCII frame packet structure (Packet Type 2) More...
struct	image_frame_packet_t
	Image frame packet structure (Packet Type 3) More...
struct	audio_batch_packet_t
	Audio batch packet structure (Packet Type 28) 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 data. More...

Macros
#define	REMOTE_LOG_FLAG_TRUNCATED   0x0001U
	Remote log packet flag definitions.

Enumerations
enum	packet_recv_result_t { PACKET_RECV_SUCCESS = 0 , PACKET_RECV_EOF = -1 , PACKET_RECV_ERROR = -2 , PACKET_RECV_SECURITY_VIOLATION = -3 }
	Packet reception result codes. More...
enum	install_method_t { INSTALL_METHOD_HOMEBREW , INSTALL_METHOD_ARCH_AUR , 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	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.
bool	update_check_is_cache_fresh (const update_check_result_t *result)
	Check if cache is fresh (< 7 days old)
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.
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.
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()   ((int)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
#define	MAX_ERROR_MESSAGE_LENGTH   512
	Maximum error message length (512 bytes)
#define	MAX_REMOTE_LOG_MESSAGE_LENGTH   512
	Maximum remote log message length (512 bytes)

Protocol Negotiation Constants
#define	FEATURE_RLE_ENCODING   0x01
	Feature flags for protocol_version_packet_t.
#define	FEATURE_DELTA_FRAMES   0x02
	Delta frame encoding (future)

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)   (((mode) & ACIP_CRYPTO_ENCRYPT) != 0)
	Check if crypto mode includes payload encryption.
#define	ACIP_CRYPTO_HAS_AUTH(mode)   (((mode) & ACIP_CRYPTO_AUTH) != 0)
	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

Macro Definition Documentation

ACCEPT_TIMEOUT

#define ACCEPT_TIMEOUT   1

#include <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 <packet.h>

Authentication only (no payload encryption)

Definition at line 1084 of file packet.h.

ACIP_CRYPTO_ENCRYPT

#define ACIP_CRYPTO_ENCRYPT   0x01

#include <packet.h>

Encryption only (no identity verification)

Definition at line 1083 of file packet.h.

ACIP_CRYPTO_FULL

#define ACIP_CRYPTO_FULL   0x03

#include <packet.h>

Full crypto: encryption + authentication.

Definition at line 1085 of file packet.h.

ACIP_CRYPTO_HAS_AUTH

#define ACIP_CRYPTO_HAS_AUTH

(

mode

)

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

#include <packet.h>

Check if crypto mode includes authentication.

Parameters

mode	Crypto mode bitmask (ACIP_CRYPTO_*)

Returns

true if authentication is enabled, false otherwise

Definition at line 1099 of file packet.h.

ACIP_CRYPTO_HAS_ENCRYPT

#define ACIP_CRYPTO_HAS_ENCRYPT

(

mode

)

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

#include <packet.h>

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 1092 of file packet.h.

ACIP_CRYPTO_NONE

#define ACIP_CRYPTO_NONE   0x00

#include <packet.h>

No encryption, no authentication (plaintext only)

Definition at line 1082 of file packet.h.

AUTH_ALGO_ED25519

#define AUTH_ALGO_ED25519   0x01

#include <packet.h>

Ed25519 authentication (Edwards-curve signatures)

Definition at line 1065 of file packet.h.

AUTH_ALGO_NONE

#define AUTH_ALGO_NONE   0x00

#include <packet.h>

No authentication (plaintext mode)

Definition at line 1066 of file packet.h.

CIPHER_ALGO_NONE

#define CIPHER_ALGO_NONE   0x00

#include <packet.h>

No encryption (plaintext mode)

Definition at line 1068 of file packet.h.

CIPHER_ALGO_XSALSA20_POLY1305

#define CIPHER_ALGO_XSALSA20_POLY1305   0x01

#include <packet.h>

XSalsa20-Poly1305 authenticated encryption.

Definition at line 1067 of file packet.h.

CLIENT_CAP_AUDIO

#define CLIENT_CAP_AUDIO   0x02

#include <packet.h>

Client can send/receive audio.

Definition at line 924 of file packet.h.

CLIENT_CAP_COLOR

#define CLIENT_CAP_COLOR   0x04

#include <packet.h>

Client supports color rendering.

Definition at line 925 of file packet.h.

CLIENT_CAP_STRETCH

#define CLIENT_CAP_STRETCH   0x08

#include <packet.h>

Client can stretch frames to fill terminal.

Definition at line 926 of file packet.h.

CLIENT_CAP_VIDEO

#define CLIENT_CAP_VIDEO   0x01

#include <packet.h>

Client can send/receive video.

Definition at line 923 of file packet.h.

CONNECT_TIMEOUT

#define CONNECT_TIMEOUT   3

#include <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 <packet.h>

Delta frame encoding (future)

Definition at line 803 of file packet.h.

FEATURE_RLE_ENCODING

#define FEATURE_RLE_ENCODING   0x01

#include <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 802 of file packet.h.

KEEPALIVE_COUNT

#define KEEPALIVE_COUNT   8

#include <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.

KEEPALIVE_IDLE

#define KEEPALIVE_IDLE   60

#include <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.

KEEPALIVE_INTERVAL

#define KEEPALIVE_INTERVAL   10

#include <network.h>

Keepalive interval in seconds (10 seconds)

Interval between subsequent keepalive probes.

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

KEX_ALGO_X25519

#define KEX_ALGO_X25519   0x01

#include <packet.h>

X25519 key exchange (Curve25519)

Definition at line 1064 of file packet.h.

MAX_ERROR_MESSAGE_LENGTH

#define MAX_ERROR_MESSAGE_LENGTH   512

#include <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 124 of file packet.h.

MAX_REMOTE_LOG_MESSAGE_LENGTH

#define MAX_REMOTE_LOG_MESSAGE_LENGTH   512

#include <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 134 of file packet.h.

network_is_test_environment

#define network_is_test_environment

(

)

((int)is_test_environment())

#include <network.h>

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.

RECV_TIMEOUT

#define RECV_TIMEOUT   1

#include <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.

REMOTE_LOG_FLAG_TRUNCATED

#define REMOTE_LOG_FLAG_TRUNCATED   0x0001U

#include <packet.h>

Remote log packet flag definitions.

Message payload was truncated to fit the maximum length

Definition at line 736 of file packet.h.

SEND_TIMEOUT

#define SEND_TIMEOUT   1

#include <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.

STREAM_TYPE_AUDIO

#define STREAM_TYPE_AUDIO   0x02

#include <packet.h>

Audio stream.

Definition at line 938 of file packet.h.

STREAM_TYPE_VIDEO

#define STREAM_TYPE_VIDEO   0x01

#include <packet.h>

Video stream.

Definition at line 937 of file packet.h.

Enumeration Type Documentation

install_method_t

enum install_method_t

#include <update_checker.h>

Installation method for suggesting upgrade command.

Enumerator
INSTALL_METHOD_HOMEBREW	Installed via Homebrew.
INSTALL_METHOD_ARCH_AUR	Installed via Arch AUR (paru/yay)
INSTALL_METHOD_GITHUB	Manual install from GitHub releases.
INSTALL_METHOD_UNKNOWN	Unknown installation method.

Definition at line 44 of file update_checker.h.

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

packet_recv_result_t

enum packet_recv_result_t

#include <packet.h>

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 1152 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;

Function Documentation

accept_with_timeout()

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

#include <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 266 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
      asciichat_errno = ERROR_NETWORK_TIMEOUT;
      asciichat_errno_context.code = ERROR_NETWORK_TIMEOUT;
      asciichat_errno_context.has_system_error = true;
      asciichat_errno_context.system_errno = 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)) {
    asciichat_errno = ERROR_NETWORK_TIMEOUT;
    asciichat_errno_context.code = ERROR_NETWORK_TIMEOUT;
    asciichat_errno_context.has_system_error = true;
    asciichat_errno_context.system_errno = ETIMEDOUT;
    return -1;
  }
 
  // Check if socket is still valid before attempting accept
  if (listenfd == INVALID_SOCKET_VALUE) {
    SET_ERRNO(ERROR_NETWORK, "accept_with_timeout: 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
      asciichat_errno = ERROR_NETWORK;
      asciichat_errno_context.code = ERROR_NETWORK;
      asciichat_errno_context.has_system_error = false;
    } else {
      SET_ERRNO_SYS(ERROR_NETWORK_BIND, "accept_with_timeout accept failed: %s", socket_get_error_string());
    }
    return -1;
  }
 
  return (int)accept_result;
}

References asciichat_errno, asciichat_errno_context, asciichat_error_context_t::code, error_code, ERROR_NETWORK, ERROR_NETWORK_BIND, ERROR_NETWORK_TIMEOUT, ETIMEDOUT, asciichat_error_context_t::has_system_error, INVALID_SOCKET_VALUE, SET_ERRNO, SET_ERRNO_SYS, socket_accept(), socket_get_error_string(), socket_get_last_error(), socket_is_invalid_socket_error(), socket_poll(), and asciichat_error_context_t::system_errno.

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 <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 1175 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_pool_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_pool_free(NULL, packet_data, total_size);
 
  return result;
}

References buffer_pool_alloc(), buffer_pool_free(), 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 <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 457 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, error_code, INVALID_SOCKET_VALUE, log_warn, set_socket_nonblocking(), socket_fd_isset(), socket_fd_set(), socket_fd_zero(), socket_get_last_error(), socket_getsockopt(), socket_is_in_progress_error(), socket_is_would_block_error(), socket_select(), and socket_set_blocking().

Referenced by tcp_client_connect().

dns_test_connectivity()

bool dns_test_connectivity

(

const char *

hostname

)

#include <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 11 of file dns.c.

                                                 {
  if (!hostname) {
    log_warn("NULL hostname provided to DNS connectivity test");
    return false;
  }
 
  struct addrinfo hints, *result = NULL;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_INET; // IPv4
  hints.ai_socktype = SOCK_STREAM;
 
  log_debug("Testing DNS connectivity to %s...", hostname);
  log_info("★ ABOUT TO CALL getaddrinfo for %s", hostname);
 
  // Use NULL for port to avoid musl strtoul parsing bug with string port numbers
  // The actual port doesn't matter for connectivity testing - we just need DNS resolution
  int ret = getaddrinfo(hostname, NULL, &hints, &result);
  log_info("★ 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 log_debug, log_info, and log_warn.

Referenced by update_check_perform().

frame_check_size_overflow()

asciichat_error_t frame_check_size_overflow	(	size_t	header_size,
		size_t	data_size
	)

#include <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 15 of file network/frame_validator.c.

                                                                                  {
  if (data_size > SIZE_MAX - header_size) {
    char size_str[32];
    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(), 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 <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 86 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, and NET_TO_HOST_U32.

frame_extract_new_header()

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

#include <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 94 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 <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 25 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 <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 47 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[32];
    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, and SET_ERRNO.

https_get()

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

#include <http_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 178 of file http_client.c.

                                                        {
  if (!hostname || !path) {
    log_error("Invalid arguments to https_get");
    return NULL;
  }
 
  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;
  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");
    // Free anchors before returning to prevent leak
    goto cleanup_anchors;
  }
  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;
 
  if (getaddrinfo(hostname, "443", &hints, &result) != 0) {
    log_error("Failed to resolve hostname: %s", hostname);
    goto cleanup_anchors;
  }
 
  // 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");
    freeaddrinfo(result);
    goto cleanup_anchors;
  }
 
  // 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);
    socket_close(sock);
    freeaddrinfo(result);
    goto cleanup_anchors;
  }
 
  freeaddrinfo(result);
 
  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
  unsigned char *iobuf;
  iobuf = SAFE_MALLOC(BR_SSL_BUFSIZE_BIDI, 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");
    SAFE_FREE(iobuf);
    socket_close(sock);
    goto cleanup_anchors;
  }
 
  br_sslio_flush(&ioc);
  log_info("Sent HTTP request");
 
  // Read HTTP response
  char *response_buf = NULL;
  size_t response_capacity = 8192;
  size_t response_len = 0;
  response_buf = SAFE_MALLOC(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);
        SAFE_FREE(response_buf);
        SAFE_FREE(iobuf);
        socket_close(sock);
        goto cleanup_anchors;
      }
      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);
        SAFE_FREE(response_buf);
        SAFE_FREE(iobuf);
        socket_close(sock);
        goto cleanup_anchors;
      }
      // 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);
 
  // Parse HTTP response
  asciichat_error_t status = check_http_status(response_buf);
  if (status != ASCIICHAT_OK) {
    SAFE_FREE(response_buf);
    SAFE_FREE(iobuf);
    goto cleanup_anchors;
  }
 
  char *body = extract_http_body(response_buf, response_len);
  SAFE_FREE(response_buf);
  SAFE_FREE(iobuf);
 
  // Cleanup trust anchors
  for (size_t i = 0; i < anchors.ptr; i++) {
    free_ta_contents(&anchors.buf[i]);
  }
  SAFE_FREE(anchors.buf);
 
  return body;
 
cleanup_anchors:
  for (size_t i = 0; i < anchors.ptr; i++) {
    free_ta_contents(&anchors.buf[i]);
  }
  SAFE_FREE(anchors.buf);
  return NULL;
}

References ANCHOR_LIST_INIT, ASCII_CHAT_VERSION_STRING, ASCIICHAT_OK, anchor_list::buf, BUFFER_SIZE_LARGE, free_ta_contents(), HTTPS_MAX_RESPONSE_SIZE, INVALID_SOCKET_VALUE, log_error, log_info, platform_load_system_ca_certs(), anchor_list::ptr, read_trust_anchors_from_memory(), SAFE_FREE, SAFE_MALLOC, SAFE_REALLOC, safe_snprintf(), and socket_close().

Referenced by parse_public_key(), and update_check_perform().

network_error_string()

const char * network_error_string

(

)

#include <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 445 of file network/network.c.

                                   {
  return socket_get_error_string();
}

References socket_get_error_string().

Referenced by add_client(), server_connection_establish(), socket_configure_buffers(), and tcp_client_connect().

packet_decrypt_envelope()

asciichat_error_t packet_decrypt_envelope	(	packet_envelope_t *	envelope,
		void *	crypto_ctx
	)

#include <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 842 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 *ciphertext = (uint8_t *)envelope->data;
  size_t ciphertext_len = envelope->len;
 
  // Allocate plaintext buffer with extra space for decryption
  size_t plaintext_size = ciphertext_len + 1024;
  uint8_t *plaintext = buffer_pool_alloc(NULL, plaintext_size);
  if (!plaintext) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate plaintext buffer for decryption");
  }
 
  size_t plaintext_len;
  crypto_result_t result =
      crypto_decrypt(crypto_ctx, ciphertext, ciphertext_len, plaintext, plaintext_size, &plaintext_len);
 
  if (result != CRYPTO_OK) {
    buffer_pool_free(NULL, plaintext, plaintext_size);
    return SET_ERRNO(ERROR_CRYPTO, "Failed to decrypt packet: %s", crypto_result_to_string(result));
  }
 
  if (plaintext_len < sizeof(packet_header_t)) {
    buffer_pool_free(NULL, plaintext, plaintext_size);
    return SET_ERRNO(ERROR_CRYPTO, "Decrypted packet too small: %zu < %zu", plaintext_len, sizeof(packet_header_t));
  }
 
  // Parse inner packet header
  const packet_header_t *inner_header = (const packet_header_t *)plaintext;
  packet_type_t inner_type = NET_TO_HOST_U16(inner_header->type);
  uint32_t inner_len = NET_TO_HOST_U32(inner_header->length);
 
  // Validate inner packet length
  if (inner_len != plaintext_len - sizeof(packet_header_t)) {
    buffer_pool_free(NULL, plaintext, plaintext_size);
    return SET_ERRNO(ERROR_CRYPTO, "Inner packet length mismatch: header=%u, actual=%zu", inner_len,
                     plaintext_len - sizeof(packet_header_t));
  }
 
  // Free the original encrypted buffer if it's different from plaintext
  if (envelope->allocated_buffer && envelope->allocated_buffer != plaintext) {
    buffer_pool_free(NULL, envelope->allocated_buffer, envelope->allocated_size);
  }
 
  // Update envelope with decrypted packet info
  envelope->type = inner_type;
  envelope->data = (uint8_t *)plaintext + sizeof(packet_header_t);
  envelope->len = inner_len;
  envelope->allocated_buffer = plaintext;
  envelope->allocated_size = plaintext_size;
 
  log_info("[PACKET_DECRYPT] 🔐 Decrypted PACKET_TYPE_ENCRYPTED: inner_type=%u (0x%04x), len=%u", inner_type,
           inner_type, inner_len);
 
  return ASCIICHAT_OK;
}

References packet_envelope_t::allocated_buffer, packet_envelope_t::allocated_size, ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), crypto_decrypt(), CRYPTO_OK, crypto_result_to_string(), packet_envelope_t::data, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_MEMORY, packet_envelope_t::len, packet_header_t::length, log_info, NET_TO_HOST_U16, NET_TO_HOST_U32, PACKET_TYPE_ENCRYPTED, SET_ERRNO, packet_header_t::type, and packet_envelope_t::type.

Referenced by acip_client_receive_and_dispatch().

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

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 <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 1056 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 <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 352 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;
  if (pkt_len > 0) {
    payload = buffer_pool_alloc(NULL, pkt_len);
 
    // Use adaptive timeout for large packets
    uint64_t recv_timeout = calculate_packet_timeout(pkt_len);
    received = recv_with_timeout(sockfd, payload, pkt_len, recv_timeout);
    if (received < 0) {
      buffer_pool_free(NULL, payload, pkt_len);
      return SET_ERRNO_SYS(ERROR_NETWORK, "Failed to receive packet payload");
    }
    if (received != (ssize_t)pkt_len) {
      buffer_pool_free(NULL, payload, 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) {
      buffer_pool_free(NULL, payload, pkt_len);
      // Error context is already set by packet_validate_crc32
      return ERROR_NETWORK_PROTOCOL;
    }
  }
 
  // Return results
  *type = (packet_type_t)pkt_type;
  *data = payload;
  *len = pkt_len;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), ERROR_INVALID_PARAM, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, INVALID_SOCKET_VALUE, log_warn, NS_PER_SEC_INT, RECV_TIMEOUT, recv_with_timeout(), SET_ERRNO, and SET_ERRNO_SYS.

Referenced by nat_measure_bandwidth(), and receive_packet().

packet_send()

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

#include <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 292 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);
  }
 
  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 = calculate_packet_timeout(len);
 
  // Send header first
  ssize_t sent = send_with_timeout(sockfd, &header, sizeof(header), timeout);
  if (sent < 0) {
    // Error context is already set by send_with_timeout
    return ERROR_NETWORK;
  }
  if ((size_t)sent != sizeof(header)) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to fully send packet header. Sent %zd/%zu bytes", sent, sizeof(header));
  }
 
  // Send payload if present
  if (len > 0 && data) {
    // Check socket validity before sending payload to avoid race conditions
    if (!socket_is_valid(sockfd)) {
      return SET_ERRNO(ERROR_NETWORK, "Socket became invalid between header and payload send");
    }
    sent = send_with_timeout(sockfd, data, len, timeout);
    // Check for error first to avoid signed/unsigned comparison issues
    if (sent < 0) {
      // Error context is already set by send_with_timeout
      return ERROR_NETWORK;
    }
    if ((size_t)sent != len) {
      return SET_ERRNO(ERROR_NETWORK, "Failed to fully send packet payload. Sent %zd/%zu bytes", sent, len);
    }
  }
 
#ifdef DEBUG_NETWORK
  log_debug("Sent packet type=%d, len=%zu, errno=%d (%s)", type, len, errno, SAFE_STRERROR(errno));
#endif
 
  return 0;
}

References asciichat_crc32, errno, ERROR_INVALID_PARAM, ERROR_NETWORK, ERROR_NETWORK_SIZE, HOST_TO_NET_U16, HOST_TO_NET_U32, HOST_TO_NET_U64, INVALID_SOCKET_VALUE, log_debug, packet_header_t::magic, MAX_PACKET_SIZE, PACKET_MAGIC, SAFE_STRERROR, send_with_timeout(), SET_ERRNO, and socket_is_valid().

Referenced by discovery_session_check_host_alive(), nat_measure_bandwidth(), packet_send_error(), packet_send_remote_log(), send_image_frame_packet(), send_packet(), send_packet_secure(), session_host_broadcast_frame(), and session_host_send_frame().

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 <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	Human-readable message to accompany the error (can be NULL)

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 910 of file packet.c.

                                                         {
  if (sockfd == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
  }
 
  if (!message) {
    message = "";
  }
 
  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_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(), error_packet_t::error_code, error_code, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, log_warn, MAX_ERROR_MESSAGE_LENGTH, error_packet_t::message_length, packet_send(), PACKET_TYPE_ERROR_MESSAGE, SAFE_FREE, SAFE_MALLOC, send_packet_secure(), and SET_ERRNO.

Referenced by disconnect_client_for_bad_data().

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 <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 999 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_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, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, remote_log_packet_t::flags, HOST_TO_NET_U16, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, 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.

receive_packet()

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

#include <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 797 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().

Referenced by acds_client_handler(), acds_session_create(), acds_session_join(), acds_session_lookup(), discovery_session_process(), and server_crypto_handshake().

receive_packet_secure()

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

#include <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 569 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.

Referenced by acip_server_receive_and_dispatch(), and add_client().

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 <packet.h>

Definition at line 575 of file packet.c.

                                                                                                          {
 
  if (!envelope) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: envelope=%p", envelope);
    return PACKET_RECV_ERROR;
  }
 
  // Initialize envelope
  memset(envelope, 0, sizeof(*envelope));
 
  // Receive packet header
  packet_header_t header;
  ssize_t received = recv_with_timeout(sockfd, &header, sizeof(header), timeout_ns);
 
  // Check for errors first (before comparing signed with unsigned)
  if (received < 0) {
    /* Preserve a poll timeout so callers can wait for the next signaling packet
     * without treating an idle connection as a receive failure. */
    asciichat_error_context_t error_context;
    if (HAS_ERRNO(&error_context) && error_context.code == ERROR_NETWORK_TIMEOUT) {
      return PACKET_RECV_ERROR;
    }
    SET_ERRNO(ERROR_NETWORK, "Failed to receive packet header: %zd/%zu bytes", received, sizeof(header));
    return PACKET_RECV_ERROR;
  }
 
  if (received == 0) {
    return PACKET_RECV_EOF;
  }
 
  if ((size_t)received != sizeof(header)) {
    SET_ERRNO(ERROR_NETWORK, "Failed to receive packet header: %zd/%zu bytes", received, sizeof(header));
    return PACKET_RECV_ERROR;
  }
 
  // Convert from network byte order
  uint64_t magic = NET_TO_HOST_U64(header.magic);
  uint16_t pkt_type = NET_TO_HOST_U16(header.type);
  uint32_t pkt_len = NET_TO_HOST_U32(header.length);
  uint32_t expected_crc = NET_TO_HOST_U32(header.crc32);
 
  // DEBUG: Log raw header bytes for debugging packet misalignment
  char header_hex[95];
  for (size_t i = 0; i < sizeof(header); i++) {
    snprintf(&header_hex[i * 2], 3, "%02x", ((uint8_t *)&header)[i]);
  }
  header_hex[94] = '\0';
 
  // DEBUG: Log all received packet types in detail
  log_info("[RECV_PKT_HEADER] 🔍 Received packet: type=%u (0x%04x), len=%u, client_id=%u, raw=%s", pkt_type, pkt_type,
           pkt_len, header.client_id, header_hex);
 
  // Validate magic number
  if (magic != PACKET_MAGIC) {
    SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid packet magic: 0x%llx (expected 0x%llx)", magic, PACKET_MAGIC);
    return PACKET_RECV_ERROR;
  }
 
  // Validate packet size
  if (pkt_len > MAX_PACKET_SIZE) {
    SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: %u > %d", pkt_len, MAX_PACKET_SIZE);
    return PACKET_RECV_ERROR;
  }
 
  // Handle encrypted packets
  if (pkt_type == PACKET_TYPE_ENCRYPTED) {
    if (!crypto_ctx) {
      SET_ERRNO(ERROR_CRYPTO, "Received encrypted packet but no crypto context");
      return PACKET_RECV_ERROR;
    }
 
    // Read encrypted payload
    uint8_t *ciphertext = buffer_pool_alloc(NULL, pkt_len);
    if (!ciphertext) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for ciphertext");
      return PACKET_RECV_ERROR;
    }
 
    uint64_t recv_timeout = MAX(timeout_ns, calculate_packet_timeout(pkt_len));
    received = recv_with_timeout(sockfd, ciphertext, pkt_len, recv_timeout);
    if (received != (ssize_t)pkt_len) {
      SET_ERRNO(ERROR_NETWORK, "Failed to receive encrypted payload: %zd/%u bytes", received, pkt_len);
      buffer_pool_free(NULL, ciphertext, pkt_len);
      return PACKET_RECV_ERROR;
    }
 
    // Decrypt - allocate plaintext buffer with extra space
    // pkt_len is already validated to be <= MAX_PACKET_SIZE, so adding 1024 cannot overflow
    size_t plaintext_size = (size_t)pkt_len + 1024;
    uint8_t *plaintext = buffer_pool_alloc(NULL, plaintext_size);
    if (!plaintext) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for plaintext");
      buffer_pool_free(NULL, ciphertext, pkt_len);
      return PACKET_RECV_ERROR;
    }
 
    size_t plaintext_len;
    crypto_result_t result = crypto_decrypt(crypto_ctx, ciphertext, pkt_len, plaintext, plaintext_size, &plaintext_len);
    buffer_pool_free(NULL, ciphertext, pkt_len);
 
    if (result != CRYPTO_OK) {
      SET_ERRNO(ERROR_CRYPTO, "Failed to decrypt packet: %s", crypto_result_to_string(result));
      buffer_pool_free(NULL, plaintext, plaintext_size);
      return PACKET_RECV_ERROR;
    }
 
    if (plaintext_len < sizeof(packet_header_t)) {
      SET_ERRNO(ERROR_CRYPTO, "Decrypted packet too small: %zu < %zu", plaintext_len, sizeof(packet_header_t));
      buffer_pool_free(NULL, plaintext, plaintext_size);
      return PACKET_RECV_ERROR;
    }
 
    // Parse decrypted header
    packet_header_t *decrypted_header = (packet_header_t *)plaintext;
    pkt_type = NET_TO_HOST_U16(decrypted_header->type);
 
    // DEBUG: Log decrypted packet type
    log_info("[RECV_PKT_DECRYPTED] 🔐 After decryption: actual_type=%u (0x%04x), len=%u", pkt_type, pkt_type,
             NET_TO_HOST_U32(decrypted_header->length));
    pkt_len = NET_TO_HOST_U32(decrypted_header->length);
    expected_crc = NET_TO_HOST_U32(decrypted_header->crc32);
 
    // Extract payload
    size_t payload_len = plaintext_len - sizeof(packet_header_t);
    if (payload_len != pkt_len) {
      SET_ERRNO(ERROR_CRYPTO, "Decrypted payload size mismatch: %zu != %u", payload_len, pkt_len);
      buffer_pool_free(NULL, plaintext, plaintext_size);
      return PACKET_RECV_ERROR;
    }
 
    // Verify CRC
    if (pkt_len > 0) {
      uint32_t actual_crc = asciichat_crc32(plaintext + sizeof(packet_header_t), pkt_len);
      if (actual_crc != expected_crc) {
        SET_ERRNO(ERROR_CRYPTO, "Decrypted packet CRC mismatch: 0x%x != 0x%x", actual_crc, expected_crc);
        buffer_pool_free(NULL, plaintext, plaintext_size);
        return PACKET_RECV_ERROR;
      }
    }
 
    // Set envelope
    envelope->type = (packet_type_t)pkt_type;
    envelope->data = plaintext + sizeof(packet_header_t);
    envelope->len = pkt_len;
    envelope->allocated_buffer = plaintext;
    envelope->allocated_size = plaintext_size;
 
    return PACKET_RECV_SUCCESS;
  }
 
  // Handle unencrypted packets
  if (enforce_encryption && !packet_is_handshake_type(pkt_type)) {
    SET_ERRNO(ERROR_CRYPTO, "Received unencrypted packet type %d but encryption is required", pkt_type);
    return PACKET_RECV_ERROR;
  }
 
  // Read payload and return header+payload in envelope (matching encrypted path format)
  size_t total_size = sizeof(packet_header_t) + pkt_len;
  uint8_t *packet_buf = buffer_pool_alloc(NULL, total_size);
  if (!packet_buf) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for packet");
    return PACKET_RECV_ERROR;
  }
 
  // Copy header into buffer
  memcpy(packet_buf, &header, sizeof(packet_header_t));
 
  if (pkt_len > 0) {
    uint64_t recv_timeout = calculate_packet_timeout(pkt_len);
    received = recv_with_timeout(sockfd, packet_buf + sizeof(packet_header_t), pkt_len, recv_timeout);
    if (received != (ssize_t)pkt_len) {
      SET_ERRNO(ERROR_NETWORK, "Failed to receive payload: %zd/%u bytes", received, pkt_len);
      buffer_pool_free(NULL, packet_buf, total_size);
      return PACKET_RECV_ERROR;
    }
 
    // Verify CRC
    uint32_t actual_crc = asciichat_crc32(packet_buf + sizeof(packet_header_t), pkt_len);
    if (actual_crc != expected_crc) {
      SET_ERRNO(ERROR_NETWORK, "Packet CRC mismatch: 0x%x != 0x%x", actual_crc, expected_crc);
      buffer_pool_free(NULL, packet_buf, total_size);
      return PACKET_RECV_ERROR;
    }
  }
 
  envelope->data = packet_buf;
  envelope->allocated_buffer = packet_buf;
  envelope->allocated_size = total_size;
  envelope->type = (packet_type_t)pkt_type;
  envelope->len = total_size;
 
  return PACKET_RECV_SUCCESS;
}

References packet_envelope_t::allocated_buffer, packet_envelope_t::allocated_size, asciichat_crc32, buffer_pool_alloc(), buffer_pool_free(), packet_header_t::client_id, asciichat_error_context_t::code, packet_header_t::crc32, crypto_decrypt(), CRYPTO_OK, crypto_result_to_string(), packet_envelope_t::data, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, ERROR_NETWORK_SIZE, ERROR_NETWORK_TIMEOUT, HAS_ERRNO, packet_envelope_t::len, packet_header_t::length, log_info, packet_header_t::magic, MAX, MAX_PACKET_SIZE, NET_TO_HOST_U16, NET_TO_HOST_U32, NET_TO_HOST_U64, PACKET_MAGIC, PACKET_RECV_EOF, PACKET_RECV_ERROR, PACKET_RECV_SUCCESS, PACKET_TYPE_ENCRYPTED, recv_with_timeout(), SET_ERRNO, packet_header_t::type, and packet_envelope_t::type.

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 <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 182 of file network/network.c.

                                                                                       {
  if (sockfd == INVALID_SOCKET_VALUE) {
    errno = EBADF;
    return -1;
  }
 
  ssize_t total_received = 0;
  char *data = (char *)buf;
 
  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
    int result = socket_poll(&pfd, 1, (int64_t)timeout_ns);
    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. */
        asciichat_errno = ERROR_NETWORK_TIMEOUT;
        asciichat_errno_context.code = ERROR_NETWORK_TIMEOUT;
        asciichat_errno_context.has_system_error = true;
        asciichat_errno_context.system_errno = ETIMEDOUT;
        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.
    if (pfd.revents & (POLLERR | POLLHUP | POLLNVAL)) {
      SET_ERRNO(ERROR_NETWORK, "recv_with_timeout poll reported socket flags 0x%x", pfd.revents);
      return -1;
    }
 
    // Other readiness flags without POLLIN are an ordinary no-data result.
    if (!(pfd.revents & POLLIN)) {
      asciichat_errno = ERROR_NETWORK_TIMEOUT;
      asciichat_errno_context.code = ERROR_NETWORK_TIMEOUT;
      asciichat_errno_context.has_system_error = true;
      asciichat_errno_context.system_errno = ETIMEDOUT;
      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 asciichat_errno, asciichat_errno_context, asciichat_error_context_t::code, EBADF, errno, ERROR_NETWORK, ERROR_NETWORK_TIMEOUT, ETIMEDOUT, asciichat_error_context_t::has_system_error, INVALID_SOCKET_VALUE, log_debug, SET_ERRNO, socket_poll(), socket_recv(), and asciichat_error_context_t::system_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 <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 1133 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.

Referenced by discovery_session_process().

send_crypto_parameters_packet()

int send_crypto_parameters_packet	(	socket_t	sockfd,
		const crypto_parameters_packet_t *	params
	)

#include <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 1147 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.

Referenced by server_crypto_handshake().

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 <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 1230 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 = width;
  packet.height = height;
  packet.pixel_format = 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_pool_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_pool_free(NULL, packet_data, total_size);
 
  return result;
}

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

send_packet()

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

#include <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 784 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 acds_session_create(), acds_session_join(), acds_session_lookup(), acip_server_send_error(), send_crypto_capabilities_packet(), send_crypto_parameters_packet(), send_error_packet_message(), send_ping_packet(), send_pong_packet(), send_protocol_version_packet(), and tcp_client_send_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 <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 434 of file packet.c.

                                                                   {
  if (len > MAX_PACKET_SIZE) {
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: %zu > %d", len, MAX_PACKET_SIZE);
  }
 
  // Handshake packets are ALWAYS sent unencrypted
  if (packet_is_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("Compressed packet: %zu -> %zu bytes (%.1f%%)", len, compressed_size, ratio * 100.0);
      } else {
        SAFE_FREE(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) {
    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) {
      SAFE_FREE(compressed_data);
    }
    if (result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send packet: %s", asciichat_error_string(result));
    }
    return result;
  }
 
  // Encrypt the packet: create header + payload, encrypt everything, wrap in PACKET_TYPE_ENCRYPTED
  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)final_len),
                            .crc32 = HOST_TO_NET_U32(final_len > 0 ? asciichat_crc32(final_data, final_len) : 0),
                            .client_id = HOST_TO_NET_U32(0)}; // Always 0 - client_id is not used in practice
 
  // Combine header + payload for encryption
  // Check for integer overflow before addition
  if (final_len > SIZE_MAX - sizeof(header)) {
    if (compressed_data) {
      SAFE_FREE(compressed_data);
    }
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: would overflow plaintext buffer size");
  }
  size_t plaintext_len = sizeof(header) + final_len;
  uint8_t *plaintext = buffer_pool_alloc(NULL, plaintext_len);
  if (!plaintext) {
    if (compressed_data) {
      SAFE_FREE(compressed_data);
    }
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for plaintext packet");
  }
 
  memcpy(plaintext, &header, sizeof(header));
  if (final_len > 0 && final_data) {
    memcpy(plaintext + sizeof(header), final_data, final_len);
  }
 
  // Encrypt
  // Check for integer overflow before calculating ciphertext size
  if (plaintext_len > SIZE_MAX - CRYPTO_NONCE_SIZE - CRYPTO_MAC_SIZE) {
    buffer_pool_free(NULL, plaintext, plaintext_len);
    if (compressed_data) {
      SAFE_FREE(compressed_data);
    }
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Packet too large: would overflow ciphertext buffer size");
  }
  size_t ciphertext_size = plaintext_len + CRYPTO_NONCE_SIZE + CRYPTO_MAC_SIZE;
  uint8_t *ciphertext = buffer_pool_alloc(NULL, ciphertext_size);
  if (!ciphertext) {
    buffer_pool_free(NULL, plaintext, plaintext_len);
    if (compressed_data) {
      SAFE_FREE(compressed_data);
    }
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for ciphertext");
  }
 
  size_t ciphertext_len;
  crypto_result_t result =
      crypto_encrypt(crypto_ctx, plaintext, plaintext_len, ciphertext, ciphertext_size, &ciphertext_len);
  buffer_pool_free(NULL, plaintext, plaintext_len);
 
  if (result != CRYPTO_OK) {
    buffer_pool_free(NULL, ciphertext, ciphertext_size);
    if (compressed_data) {
      SAFE_FREE(compressed_data);
    }
    return SET_ERRNO(ERROR_CRYPTO, "Failed to encrypt packet: %s", crypto_result_to_string(result));
  }
 
  // Send as PACKET_TYPE_ENCRYPTED
  log_debug_every(LOG_RATE_SLOW, "CRYPTO_DEBUG: Sending encrypted packet (original type %d as PACKET_TYPE_ENCRYPTED)",
                  type);
  asciichat_error_t send_result = packet_send(sockfd, PACKET_TYPE_ENCRYPTED, ciphertext, ciphertext_len);
  buffer_pool_free(NULL, ciphertext, ciphertext_size);
 
  if (compressed_data) {
    SAFE_FREE(compressed_data);
  }
 
  return send_result;
}

References asciichat_crc32, ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), compress_data(), COMPRESSION_MIN_SIZE, COMPRESSION_RATIO_THRESHOLD, crypto_encrypt(), crypto_is_ready(), CRYPTO_MAC_SIZE, CRYPTO_NONCE_SIZE, CRYPTO_OK, crypto_result_to_string(), ERROR_CRYPTO, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_SIZE, GET_OPTION, HOST_TO_NET_U16, HOST_TO_NET_U32, HOST_TO_NET_U64, log_debug, log_debug_every, LOG_RATE_FAST, LOG_RATE_SLOW, log_warn_every, packet_header_t::magic, MAX_PACKET_SIZE, PACKET_MAGIC, packet_send(), PACKET_TYPE_ENCRYPTED, SAFE_FREE, SET_ERRNO, and should_compress().

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 <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 813 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 <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 822 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 <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 1119 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.

Referenced by discovery_session_process(), and server_crypto_handshake().

send_with_timeout()

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

#include <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 112 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, "send_with_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, "send_with_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, INVALID_SOCKET_VALUE, network_is_test_environment, NS_PER_MS_INT, SET_ERRNO_SYS, socket_poll(), and socket_send().

Referenced by packet_send().

set_socket_keepalive()

asciichat_error_t set_socket_keepalive

(

socket_t

sockfd

)

#include <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 371 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, INVALID_SOCKET_VALUE, KEEPALIVE_COUNT, KEEPALIVE_IDLE, KEEPALIVE_INTERVAL, SET_ERRNO, SET_ERRNO_SYS, and socket_set_keepalive_params().

set_socket_nonblocking()

asciichat_error_t set_socket_nonblocking

(

socket_t

sockfd

)

#include <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 387 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, INVALID_SOCKET_VALUE, SET_ERRNO, SET_ERRNO_SYS, and socket_set_nonblocking().

Referenced by connect_with_timeout().

set_socket_timeout()

asciichat_error_t set_socket_timeout	(	socket_t	sockfd,
		uint64_t	timeout_ns
	)

#include <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 336 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, INVALID_SOCKET_VALUE, SET_ERRNO, SET_ERRNO_SYS, and socket_setsockopt().

Referenced by add_client().

socket_configure_buffers()

asciichat_error_t socket_configure_buffers

(

socket_t

sockfd

)

#include <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 403 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, INVALID_SOCKET_VALUE, log_warn, network_error_string(), SET_ERRNO_SYS, and socket_setsockopt().

Referenced by server_connection_establish(), and tcp_client_connect().

update_check_detect_install_method()

install_method_t update_check_detect_install_method

(

void

)

#include <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 380 of file update_checker.c.

                                                          {
  if (is_homebrew_install()) {
    return INSTALL_METHOD_HOMEBREW;
  }
 
  if (is_arch_linux()) {
    return INSTALL_METHOD_ARCH_AUR;
  }
 
  // Default to GitHub releases
  return INSTALL_METHOD_GITHUB;
}

References INSTALL_METHOD_ARCH_AUR, INSTALL_METHOD_GITHUB, and INSTALL_METHOD_HOMEBREW.

Referenced by update_banner_print_instructions(), update_banner_show_prompt(), and update_check_format_notification().

update_check_format_notification()

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

#include <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 437 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[512];
  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, 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_upgrade_suggestion()

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

#include <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 393 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_ARCH_AUR: {
    // Cache AUR helper detection to avoid spawning subprocesses on every call
    static int aur_helper = -1; // -1 = unknown, 0 = none, 1 = paru, 2 = yay
    if (aur_helper == -1) {
      const char *argv_paru[] = {"paru", "--version", NULL};
      const char *argv_yay[] = {"yay", "--version", NULL};
      if (platform_execute_subprocess("paru", argv_paru, NULL, 0) == 0) {
        aur_helper = 1;
      } else if (platform_execute_subprocess("yay", argv_yay, NULL, 0) == 0) {
        aur_helper = 2;
      } else {
        aur_helper = 0;
      }
    }
    if (aur_helper == 1) {
      snprintf(buffer, buffer_size, "paru -S ascii-chat");
    } else if (aur_helper == 2) {
      snprintf(buffer, buffer_size, "yay -S ascii-chat");
    } 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_UNKNOWN, and platform_execute_subprocess().

Referenced by update_banner_print_instructions(), update_banner_show_prompt(), and update_check_format_notification().

update_check_is_cache_fresh()

bool update_check_is_cache_fresh

(

const update_check_result_t *

result

)

#include <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 211 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().

update_check_load_cache()

asciichat_error_t update_check_load_cache

(

update_check_result_t *

result

)

#include <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 79 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");
  }
 
  FILE *f = platform_fopen("file_stream", cache_path, "r");
  if (!f) {
    const char *error_msg = file_read_error_message(cache_path);
    SAFE_FREE(cache_path);
    return SET_ERRNO(ERROR_FILE_OPERATION, "%s", error_msg);
  }
 
  // Read line 1: timestamp
  char line[512];
  if (!fgets(line, sizeof(line), f)) {
    fclose(f);
    SAFE_FREE(cache_path);
    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);
    fclose(f);
    SAFE_FREE(cache_path);
    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)) {
    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);
    SAFE_FREE(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));
 
  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);
      }
      SAFE_FREE(cache_path);
      return SET_ERRNO(ERROR_FORMAT, "Corrupted cache file deleted");
    }
  }
 
  SAFE_FREE(cache_path);
  return ASCIICHAT_OK;
}

References ASCII_CHAT_GIT_COMMIT_HASH, ASCII_CHAT_VERSION_STRING, ASCIICHAT_OK, update_check_result_t::check_succeeded, update_check_result_t::current_sha, update_check_result_t::current_version, errno, ERROR_FILE_OPERATION, ERROR_FORMAT, ERROR_INVALID_PARAM, file_read_error_message(), update_check_result_t::last_check_time, update_check_result_t::latest_sha, update_check_result_t::latest_version, log_error, log_warn, platform_fopen(), update_check_result_t::release_url, SAFE_FREE, SAFE_STRNCPY, SET_ERRNO, update_check_result_t::update_available, semantic_version_t::valid, version_compare(), and version_parse().

Referenced by update_check_startup().

update_check_perform()

asciichat_error_t update_check_perform

(

update_check_result_t *

result

)

#include <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 265 of file update_checker.c.

                                                                      {
  if (!result) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL result pointer");
  }
 
  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);
 
  // Test DNS connectivity first
  if (!dns_test_connectivity(GITHUB_API_HOSTNAME)) {
    log_warn("No internet connectivity detected, skipping update check");
    // Don't update cache - we'll retry when online
    return SET_ERRNO(ERROR_NETWORK, "DNS connectivity test failed");
  }
 
  // 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");
  }
 
  // Parse JSON response
  char latest_tag[64] = {0};
  char release_url[512] = {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");
    SAFE_FREE(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");
  }
 
  SAFE_FREE(response);
 
  // 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;
 
  // 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 ASCII_CHAT_GIT_COMMIT_HASH, ASCII_CHAT_VERSION_STRING, ASCIICHAT_OK, update_check_result_t::check_succeeded, update_check_result_t::current_sha, update_check_result_t::current_version, dns_test_connectivity(), 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, update_check_result_t::release_url, SAFE_FREE, SAFE_STRNCPY, SET_ERRNO, update_check_result_t::update_available, update_check_save_cache(), semantic_version_t::valid, 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 <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 175 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");
  }
 
  FILE *f = platform_fopen("file_stream", cache_path, "w");
  if (!f) {
    const char *error_msg = file_write_error_message(cache_path);
    SAFE_FREE(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);
 
  fclose(f);
  SAFE_FREE(cache_path);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_FILE_OPERATION, ERROR_INVALID_PARAM, file_write_error_message(), update_check_result_t::last_check_time, update_check_result_t::latest_sha, update_check_result_t::latest_version, platform_fopen(), update_check_result_t::release_url, SAFE_FREE, and SET_ERRNO.

Referenced by update_check_perform().

update_check_startup()

asciichat_error_t update_check_startup

(

update_check_result_t *

result

)

#include <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 456 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 = update_check_load_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(), update_check_load_cache(), and update_check_perform().