packet.h

Go to the documentation of this file.

 
#pragma once
 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define NETWORK_PACKET_TERM_TYPE_BUFFER_SIZE 32
#define NETWORK_PACKET_COLORTERM_BUFFER_SIZE 32
#define NETWORK_PACKET_PALETTE_CUSTOM_BUFFER_SIZE 64
 
/* Existing buffer budgets in bytes, including NUL for text storage. */
#define ACIP_OPUS_BATCH_HEADER_SIZE 16
 
#include <libplatform/socket.h>
#include <libplatform/compiler.h>
#include "../../crypto/crypto.h"
#include "../../log/log.h"
#include "../../util/magic.h"
#include "../../media/codecs.h"
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <errno.h>
 
// Pack network protocol structures tightly for wire format
#ifdef _WIN32
#pragma pack(push, 1)
#endif


#define LARGE_PACKET_THRESHOLD (100 * 1024)

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

#define MAX_ERROR_MESSAGE_LENGTH 4096

#define MAX_REMOTE_LOG_MESSAGE_LENGTH 512



#define BASE_SEND_TIMEOUT (5LL * NS_PER_SEC_INT)

#define LARGE_PACKET_EXTRA_TIMEOUT_PER_MB (800LL * NS_PER_MS_INT)

#define MIN_CLIENT_TIMEOUT (10LL * NS_PER_SEC_INT)

#define MAX_CLIENT_TIMEOUT (60LL * NS_PER_SEC_INT)



#define AUDIO_BATCH_COUNT 32

#define AUDIO_BATCH_SAMPLES (AUDIO_SAMPLES_PER_PACKET * AUDIO_BATCH_COUNT)

#define AUDIO_BATCH_MS 186

#define AUDIO_SAMPLES_PER_PACKET 256



