@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/c/examples/networking/README.md

@@ -0,0 +1,207 @@
+# Networking Examples
+
+This directory contains network programming examples demonstrating socket programming and protocol handling.
+
+## Examples
+
+### 1. tcp-server.c
+TCP server with connection handling:
+- Socket creation and binding
+- Connection acceptance
+- Echo server implementation
+- Error handling
+- Resource cleanup
+
+**Key Concepts:**
+- Use `SO_REUSEADDR` for quick restart
+- Check all socket operation return values
+- Close sockets properly
+- Handle partial reads/writes
+
+### 2. udp-multicast.c
+UDP multicast sender and receiver:
+- Multicast group management
+- Sending multicast packets
+- Receiving multicast packets
+- TTL configuration
+- Multiple receivers
+
+**Key Concepts:**
+- Join multicast group with `IP_ADD_MEMBERSHIP`
+- Set multicast TTL appropriately
+- Use `SO_REUSEADDR` for multiple receivers
+- Multicast addresses: 224.0.0.0 to 239.255.255.255
+
+### 3. protocol-parser.c
+Binary protocol parser:
+- State machine parsing
+- Endianness handling
+- Checksum validation
+- Error detection
+- Input validation
+
+**Key Concepts:**
+- Parse byte-by-byte with state machine
+- Validate all inputs
+- Handle network byte order (big-endian)
+- Implement error recovery
+
+## Building
+
+```bash
+# Build all examples
+make
+
+# Build specific example
+make tcp-server
+
+# Clean
+make clean
+
+# Run tests
+make test
+```
+
+## Running Examples
+
+### TCP Server
+
+```bash
+# Terminal 1: Start server
+./tcp-server 8080
+
+# Terminal 2: Connect with telnet
+telnet localhost 8080
+
+# Or use netcat
+nc localhost 8080
+```
+
+### UDP Multicast
+
+```bash
+# Terminal 1: Start receiver
+./udp-multicast recv 239.0.0.1 5000
+
+# Terminal 2: Start sender
+./udp-multicast send 239.0.0.1 5000
+
+# You can run multiple receivers
+```
+
+### Protocol Parser
+
+```bash
+# Run parser test
+./protocol-parser
+```
+
+## Network Programming Best Practices
+
+1. **Error Handling**
+   - Check all socket operations
+   - Handle `EINTR` for interrupted system calls
+   - Handle `EAGAIN`/`EWOULDBLOCK` for non-blocking I/O
+   - Close sockets on error
+
+2. **Resource Management**
+   - Always close sockets
+   - Use `SO_REUSEADDR` for servers
+   - Set appropriate timeouts
+   - Limit buffer sizes
+
+3. **Protocol Design**
+   - Use network byte order (big-endian)
+   - Include length fields
+   - Add checksums for integrity
+   - Version your protocol
+
+4. **Security**
+   - Validate all inputs
+   - Limit buffer sizes
+   - Use timeouts
+   - Handle malformed data
+
+## Common Pitfalls
+
+1. **Forgetting Network Byte Order**
+   ```c
+   // WRONG
+   uint16_t port = 8080;
+   addr.sin_port = port;
+   
+   // CORRECT
+   addr.sin_port = htons(8080);
+   ```
+
+2. **Not Handling Partial Reads/Writes**
+   ```c
+   // WRONG - Assumes all data sent
+   send(sockfd, buffer, size, 0);
+   
+   // CORRECT - Handle partial sends
+   size_t sent = 0;
+   while (sent < size) {
+       ssize_t n = send(sockfd, buffer + sent, size - sent, 0);
+       if (n < 0) { /* error */ }
+       sent += n;
+   }
+   ```
+
+3. **Not Closing Sockets**
+   ```c
+   // WRONG - Socket leak
+   int sockfd = socket(AF_INET, SOCK_STREAM, 0);
+   if (bind(sockfd, ...) < 0) {
+       return -1;  // Leaked socket!
+   }
+   
+   // CORRECT
+   int sockfd = socket(AF_INET, SOCK_STREAM, 0);
+   if (bind(sockfd, ...) < 0) {
+       close(sockfd);
+       return -1;
+   }
+   ```
+
+4. **Buffer Overflows**
+   ```c
+   // WRONG - No bounds checking
+   char buffer[100];
+   recv(sockfd, buffer, 1000, 0);  // Overflow!
+   
+   // CORRECT
+   char buffer[100];
+   ssize_t n = recv(sockfd, buffer, sizeof(buffer) - 1, 0);
+   if (n > 0) {
+       buffer[n] = '\0';
+   }
+   ```
+
+## Protocol Format
+
+The example protocol uses this format:
+
+```
++--------+--------+--------+--------+--------+--------+
+| MAGIC  | MAGIC  | TYPE   | LENGTH | LENGTH | CHKSUM |
+| (MSB)  | (LSB)  |        | (MSB)  | (LSB)  |        |
++--------+--------+--------+--------+--------+--------+
+| PAYLOAD (variable length)                          |
++----------------------------------------------------+
+```
+
+- **MAGIC**: 0xABCD (protocol identifier)
+- **TYPE**: Message type (1 byte)
+- **LENGTH**: Payload length in bytes (2 bytes, big-endian)
+- **CHECKSUM**: XOR checksum of payload
+- **PAYLOAD**: Message data
+
+## References
+
+- POSIX Socket API: https://pubs.opengroup.org/onlinepubs/9699919799/
+- TCP/IP Illustrated by W. Richard Stevens
+- Unix Network Programming by W. Richard Stevens
+- RFC 1112: Host Extensions for IP Multicasting
+- Beej's Guide to Network Programming
+

