example_evolution.c

/**
 * @file example_evolution.c
 * @brief Example demonstrating schema versioning and evolution
 */

#include "binserde.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* Version 1 of User structure */
typedef struct {
    int32_t user_id;
    char username[32];
} UserV1;

/* Version 2 of User structure (with additional fields) */
typedef struct {
    int32_t user_id;
    char username[32];
    char email[64];     /* New field in v2 */
    uint32_t created_at; /* New field in v2 */
} UserV2;

/* Serialize Version 1 */
static binserde_error_t serialize_user_v1(const UserV1 *user, uint8_t *buffer, 
                                          size_t capacity, size_t *out_size) {
    binserde_writer_t writer;
    binserde_error_t err;
    
    err = binserde_writer_init(&writer, buffer, capacity, 1);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_header(&writer);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_int32(&writer, user->user_id);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_string(&writer, user->username);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_checksum(&writer);
    if (err != BINSERDE_OK) return err;
    
    *out_size = binserde_writer_position(&writer);
    return BINSERDE_OK;
}

/* Serialize Version 2 */
static binserde_error_t serialize_user_v2(const UserV2 *user, uint8_t *buffer,
                                          size_t capacity, size_t *out_size) {
    binserde_writer_t writer;
    binserde_error_t err;
    
    err = binserde_writer_init(&writer, buffer, capacity, 2);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_header(&writer);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_int32(&writer, user->user_id);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_string(&writer, user->username);
    if (err != BINSERDE_OK) return err;
    
    /* New fields in v2 */
    err = binserde_write_string(&writer, user->email);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_uint32(&writer, user->created_at);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_write_checksum(&writer);
    if (err != BINSERDE_OK) return err;
    
    *out_size = binserde_writer_position(&writer);
    return BINSERDE_OK;
}

/* Deserialize with version handling */
static binserde_error_t deserialize_user(const uint8_t *buffer, size_t size,
                                         UserV2 *user, uint32_t *version) {
    binserde_reader_t reader;
    binserde_error_t err;
    
    err = binserde_reader_init(&reader, buffer, size);
    if (err != BINSERDE_OK) return err;
    
    err = binserde_read_header(&reader, version);
    if (err != BINSERDE_OK) return err;
    
    /* Read common fields (present in all versions) */
    err = binserde_read_int32(&reader, &user->user_id);
    if (err != BINSERDE_OK) return err;
    
    char *username_ptr = NULL;
    err = binserde_read_string(&reader, &username_ptr);
    if (err != BINSERDE_OK) return err;
    strncpy(user->username, username_ptr, sizeof(user->username) - 1);
    user->username[sizeof(user->username) - 1] = '\0';
    free(username_ptr);
    
    /* Handle version-specific fields */
    if (*version >= 2) {
        /* Read v2 fields */
        char *email_ptr = NULL;
        err = binserde_read_string(&reader, &email_ptr);
        if (err != BINSERDE_OK) return err;
        strncpy(user->email, email_ptr, sizeof(user->email) - 1);
        user->email[sizeof(user->email) - 1] = '\0';
        free(email_ptr);
        
        err = binserde_read_uint32(&reader, &user->created_at);
        if (err != BINSERDE_OK) return err;
    } else {
        /* Set defaults for missing fields */
        strcpy(user->email, "unknown@example.com");
        user->created_at = 0;
    }
    
    /* Validate checksum */
    err = binserde_validate_checksum(&reader);
    if (err != BINSERDE_OK) return err;
    
    return BINSERDE_OK;
}

