Shared Packet Parsing Utilities

📡 Shared protocol parsing utilities for server and client packet handlers More...

Files
file	packet_parsing.c
	📡 Shared packet parsing utilities implementation
file	packet_parsing.h
	Shared packet parsing utilities to eliminate duplication between server and client handlers.

Macros
#define	PACKET_MAX_FRAME_SIZE   (256 * 1024 * 1024)
	Maximum frame size (256MB) - prevents memory exhaustion attacks.
#define	PACKET_MAX_DIMENSION   32768
	Maximum frame dimension (32768x32768) - prevents overflow.

Frame Decoding Functions
Unified frame data decoding for both compressed and uncompressed formats
char *	packet_decode_frame_data_malloc (const char *frame_data_ptr, size_t frame_data_len, bool is_compressed, uint32_t original_size, uint32_t compressed_size)
	Decode frame data (malloc version for client handlers)
asciichat_error_t	packet_decode_frame_data_buffer (const char *frame_data_ptr, size_t frame_data_len, bool is_compressed, void *output_buffer, size_t output_size, uint32_t original_size, uint32_t compressed_size)
	Decode frame data (fixed buffer version for server handlers)

Frame Dimension Validation
Validation helpers for frame dimensions with overflow checking
asciichat_error_t	packet_validate_frame_dimensions (uint32_t width, uint32_t height, size_t *out_rgb_size)
	Validate frame dimensions and calculate RGB buffer size.

Opus Audio Batch Parsing
Helpers for parsing Opus audio batch packets
asciichat_error_t	packet_parse_opus_batch (const void *packet_data, size_t packet_len, const uint8_t **out_opus_data, size_t *out_opus_size, const uint16_t **out_frame_sizes, int *out_sample_rate, int *out_frame_duration, int *out_frame_count)
	Parse Opus audio batch packet header and extract frame data.

Detailed Description

📡 Shared protocol parsing utilities for server and client packet handlers

This module provides reusable utilities for parsing and validating protocol packets, used by both server (src/server/protocol.c) and client (src/client/protocol.c) handlers.

CORE RESPONSIBILITIES:

1. Frame data decoding (handles compressed and uncompressed formats)
2. Network byte order conversions and validation
3. Audio batch header parsing and validation
4. Frame dimension validation with overflow checking
5. Generic packet payload validation helpers

DESIGN PRINCIPLES:

• Minimal dependencies on protocol-specific types
• Clear error codes and messages
• No assumptions about error handling (caller decides)
• Support for both server and client usage patterns
• Overflow-safe integer arithmetic throughout

USAGE PATTERNS:

Server handlers use these for incoming client packets:

// Decode compressed/uncompressed frame data
frame_buffer_t *decoded = packet_decode_frame_data(
    frame_data_ptr, frame_data_len, is_compressed,
    expected_size, compressed_size);
 
// Validate audio batch header
audio_batch_info_t batch;
result = packet_parse_audio_batch_header(data, len, &batch);

Client handlers use these for incoming server packets:

// Same frame decoding for server->client frames
char *decoded = packet_decode_frame_data_malloc(
    frame_data, frame_data_len, is_compressed,
    original_size, compressed_size);

INTEGRATION POINTS:

• src/server/protocol.c: IMAGE_FRAME, AUDIO_BATCH, AUDIO_OPUS_BATCH packet handling
• src/client/protocol.c: ASCII_FRAME, AUDIO_BATCH, AUDIO_OPUS_BATCH packet handling
• lib/network/packet.h: Low-level packet structure definitions
• lib/network/av.h: Audio/video packet serialization
• lib/util/validation.h: High-level packet validation macros

OVERFLOW SAFETY:

All integer calculations use safe_size_mul() and overflow checking to prevent buffer overflows from malicious or malformed packets.

Author

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

Date

December 2025

Macro Definition Documentation

PACKET_MAX_DIMENSION

#define PACKET_MAX_DIMENSION   32768

#include <packet_parsing.c>

Maximum frame dimension (32768x32768) - prevents overflow.

Definition at line 31 of file packet_parsing.c.

PACKET_MAX_FRAME_SIZE

#define PACKET_MAX_FRAME_SIZE   (256 * 1024 * 1024)

#include <packet_parsing.c>

Maximum frame size (256MB) - prevents memory exhaustion attacks.

Definition at line 25 of file packet_parsing.c.

Function Documentation

packet_decode_frame_data_buffer()

asciichat_error_t packet_decode_frame_data_buffer	(	const char *	frame_data_ptr,
		size_t	frame_data_len,
		bool	is_compressed,
		void *	output_buffer,
		size_t	output_size,
		uint32_t	original_size,
		uint32_t	compressed_size
	)