#define PACKET_MAGIC MAGIC_PACKET_VALID


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

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

  PACKET_TYPE_CRYPTO_CAPABILITIES = 1100,
  PACKET_TYPE_CRYPTO_PARAMETERS = 1101,
  PACKET_TYPE_CRYPTO_KEY_EXCHANGE_INIT = 1102,
  PACKET_TYPE_CRYPTO_KEY_EXCHANGE_RESP = 1103,
  PACKET_TYPE_CRYPTO_AUTH_CHALLENGE = 1104,
  PACKET_TYPE_CRYPTO_AUTH_RESPONSE = 1105,
  PACKET_TYPE_CRYPTO_AUTH_FAILED = 1106,
  PACKET_TYPE_CRYPTO_SERVER_AUTH_RESP = 1107,
  PACKET_TYPE_CRYPTO_HANDSHAKE_COMPLETE = 1108,
  PACKET_TYPE_CRYPTO_NO_ENCRYPTION = 1109,
  PACKET_TYPE_QUIC_READY = 1110,
  PACKET_TYPE_QUIC_KEYFRAME_REQUEST = 1111,
  PACKET_TYPE_CRYPTO_EPOCH_MARKER = 1112,
  PACKET_TYPE_CRYPTO_REKEY_NEEDED = 1113,
  PACKET_TYPE_CRYPTO_EPOCH_ACK = 1114,
 
  // ============================================================================
  // Cryptographic Rekeying (Types 1200-1299)
  // ============================================================================
  // ALWAYS UNENCRYPTED during rekey phase

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

  PACKET_TYPE_SIZE_MESSAGE = 2000,
  PACKET_TYPE_AUDIO_MESSAGE = 2001,
  PACKET_TYPE_TEXT_MESSAGE = 2002,
  PACKET_TYPE_ERROR_MESSAGE = 2003,
  PACKET_TYPE_REMOTE_LOG = 2004,
 
  // ============================================================================
  // Media Frames (Types 3000-3999)
  // ============================================================================

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

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

  PACKET_TYPE_CLIENT_CAPABILITIES = 5000,
  PACKET_TYPE_PING = 5001,
  PACKET_TYPE_PONG = 5002,
  PACKET_TYPE_CLIENT_JOIN = 5003,
  PACKET_TYPE_CLIENT_LEAVE = 5004,
  PACKET_TYPE_STREAM_START = 5005,
  PACKET_TYPE_STREAM_STOP = 5006,
  PACKET_TYPE_CLEAR_CONSOLE = 5007,
  PACKET_TYPE_SERVER_STATE = 5008,
 
  // ============================================================================
  // Discovery Service Protocol (ACDS) (Types 6000+)
  // ============================================================================
  // ACIP packets use range 6000+ for discovery mode operations
  // See network/acip/protocol.h for protocol overview and utility functions
  // See network/acip/acds.h for ACDS message structures and detailed documentation

  PACKET_TYPE_ACIP_SESSION_CREATE = 6000,
  PACKET_TYPE_ACIP_SESSION_CREATED = 6001,
  PACKET_TYPE_ACIP_SESSION_LOOKUP = 6002,
  PACKET_TYPE_ACIP_SESSION_INFO = 6003,
  PACKET_TYPE_ACIP_SESSION_JOIN = 6004,
  PACKET_TYPE_ACIP_SESSION_JOINED = 6005,
  PACKET_TYPE_ACIP_SESSION_LEAVE = 6006,
  PACKET_TYPE_ACIP_SESSION_END = 6007,
  PACKET_TYPE_ACIP_SESSION_RECONNECT = 6008,

  PACKET_TYPE_ACIP_WEBRTC_SDP = 6009,
  PACKET_TYPE_ACIP_WEBRTC_ICE = 6010,

  PACKET_TYPE_ACIP_STRING_RESERVE = 6020,
  PACKET_TYPE_ACIP_STRING_RESERVED = 6021,
  PACKET_TYPE_ACIP_STRING_RENEW = 6022,
  PACKET_TYPE_ACIP_STRING_RELEASE = 6023,
 
  // ============================================================================
  // Ring Consensus Protocol (6050-6051)
  // ============================================================================
  // Used for proactive future host election every 5 minutes

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

  PACKET_TYPE_ACIP_NETWORK_QUALITY = 6060,
  PACKET_TYPE_ACIP_HOST_ANNOUNCEMENT = 6061,
  PACKET_TYPE_ACIP_HOST_DESIGNATED = 6062,
  PACKET_TYPE_ACIP_SETTINGS_SYNC = 6063,
  PACKET_TYPE_ACIP_SETTINGS_ACK = 6064,
  PACKET_TYPE_ACIP_HOST_LOST = 6065,
  PACKET_TYPE_ACIP_FUTURE_HOST_ELECTED = 6066,
  PACKET_TYPE_ACIP_PARTICIPANT_JOINED = 6067,
  PACKET_TYPE_ACIP_PARTICIPANT_LEFT = 6068,
 
  // ============================================================================
  // Bandwidth Testing (6070-6071)
  // ============================================================================
  // Used for measuring network bandwidth during NAT quality detection

  PACKET_TYPE_ACIP_BANDWIDTH_TEST = 6070,
  PACKET_TYPE_ACIP_BANDWIDTH_RESULT = 6071,

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

  PACKET_TYPE_RING_MEMBERS = 6100,
  PACKET_TYPE_STATS_COLLECTION_START = 6101,
  PACKET_TYPE_STATS_UPDATE = 6102,
  PACKET_TYPE_RING_ELECTION_RESULT = 6103,
  PACKET_TYPE_STATS_ACK = 6104,
 
  // ============================================================================
  // Discovery Service Keepalive (6190-6199)
  // ============================================================================

  PACKET_TYPE_ACIP_DISCOVERY_PING = 6190,
  PACKET_TYPE_ACIP_ERROR = 6199
} packet_type_t;

static inline bool packet_is_handshake_type(packet_type_t type) {
  // Client hello for multi-key selection (type 1000)
  if (type == PACKET_TYPE_CRYPTO_CLIENT_HELLO) {
    return true;
  }
  // Crypto handshake packets (1100-1109)
  if (type >= PACKET_TYPE_CRYPTO_CAPABILITIES && type <= PACKET_TYPE_CRYPTO_NO_ENCRYPTION) {
    return true;
  }
  // Crypto rekey packets (1201-1203)
  if (type >= PACKET_TYPE_CRYPTO_REKEY_REQUEST && type <= PACKET_TYPE_CRYPTO_REKEY_COMPLETE) {
    return true;
  }
  return false;
}

static inline bool packet_is_initial_handshake_type(packet_type_t type) {
  return packet_is_handshake_type(type) &&
         !(type >= PACKET_TYPE_CRYPTO_REKEY_REQUEST && type <= PACKET_TYPE_CRYPTO_REKEY_COMPLETE);
}