int main(void) {
    printf("=== Binary Serialization Schema Evolution Example ===\n\n");
    
    /* Create Version 1 user data */
    UserV1 user_v1 = {
        .user_id = 1001
    };
    strncpy(user_v1.username, "alice", sizeof(user_v1.username) - 1);
    user_v1.username[sizeof(user_v1.username) - 1] = '\0';
    
    printf("Creating Version 1 user:\n");
    printf("  User ID: %d\n", user_v1.user_id);
    printf("  Username: %s\n", user_v1.username);
    printf("  Schema Version: 1\n\n");
    
    /* Serialize v1 */
    uint8_t buffer_v1[512];
    size_t size_v1;
    binserde_error_t err;
    
    err = serialize_user_v1(&user_v1, buffer_v1, sizeof(buffer_v1), &size_v1);
    if (err != BINSERDE_OK) {
        fprintf(stderr, "Serialize v1 failed: %s\n", binserde_error_string(err));
        return 1;
    }
    printf("Serialized v1 user: %zu bytes\n\n", size_v1);
    
    /* Deserialize v1 data (forward compatibility: v1 reader can read v1 data) */
    UserV2 deserialized_v1 = {0};
    uint32_t version;
    
    err = deserialize_user(buffer_v1, size_v1, &deserialized_v1, &version);
    if (err != BINSERDE_OK) {
        fprintf(stderr, "Deserialize v1 failed: %s\n", binserde_error_string(err));
        return 1;
    }
    
    printf("Deserialized v1 data (with v2 reader):\n");
    printf("  Schema Version: %u\n", version);
    printf("  User ID: %d\n", deserialized_v1.user_id);
    printf("  Username: %s\n", deserialized_v1.username);
    printf("  Email: %s (default for v1)\n", deserialized_v1.email);
    printf("  Created At: %u (default for v1)\n\n", deserialized_v1.created_at);
    
    /* Create Version 2 user data */
    UserV2 user_v2 = {
        .user_id = 1002,
        .created_at = 1640000000
    };
    strncpy(user_v2.username, "bob", sizeof(user_v2.username) - 1);
    user_v2.username[sizeof(user_v2.username) - 1] = '\0';
    strncpy(user_v2.email, "bob@example.com", sizeof(user_v2.email) - 1);
    user_v2.email[sizeof(user_v2.email) - 1] = '\0';
    
    printf("Creating Version 2 user:\n");
    printf("  User ID: %d\n", user_v2.user_id);
    printf("  Username: %s\n", user_v2.username);
    printf("  Email: %s\n", user_v2.email);
    printf("  Created At: %u\n", user_v2.created_at);
    printf("  Schema Version: 2\n\n");
    
    /* Serialize v2 */
    uint8_t buffer_v2[512];
    size_t size_v2;
    
    err = serialize_user_v2(&user_v2, buffer_v2, sizeof(buffer_v2), &size_v2);
    if (err != BINSERDE_OK) {
        fprintf(stderr, "Serialize v2 failed: %s\n", binserde_error_string(err));
        return 1;
    }
    printf("Serialized v2 user: %zu bytes\n\n", size_v2);
    
    /* Deserialize v2 data */
    UserV2 deserialized_v2 = {0};
    
    err = deserialize_user(buffer_v2, size_v2, &deserialized_v2, &version);
    if (err != BINSERDE_OK) {
        fprintf(stderr, "Deserialize v2 failed: %s\n", binserde_error_string(err));
        return 1;
    }
    
    printf("Deserialized v2 data:\n");
    printf("  Schema Version: %u\n", version);
    printf("  User ID: %d\n", deserialized_v2.user_id);
    printf("  Username: %s\n", deserialized_v2.username);
    printf("  Email: %s\n", deserialized_v2.email);
    printf("  Created At: %u\n\n", deserialized_v2.created_at);
    
    /* Demonstrate schema evolution benefits */
    printf("Schema Evolution Benefits:\n");
    printf("  ✓ Backward compatibility: v2 reader can read v1 data\n");
    printf("  ✓ Forward compatibility: v1 data gets sensible defaults for new fields\n");
    printf("  ✓ Version detection: readers know which version they're handling\n");
    printf("  ✓ Graceful degradation: missing fields handled with defaults\n");
    
    return 0;
}