#include <packet_parsing.h>

Decode frame data (fixed buffer version for server handlers)

Decodes frame data into a pre-allocated fixed-size buffer. Used when buffer allocation is managed separately (e.g., ring buffers).

Parameters

frame_data_ptr	Pointer to frame data (compressed or uncompressed)
frame_data_len	Actual size of frame_data_ptr buffer
is_compressed	True if data is zstd-compressed
output_buffer	Pre-allocated output buffer
output_size	Size of output_buffer in bytes
original_size	Expected decompressed/uncompressed size
compressed_size	Expected compressed size (if is_compressed=true)

Returns

ASCIICHAT_OK on success, error code on failure Errors set asciichat_errno with context message

Note

Used by server handlers for client->server IMAGE_FRAME packets

See also

packet_decode_frame_data_malloc() For malloc version

Definition at line 89 of file packet_parsing.c.

                                                                            {
  if (!frame_data_ptr || !output_buffer) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL pointer in frame decode");
  }
 
  if (output_size < original_size) {
    return SET_ERRNO(ERROR_BUFFER_FULL, "Output buffer too small: %zu < %u", output_size, original_size);
  }
 
  if (is_compressed) {
    // Validate compressed frame size
    if (frame_data_len != compressed_size) {
      return SET_ERRNO(ERROR_NETWORK_SIZE, "Compressed frame size mismatch: expected %u, got %zu", compressed_size,
                       frame_data_len);
    }
 
    // Decompress using compression API
    asciichat_error_t decompress_result = decompress_data(frame_data_ptr, frame_data_len, output_buffer, original_size);
 
    if (decompress_result != ASCIICHAT_OK) {
      return SET_ERRNO(ERROR_COMPRESSION, "Decompression failed for expected size %u: %s", original_size,
                       asciichat_error_string(decompress_result));
    }
 
    log_debug("Decompressed frame to buffer: %zu -> %u bytes", frame_data_len, original_size);
  } else {
    // Uncompressed frame - validate size
    if (frame_data_len != original_size) {
      return SET_ERRNO(ERROR_NETWORK_SIZE, "Uncompressed frame size mismatch: expected %u, got %zu", original_size,
                       frame_data_len);
    }
 
    // Copy data to output buffer
    memcpy(output_buffer, frame_data_ptr, original_size);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, decompress_data(), ERROR_BUFFER_FULL, ERROR_COMPRESSION, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, log_debug, and SET_ERRNO.

packet_decode_frame_data_malloc()

char * packet_decode_frame_data_malloc	(	const char *	frame_data_ptr,
		size_t	frame_data_len,
		bool	is_compressed,
		uint32_t	original_size,
		uint32_t	compressed_size
	)

#include <packet_parsing.h>

Decode frame data (malloc version for client handlers)

Handles both compressed (zstd) and uncompressed frame formats. Allocates buffer using SAFE_MALLOC that caller must free. Validates sizes to prevent memory exhaustion attacks.

Frame formats supported:

• Uncompressed: Raw pixel/text data at expected_size bytes
• Compressed: zstd-compressed data, decompresses to expected_size bytes

SIZE VALIDATION:

• Validates original_size <= 100MB (prevents excessive allocation)
• Validates expected_size == uncompressed size
• Validates compressed_size <= frame_data_len (if compressed)

ERROR HANDLING:

• Returns NULL on allocation failure
• Returns NULL on decompression failure
• Returns NULL on size validation failure
• Sets asciichat_errno for detailed error reporting

Parameters

frame_data_ptr	Pointer to frame data (compressed or uncompressed)
frame_data_len	Actual size of frame_data_ptr buffer
is_compressed	True if data is zstd-compressed, false if raw
original_size	Expected decompressed/uncompressed size in bytes
compressed_size	Expected compressed size (validated only if is_compressed=true)

Returns

Allocated buffer with decoded data (caller must SAFE_FREE), or NULL on error

Note

Caller is responsible for freeing returned buffer with SAFE_FREE()

Added null terminator to decoded data (buffer is original_size + 1)

Used by client handlers for server->client frame packets

See also

packet_decode_frame_data_buffer() For fixed-size buffer variant

Definition at line 33 of file packet_parsing.c.

                                                                                        {
  // Validate size before allocation to prevent excessive memory usage
  if (original_size > PACKET_MAX_FRAME_SIZE) {
    char size_str[32];
    format_bytes_pretty(original_size, size_str, sizeof(size_str));
    SET_ERRNO(ERROR_NETWORK_SIZE, "Frame size exceeds maximum: %s (max %d MB)", size_str,
              PACKET_MAX_FRAME_SIZE / (1024 * 1024));
    return NULL;
  }
 
  // Allocate buffer with extra byte for null terminator
  char *frame_data = SAFE_MALLOC(original_size + 1, char *);
  if (!frame_data) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate %u bytes for frame decode", original_size);
    return NULL;
  }
 
  if (is_compressed) {
    // Validate compressed frame size
    if (frame_data_len != compressed_size) {
      SET_ERRNO(ERROR_NETWORK_SIZE, "Compressed frame size mismatch: expected %u, got %zu", compressed_size,
                frame_data_len);
      SAFE_FREE(frame_data);
      return NULL;
    }
 
    // Decompress using compression API
    asciichat_error_t decompress_result = decompress_data(frame_data_ptr, frame_data_len, frame_data, original_size);
 
    if (decompress_result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_COMPRESSION, "Decompression failed for expected size %u: %s", original_size,
                asciichat_error_string(decompress_result));
      SAFE_FREE(frame_data);
      return NULL;
    }
 
    log_debug("Decompressed frame: %zu -> %u bytes", frame_data_len, original_size);
  } else {
    // Uncompressed frame - validate size
    if (frame_data_len != original_size) {
      log_error("Uncompressed frame size mismatch: expected %u, got %zu", original_size, frame_data_len);
      SAFE_FREE(frame_data);
      return NULL;
    }
 
    // Only copy the actual amount of data we received
    size_t copy_size = (frame_data_len > original_size) ? original_size : frame_data_len;
    memcpy(frame_data, frame_data_ptr, copy_size);
  }
 
  // Null-terminate the frame data
  frame_data[original_size] = '\0';
  return frame_data;
}