static inline bool packet_is_precompressed(packet_type_t type) {
  // Opus audio packets are already compressed by Opus codec
  return (type == PACKET_TYPE_AUDIO_OPUS_BATCH);
}

typedef struct {
  uint64_t magic;
  uint16_t type;
  uint32_t length;
  uint32_t crc32;
  uint32_t client_id;
} 
PACKED_ATTR  packet_header_t;

asciichat_error_t packet_header_build(packet_header_t *header, packet_type_t type, const socket_buffer_t *payload,
                                      size_t count, uint32_t client_id);
asciichat_error_t packet_encode(packet_type_t type, const void *payload, size_t length, uint32_t client_id,
                                void *output, size_t capacity, size_t *written);
asciichat_error_t packet_validate(const void *packet, size_t length, size_t limit, packet_header_t *header);


#define ASCIICHAT_DEFAULT_DISPLAY_NAME "AsciiChatter"


typedef struct {
  uint32_t width;
  uint32_t height;
} 
PACKED_ATTR  size_packet_t;

typedef struct {
  uint32_t client_id;
  char display_name[MAX_DISPLAY_NAME_LEN];
  uint32_t capabilities;
} 
PACKED_ATTR  client_info_packet_t;

typedef struct {
  uint32_t client_id;
  uint32_t stream_type;
  uint32_t timestamp;
} 
PACKED_ATTR  stream_header_t;

typedef struct {
  uint32_t client_count;
  client_info_packet_t clients[MAX_CLIENTS];
} 
PACKED_ATTR  client_list_packet_t;

typedef struct {
  uint32_t connected_client_count;
  uint32_t active_client_count;
  uint32_t reserved[6];
} 
PACKED_ATTR  server_state_packet_t;

typedef struct {
  uint32_t error_code;
  uint32_t message_length;
} 
PACKED_ATTR  error_packet_t;

#define REMOTE_LOG_FLAG_TRUNCATED 0x0001U 

typedef struct {
  uint8_t log_level;
  uint8_t direction;
  uint16_t flags;
  uint32_t message_length;
} 
PACKED_ATTR  remote_log_packet_t;

typedef enum {
  AUTH_FAIL_PASSWORD_REQUIRED = 0x01,
  AUTH_FAIL_PASSWORD_INCORRECT = 0x02,
  AUTH_FAIL_CLIENT_KEY_REQUIRED = 0x04,
  AUTH_FAIL_CLIENT_KEY_REJECTED = 0x08,
  AUTH_FAIL_SIGNATURE_INVALID = 0x10
} auth_failure_reason_t;

typedef struct {
  uint8_t reason_flags;
  uint8_t reserved[7];
} 
PACKED_ATTR  auth_failure_packet_t;


#define FEATURE_RLE_ENCODING 0x01                
#define FEATURE_DELTA_FRAMES 0x02                
#define PROTOCOL_FEATURE_RECOVERABLE_ERRORS 0x04 
#define PROTOCOL_FEATURE_IDENTITY_SET 0x08       


typedef struct {
  uint16_t protocol_version;
  uint16_t protocol_revision;
  uint16_t protocol_patch;
  uint8_t supports_encryption;
  uint8_t compression_algorithms;
  uint8_t compression_threshold;
  uint16_t feature_flags;
  uint8_t reserved[5];
} 
PACKED_ATTR  protocol_version_packet_t;
 
_Static_assert(sizeof(protocol_version_packet_t) == 16, "protocol version packet wire size must remain 16 bytes");

void protocol_version_packet_init(protocol_version_packet_t *version, uint8_t supports_encryption);

typedef struct {
  uint32_t width;
  uint32_t height;
  uint32_t original_size;
  uint32_t compressed_size;
  uint32_t checksum;
  uint32_t flags;
} 
PACKED_ATTR  ascii_frame_packet_t;

typedef struct {
  uint32_t width;
  uint32_t height;
  uint32_t pixel_format;
  uint32_t compressed_size;
  uint32_t checksum;
  uint32_t timestamp;
} 
PACKED_ATTR  image_frame_packet_t;

typedef struct {
  uint32_t batch_count;
  uint32_t total_samples;
  uint32_t sample_rate;
  uint32_t channels;
} 
PACKED_ATTR  audio_batch_packet_t;

