ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
server/protocol.c
Go to the documentation of this file.
1
111
112/* Storage capacities in elements; text buffers include the terminating NUL. */
113#define SERVER_PROTOCOL_REASON_BUFFER_SIZE 257
114#define SERVER_PROTOCOL_PRETTY_BUFFER_SIZE 64
115#define SERVER_PROTOCOL_SIZE_BUFFER_SIZE 32
116
117/* Existing buffer budgets in bytes, including NUL for text storage. */
118#define SERVER_H265_RGBA_WIDTH 512
119#define SERVER_H265_RGBA_HEIGHT 512
120#define SERVER_H265_RGBA_BUFFER_SIZE (SERVER_H265_RGBA_WIDTH * SERVER_H265_RGBA_HEIGHT * 4)
121
123#include <math.h>
124#include <stdarg.h>
125#include <libplatform/atomic.h>
126#include <stdio.h>
127#include <string.h>
128#include <time.h>
129
130#include "main.h"
131#include "protocol.h"
132
133#include "client.h"
134#include "session/h265/server.h"
136#include <ascii-chat/common.h>
143#include <ascii-chat/util/time.h>
155#include <libplatform/system.h>
160
161static void protocol_cleanup_thread_locals(void) {
162 // Placeholder for thread-local resources owned by the receive thread.
163 // Add cleanup logic here if future protocol changes introduce
164 // thread-local allocations that must be released before disconnecting.
165}
166
167void disconnect_client_for_bad_data(client_info_t *client, const char *format, ...) {
168 if (!client) {
169 return;
170 }
171
172 protocol_cleanup_thread_locals();
173
174 // Atomically set the disconnect flag and get the old value
175 // This ensures only one thread proceeds to disconnect (the first one)
176 bool already_requested = atomic_exchange_bool(&client->protocol_disconnect_requested, true);
177 if (already_requested) {
178 return; // Already disconnecting, don't do it again
179 }
180
181 char reason[BUFFER_SIZE_SMALL] = {0};
182 if (format) {
183 va_list args;
184 va_start(args, format);
185 safe_vsnprintf(reason, sizeof(reason), format, args);
186 va_end(args);
187 } else {
188 SAFE_STRNCPY(reason, "Protocol violation", sizeof(reason));
189 }
190
191 const char *reason_str = reason[0] != '\0' ? reason : "Protocol violation";
192 const char *client_id = client->client_id;
193
194 log_warn("Disconnecting client %s due to protocol violation: %s", client_id, reason_str);
195 mutex_lock(&client->send_mutex);
196 if (client->transport)
198 mutex_unlock(&client->send_mutex);
199
200 log_debug("Setting active=false (client_id=%s, reason=%s)", client_id, reason_str);
201 atomic_store_bool(&client->active, false);
202 atomic_store_bool(&client->shutting_down, true);
206}
207
208/* ============================================================================
209 * Client Lifecycle Packet Handlers
210 * ============================================================================
211 */
212
249
250void handle_client_join_packet(client_info_t *client, const void *data, size_t len) {
251 VALIDATE_PACKET_SIZE(client, data, len, sizeof(client_info_packet_t), "CLIENT_JOIN");
252
253 const client_info_packet_t *join_info = (const client_info_packet_t *)data;
254
255 // Validate display name is present and not just whitespace
256 if (join_info->display_name[0] == '\0') {
257 disconnect_client_for_bad_data(client, "CLIENT_JOIN display_name cannot be empty");
258 return;
259 }
260
261 uint32_t capabilities = NET_TO_HOST_U32(join_info->capabilities);
262
263 // Validate at least one capability flag is set
265 VALIDATE_CAPABILITY_FLAGS(client, capabilities, VALID_CAP_MASK, "CLIENT_JOIN");
266
267 // Validate no unknown capability bits are set
268 VALIDATE_FLAGS_MASK(client, capabilities, VALID_CAP_MASK, "CLIENT_JOIN");
269
271
272 client->can_send_video = (capabilities & CLIENT_CAP_VIDEO) != 0;
273 client->can_send_audio = (capabilities & CLIENT_CAP_AUDIO) != 0;
274 client->wants_stretch = (capabilities & CLIENT_CAP_STRETCH) != 0;
275
276 log_info("Client %s joined: %s (video=%d, audio=%d, stretch=%d)", client->client_id, client->display_name, client->can_send_video, client->can_send_audio, client->wants_stretch);
277
278 // Notify client of successful join (encrypted channel)
279 if (client->transport != NULL) {
280 log_info_client(client, "Joined as '%s' (video=%s, audio=%s)", client->display_name, client->can_send_video ? "yes" : "no", client->can_send_audio ? "yes" : "no");
281 }
282}
283
316void handle_protocol_version_packet(client_info_t *client, const void *data, size_t len) {
317 if (!data) {
318 disconnect_client_for_bad_data(client, "PROTOCOL_VERSION payload missing");
319 return;
320 }
321
322 if (len != sizeof(protocol_version_packet_t)) {
323 disconnect_client_for_bad_data(client, "PROTOCOL_VERSION invalid size: %zu (expected %zu)", len, sizeof(protocol_version_packet_t));
324 return;
325 }
326
327 const protocol_version_packet_t *version = (const protocol_version_packet_t *)data;
328 uint16_t client_major = NET_TO_HOST_U16(version->protocol_version);
329 uint16_t client_minor = NET_TO_HOST_U16(version->protocol_revision);
330 uint16_t client_patch = NET_TO_HOST_U16(version->protocol_patch);
331
332 // Validate major version match (minor version can differ for backward compat)
333 if (client_major != PROTOCOL_VERSION_MAJOR) {
334 log_warn("Client %s protocol version mismatch: client=%u.%u.%u, server=%u.%u.%u", client->client_id, client_major, client_minor, client_patch, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR,
336 // Note: We don't disconnect on version mismatch for backward compatibility
337 // Clients may be older or newer than server
338 } else if (client_minor != PROTOCOL_VERSION_MINOR) {
339 log_info("Client %s has different protocol revision: client=%u.%u.%u, server=%u.%u.%u", client->client_id, client_major, client_minor, client_patch, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR,
341 }
342
343 // Validate reserved bytes are zero
344 for (size_t i = 0; i < sizeof(version->reserved); i++) {
345 if (version->reserved[i] != 0) {
346 log_warn("Client %s sent non-zero reserved bytes in PROTOCOL_VERSION packet", client->client_id);
347 // Don't disconnect - reserved bytes may be used in future versions
348 break;
349 }
350 }
351
352 // Log supported features
354 log_debug("Client %s supports encryption", client->client_id);
355 }
356 if (version->compression_algorithms != 0) {
357 log_debug("Client %s supports compression: 0x%02x", client->client_id, version->compression_algorithms);
358 }
359 if (version->feature_flags != 0) {
360 uint16_t feature_flags = NET_TO_HOST_U16(version->feature_flags);
362 log_debug("Client %s supports features: 0x%04x", client->client_id, feature_flags);
363 }
364}
365
393void handle_client_leave_packet(client_info_t *client, const void *data, size_t len) {
394 if (!client) {
395 return;
396 }
397
398 const char *client_id = client->client_id;
399
400 if (len == 0) {
401 // Empty reason - client disconnecting without explanation
402 log_info("Client %s sent leave notification (no reason)", client_id);
403 } else if (len <= 256) {
404 // Reason provided - extract and log it
405 if (!data) {
406 SET_ERRNO(ERROR_INVALID_STATE, "Client %s sent leave notification with non-zero length but NULL data", client_id);
407 return;
408 }
409
410 char reason[SERVER_PROTOCOL_REASON_BUFFER_SIZE] = {0};
411 memcpy(reason, data, len);
412 reason[len] = '\0';
413
414 // Validate reason is printable (handle potential non-UTF8 gracefully)
415 bool all_printable = true;
416 for (size_t i = 0; i < len; i++) {
417 uint8_t c = (uint8_t)reason[i];
418 if (c < 32 && c != '\t' && c != '\n') {
419 all_printable = false;
420 break;
421 }
422 }
423
424 if (all_printable) {
425 log_info("Client %s sent leave notification: %s", client_id, reason);
426 } else {
427 log_info("Client %s sent leave notification (reason contains non-printable characters)", client_id);
428 }
429 } else {
430 // Oversized reason - shouldn't happen with validation.h checks
431 log_warn("Client %s sent oversized leave reason (%zu bytes, max 256)", client_id, len);
432 }
433
434 // Deactivate client to stop processing packets
435 // Sets client->active = false immediately - triggers client cleanup procedures
436 log_debug("Setting active=false (client_id=%s)", client_id);
437 atomic_store_bool(&client->active, false);
438
439 // Request transport shutdown immediately. This keeps the server's client
440 // accounting from depending on the peer closing its socket after sending
441 // CLIENT_LEAVE. Final resource removal remains serialized in the normal
442 // connection-closed callback.
443 if (client->network_connection) {
445 }
446}
447
484void handle_stream_start_packet(client_info_t *client, const void *data, size_t len) {
485 VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_START");
486
487 uint32_t stream_type;
488 memcpy(&stream_type, data, sizeof(uint32_t));
489 stream_type = NET_TO_HOST_U32(stream_type);
490
491 /* Older browser/WASM packet serializers emitted this control payload in
492 * host order while the enclosing ACIP header remained in network order.
493 * Accept that unambiguous two-bit form so a connected browser is not
494 * disconnected before it can send its first frame. */
495 const uint32_t VALID_STREAM_MASK = STREAM_TYPE_VIDEO | STREAM_TYPE_AUDIO;
496 if ((stream_type & VALID_STREAM_MASK) == 0) {
497 uint32_t host_order_stream_type = HOST_TO_NET_U32(stream_type);
498 if ((host_order_stream_type & ~VALID_STREAM_MASK) == 0 && host_order_stream_type != 0) {
499 log_debug("Normalizing legacy host-order STREAM_START flags 0x%x", stream_type);
500 stream_type = host_order_stream_type;
501 }
502 }
503
504 // Validate at least one stream type flag is set
505 VALIDATE_CAPABILITY_FLAGS(client, stream_type, VALID_STREAM_MASK, "STREAM_START");
506
507 // Validate no unknown stream type bits are set
508 VALIDATE_FLAGS_MASK(client, stream_type, VALID_STREAM_MASK, "STREAM_START");
509
510 if (stream_type & STREAM_TYPE_VIDEO) {
511 atomic_store_bool(&client->is_sending_video, true);
512 }
513 if (stream_type & STREAM_TYPE_AUDIO) {
514 atomic_store_bool(&client->is_sending_audio, true);
515
516 // Create Opus decoder for this client if not already created
517 if (!client->opus_decoder) {
519 if (client->opus_decoder) {
520 log_info("Client %s: Opus decoder created (48kHz)", client->client_id);
521 } else {
522 log_error("Client %s: Failed to create Opus decoder", client->client_id);
523 }
524 }
525 }
526
527 if (stream_type & STREAM_TYPE_VIDEO) {
528 log_info("Client %s announced video stream (waiting for first frame)", client->client_id);
529 }
530 if (stream_type & STREAM_TYPE_AUDIO) {
531 log_info("Client %s started audio stream", client->client_id);
532 }
533
534 // Notify client of stream start acknowledgment
535 const char *streams = (stream_type & STREAM_TYPE_VIDEO) && (stream_type & STREAM_TYPE_AUDIO) ? "video+audio" : ((stream_type & STREAM_TYPE_VIDEO) ? "video" : "audio");
536 if (client->transport != NULL) {
537 log_info_client(client, "Stream started: %s", streams);
538 }
539}
540
576void handle_stream_stop_packet(client_info_t *client, const void *data, size_t len) {
577 VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_STOP");
578
579 uint32_t stream_type;
580 memcpy(&stream_type, data, sizeof(uint32_t));
581 stream_type = NET_TO_HOST_U32(stream_type);
582
583 // Validate at least one stream type flag is set
584 const uint32_t VALID_STREAM_MASK = STREAM_TYPE_VIDEO | STREAM_TYPE_AUDIO;
585 VALIDATE_CAPABILITY_FLAGS(client, stream_type, VALID_STREAM_MASK, "STREAM_STOP");
586
587 // Validate no unknown stream type bits are set
588 VALIDATE_FLAGS_MASK(client, stream_type, VALID_STREAM_MASK, "STREAM_STOP");
589
590 if (stream_type & STREAM_TYPE_VIDEO) {
591 atomic_store_bool(&client->is_sending_video, false);
592 }
593 if (stream_type & STREAM_TYPE_AUDIO) {
594 atomic_store_bool(&client->is_sending_audio, false);
595 }
596
597 if (stream_type & STREAM_TYPE_VIDEO) {
598 log_info("Client %s stopped video stream", client->client_id);
599 }
600 if (stream_type & STREAM_TYPE_AUDIO) {
601 log_info("Client %s stopped audio stream", client->client_id);
602 }
603
604 // Notify client of stream stop acknowledgment
605 const char *streams = (stream_type & STREAM_TYPE_VIDEO) && (stream_type & STREAM_TYPE_AUDIO) ? "video+audio" : ((stream_type & STREAM_TYPE_VIDEO) ? "video" : "audio");
606 if (client->transport != NULL) {
607 log_info_client(client, "Stream stopped: %s", streams);
608 }
609}
610
614void handle_ping_packet(client_info_t *client, const void *data, size_t len) {
615 (void)data;
616 (void)len;
617
618 // Serialize the complete PONG write with the sender. TCP packets cannot be
619 // sent concurrently without risking byte-stream interleaving.
620 mutex_lock(&client->send_mutex);
621 if (atomic_load_bool(&client->shutting_down) || !client->transport) {
622 mutex_unlock(&client->send_mutex);
623 return;
624 }
625 acip_transport_t *pong_transport = client->transport;
626 asciichat_error_t pong_result = acip_send_pong(pong_transport);
627 mutex_unlock(&client->send_mutex);
628 if (pong_result != ASCIICHAT_OK) {
629 SET_ERRNO(ERROR_NETWORK, "Failed to send PONG response to client %s: %s", client->client_id, asciichat_error_string(pong_result));
630 }
631}
632
636void handle_pong_packet(client_info_t *client, const void *data, size_t len) {
637 (void)client;
638 (void)data;
639 (void)len;
640 // No action needed - client acknowledged our PING
641}
642
643/* ============================================================================
644 * Media Data Packet Handlers
645 * ============================================================================
646 */
647
702void handle_image_frame_packet(client_info_t *client, void *data, size_t len) {
703 // Handle incoming image data from client
704 // New format: [width:4][height:4][compressed_flag:4][data_size:4][rgb_data:data_size]
705 // Old format: [width:4][height:4][rgb_data:w*h*3] (for backward compatibility)
706 // Use atomic compare-and-swap to avoid race condition - ensures thread-safe auto-enabling of video stream
707
708 log_debug_every(US_PER_SEC_INT, "RECV_IMAGE_FRAME: client_id=%s, len=%zu", client->client_id, len);
709
710 // Validate codec capability for RGBA frames
712 log_error("Client %s sent RGBA frame but does not support VIDEO_CODEC_RGBA (capabilities=0x%x)", client->client_id, client->codec_capabilities_video);
713 disconnect_client_for_bad_data(client, "VIDEO_CODEC_RGBA not supported by client (capabilities=0x%x)", client->codec_capabilities_video);
714 return;
715 }
716
717 if (!data || len < sizeof(uint32_t) * 2) {
718 disconnect_client_for_bad_data(client, "IMAGE_FRAME payload too small: %zu bytes", len);
719 return;
720 }
721 bool was_sending_video = atomic_load_bool(&client->is_sending_video);
722 if (!was_sending_video) {
723 // Try to atomically enable video sending
724 // Use atomic_compare_exchange_strong to avoid spurious failures
725 if (atomic_cas_bool(&client->is_sending_video, &was_sending_video, true)) {
726 log_info("Client %s auto-enabled video stream (received IMAGE_FRAME)", client->client_id);
727 // Notify client that their first video frame was received
728 if (client->transport != NULL) {
729 log_info_client(client, "First video frame received - streaming active");
730 }
731 }
732 } else {
733 // Log periodically to confirm we're receiving frames
734 // Use per-client counter protected by client_state_mutex to avoid race conditions
735 mutex_lock(&client->client_state_mutex);
736 client->frames_received_logged++;
737 if (client->frames_received_logged % 25000 == 0) {
739 format_bytes_pretty(len, pretty, sizeof(pretty));
740 log_debug("Client %s has sent %u IMAGE_FRAME packets (%s)", client->client_id, client->frames_received_logged, pretty);
741 }
742 mutex_unlock(&client->client_state_mutex);
743 }
744
745 // Parse image dimensions (use memcpy to avoid unaligned access)
746 uint32_t img_width_net, img_height_net;
747 memcpy(&img_width_net, data, sizeof(uint32_t));
748 memcpy(&img_height_net, (char *)data + sizeof(uint32_t), sizeof(uint32_t));
749 uint32_t img_width = NET_TO_HOST_U32(img_width_net);
750 uint32_t img_height = NET_TO_HOST_U32(img_height_net);
751
752 log_debug_every(US_PER_SEC_INT, "IMAGE_FRAME packet: width=%u, height=%u, payload_len=%zu", img_width, img_height, len);
753
754 // Validate dimensions using image utility functions
755 if (image_validate_dimensions((size_t)img_width, (size_t)img_height) != ASCIICHAT_OK) {
756 log_error("IMAGE_FRAME validation failed for dimensions: %u x %u", img_width, img_height);
757 disconnect_client_for_bad_data(client, "IMAGE_FRAME invalid dimensions");
758 return;
759 }
760
761 // Calculate RGB buffer size with overflow checking
762 size_t rgb_size = 0;
763 if (image_calc_rgb_size((size_t)img_width, (size_t)img_height, &rgb_size) != ASCIICHAT_OK) {
764 disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size calculation failed");
765 return;
766 }
767
768 // Validate final buffer size against maximum
769 if (image_validate_buffer_size(rgb_size) != ASCIICHAT_OK) {
770 disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size exceeds maximum");
771 return;
772 }
773
774 // Only support legacy format: [width:4][height:4][rgb_data:w*h*3]
775 if (rgb_size > SIZE_MAX - FRAME_HEADER_SIZE_LEGACY) {
777 format_bytes_pretty(rgb_size, size_str, sizeof(size_str));
778 disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy packet size overflow: %s", size_str);
779 return;
780 }
781 size_t expected_size = FRAME_HEADER_SIZE_LEGACY + rgb_size;
782
783 if (len != expected_size) {
784 disconnect_client_for_bad_data(client, "IMAGE_FRAME size mismatch: expected %zu bytes got %zu", expected_size, len);
785 return;
786 }
787
788 // Validate legacy format
789 asciichat_error_t validate_result = frame_validate_legacy(len, rgb_size);
790 if (validate_result != ASCIICHAT_OK) {
791 disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy validation failed");
792 return;
793 }
794
795 void *rgb_data = (char *)data + FRAME_HEADER_SIZE_LEGACY;
796 size_t rgb_data_size = rgb_size;
797 bool needs_free = false;
798
799 if (client->incoming_video_buffer) {
800 // Get the write buffer
802
803 if (frame && frame->data) {
804 // Build the packet in the old format for internal storage: [width:4][height:4][rgb_data:w*h*3]
805 // Use frame_check_size_overflow to validate overflow before repacking
807 if (overflow_check != ASCIICHAT_OK) {
808 if (needs_free && rgb_data) {
809 SAFE_FREE(rgb_data);
810 }
811 disconnect_client_for_bad_data(client, "IMAGE_FRAME size overflow while repacking");
812 return;
813 }
814 size_t old_packet_size = FRAME_HEADER_SIZE_LEGACY + rgb_data_size;
815
816 if (old_packet_size <= MAX_FRAME_BUFFER_SIZE) { // Max frame buffer size
817 uint32_t width_net = HOST_TO_NET_U32(img_width);
818 uint32_t height_net = HOST_TO_NET_U32(img_height);
819
820 // Pack in old format for internal consistency
821 memcpy(frame->data, &width_net, sizeof(uint32_t));
822 memcpy((char *)frame->data + sizeof(uint32_t), &height_net, sizeof(uint32_t));
823 memcpy((char *)frame->data + sizeof(uint32_t) * 2, rgb_data, rgb_data_size);
824
825 frame->size = old_packet_size;
826 frame->width = img_width;
827 frame->height = img_height;
828 frame->capture_timestamp_ns = (uint64_t)time(NULL) * NS_PER_SEC_INT;
829 frame->sequence_number = ++client->frames_received;
830
831 // DEBUG: Compute hash of incoming RGB data to detect duplicates
832 uint32_t incoming_rgb_hash = 0;
833 for (size_t i = 0; i < rgb_data_size && i < 1000; i++) {
834 incoming_rgb_hash = (uint32_t)((uint64_t)incoming_rgb_hash * 31 + ((unsigned char *)rgb_data)[i]);
835 }
836
837 // Per-client hash tracking (not static!) to avoid cross-client interference
838 const char *client_id = client->client_id;
839 bool is_new_frame = (incoming_rgb_hash != client->last_received_frame_hash);
840
841 if (is_new_frame) {
842 log_debug_every(US_PER_SEC_INT, "RECV_FRAME #%llu NEW: Client %s size=%zu dims=%ux%u hash=0x%08x (prev=0x%08x)", (unsigned long long)client->frames_received, client_id, rgb_data_size,
843 img_width, img_height, incoming_rgb_hash, client->last_received_frame_hash);
844 client->last_received_frame_hash = incoming_rgb_hash;
845 } else {
846 log_debug_every(US_PER_SEC_INT, "RECV_FRAME #%llu DUP: Client %s size=%zu dims=%ux%u hash=0x%08x", (unsigned long long)client->frames_received, client_id, rgb_data_size, img_width,
847 img_height, incoming_rgb_hash);
848 }
849
851 } else {
852 if (needs_free && rgb_data) {
853 SAFE_FREE(rgb_data);
854 }
855 disconnect_client_for_bad_data(client, "IMAGE_FRAME repacked frame too large (%zu bytes)", old_packet_size);
856 return;
857 }
858 } else {
859 log_warn("Failed to get write buffer for client %s (frame=%p, frame->data=%p)", client->client_id, (void *)frame, frame ? frame->data : NULL);
860 }
861 } else {
862 // During shutdown, this is expected - don't spam error logs
864 SET_ERRNO(ERROR_INVALID_STATE, "Client %s has no incoming video buffer!", client->client_id);
865 } else {
866 log_debug("Client %s: ignoring video packet during shutdown", client->client_id);
867 }
868 }
869
870 // Clean up decompressed data if allocated
871 if (needs_free && rgb_data) {
872 SAFE_FREE(rgb_data);
873 }
874}
875
899void handle_image_frame_h265_packet(client_info_t *client, const void *data, size_t len) {
900 // Validate codec capability for H.265 frames
902 log_error("Client %s sent H.265 frame but does not support VIDEO_CODEC_H265 (capabilities=0x%x)", client->client_id, client->codec_capabilities_video);
903 disconnect_client_for_bad_data(client, "VIDEO_CODEC_H265 not supported by client (capabilities=0x%x)", client->codec_capabilities_video);
904 return;
905 }
906
907 if (!data || len < 5) {
908 disconnect_client_for_bad_data(client, "H265_FRAME payload too small: %zu bytes (min 5)", len);
909 return;
910 }
911
912 // Auto-enable video stream if not already enabled
913 // Use atomic_exchange to atomically set flag and check old value
914 bool was_sending_video = atomic_exchange_bool(&client->is_sending_video, true);
915 if (!was_sending_video) {
916 log_info("Client %s auto-enabled H.265 video stream (received IMAGE_FRAME_H265)", client->client_id);
917 if (client->transport != NULL) {
918 log_info_client(client, "First H.265 video frame received - streaming active");
919 }
920 }
921
922 uint8_t flags = *(const uint8_t *)data;
923 bool is_keyframe = (flags & 0x01) != 0;
924 bool size_changed = (flags & 0x02) != 0;
925
926 log_debug_every(US_PER_SEC_INT, "H265_FRAME: flags=0x%02x, keyframe=%s, size_change=%s, len=%zu", flags, is_keyframe ? "yes" : "no", size_changed ? "yes" : "no", len);
927
928 if (!client->incoming_video_buffer) {
929 log_error("Client %s has no incoming video buffer for H.265 frames", client->client_id);
930 return;
931 }
932
933 // Get H.265 server context (may be NULL during shutdown)
935 if (!h265_ctx) {
937 log_error("H.265 codec server context not initialized");
938 }
939 return;
940 }
941
942 // Get or create decoder for this client
943 uint32_t client_id_num = 0;
944 char *end = NULL;
945 unsigned long parsed = strtoul(client->client_id, &end, 10);
946 if (end != client->client_id && *end == '\0') {
947 client_id_num = (uint32_t)parsed;
948 } else {
949 // Fallback to string hash if can't parse as number
950 client_id_num = 0;
951 for (int i = 0; client->client_id[i]; i++) {
952 client_id_num = (uint32_t)((uint64_t)client_id_num * 31 + (unsigned char)client->client_id[i]);
953 }
954 }
955
956 h265_server_client_t *client_decoder = h265_server_get_client_decoder(h265_ctx, client_id_num);
957 if (!client_decoder) {
958 log_error("Failed to get H.265 decoder for client %s", client->client_id);
959 disconnect_client_for_bad_data(client, "Failed to initialize H.265 decoder");
960 return;
961 }
962
963 // Allocate temporary RGBA buffer for decoding
964 // H.265 frames from client are sent as [flags:u8][width:u16][height:u16][h265_data...]
965 // Existing scratch budget for a 512-by-512 RGBA image.
967 if (!rgba_buf) {
968 log_error("Failed to allocate RGBA buffer for H.265 decoding");
969 disconnect_client_for_bad_data(client, "Out of memory for H.265 frame decoding");
970 return;
971 }
972
973 uint16_t frame_width = 0;
974 uint16_t frame_height = 0;
975 size_t rgba_size = SERVER_H265_RGBA_BUFFER_SIZE;
976
977 // Decode H.265 packet to RGBA
978 asciichat_error_t decode_result = h265_server_decode_and_convert(client_decoder, (const uint8_t *)data, len, rgba_buf, &frame_width, &frame_height, &rgba_size);
979
980 if (decode_result != ASCIICHAT_OK) {
981 log_error("H.265 decoding failed for client %s: %s", client->client_id, asciichat_error_format(NULL, decode_result));
982 SAFE_FREE(rgba_buf);
983 disconnect_client_for_bad_data(client, "H.265 frame decode error");
984 return;
985 }
986
987 // Write decoded frame to video buffer
989 if (frame && frame->data) {
990 memcpy(frame->data, rgba_buf, rgba_size);
991 frame->size = rgba_size;
992 frame->width = frame_width;
993 frame->height = frame_height;
994 frame->is_keyframe = is_keyframe;
995
996 // Update frame metadata
997 frame->receive_timestamp_ns = time_get_realtime_ns();
998 frame->sequence_number = client->frames_received++;
999
1000 log_debug_every(US_PER_SEC_INT, "RECV_H265 #%llu: client_id=%s size=%zu dims=%ux%u keyframe=%s", (unsigned long long)frame->sequence_number, client->client_id, rgba_size, frame_width,
1001 frame_height, is_keyframe ? "yes" : "no");
1002
1004 } else {
1005 log_warn("Failed to get write buffer for client %s (frame=%p, frame->data=%p)", client->client_id, (void *)frame, frame ? frame->data : NULL);
1006 }
1007
1008 SAFE_FREE(rgba_buf);
1009}
1010
1052void handle_audio_packet(client_info_t *client, const void *data, size_t len) {
1053 VALIDATE_NOTNULL_DATA(client, data, "AUDIO");
1054 VALIDATE_AUDIO_ALIGNMENT(client, len, sizeof(float), "AUDIO");
1055 VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO");
1056
1057 int num_samples = (int)(len / sizeof(float));
1058 VALIDATE_AUDIO_SAMPLE_COUNT(client, num_samples, AUDIO_SAMPLES_PER_PACKET, "AUDIO");
1059 VALIDATE_RESOURCE_INITIALIZED(client, client->incoming_audio_buffer, "audio buffer");
1060
1061 const float *samples = (const float *)data;
1063 float *stereo = SAFE_MALLOC((size_t)num_samples * AUDIO_CHANNELS * sizeof(float), float *);
1064 if (audio_convert_channels(samples, (size_t)num_samples, 1, stereo, AUDIO_CHANNELS) == ASCIICHAT_OK)
1065 result = audio_ring_buffer_write(client->incoming_audio_buffer, stereo, num_samples * AUDIO_CHANNELS);
1066 SAFE_FREE(stereo);
1067 if (result != ASCIICHAT_OK) {
1068 log_error("Failed to write audio samples to buffer: %s", asciichat_error_format(NULL, result));
1069 }
1070}
1071
1072void handle_remote_log_packet_from_client(client_info_t *client, const void *data, size_t len) {
1073 if (!client) {
1074 return;
1075 }
1076
1077 log_level_t remote_level = LOG_INFO;
1079 uint16_t flags = 0;
1080 char message[MAX_REMOTE_LOG_MESSAGE_LENGTH + 1] = {0};
1081
1082 asciichat_error_t parse_result = packet_parse_remote_log(data, len, &remote_level, &direction, &flags, message, sizeof(message), NULL);
1083 if (parse_result != ASCIICHAT_OK) {
1084 disconnect_client_for_bad_data(client, "Invalid REMOTE_LOG packet: %s", asciichat_error_string(parse_result));
1085 return;
1086 }
1087
1088 if (direction != REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER) {
1089 disconnect_client_for_bad_data(client, "REMOTE_LOG direction mismatch: %u", direction);
1090 return;
1091 }
1092
1093 const bool truncated = (flags & REMOTE_LOG_FLAG_TRUNCATED) != 0;
1094 const char *display_name = client->display_name[0] ? client->display_name : "(unnamed)";
1095 const char *client_id = client->client_id;
1096
1097 if (truncated) {
1098 log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %s \"%s\"] %s [message truncated]", client_id, display_name, message);
1099 } else {
1100 log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %s \"%s\"] %s", client_id, display_name, message);
1101 }
1102}
1103
1150void handle_audio_batch_packet(client_info_t *client, const void *data, size_t len) {
1151 // Log every audio batch packet reception
1152 log_debug_every(LOG_RATE_DEFAULT, "Received audio batch packet from client %s (len=%zu, is_sending_audio=%d)", client->client_id, len, atomic_load_bool(&client->is_sending_audio));
1153
1154 VALIDATE_NOTNULL_DATA(client, data, "AUDIO_BATCH");
1155 VALIDATE_MIN_SIZE(client, len, sizeof(audio_batch_packet_t), "AUDIO_BATCH");
1156 VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO_BATCH");
1157
1158 // Parse batch header using utility function
1159 audio_batch_info_t batch_info;
1160 asciichat_error_t parse_result = audio_parse_batch_header(data, len, &batch_info);
1161 if (parse_result != ASCIICHAT_OK) {
1162 disconnect_client_for_bad_data(client, "Failed to parse audio batch header");
1163 return;
1164 }
1165
1166 uint32_t packet_batch_count = batch_info.batch_count;
1167 uint32_t total_samples = batch_info.total_samples;
1168 uint32_t sample_rate = batch_info.sample_rate;
1169 if (sample_rate != AUDIO_SAMPLE_RATE || (batch_info.channels != 1 && batch_info.channels != 2) || total_samples % batch_info.channels) {
1170 disconnect_client_for_bad_data(client, "Unsupported PCM audio format");
1171 return;
1172 }
1173
1174 (void)packet_batch_count;
1175 (void)sample_rate;
1176
1177 VALIDATE_NONZERO(client, packet_batch_count, "batch_count", "AUDIO_BATCH");
1178 VALIDATE_NONZERO(client, total_samples, "total_samples", "AUDIO_BATCH");
1179
1180 size_t samples_bytes = 0;
1181 if (safe_size_mul(total_samples, sizeof(uint32_t), &samples_bytes)) {
1182 disconnect_client_for_bad_data(client, "AUDIO_BATCH sample size overflow (samples=%u)", total_samples);
1183 return;
1184 }
1185
1186 size_t expected_size = sizeof(audio_batch_packet_t) + samples_bytes;
1187 if (len != expected_size) {
1188 disconnect_client_for_bad_data(client, "AUDIO_BATCH length mismatch: got %zu expected %zu", len, expected_size);
1189 return;
1190 }
1191
1192 // Bounds check to prevent integer overflow on allocation
1193 // Maximum allowed samples: AUDIO_BATCH_SAMPLES * 2 (2048 samples)
1194 // This prevents total_samples * sizeof(float) from exceeding 8KB
1195 const uint32_t MAX_AUDIO_SAMPLES = AUDIO_BATCH_SAMPLES * 2;
1196 if (total_samples > MAX_AUDIO_SAMPLES) {
1197 disconnect_client_for_bad_data(client, "AUDIO_BATCH too many samples: %u (max: %u)", total_samples, MAX_AUDIO_SAMPLES);
1198 return;
1199 }
1200
1201 const uint8_t *samples_ptr = (const uint8_t *)data + sizeof(audio_batch_packet_t);
1202
1203 // Safe allocation: total_samples is bounded above, so multiplication won't overflow
1204 size_t alloc_size = (size_t)total_samples * AUDIO_CHANNELS * sizeof(float);
1205 float *samples = SAFE_MALLOC(alloc_size, float *);
1206 if (!samples) {
1207 SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for audio sample conversion");
1208 return;
1209 }
1210
1211 // Use helper function to dequantize samples
1212 asciichat_error_t dq_result = audio_dequantize_samples(samples_ptr, total_samples, samples);
1213 if (dq_result != ASCIICHAT_OK) {
1214 SAFE_FREE(samples);
1215 return;
1216 }
1217
1218#ifndef NDEBUG
1219 static int recv_count = 0;
1220 recv_count++;
1221 if (recv_count % 100 == 0) {
1222 uint32_t raw0 = bytes_read_u32_unaligned(samples_ptr + 0 * sizeof(uint32_t));
1223 uint32_t raw1 = bytes_read_u32_unaligned(samples_ptr + 1 * sizeof(uint32_t));
1224 uint32_t raw2 = bytes_read_u32_unaligned(samples_ptr + 2 * sizeof(uint32_t));
1225 int32_t scaled0 = (int32_t)NET_TO_HOST_U32(raw0);
1226 int32_t scaled1 = (int32_t)NET_TO_HOST_U32(raw1);
1227 int32_t scaled2 = (int32_t)NET_TO_HOST_U32(raw2);
1228 log_debug_every(US_PER_SEC_INT, "RECV: network[0]=0x%08x, network[1]=0x%08x, network[2]=0x%08x", raw0, raw1, raw2);
1229 log_debug_every(US_PER_SEC_INT, "RECV: scaled[0]=%d, scaled[1]=%d, scaled[2]=%d", scaled0, scaled1, scaled2);
1230 log_debug_every(US_PER_SEC_INT, "RECV: samples[0]=%.6f, samples[1]=%.6f, samples[2]=%.6f", samples[0], samples[1], samples[2]);
1231 }
1232#endif
1233
1234 if (client->incoming_audio_buffer) {
1235 uint32_t frames = total_samples / batch_info.channels;
1236 (void)audio_convert_channels(samples, frames, batch_info.channels, samples, AUDIO_CHANNELS);
1237 asciichat_error_t write_result = audio_ring_buffer_write(client->incoming_audio_buffer, samples, frames * AUDIO_CHANNELS);
1238 if (write_result != ASCIICHAT_OK) {
1239 log_error("Failed to write decoded audio batch to buffer: %s", asciichat_error_format(NULL, write_result));
1240 }
1241 }
1242
1243 SAFE_FREE(samples);
1244}
1245
1281void handle_audio_opus_batch_packet(client_info_t *client, const void *data, size_t len) {
1282 log_debug_every(LOG_RATE_SLOW, "Received Opus audio batch from client %s (len=%zu)", client->client_id, len);
1283
1284 VALIDATE_NOTNULL_DATA(client, data, "AUDIO_OPUS_BATCH");
1285 VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO_OPUS_BATCH");
1286 VALIDATE_RESOURCE_INITIALIZED(client, client->opus_decoder, "Opus decoder");
1287
1288 // Parse Opus batch packet
1289 const uint8_t *opus_data = NULL;
1290 size_t opus_size = 0;
1291 const uint16_t *frame_sizes = NULL;
1292 int sample_rate = 0;
1293 int frame_duration = 0;
1294 int frame_count = 0;
1295
1296 asciichat_error_t result = packet_parse_opus_batch(data, len, &opus_data, &opus_size, &frame_sizes, &sample_rate, &frame_duration, &frame_count);
1297
1298 if (result != ASCIICHAT_OK) {
1299 disconnect_client_for_bad_data(client, "Failed to parse AUDIO_OPUS_BATCH packet");
1300 return;
1301 }
1302
1303 VALIDATE_NONZERO(client, frame_count, "frame_count", "AUDIO_OPUS_BATCH");
1304 VALIDATE_NONZERO(client, opus_size, "opus_size", "AUDIO_OPUS_BATCH");
1305
1306 // Calculate samples per frame (20ms @ 48kHz = OPUS_FRAME_SAMPLES samples)
1307 int samples_per_frame = (sample_rate * frame_duration) / 1000 * AUDIO_CHANNELS;
1308 VALIDATE_RANGE(client, samples_per_frame, 1, AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS, "samples_per_frame", "AUDIO_OPUS_BATCH");
1309
1310 // Use static buffer for common case to avoid malloc in hot path
1311 // Typical batches: 1-32 frames of OPUS_FRAME_SAMPLES samples = up to 30,720 samples
1312 // Static buffer holds 32 frames @ 48kHz 20ms = 30,720 samples (120KB)
1313#define OPUS_DECODE_STATIC_MAX_SAMPLES (32 * OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)
1314 // Each client receive thread decodes independently. Sharing this scratch
1315 // buffer lets concurrent clients overwrite one another's PCM before it is
1316 // written to their source rings.
1317 static _Thread_local float static_decode_buffer[OPUS_DECODE_STATIC_MAX_SAMPLES];
1318
1319 size_t total_samples = (size_t)samples_per_frame * (size_t)frame_count;
1320 float *decoded_samples;
1321 bool used_malloc = false;
1322
1323 if (total_samples <= OPUS_DECODE_STATIC_MAX_SAMPLES) {
1324 decoded_samples = static_decode_buffer;
1325 } else {
1326 // Unusual large batch - fall back to malloc
1327 log_warn("Client %s: Large audio batch requires malloc (%zu samples)", client->client_id, total_samples);
1328 decoded_samples = SAFE_MALLOC(total_samples * sizeof(float), float *);
1329 if (!decoded_samples) {
1330 SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for Opus decoded samples");
1331 return;
1332 }
1333 used_malloc = true;
1334 }
1335
1336 // Decode each Opus frame using frame_sizes array
1337 int total_decoded = 0;
1338 size_t opus_offset = 0;
1339
1340 for (int i = 0; i < frame_count; i++) {
1341 // Get exact frame size from frame_sizes array (convert from network byte order)
1342 size_t frame_size = (size_t)NET_TO_HOST_U16(frame_sizes[i]);
1343
1344 // DEBUG: Log the actual bytes of each Opus frame
1345 if (frame_size > 0) {
1346 log_debug_every(LOG_RATE_DEFAULT, "Client %s: Opus frame %d: size=%zu, first_bytes=[0x%02x,0x%02x,0x%02x,0x%02x]", client->client_id, i, frame_size, opus_data[opus_offset] & 0xFF,
1347 frame_size > 1 ? (opus_data[opus_offset + 1] & 0xFF) : 0, frame_size > 2 ? (opus_data[opus_offset + 2] & 0xFF) : 0, frame_size > 3 ? (opus_data[opus_offset + 3] & 0xFF) : 0);
1348 }
1349
1350 if (opus_offset + frame_size > opus_size) {
1351 log_error("Client %s: Frame %d size overflow (offset=%zu, frame_size=%zu, total=%zu)", client->client_id, i + 1, opus_offset, frame_size, opus_size);
1352 if (used_malloc) {
1353 SAFE_FREE(decoded_samples);
1354 }
1355 return;
1356 }
1357
1358 // SECURITY: Bounds check before writing decoded samples to prevent buffer overflow
1359 // An attacker could send malicious Opus frames that decode to more samples than expected
1360 if ((size_t)total_decoded + (size_t)samples_per_frame > total_samples) {
1361 log_error("Client %s: Opus decode would overflow buffer (decoded=%d, frame_samples=%d, max=%zu)", client->client_id, total_decoded, samples_per_frame, total_samples);
1362 if (used_malloc) {
1363 SAFE_FREE(decoded_samples);
1364 }
1365 return;
1366 }
1367
1368 int decoded_count = opus_codec_decode((opus_codec_t *)client->opus_decoder, &opus_data[opus_offset], frame_size, &decoded_samples[total_decoded], samples_per_frame);
1369
1370 if (decoded_count < 0) {
1371 log_error("Client %s: Opus decoding failed for frame %d/%d (size=%zu)", client->client_id, i + 1, frame_count, frame_size);
1372 if (used_malloc) {
1373 SAFE_FREE(decoded_samples);
1374 }
1375 return;
1376 }
1377
1378 total_decoded += decoded_count;
1379 opus_offset += frame_size;
1380 }
1381
1382 log_debug_every(LOG_RATE_DEFAULT, "Client %s: Decoded %d Opus frames -> %d samples", client->client_id, frame_count, total_decoded);
1383
1384 // DEBUG: Log sample values to detect all-zero issue
1385 static _Thread_local int server_decode_count = 0;
1386 server_decode_count++;
1387 if (total_decoded > 0 && (server_decode_count <= 10 || server_decode_count % 100 == 0)) {
1388 float peak = 0.0f, rms = 0.0f;
1389 for (int i = 0; i < total_decoded && i < 100; i++) {
1390 float abs_val = fabsf(decoded_samples[i]);
1391 if (abs_val > peak)
1392 peak = abs_val;
1393 rms += decoded_samples[i] * decoded_samples[i];
1394 }
1395 rms = sqrtf(rms / (total_decoded > 100 ? 100 : total_decoded));
1396 // Log first 4 bytes of Opus data to compare with client encode
1397 log_debug_every(US_PER_SEC_INT, "SERVER OPUS DECODE #%d from client %s: decoded_rms=%.6f, opus_first4=[0x%02x,0x%02x,0x%02x,0x%02x]", server_decode_count, client->client_id, rms,
1398 opus_size > 0 ? opus_data[0] : 0, opus_size > 1 ? opus_data[1] : 0, opus_size > 2 ? opus_data[2] : 0, opus_size > 3 ? opus_data[3] : 0);
1399 }
1400
1401 // Write decoded samples to client's incoming audio buffer
1402 // Note: audio_ring_buffer_write returns error code, not sample count
1403 // Buffer overflow warnings are logged inside audio_ring_buffer_write if buffer is full
1404 if (client->incoming_audio_buffer && total_decoded > 0) {
1405 asciichat_error_t result = audio_ring_buffer_write(client->incoming_audio_buffer, decoded_samples, total_decoded);
1406 if (result != ASCIICHAT_OK) {
1407 log_error("Client %s: Failed to write decoded audio to buffer: %s", client->client_id, asciichat_error_format(NULL, result));
1408 }
1409 }
1410
1411 if (used_malloc) {
1412 SAFE_FREE(decoded_samples);
1413 }
1414}
1415
1434void handle_audio_opus_packet(client_info_t *client, const void *data, size_t len) {
1435 log_debug_every(LOG_RATE_DEFAULT, "Received Opus audio from client %s (len=%zu)", client->client_id, len);
1436
1437 if (VALIDATE_PACKET_NOT_NULL(client, data, "AUDIO_OPUS")) {
1438 return;
1439 }
1440
1441 // Minimum size: 16-byte header + at least 1 byte of Opus data
1442 if (len < 17) {
1443 disconnect_client_for_bad_data(client, "AUDIO_OPUS packet too small: %zu bytes", len);
1444 return;
1445 }
1446
1447 if (!atomic_load_bool(&client->is_sending_audio)) {
1448 disconnect_client_for_bad_data(client, "AUDIO_OPUS received before audio stream enabled");
1449 return;
1450 }
1451
1452 if (!client->opus_decoder) {
1453 disconnect_client_for_bad_data(client, "Opus decoder not initialized");
1454 return;
1455 }
1456
1457 // Parse header (16 bytes) - convert from network byte order
1458 const uint8_t *buf = (const uint8_t *)data;
1459 uint32_t sample_rate_net, frame_duration_net;
1460 memcpy(&sample_rate_net, buf, 4);
1461 memcpy(&frame_duration_net, buf + 4, 4);
1462 uint32_t sample_rate = NET_TO_HOST_U32(sample_rate_net);
1463 uint32_t frame_duration = NET_TO_HOST_U32(frame_duration_net);
1464
1465 // Extract Opus data (after 16-byte header)
1466 const uint8_t *opus_data = buf + 16;
1467 size_t opus_size = len - 16;
1468
1469 // Validate parameters
1470 if (sample_rate == 0 || sample_rate > 192000) {
1471 disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid sample_rate: %u", sample_rate);
1472 return;
1473 }
1474
1475 if (frame_duration == 0 || frame_duration > 120) {
1476 disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid frame_duration: %u ms", frame_duration);
1477 return;
1478 }
1479
1480 // Calculate expected samples per frame
1481 int samples_per_frame = (int)((sample_rate * frame_duration) / 1000) * AUDIO_CHANNELS;
1482 if (samples_per_frame <= 0 || samples_per_frame > AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS) { // Max 120ms @ 48kHz
1483 disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid samples_per_frame: %d", samples_per_frame);
1484 return;
1485 }
1486
1487 // Decode Opus frame
1488 float decoded_samples[AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS]; // Max Opus frame size (120ms @ 48kHz)
1489 int decoded_count = opus_codec_decode((opus_codec_t *)client->opus_decoder, opus_data, opus_size, decoded_samples, samples_per_frame);
1490
1491 if (decoded_count < 0) {
1492 log_error("Client %s: Opus decoding failed (size=%zu)", client->client_id, opus_size);
1493 return;
1494 }
1495
1496 log_debug_every(LOG_RATE_VERY_FAST, "Client %s: Decoded Opus frame -> %d samples", client->client_id, decoded_count);
1497
1498 // Write decoded samples to client's incoming audio buffer
1499 if (client->incoming_audio_buffer && decoded_count > 0) {
1500 asciichat_error_t write_result = audio_ring_buffer_write(client->incoming_audio_buffer, decoded_samples, decoded_count);
1501 if (write_result != ASCIICHAT_OK) {
1502 log_error("Failed to write decoded Opus samples to buffer: %s", asciichat_error_format(NULL, write_result));
1503 }
1504 }
1505}
1506
1507/* ============================================================================
1508 * Client Configuration Packet Handlers
1509 * ============================================================================
1510 */
1511
1513static void publish_render_settings(client_info_t *client) {
1514 const acip_render_settings_t *state = &client->render_settings;
1515 client->width = state->width;
1516 client->height = state->height;
1517 client->terminal_caps = state->caps;
1518 memcpy(client->client_palette_chars, state->palette, sizeof(state->palette));
1519 memcpy(client->client_luminance_palette, state->luminance, sizeof(state->luminance));
1520 client->client_palette_len = state->palette_length;
1521 client->client_palette_type = state->caps.palette_type;
1522 client->client_palette_initialized = true;
1523 client->has_terminal_caps = true;
1524 log_info("Client %s render settings: width=%u height=%u color=%u filter=%u palette=%u mode=%u fps=%u matrix=%u "
1525 "revision=%u",
1526 client->client_id, state->width, state->height, state->caps.color_level, state->caps.color_filter, state->caps.palette_type, state->caps.render_mode, state->caps.desired_fps,
1527 (state->caps.capabilities & TERM_CAP_MATRIX_RAIN) != 0, state->revision);
1528}
1529
1535void handle_client_capabilities_packet(client_info_t *client, const void *data, size_t len) {
1536 if (!data || len != sizeof(terminal_capabilities_packet_t)) {
1537 disconnect_client_for_bad_data(client, "Invalid capabilities size");
1538 return;
1539 }
1541 memcpy(&packet, data, sizeof(packet));
1542 mutex_lock(&client->client_state_mutex);
1545 // Encoder changes advertise codec support without overwriting live preferences.
1546 if (client->has_terminal_caps) {
1547 mutex_unlock(&client->client_state_mutex);
1548 return;
1549 }
1552 if (result == ASCIICHAT_OK) {
1553 publish_render_settings(client);
1554 log_info("Client %s rendering configured: %ux%u, color=%u, palette=%u, mode=%u, fps=%u", client->client_id, client->width, client->height, client->terminal_caps.color_level,
1555 client->terminal_caps.palette_type, client->terminal_caps.render_mode, client->terminal_caps.desired_fps);
1556 }
1557 mutex_unlock(&client->client_state_mutex);
1558 if (result != ASCIICHAT_OK)
1559 disconnect_client_for_bad_data(client, "Invalid render capabilities");
1560 else {
1562 size_t query_length;
1563 acip_settings_header_t header = {.schema = 1, .expected_revision = UINT32_MAX};
1564 if (acip_settings_encode(&header, "", query, sizeof(query), &query_length) == ASCIICHAT_OK)
1565 (void)handle_runtime_settings(client, query, query_length);
1566 }
1567}
1568
1569asciichat_error_t handle_runtime_settings(client_info_t *client, const void *data, size_t length) {
1571 size_t reply_length = 0;
1572 mutex_lock(&client->client_state_mutex);
1573 if (!client->has_terminal_caps || atomic_load_bool(&client->shutting_down)) {
1574 mutex_unlock(&client->client_state_mutex);
1575 return SET_ERRNO(ERROR_INVALID_STATE, "Settings require an active bootstrapped viewer");
1576 }
1577 asciichat_error_t result = acip_settings_request(&client->render_settings, data, length, reply, sizeof(reply), &reply_length);
1578 if (result == ASCIICHAT_OK)
1579 publish_render_settings(client);
1580 mutex_unlock(&client->client_state_mutex);
1581 if (result == ASCIICHAT_OK) {
1582 // Teardown takes this mutex before releasing the transport.
1583 mutex_lock(&client->send_mutex);
1584 if (atomic_load_bool(&client->shutting_down) || !client->transport)
1585 result = SET_ERRNO(ERROR_INVALID_STATE, "Viewer is shutting down");
1586 else
1587 result = packet_send_via_transport(client->transport, PACKET_TYPE_ACIP_SETTINGS_ACK, reply, reply_length, 0);
1588 mutex_unlock(&client->send_mutex);
1589 }
1590 return result;
1591}
1592
1627void handle_size_packet(client_info_t *client, const void *data, size_t len) {
1628 VALIDATE_PACKET_SIZE(client, data, len, sizeof(size_packet_t), "SIZE");
1629
1630 const size_packet_t *size_pkt = (const size_packet_t *)data;
1631
1632 // Extract and validate new dimensions
1633 uint16_t width = NET_TO_HOST_U16(size_pkt->width);
1635
1636 VALIDATE_NONZERO(client, width, "width", "SIZE");
1637 VALIDATE_NONZERO(client, height, "height", "SIZE");
1638 VALIDATE_RANGE(client, width, 1, 4096, "width", "SIZE");
1639 VALIDATE_RANGE(client, height, 1, 4096, "height", "SIZE");
1640
1641 mutex_lock(&client->client_state_mutex);
1642 client->width = width;
1643 client->height = height;
1644 mutex_unlock(&client->client_state_mutex);
1645
1646 log_info("Client %s updated terminal size: %ux%u", client->client_id, width, height);
1647}
1648
1649/* ============================================================================
1650 * Protocol Control Packet Handlers
1651 * ============================================================================
1652 */
1653
1654/* ============================================================================
1655 * Protocol Utility Functions
1656 * ============================================================================
1657 */
1658
1700
1702 if (!client) {
1703 return -1;
1704 }
1705
1706 // Count active clients - LOCK OPTIMIZATION: Use atomic reads, no rwlock needed
1707 int active_count = 0;
1708 for (int i = 0; i < MAX_CLIENTS; i++) {
1709 if (atomic_load_bool(&g_client_manager.clients[i].active)) {
1710 active_count++;
1711 }
1712 }
1713
1714 // Prepare server state packet
1716 state.connected_client_count = active_count;
1717 state.active_client_count = active_count; // For now, all connected are active
1718 memset(state.reserved, 0, sizeof(state.reserved));
1719
1720 // Convert to network byte order
1721 server_state_packet_t net_state;
1724 memset(net_state.reserved, 0, sizeof(net_state.reserved));
1725
1726 // Send server state via ACIP transport
1727 // Protect socket writes with send_mutex to prevent race with send_thread.
1728 mutex_lock(&client->send_mutex);
1729 asciichat_error_t result = acip_send_server_state(client->transport, &net_state);
1730 mutex_unlock(&client->send_mutex);
1731
1732 if (result != ASCIICHAT_OK) {
1733 SET_ERRNO(ERROR_NETWORK, "Failed to send server state to client %s: %s", client->client_id, asciichat_error_string(result));
1734 return -1;
1735 }
1736
1737 log_debug("Sent server state to client %s: %u connected, %u active", client->client_id, state.connected_client_count, state.active_client_count);
1738 return 0;
1739}
1740
1766// NOTE: This function is no longer used - CLEAR_CONSOLE is now sent directly
1767// from each client's render thread when it detects a grid layout change.
1768// Keeping this for reference but it should not be called.
1770 SET_ERRNO(ERROR_INVALID_STATE, "Unexpected console clear broadcast");
1771 log_warn("CLEAR_CONSOLE is now sent from render threads, not broadcast");
1772}
Application-level callbacks for library code.
const char * asciichat_error_format(const char *message, asciichat_error_t code)
#define SET_ERRNO(code,...)
void atomic_store_bool(atomic_t *a, bool value)
Atomically store a boolean value.
bool atomic_load_bool(atomic_t *a)
Atomic pointer wrapper.
bool atomic_exchange_bool(atomic_t *a, bool new_value)
Atomically exchange a boolean and return the old value.
bool atomic_cas_bool(atomic_t *a, bool *expected, bool new_value)
Atomically compare-and-swap a boolean.
asciichat_error_t audio_convert_channels(const float *input, size_t frames, unsigned input_channels, float *output, unsigned output_channels)
#define AUDIO_OPUS_MAX_DECODE_SAMPLES
#define AUDIO_SAMPLE_RATE
Definition audio/limits.h:8
#define AUDIO_CHANNELS
Definition audio/limits.h:9
Common buffer size definitions.
🔢 Byte-Level Access and Arithmetic Utilities
Video and audio codec definitions and capability bitmasks.
@ VIDEO_CODEC_RGBA
Raw RGBA (4 bytes per pixel, uncompressed).
Definition codecs.h:29
@ VIDEO_CODEC_H265
H.265 (HEVC) video codec.
Definition codecs.h:30
📦 Network Packet Compression Utilities
🔄 Network byte order conversion helpers
#define HOST_TO_NET_U32(val)
Definition endian.h:70
#define NET_TO_HOST_U16(val)
Definition endian.h:115
#define NET_TO_HOST_U32(val)
Definition endian.h:85
unsigned int height
Definition fft.c:24
unsigned int width
Definition fft.c:24
atomic_t g_should_exit
Global application exit flag (shared across all modes).
Definition globals.c:31
asciichat_error_t audio_ring_buffer_write(audio_ring_buffer_t *rb, const float *data, int samples)
Write audio samples to ring buffer.
int opus_codec_decode(opus_codec_t *codec, const uint8_t *data, size_t data_len, float *out_samples, int out_num_samples)
Decode Opus audio frame.
Definition opus.c:171
asciichat_error_t audio_parse_batch_header(const void *data, size_t len, audio_batch_info_t *out_batch)
Parse an audio batch packet header from raw packet data.
asciichat_error_t audio_dequantize_samples(const uint8_t *samples_ptr, uint32_t total_samples, float *out_samples)
Dequantize network audio samples from int32 to float.
opus_codec_t * opus_codec_create_decoder_channels(int sample_rate, int channels)
Definition opus.c:91
#define MAX_FRAME_BUFFER_SIZE
Maximum frame buffer size including headers and compression.
#define BUFFER_SIZE_SMALL
Small buffer size (256 bytes).
unsigned short uint16_t
unsigned int uint32_t
#define SAFE_STRNCPY(dst, src, size)
#define SAFE_FREE(ptr)
#define SAFE_MALLOC(size, cast)
#define safe_size_mul
unsigned long long uint64_t
unsigned char uint8_t
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_INVALID_STATE
@ ERROR_NETWORK
Definition error_codes.h:76
@ ERROR_NETWORK_PROTOCOL
Definition error_codes.h:80
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
#define DEFAULT_MAX_FPS
Default maximum frame rate (frames per second).
#define MAX_CLIENTS
Maximum possible clients (static array size) - actual runtime limit set by –max-clients (1-128).
#define MAX_DISPLAY_NAME_LEN
Maximum display name length in characters.
#define LOG_RATE_VERY_FAST
Log rate limit: 0.1 seconds (100,000 microseconds) - for very high frequency operations.
Definition log_rates.h:27
#define LOG_RATE_SLOW
Log rate limit: 10 seconds (10,000,000 microseconds).
Definition log_rates.h:39
#define LOG_RATE_DEFAULT
Log rate limit: 5 seconds (5,000,000 microseconds) - default for audio/video packets.
Definition log_rates.h:36
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615
void log_msg(log_level_t level, const char *file, int line, const char *func, const char *fmt,...)
Log a message at a specific level.
enum remote_log_direction remote_log_direction_t
Remote log packet direction enumeration.
#define log_info_client(client, fmt,...)
Server sends INFO log message to client.
Definition network/log.h:65
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628
log_level_t
Logging levels enumeration.
Definition types.h:33
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
@ REMOTE_LOG_DIRECTION_UNKNOWN
Definition network/log.h:20
@ REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER
Definition network/log.h:20
#define VIDEO_CODEC_SUPPORTED(cap, codec)
Check if a video codec is supported in capabilities bitmask.
Definition codecs.h:89
#define NS_PER_SEC_INT
Definition time.h:173
#define US_PER_SEC_INT
Definition time.h:177
asciichat_error_t frame_validate_legacy(size_t len, size_t expected_rgb_size)
Validate legacy frame format.
#define AUDIO_BATCH_SAMPLES
Total samples in audio batch (8192 samples).
Definition packet.h:245
#define AUDIO_SAMPLES_PER_PACKET
Samples per audio packet (256 samples).
Definition packet.h:264
#define CLIENT_CAP_STRETCH
Client can stretch frames to fill terminal.
Definition packet.h:1001
#define STREAM_TYPE_VIDEO
Video stream.
Definition packet.h:1012
#define STREAM_TYPE_AUDIO
Audio stream.
Definition packet.h:1013
#define ACIP_CRYPTO_HAS_ENCRYPT(mode)
Check if crypto mode includes payload encryption.
Definition packet.h:1167
#define MAX_REMOTE_LOG_MESSAGE_LENGTH
Maximum remote log message length (512 bytes).
Definition packet.h:163
#define CLIENT_CAP_COLOR
Client supports color rendering.
Definition packet.h:1000
#define PROTOCOL_FEATURE_RECOVERABLE_ERRORS
Definition packet.h:855
asciichat_error_t frame_check_size_overflow(size_t header_size, size_t data_size)
Check for overflow when adding header to data.
#define REMOTE_LOG_FLAG_TRUNCATED
Remote log packet flag definitions.
Definition packet.h:787
#define CLIENT_CAP_AUDIO
Client can send/receive audio.
Definition packet.h:999
#define CLIENT_CAP_VIDEO
Client can send/receive video.
Definition packet.h:998
@ PACKET_TYPE_ACIP_SETTINGS_ACK
Settings acknowledgment (Participant -> Initiator).
Definition packet.h:501
#define GET_OPTION(field)
Definition options.h:1333
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.
#define PROTOCOL_VERSION_MAJOR
Major protocol version number.
#define PROTOCOL_VERSION_MINOR
Minor protocol version number.
#define PROTOCOL_VERSION_PATCH
Patch protocol version number.
struct acip_transport acip_transport_t
Forward declaration of ACIP transport.
Definition host.h:508
void format_bytes_pretty(size_t bytes, char *out, size_t out_capacity)
Format byte count into human-readable string.
Definition util/format.c:11
#define VALIDATE_PACKET_NOT_NULL(client, data, packet_name)
struct client_info client_info_t
#define VALIDATE_AUDIO_SAMPLE_COUNT(client, num_samples, max_samples, packet_name)
#define VALIDATE_RESOURCE_INITIALIZED(client, resource, resource_name)
#define VALIDATE_AUDIO_STREAM_ENABLED(client, packet_name)
#define VALIDATE_AUDIO_ALIGNMENT(client, len, sample_size, packet_name)
#define VALIDATE_NONZERO(client, value, value_name, packet_name)
#define VALIDATE_MIN_SIZE(client, len, min_size, packet_name)
#define VALIDATE_PACKET_SIZE(client, data, len, expected_size, packet_name)
#define VALIDATE_NOTNULL_DATA(client, data, packet_name)
#define VALIDATE_FLAGS_MASK(client, flags, valid_mask, packet_name)
#define VALIDATE_RANGE(client, value, min_val, max_val, value_name, packet_name)
void disconnect_client_for_bad_data(client_info_t *client, const char *format,...)
#define VALIDATE_CAPABILITY_FLAGS(client, flags, valid_mask, packet_name)
video_frame_t * video_frame_begin_write(video_frame_buffer_t *vfb)
Writer API: Start writing a new frame.
void video_frame_commit(video_frame_buffer_t *vfb)
Writer API: Commit the frame and swap buffers.
🔊 Audio Capture and Playback Interface for ascii-chat
⚙️ Common definitions, error codes, macros, and types shared throughout the application
Common declarations and data structures for cryptographic handshake.
ACIP server-side protocol API.
asciichat_error_t acip_send_server_state(acip_transport_t *transport, const server_state_packet_t *state)
Send server state update to client (server → client).
asciichat_error_t acip_render_settings_capabilities(acip_render_settings_t *state, const terminal_capabilities_packet_t *packet)
asciichat_error_t acip_settings_encode(const acip_settings_header_t *header, const char *json, uint8_t *buffer, size_t capacity, size_t *length)
asciichat_error_t acip_settings_request(acip_render_settings_t *state, const void *payload, size_t length, uint8_t *reply, size_t capacity, size_t *reply_length)
void network_connection_request_stop(network_connection_t *c)
action_args_t args
#define log_debug_every(interval_us, fmt,...)
Rate-limited DEBUG logging.
Definition log/log.h:743
🔢 Mathematical Utility Functions
Frame validation utilities for IMAGE_FRAME packets.
#define FRAME_HEADER_SIZE_LEGACY
Legacy frame header size (width:4 + height:4).
Opus audio codec wrapper for real-time encoding/decoding.
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.
Definition packet.c:885
ASCII Palette Management for Video-to-ASCII Conversion.
asciichat_error_t acip_send_error(acip_transport_t *transport, uint32_t error_code, const char *message)
Send error message packet.
Definition send.c:402
asciichat_error_t acip_send_pong(acip_transport_t *transport)
Send pong packet.
Definition send.c:382
asciichat_error_t packet_send_via_transport(acip_transport_t *transport, packet_type_t type, const void *payload, size_t payload_len, uint32_t client_id)
Definition send.c:183
ACIP shared/bidirectional packet sending functions.
h265_server_context_t *volatile g_h265_server
Global H.265 codec server context.
void handle_client_join_packet(client_info_t *client, const void *data, size_t len)
Process CLIENT_JOIN packet - client announces identity and capabilities.
void handle_pong_packet(client_info_t *client, const void *data, size_t len)
Handle PONG packet - client acknowledged our PING.
void handle_audio_opus_packet(client_info_t *client, const void *data, size_t len)
Process AUDIO_OPUS packet - decode single Opus frame from client.
void handle_protocol_version_packet(client_info_t *client, const void *data, size_t len)
Process PROTOCOL_VERSION packet - validate protocol compatibility.
void handle_image_frame_packet(client_info_t *client, void *data, size_t len)
Process IMAGE_FRAME packet - store client's video data for rendering.
void handle_audio_batch_packet(client_info_t *client, const void *data, size_t len)
Process AUDIO_BATCH packet - store efficiently batched audio samples.
#define SERVER_PROTOCOL_REASON_BUFFER_SIZE
void handle_size_packet(client_info_t *client, const void *data, size_t len)
Process terminal size update packet - handle client window resize.
void handle_image_frame_h265_packet(client_info_t *client, const void *data, size_t len)
Process H.265-encoded image frame from client.
void handle_audio_packet(client_info_t *client, const void *data, size_t len)
Process AUDIO packet - store single audio sample batch (legacy format).
void handle_client_leave_packet(client_info_t *client, const void *data, size_t len)
Process CLIENT_LEAVE packet - handle clean client disconnect.
#define SERVER_H265_RGBA_BUFFER_SIZE
#define SERVER_PROTOCOL_SIZE_BUFFER_SIZE
#define OPUS_DECODE_STATIC_MAX_SAMPLES
void handle_stream_stop_packet(client_info_t *client, const void *data, size_t len)
Process STREAM_STOP packet - client requests to halt media transmission.
int send_server_state_to_client(client_info_t *client)
Send current server state to a specific client.
void handle_client_capabilities_packet(client_info_t *client, const void *data, size_t len)
void broadcast_clear_console_to_all_clients(void)
Signal all active clients to clear their displays before next video frame.
void handle_stream_start_packet(client_info_t *client, const void *data, size_t len)
Process STREAM_START packet - client requests to begin media transmission.
#define SERVER_PROTOCOL_PRETTY_BUFFER_SIZE
void handle_remote_log_packet_from_client(client_info_t *client, const void *data, size_t len)
asciichat_error_t handle_runtime_settings(client_info_t *client, const void *data, size_t length)
void handle_audio_opus_batch_packet(client_info_t *client, const void *data, size_t len)
Process AUDIO_OPUS_BATCH packet - efficient Opus-encoded audio batch from client.
void handle_ping_packet(client_info_t *client, const void *data, size_t len)
Handle PING packet - respond with PONG.
client_manager_t g_client_manager
Hash table entry for client packet dispatch.
Per-client state management and lifecycle orchestration.
Server packet processing and protocol implementation.
struct h265_server_context h265_server_context_t
The useful part of h265 client decoder is in client_id, decoder, last_width, last_height: together th...
asciichat_error_t h265_server_decode_and_convert(h265_server_client_t *client, const uint8_t *h265_packet, size_t packet_size, uint8_t *output_rgba, uint16_t *output_width, uint16_t *output_height, size_t *output_size)
h265_server_client_t * h265_server_get_client_decoder(h265_server_context_t *ctx, uint32_t client_id)
Server-side H.265 decoding pipeline for multi-client streams.
struct h265_server_client h265_server_client_t
🔤 String Manipulation and Shell Escaping Utilities
acip render settings keeps the values that move through the subsystem: caps, width,...
acip settings header keeps the values that move through the subsystem: schema, request,...
Parsed audio batch packet header information.
uint32_t batch_count
Number of audio frames in this batch.
uint32_t channels
Number of channels (1=mono, 2=stereo).
uint32_t sample_rate
Sample rate in Hz (e.g., 48000).
uint32_t total_samples
Total number of samples across all frames.
The metadata prefix for a batch of encoded audio samples. batch_count, total_samples,...
Definition packet.h:979
Client information packet structure.
Definition packet.h:703
char display_name[32]
User display name (null-terminated, max MAX_DISPLAY_NAME_LEN bytes).
Definition packet.h:707
uint32_t capabilities
Client capabilities bitmask (CLIENT_CAP_VIDEO | CLIENT_CAP_AUDIO | CLIENT_CAP_COLOR | CLIENT_CAP_STRE...
Definition packet.h:710
terminal_capabilities_t terminal_caps
char display_name[MAX_DISPLAY_NAME_LEN]
network_connection_t * network_connection
acip_render_settings_t render_settings
video_frame_buffer_t * incoming_video_buffer
audio_ring_buffer_t * incoming_audio_buffer
char client_palette_chars[ASCII_PALETTE_BUFFER_SIZE]
char client_luminance_palette[ASCII_LUMINANCE_LEVELS]
char client_id[MAX_CLIENT_ID_LEN]
State for one Opus encoding or decoding direction.
Definition opus.h:105
Protocol version negotiation packet structure (Packet Type 1).
Definition packet.h:871
uint16_t protocol_patch
Patch protocol revision.
Definition packet.h:877
uint16_t protocol_revision
Minor protocol revision (server can be newer).
Definition packet.h:875
uint16_t protocol_version
Major protocol version (must match for compatibility).
Definition packet.h:873
uint8_t reserved[5]
Reserved bytes for future expansion (must be zero).
Definition packet.h:887
uint16_t feature_flags
Feature flags bitmask (FEATURE_RLE_ENCODING, etc.).
Definition packet.h:885
uint8_t compression_algorithms
Supported compression algorithms bitmask (COMPRESS_ALGO_*).
Definition packet.h:881
uint8_t supports_encryption
Encryption & authentication mode bitmask (ACIP_CRYPTO_* constants: NONE, ENCRYPT, AUTH,...
Definition packet.h:879
Server state packet structure.
Definition packet.h:757
uint32_t reserved[6]
Reserved fields for future use (must be zero).
Definition packet.h:763
uint32_t active_client_count
Number of clients actively sending video/audio streams.
Definition packet.h:761
uint32_t connected_client_count
Total number of currently connected clients.
Definition packet.h:759
Terminal size update packet.
Definition packet.h:687
uint32_t height
Terminal height in characters.
Definition packet.h:691
uint32_t width
Terminal width in characters.
Definition packet.h:689
Terminal capabilities packet structure (Packet Type 5).
Definition packet.h:1093
uint32_t codec_capabilities_video
Video codec capabilities bitmask (VIDEO_CODEC_CAP_*).
Definition packet.h:1125
uint32_t codec_capabilities_audio
Audio codec capabilities bitmask (AUDIO_CODEC_CAP_*).
Definition packet.h:1127
When code needs to work with simple frame swap, it keeps current_frame, frame_a, frame_b,...
uint64_t sequence_number
Frame sequence number (for drop detection).
uint32_t height
Frame height in pixels.
bool is_keyframe
True if this is a keyframe (important frame).
size_t size
Size of frame data in bytes.
uint64_t receive_timestamp_ns
Timestamp when frame was received (nanoseconds).
uint32_t width
Frame width in pixels.
uint64_t capture_timestamp_ns
Timestamp when frame was captured (nanoseconds).
void * data
Frame data pointer (points to pre-allocated buffer).
⏱️ High-precision timing utilities using sokol_time.h and uthash
#define LOG_INFO
Definition types.h:44
📊 String Formatting Utilities
asciichat_error_t image_validate_buffer_size(size_t requested_size)
Validate buffer size against maximum allocation limit.
Definition util/image.c:111
asciichat_error_t image_validate_dimensions(size_t width, size_t height)
Validate image dimensions (non-zero, within limits).
Definition util/image.c:97
asciichat_error_t image_calc_rgb_size(size_t width, size_t height, size_t *out_size)
Calculate total RGB buffer size from dimensions.
Definition util/image.c:53
🖼️ Safe overflow-checked buffer size calculations for images and video frames
Common validation macros to reduce duplication in protocol handlers.