package/augment-extensions/coding-standards/c/examples/networking/protocol-parser.c

@@ -0,0 +1,270 @@
+/**
+ * @file protocol-parser.c
+ * @brief Example binary protocol parser with error handling
+ * 
+ * This example demonstrates:
+ * - Binary protocol parsing
+ * - Endianness handling
+ * - Input validation
+ * - State machine for parsing
+ * - Error detection and recovery
+ * 
+ * Protocol Format:
+ *   Header: [MAGIC(2)] [TYPE(1)] [LENGTH(2)] [CHECKSUM(1)]
+ *   Payload: [DATA(LENGTH)]
+ * 
+ * Compile: gcc -Wall -Wextra -std=c11 -o protocol-parser protocol-parser.c
+ * Run: ./protocol-parser
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include <arpa/inet.h>  /* For ntohs/htons */
+
+#define PROTOCOL_MAGIC      0xABCD
+#define MAX_PAYLOAD_SIZE    1024
+#define HEADER_SIZE         6
+
+/* Message types */
+typedef enum {
+    MSG_TYPE_DATA    = 0x01,
+    MSG_TYPE_ACK     = 0x02,
+    MSG_TYPE_NACK    = 0x03,
+    MSG_TYPE_PING    = 0x04,
+    MSG_TYPE_PONG    = 0x05
+} message_type_t;
+
+/* Parser states */
+typedef enum {
+    STATE_WAIT_MAGIC,
+    STATE_WAIT_TYPE,
+    STATE_WAIT_LENGTH,
+    STATE_WAIT_CHECKSUM,
+    STATE_WAIT_PAYLOAD,
+    STATE_COMPLETE,
+    STATE_ERROR
+} parser_state_t;
+
+/* Protocol message structure */
+typedef struct {
+    uint16_t magic;
+    uint8_t type;
+    uint16_t length;
+    uint8_t checksum;
+    uint8_t payload[MAX_PAYLOAD_SIZE];
+} protocol_message_t;
+
+/* Parser context */
+typedef struct {
+    parser_state_t state;
+    protocol_message_t message;
+    size_t bytes_received;
+    size_t payload_received;
+} parser_context_t;
+
+/**
+ * @brief Calculate simple checksum
+ */
+static uint8_t calculate_checksum(const uint8_t *data, size_t length) {
+    uint8_t checksum = 0;
+    for (size_t i = 0; i < length; i++) {
+        checksum ^= data[i];
+    }
+    return checksum;
+}
+
+/**
+ * @brief Initialize parser context
+ */
+static void parser_init(parser_context_t *ctx) {
+    memset(ctx, 0, sizeof(*ctx));
+    ctx->state = STATE_WAIT_MAGIC;
+}
+
+/**
+ * @brief Parse incoming byte
+ * @return true if message complete, false otherwise
+ */
+static bool parser_process_byte(parser_context_t *ctx, uint8_t byte) {
+    switch (ctx->state) {
+        case STATE_WAIT_MAGIC:
+            if (ctx->bytes_received == 0) {
+                /* First byte of magic */
+                ctx->message.magic = byte << 8;
+                ctx->bytes_received = 1;
+            } else {
+                /* Second byte of magic */
+                ctx->message.magic |= byte;
+                if (ctx->message.magic == PROTOCOL_MAGIC) {
+                    ctx->state = STATE_WAIT_TYPE;
+                    ctx->bytes_received = 0;
+                } else {
+                    /* Invalid magic, reset */
+                    printf("Error: Invalid magic 0x%04X\n", ctx->message.magic);
+                    parser_init(ctx);
+                }
+            }
+            break;
+            
+        case STATE_WAIT_TYPE:
+            ctx->message.type = byte;
+            ctx->state = STATE_WAIT_LENGTH;
+            ctx->bytes_received = 0;
+            break;
+            
+        case STATE_WAIT_LENGTH:
+            if (ctx->bytes_received == 0) {
+                /* First byte of length (MSB) */
+                ctx->message.length = byte << 8;
+                ctx->bytes_received = 1;
+            } else {
+                /* Second byte of length (LSB) */
+                ctx->message.length |= byte;
+                if (ctx->message.length > MAX_PAYLOAD_SIZE) {
+                    printf("Error: Payload too large (%u bytes)\n", ctx->message.length);
+                    ctx->state = STATE_ERROR;
+                } else {
+                    ctx->state = STATE_WAIT_CHECKSUM;
+                    ctx->bytes_received = 0;
+                }
+            }
+            break;
+            
+        case STATE_WAIT_CHECKSUM:
+            ctx->message.checksum = byte;
+            if (ctx->message.length > 0) {
+                ctx->state = STATE_WAIT_PAYLOAD;
+                ctx->payload_received = 0;
+            } else {
+                /* No payload, verify checksum */
+                uint8_t expected = calculate_checksum(NULL, 0);
+                if (ctx->message.checksum == expected) {
+                    ctx->state = STATE_COMPLETE;
+                    return true;
+                } else {
+                    printf("Error: Checksum mismatch\n");
+                    ctx->state = STATE_ERROR;
+                }
+            }
+            break;
+            
+        case STATE_WAIT_PAYLOAD:
+            ctx->message.payload[ctx->payload_received++] = byte;
+            if (ctx->payload_received >= ctx->message.length) {
+                /* Verify checksum */
+                uint8_t expected = calculate_checksum(ctx->message.payload,
+                                                      ctx->message.length);
+                if (ctx->message.checksum == expected) {
+                    ctx->state = STATE_COMPLETE;
+                    return true;
+                } else {
+                    printf("Error: Checksum mismatch (expected 0x%02X, got 0x%02X)\n",
+                           expected, ctx->message.checksum);
+                    ctx->state = STATE_ERROR;
+                }
+            }
+            break;
+            
+        case STATE_COMPLETE:
+        case STATE_ERROR:
+            /* Reset parser */
+            parser_init(ctx);
+            break;
+    }
+    
+    return false;
+}
+
+/**
+ * @brief Create protocol message
+ */
+static size_t create_message(uint8_t *buffer, size_t buffer_size,
+                             message_type_t type, const uint8_t *payload,
+                             uint16_t payload_len) {
+    if (buffer_size < HEADER_SIZE + payload_len) {
+        return 0;  /* Buffer too small */
+    }
+    
+    size_t offset = 0;
+    
+    /* Magic (big-endian) */
+    uint16_t magic = htons(PROTOCOL_MAGIC);
+    memcpy(buffer + offset, &magic, 2);
+    offset += 2;
+    
+    /* Type */
+    buffer[offset++] = type;
+    
+    /* Length (big-endian) */
+    uint16_t length = htons(payload_len);
+    memcpy(buffer + offset, &length, 2);
+    offset += 2;
+    
+    /* Checksum */
+    uint8_t checksum = calculate_checksum(payload, payload_len);
+    buffer[offset++] = checksum;
+    
+    /* Payload */
+    if (payload_len > 0) {
+        memcpy(buffer + offset, payload, payload_len);
+        offset += payload_len;
+    }
+    
+    return offset;
+}
+
+/**
+ * @brief Print parsed message
+ */
+static void print_message(const protocol_message_t *msg) {
+    printf("\n=== Parsed Message ===\n");
+    printf("Magic:    0x%04X\n", msg->magic);
+    printf("Type:     0x%02X\n", msg->type);
+    printf("Length:   %u bytes\n", msg->length);
+    printf("Checksum: 0x%02X\n", msg->checksum);
+    if (msg->length > 0) {
+        printf("Payload:  ");
+        for (uint16_t i = 0; i < msg->length && i < 32; i++) {
+            printf("%02X ", msg->payload[i]);
+        }
+        if (msg->length > 32) {
+            printf("...");
+        }
+        printf("\n");
+    }
+    printf("=====================\n\n");
+}
+
+/**
+ * @brief Test protocol parser
+ */
+int main(void) {
+    uint8_t buffer[256];
+    parser_context_t parser;
+    
+    printf("Protocol Parser Example\n\n");
+    
+    /* Create test message */
+    const char *test_data = "Hello, Protocol!";
+    size_t msg_len = create_message(buffer, sizeof(buffer),
+                                    MSG_TYPE_DATA,
+                                    (const uint8_t *)test_data,
+                                    strlen(test_data));
+    
+    printf("Created message of %zu bytes\n", msg_len);
+    
+    /* Parse message byte by byte */
+    parser_init(&parser);
+    for (size_t i = 0; i < msg_len; i++) {
+        if (parser_process_byte(&parser, buffer[i])) {
+            printf("Message parsed successfully!\n");
+            print_message(&parser.message);
+        }
+    }
+    
+    return EXIT_SUCCESS;
+}
+