#define CLIENT_CAP_VIDEO 0x01   
#define CLIENT_CAP_AUDIO 0x02   
#define CLIENT_CAP_COLOR 0x04   
#define CLIENT_CAP_STRETCH 0x08 


#define STREAM_TYPE_VIDEO 0x01 
#define STREAM_TYPE_AUDIO 0x02 


typedef struct {
  uint16_t supported_kex_algorithms;
  uint16_t supported_auth_algorithms;
  uint16_t supported_cipher_algorithms;
  uint8_t requires_verification;
  uint8_t preferred_kex;
  uint8_t preferred_auth;
  uint8_t preferred_cipher;
} 
PACKED_ATTR  crypto_capabilities_packet_t;

typedef struct {
  uint8_t selected_kex;
  uint8_t selected_auth;
  uint8_t selected_cipher;
  uint8_t verification_enabled;
  uint16_t kex_public_key_size;
  uint16_t auth_public_key_size;
  uint16_t signature_size;
  uint16_t shared_secret_size;
  uint8_t nonce_size;
  uint8_t mac_size;
  uint8_t hmac_size;
  uint8_t reserved[3];
} 
PACKED_ATTR  crypto_parameters_packet_t;

typedef struct {
  uint32_t capabilities;
  uint32_t color_level;
  uint32_t color_count;
  uint32_t render_mode;
  uint16_t width;
  uint16_t height;
  char term_type[NETWORK_PACKET_TERM_TYPE_BUFFER_SIZE];
  char colorterm[NETWORK_PACKET_COLORTERM_BUFFER_SIZE];
  uint8_t detection_reliable;
  uint32_t utf8_support;
  uint32_t palette_type;
  char palette_custom[NETWORK_PACKET_PALETTE_CUSTOM_BUFFER_SIZE];
  uint8_t desired_fps;
  uint8_t color_filter;
  uint8_t wants_padding;
  uint32_t codec_capabilities_video;
  uint32_t codec_capabilities_audio;
} 
PACKED_ATTR  terminal_capabilities_packet_t;

#define KEX_ALGO_X25519 0x01               
#define AUTH_ALGO_ED25519 0x01             
#define AUTH_ALGO_NONE 0x00                
#define CIPHER_ALGO_XSALSA20_POLY1305 0x01 
#define CIPHER_ALGO_NONE 0x00              

#define ACIP_CRYPTO_NONE 0x00    
#define ACIP_CRYPTO_ENCRYPT 0x01 
#define ACIP_CRYPTO_AUTH 0x02    
#define ACIP_CRYPTO_FULL 0x03    

#define ACIP_CRYPTO_HAS_ENCRYPT(mode) (((mode) & ACIP_CRYPTO_ENCRYPT) != 0)

#define ACIP_CRYPTO_HAS_AUTH(mode) (((mode) & ACIP_CRYPTO_AUTH) != 0)


 
#ifdef _WIN32
#pragma pack(pop)
#endif

typedef struct {
  packet_type_t type;
  void *data;
  size_t len;
  bool was_encrypted;
  bool consumed; 
  void *allocated_buffer;
  size_t allocated_size;
} packet_envelope_t;

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


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

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



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

packet_recv_result_t receive_packet_secure(socket_t sockfd, void *crypto_ctx, bool enforce_encryption,
                                           packet_envelope_t *envelope);
packet_recv_result_t receive_packet_secure_with_timeout(socket_t sockfd, void *crypto_ctx, bool enforce_encryption,
                                                        packet_envelope_t *envelope, uint64_t timeout_ns);

asciichat_error_t packet_decrypt_envelope(packet_envelope_t *envelope, void *crypto_ctx);



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

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



int send_ping_packet(socket_t sockfd);

int send_pong_packet(socket_t sockfd);

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

size_t packet_format_error_stack(char *buffer, size_t size);

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

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

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

int send_protocol_version_packet(socket_t sockfd, const protocol_version_packet_t *version);

int send_crypto_capabilities_packet(socket_t sockfd, const crypto_capabilities_packet_t *caps);

int send_crypto_parameters_packet(socket_t sockfd, const crypto_parameters_packet_t *params);

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

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


uint64_t packet_send_timeout_ns(size_t packet_size);