References ASCIICHAT_OK, decompress_data(), ERROR_COMPRESSION, ERROR_MEMORY, ERROR_NETWORK_SIZE, format_bytes_pretty(), log_debug, log_error, PACKET_MAX_FRAME_SIZE, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

packet_parse_opus_batch()

asciichat_error_t packet_parse_opus_batch	(	const void *	packet_data,
		size_t	packet_len,
		const uint8_t **	out_opus_data,
		size_t *	out_opus_size,
		const uint16_t **	out_frame_sizes,
		int *	out_sample_rate,
		int *	out_frame_duration,
		int *	out_frame_count
	)

#include <packet_parsing.h>

Parse Opus audio batch packet header and extract frame data.

Parses PACKET_TYPE_AUDIO_OPUS_BATCH packet and extracts metadata and Opus data. The Opus data and frame_sizes pointers point into the packet_data buffer (NOT copied), so packet_data must remain valid while using these outputs.

Packet format:

• Offset 0-3: sample_rate (uint32_t, network byte order)
• Offset 4-7: frame_duration (uint32_t, network byte order)
• Offset 8-11: frame_count (uint32_t, network byte order)
• Offset 12-15: reserved (4 bytes, zeroed)
• Offset 16+: frame_sizes array (uint16_t[], network byte order)
• After sizes: Opus-encoded data (concatenated frames)

Parameters

packet_data	Packet payload data
packet_len	Packet payload length
out_opus_data	Output: Pointer to Opus-encoded data within packet (NOT copied)
out_opus_size	Output: Size of Opus-encoded data
out_frame_sizes	Output: Pointer to frame sizes array within packet (NOT copied)
out_sample_rate	Output: Sample rate in Hz
out_frame_duration	Output: Frame duration in milliseconds
out_frame_count	Output: Number of frames in batch

Returns

ASCIICHAT_OK on success, error code on failure:

• ERROR_INVALID_PARAM: NULL pointers
• ERROR_NETWORK_PROTOCOL: Packet too small or malformed

Note

out_opus_data and out_frame_sizes point into packet_data - do not free separately

Frame sizes in out_frame_sizes are in NETWORK byte order - use NET_TO_HOST_U16() when reading

Warning

packet_data must remain valid while using out_opus_data and out_frame_sizes