package/augment-extensions/coding-standards/c/examples/networking/tcp-server.c

@@ -0,0 +1,197 @@
+/**
+ * @file tcp-server.c
+ * @brief Example TCP server with proper error handling
+ * 
+ * This example demonstrates:
+ * - TCP socket creation and binding
+ * - Connection handling
+ * - Non-blocking I/O
+ * - Error handling
+ * - Resource cleanup
+ * 
+ * Compile: gcc -Wall -Wextra -std=c11 -o tcp-server tcp-server.c
+ * Run: ./tcp-server 8080
+ * Test: telnet localhost 8080
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+#include <fcntl.h>
+
+#define BUFFER_SIZE 1024
+#define MAX_PENDING 5
+
+/**
+ * @brief Set socket to non-blocking mode
+ */
+static int set_nonblocking(int sockfd) {
+    int flags = fcntl(sockfd, F_GETFL, 0);
+    if (flags < 0) {
+        perror("fcntl(F_GETFL)");
+        return -1;
+    }
+    
+    if (fcntl(sockfd, F_SETFL, flags | O_NONBLOCK) < 0) {
+        perror("fcntl(F_SETFL)");
+        return -1;
+    }
+    
+    return 0;
+}
+
+/**
+ * @brief Create and configure TCP server socket
+ */
+static int create_server_socket(uint16_t port) {
+    int sockfd;
+    struct sockaddr_in server_addr;
+    int reuse = 1;
+    
+    /* Create socket */
+    sockfd = socket(AF_INET, SOCK_STREAM, 0);
+    if (sockfd < 0) {
+        perror("socket");
+        return -1;
+    }
+    
+    /* Set SO_REUSEADDR to reuse port immediately */
+    if (setsockopt(sockfd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse)) < 0) {
+        perror("setsockopt(SO_REUSEADDR)");
+        close(sockfd);
+        return -1;
+    }
+    
+    /* Bind to address */
+    memset(&server_addr, 0, sizeof(server_addr));
+    server_addr.sin_family = AF_INET;
+    server_addr.sin_addr.s_addr = INADDR_ANY;
+    server_addr.sin_port = htons(port);
+    
+    if (bind(sockfd, (struct sockaddr *)&server_addr, sizeof(server_addr)) < 0) {
+        perror("bind");
+        close(sockfd);
+        return -1;
+    }
+    
+    /* Listen for connections */
+    if (listen(sockfd, MAX_PENDING) < 0) {
+        perror("listen");
+        close(sockfd);
+        return -1;
+    }
+    
+    printf("TCP server listening on port %u\n", port);
+    return sockfd;
+}
+
+/**
+ * @brief Handle client connection
+ */
+static void handle_client(int client_fd, struct sockaddr_in *client_addr) {
+    char buffer[BUFFER_SIZE];
+    ssize_t bytes_read;
+    
+    printf("New connection from %s:%u\n",
+           inet_ntoa(client_addr->sin_addr),
+           ntohs(client_addr->sin_port));
+    
+    /* Send welcome message */
+    const char *welcome = "Welcome to TCP server!\r\n";
+    if (send(client_fd, welcome, strlen(welcome), 0) < 0) {
+        perror("send");
+        return;
+    }
+    
+    /* Echo loop */
+    while (1) {
+        bytes_read = recv(client_fd, buffer, sizeof(buffer) - 1, 0);
+        
+        if (bytes_read < 0) {
+            if (errno == EAGAIN || errno == EWOULDBLOCK) {
+                /* No data available, continue */
+                usleep(10000);  /* 10ms */
+                continue;
+            }
+            perror("recv");
+            break;
+        } else if (bytes_read == 0) {
+            /* Connection closed by client */
+            printf("Client disconnected\n");
+            break;
+        }
+        
+        buffer[bytes_read] = '\0';
+        printf("Received: %s", buffer);
+        
+        /* Echo back to client */
+        if (send(client_fd, buffer, bytes_read, 0) < 0) {
+            perror("send");
+            break;
+        }
+        
+        /* Check for quit command */
+        if (strncmp(buffer, "quit", 4) == 0) {
+            printf("Client requested disconnect\n");
+            break;
+        }
+    }
+}
+
+/**
+ * @brief Main server loop
+ */
+int main(int argc, char *argv[]) {
+    int server_fd, client_fd;
+    struct sockaddr_in client_addr;
+    socklen_t client_len;
+    uint16_t port;
+    
+    /* Parse command line arguments */
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s <port>\n", argv[0]);
+        return EXIT_FAILURE;
+    }
+    
+    port = (uint16_t)atoi(argv[1]);
+    if (port == 0) {
+        fprintf(stderr, "Invalid port number\n");
+        return EXIT_FAILURE;
+    }
+    
+    /* Create server socket */
+    server_fd = create_server_socket(port);
+    if (server_fd < 0) {
+        return EXIT_FAILURE;
+    }
+    
+    printf("Server started. Press Ctrl+C to stop.\n");
+    
+    /* Accept connections */
+    while (1) {
+        client_len = sizeof(client_addr);
+        client_fd = accept(server_fd, (struct sockaddr *)&client_addr, &client_len);
+        
+        if (client_fd < 0) {
+            perror("accept");
+            continue;
+        }
+        
+        /* Handle client (single-threaded for simplicity) */
+        handle_client(client_fd, &client_addr);
+        
+        /* Close client connection */
+        close(client_fd);
+    }
+    
+    /* Cleanup */
+    close(server_fd);
+    return EXIT_SUCCESS;
+}
+