Definition at line 173 of file packet_parsing.c.

                                                                                         {
  if (!packet_data || !out_opus_data || !out_opus_size || !out_frame_sizes || !out_sample_rate || !out_frame_duration ||
      !out_frame_count) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL parameter in Opus batch parsing");
  }
 
  // Verify minimum packet size (16-byte header)
  const size_t header_size = 16;
  if (packet_len < header_size) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Opus batch packet too small: %zu < %zu", packet_len, header_size);
  }
 
  // Parse header (convert from network byte order)
  const uint8_t *buf = (const uint8_t *)packet_data;
  uint32_t sr, fd, fc;
  memcpy(&sr, buf, 4);
  memcpy(&fd, buf + 4, 4);
  memcpy(&fc, buf + 8, 4);
  *out_sample_rate = (int)NET_TO_HOST_U32(sr);
  *out_frame_duration = (int)NET_TO_HOST_U32(fd);
  int frame_count = (int)NET_TO_HOST_U32(fc);
  *out_frame_count = frame_count;
 
  // Validate frame count to prevent overflow
  if (frame_count < 0 || frame_count > 1000) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid Opus frame count: %d (must be 0-1000)", frame_count);
  }
 
  // Extract frame sizes array (after 16-byte header)
  size_t frame_sizes_bytes = (size_t)frame_count * sizeof(uint16_t);
  if (packet_len < header_size + frame_sizes_bytes) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Opus batch packet too small for frame sizes: %zu < %zu", packet_len,
                     header_size + frame_sizes_bytes);
  }
  // NOTE: Frame sizes are in network byte order - caller must use NET_TO_HOST_U16() when reading
  *out_frame_sizes = (const uint16_t *)(buf + header_size);
 
  // Extract Opus data (after header + frame sizes)
  *out_opus_data = buf + header_size + frame_sizes_bytes;
  *out_opus_size = packet_len - header_size - frame_sizes_bytes;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK_PROTOCOL, NET_TO_HOST_U32, and SET_ERRNO.

Referenced by handle_audio_opus_batch_packet().

packet_validate_frame_dimensions()

asciichat_error_t packet_validate_frame_dimensions	(	uint32_t	width,
		uint32_t	height,
		size_t *	out_rgb_size
	)

#include <packet_parsing.h>

Validate frame dimensions and calculate RGB buffer size.

Performs comprehensive validation of frame dimensions:

1. Checks width and height are non-zero and reasonable (< 32768)
2. Calculates RGB buffer size (width * height * 3) with overflow checking
3. Validates result size doesn't exceed max image size (256MB)

OVERFLOW PROTECTION:

• Uses safe_size_mul() for dimension multiplication
• Checks for integer overflow at each step
• Returns error instead of wrapping around

Parameters

width	Frame width in pixels
height	Frame height in pixels
out_rgb_size	Output parameter: calculated RGB size (width*height*3)

Returns

ASCIICHAT_OK on success, error code on failure:

• ERROR_INVALID_STATE: width or height is zero
• ERROR_INVALID_STATE: dimensions exceed max (32768)
• ERROR_MEMORY: Calculated size exceeds max (256MB)
• ERROR_MEMORY: Integer overflow in multiplication

Note

Critical for preventing integer overflow attacks

Used by both server and client frame handlers

Definition at line 130 of file packet_parsing.c.

                                                                                                          {
  if (!out_rgb_size) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "out_rgb_size pointer is NULL");
  }
 
  // Check dimensions are non-zero
  if (width == 0 || height == 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Frame dimensions cannot be zero: %ux%u", width, height);
  }
 
  // Check dimensions are within reasonable bounds
  if (width > PACKET_MAX_DIMENSION || height > PACKET_MAX_DIMENSION) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Frame dimensions exceed maximum: %ux%u (max %u)", width, height,
                     PACKET_MAX_DIMENSION);
  }
 
  // Calculate RGB buffer size with overflow checking (width * height * 3 bytes per pixel)
  size_t pixel_count = 0;
  if (safe_size_mul(width, height, &pixel_count) != 0) {
    return SET_ERRNO(ERROR_MEMORY, "Frame dimension multiplication overflow: %u * %u", width, height);
  }
 
  size_t rgb_size = 0;
  if (safe_size_mul(pixel_count, 3, &rgb_size) != 0) {
    return SET_ERRNO(ERROR_MEMORY, "RGB buffer size overflow: %zu * 3", pixel_count);
  }
 
  // Validate final buffer size against maximum
  if (rgb_size > PACKET_MAX_FRAME_SIZE) {
    char size_str[32];
    format_bytes_pretty(rgb_size, size_str, sizeof(size_str));
    return SET_ERRNO(ERROR_MEMORY, "Frame buffer size exceeds maximum: %s (max %d MB)", size_str,
                     PACKET_MAX_FRAME_SIZE / (1024 * 1024));
  }
 
  *out_rgb_size = rgb_size;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, format_bytes_pretty(), PACKET_MAX_DIMENSION, PACKET_MAX_FRAME_SIZE, safe_size_mul, and SET_ERRNO.