flux.c

Go to the documentation of this file.

/*
 * This file is part of the Aaru Data Preservation Suite.
 * Copyright (c) 2019-2025 Natalia Portillo.
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
 */
 
#include <inttypes.h>
#include <limits.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "aaruformat/context.h"
#include "aaruformat/errors.h"
#include "aaruformat/structs/index.h"
#include "consts.h"
#include "decls.h"
#include "internal.h"
#include "log.h"
#include "utarray.h"
#include "uthash.h"
 
struct FluxCaptureMapEntry
{
    FluxCaptureKey key;
    uint32_t       index;
    UT_hash_handle hh;
};

static void flux_capture_record_dtor(void *element)
{
    if(element == NULL) return;
 
    FluxCaptureRecord *record = element;
    free(record->data_buffer);
    free(record->index_buffer);
    record->data_buffer  = NULL;
    record->index_buffer = NULL;
}
 
static const UT_icd FLUX_CAPTURE_RECORD_ICD = {sizeof(FluxCaptureRecord), NULL, NULL, flux_capture_record_dtor};

static void flux_map_clear(aaruformat_context *ctx)
{
    if(ctx->flux_map == NULL) return;
 
    FluxCaptureMapEntry *entry;
    FluxCaptureMapEntry *tmp;
    HASH_ITER(hh, ctx->flux_map, entry, tmp)
    {
        HASH_DEL(ctx->flux_map, entry);
        free(entry);
    }
 
    ctx->flux_map = NULL;
}

static int flux_map_add(aaruformat_context *ctx, const FluxCaptureKey *key, uint32_t index)
{
    FluxCaptureMapEntry *entry = NULL;
    HASH_FIND(hh, ctx->flux_map, key, sizeof(FluxCaptureKey), entry);
 
    if(entry == NULL)
    {
        entry = malloc(sizeof(FluxCaptureMapEntry));
        if(entry == NULL) return -1;
        entry->key = *key;
        HASH_ADD(hh, ctx->flux_map, key, sizeof(FluxCaptureKey), entry);
    }
 
    entry->index = index;
    return 0;
}

int32_t flux_map_rebuild_from_entries(aaruformat_context *ctx)
{
    flux_map_clear(ctx);
 
    if(ctx->flux_entries == NULL || ctx->flux_data_header.entries == 0) return AARUF_STATUS_OK;
 
    for(uint32_t i = 0; i < ctx->flux_data_header.entries; i++)
    {
        const FluxEntry *entry = &ctx->flux_entries[i];
        FluxCaptureKey   key   = {entry->head, entry->track, entry->subtrack, entry->captureIndex};
 
        if(flux_map_add(ctx, &key, i) != 0)
        {
            FATAL("Could not add flux capture to lookup map");
            flux_map_clear(ctx);
            return AARUF_ERROR_NOT_ENOUGH_MEMORY;
        }
    }
 
    return AARUF_STATUS_OK;
}

void process_flux_data_block(aaruformat_context *ctx, const IndexEntry *entry)
{
    int      pos        = 0;
    size_t   read_bytes = 0;
    uint64_t crc64      = 0;
 
    // Check if the context and image stream are valid
    if(ctx == NULL || ctx->imageStream == NULL)
    {
        FATAL("Invalid context or image stream.");
        return;
    }
 
    if(ctx->flux_captures != NULL)
    {
        utarray_free(ctx->flux_captures);
        ctx->flux_captures = NULL;
    }
 
    if(ctx->flux_entries != NULL)
    {
        free(ctx->flux_entries);
        ctx->flux_entries = NULL;
    }
 
    flux_map_clear(ctx);
 
    memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
 
    // Seek to block
    pos = aaruf_fseek(ctx->imageStream, (aaru_off_t)entry->offset, SEEK_SET);
    if(pos < 0 || aaruf_ftell(ctx->imageStream) != (aaru_off_t)entry->offset)
    {
        FATAL("Could not seek to %" PRIu64 " as indicated by index entry...\n", entry->offset);
        return;
    }
 
    // Even if those two checks shall have been done before
    read_bytes = fread(&ctx->flux_data_header, 1, sizeof(FluxHeader), ctx->imageStream);
 
    if(read_bytes != sizeof(FluxHeader))
    {
        memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
        TRACE("Could not read flux data header, continuing...\n");
        return;
    }
 
    if(ctx->flux_data_header.identifier != FluxDataBlock)
    {
        memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
        TRACE("Incorrect identifier for flux data block at position %" PRIu64 "\n", entry->offset);
        return;
    }
 
    ctx->image_info.ImageSize += sizeof(FluxEntry) * ctx->flux_data_header.entries;
 
    ctx->flux_entries = (FluxEntry *)malloc(sizeof(FluxEntry) * ctx->flux_data_header.entries);
 
    if(ctx->flux_entries == NULL)
    {
        memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
        FATAL("Could not allocate memory for flux data block, continuing...\n");
        return;
    }
 
    read_bytes = fread(ctx->flux_entries, sizeof(FluxEntry), ctx->flux_data_header.entries, ctx->imageStream);
 
    if(read_bytes != ctx->flux_data_header.entries)
    {
        memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
        free(ctx->flux_entries);
        ctx->flux_entries = NULL;
        FATAL("Could not read flux data block, continuing...\n");
        return;
    }
 
    crc64 = aaruf_crc64_data((const uint8_t *)ctx->flux_entries, ctx->flux_data_header.entries * sizeof(FluxEntry));
 
    if(crc64 != ctx->flux_data_header.crc64)
    {
        TRACE("Incorrect CRC found: 0x%" PRIx64 " found, expected 0x%" PRIx64 ", continuing...\n", crc64,
              ctx->flux_data_header.crc64);
        return;
    }
 
    if(flux_map_rebuild_from_entries(ctx) != AARUF_STATUS_OK)
    {
        free(ctx->flux_entries);
        ctx->flux_entries = NULL;
        memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
        return;
    }
 
    TRACE("Found %d flux entries at position %" PRIu64 ".\n", ctx->flux_data_header.entries, entry->offset);
}

static int32_t ensure_flux_entries_loaded(aaruformat_context *ctx)
{
    // If already loaded, nothing to do
    if(ctx->flux_entries != NULL || ctx->flux_data_header.entries > 0) { return AARUF_STATUS_OK; }
 
    // Find FluxDataBlock in index
    if(ctx->index_entries == NULL) { return AARUF_ERROR_FLUX_DATA_NOT_FOUND; }
 
    IndexEntry *entry = NULL;
    for(unsigned int i = 0; i < utarray_len(ctx->index_entries); i++)
    {
        entry = (IndexEntry *)utarray_eltptr(ctx->index_entries, i);
        if(entry && entry->blockType == FluxDataBlock) { break; }
        entry = NULL;
    }
 
    if(entry == NULL) { return AARUF_ERROR_FLUX_DATA_NOT_FOUND; }
 
    // Load the flux data block
    process_flux_data_block(ctx, entry);
 
    // Check if loading was successful
    if(ctx->flux_entries == NULL || ctx->flux_data_header.entries == 0) { return AARUF_ERROR_FLUX_DATA_NOT_FOUND; }
 
    return AARUF_STATUS_OK;
}

AARU_EXPORT int32_t AARU_CALL aaruf_get_flux_captures(void *context, uint8_t *buffer, size_t *length)
{
    TRACE("Entering aaruf_get_flux_captures(%p, %p, %zu)", context, buffer, (length ? *length : 0));
 
    // Check context is correct AaruFormat context
    if(context == NULL)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    aaruformat_context *ctx = (aaruformat_context *)context;
 
    // Not a libaaruformat context
    if(ctx->magic != AARU_MAGIC)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    // Lazy load flux entries if not already loaded
    int32_t res = ensure_flux_entries_loaded(ctx);
    if(res != AARUF_STATUS_OK)
    {
        TRACE("Exiting aaruf_get_flux_captures() = %d", res);
        return res;
    }
 
    if(ctx->flux_data_header.entries == 0 || ctx->flux_entries == NULL)
    {
        FATAL("Image contains no flux captures");
        TRACE("Exiting aaruf_get_flux_captures() = AARUF_ERROR_FLUX_DATA_NOT_FOUND");
        return AARUF_ERROR_FLUX_DATA_NOT_FOUND;
    }
 
    size_t required_length = ctx->flux_data_header.entries * sizeof(FluxCaptureMeta);
 
    if(length == NULL)
    {
        TRACE("Buffer too small for flux captures, required %zu bytes", required_length);
        TRACE("Exiting aaruf_get_flux_captures() = AARUF_ERROR_BUFFER_TOO_SMALL");
        return AARUF_ERROR_BUFFER_TOO_SMALL;
    }
 
    if(buffer == NULL || *length < required_length)
    {
        *length = required_length;
        TRACE("Buffer too small for flux captures, required %zu bytes", required_length);
        TRACE("Exiting aaruf_get_flux_captures() = AARUF_ERROR_BUFFER_TOO_SMALL");
        return AARUF_ERROR_BUFFER_TOO_SMALL;
    }
 
    FluxCaptureMeta *out_entries = (FluxCaptureMeta *)buffer;
    for(uint16_t i = 0; i < ctx->flux_data_header.entries; i++)
    {
        const FluxEntry *entry         = &ctx->flux_entries[i];
        out_entries[i].head            = entry->head;
        out_entries[i].track           = entry->track;
        out_entries[i].subtrack        = entry->subtrack;
        out_entries[i].captureIndex    = entry->captureIndex;
        out_entries[i].indexResolution = entry->indexResolution;
        out_entries[i].dataResolution  = entry->dataResolution;
    }
 
    *length = required_length;
 
    TRACE("Exiting aaruf_get_flux_captures(%p, %p, %zu) = AARUF_STATUS_OK", context, buffer, *length);
    return AARUF_STATUS_OK;
}

AARU_EXPORT int32_t AARU_CALL aaruf_write_flux_capture(void *context, uint32_t head, uint16_t track, uint8_t subtrack,
                                                       uint32_t capture_index, uint64_t data_resolution,
                                                       uint64_t index_resolution, const uint8_t *data,
                                                       uint32_t data_length, const uint8_t *index,
                                                       uint32_t index_length)
{
    TRACE("Entering aaruf_add_flux_capture(%p, %u, %u, %u, %u, %" PRIu64 ", %" PRIu64 ", %p, %u, %p, %u)", context,
          head, track, subtrack, capture_index, data_resolution, index_resolution, data, data_length, index,
          index_length);
 
    if(context == NULL)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    aaruformat_context *ctx = context;
 
    if(ctx->magic != AARU_MAGIC)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    if(!ctx->is_writing)
    {
        FATAL("Flux captures can only be added when writing");
        return AARUF_READ_ONLY;
    }
 
    if((index_length != 0 && index == NULL) || (data_length != 0 && data == NULL))
    {
        FATAL("Invalid flux capture buffers");
        return AARUF_ERROR_INCORRECT_DATA_SIZE;
    }
 
    if((uint64_t)data_length + index_length > UINT32_MAX)
    {
        FATAL("Flux capture too large (%" PRIu64 " bytes)", (uint64_t)data_length + index_length);
        return AARUF_ERROR_INCORRECT_DATA_SIZE;
    }
 
    if(ctx->flux_captures == NULL)
    {
        utarray_new(ctx->flux_captures, &FLUX_CAPTURE_RECORD_ICD);
        if(ctx->flux_captures == NULL)
        {
            FATAL("Could not allocate flux capture storage");
            return AARUF_ERROR_NOT_ENOUGH_MEMORY;
        }
    }
 
    size_t existing_captures = utarray_len(ctx->flux_captures);
    if(existing_captures >= UINT16_MAX)
    {
        FATAL("Flux capture limit exceeded (%zu >= %u)", existing_captures, UINT16_MAX);
        return AARUF_ERROR_INCORRECT_DATA_SIZE;
    }
 
    uint8_t *data_copy  = NULL;
    uint8_t *index_copy = NULL;
 
    if(data_length != 0)
    {
        data_copy = malloc(data_length);
        if(data_copy == NULL)
        {
            FATAL("Could not allocate %u bytes for flux data", data_length);
            return AARUF_ERROR_NOT_ENOUGH_MEMORY;
        }
        memcpy(data_copy, data, data_length);
    }
 
    if(index_length != 0)
    {
        index_copy = malloc(index_length);
        if(index_copy == NULL)
        {
            free(data_copy);
            FATAL("Could not allocate %u bytes for flux index", index_length);
            return AARUF_ERROR_NOT_ENOUGH_MEMORY;
        }
        memcpy(index_copy, index, index_length);
    }
 
    FluxCaptureRecord record     = {0};
    record.entry.head            = head;
    record.entry.track           = track;
    record.entry.subtrack        = subtrack;
    record.entry.captureIndex    = capture_index;
    record.entry.dataResolution  = data_resolution;
    record.entry.indexResolution = index_resolution;
    record.entry.indexOffset     = data_length;
    record.entry.payloadOffset   = 0;
    record.data_buffer           = data_copy;
    record.data_length           = data_length;
    record.index_buffer          = index_copy;
    record.index_length          = index_length;
 
    FluxEntry *new_entries = realloc(ctx->flux_entries, (existing_captures + 1) * sizeof(FluxEntry));
    if(new_entries == NULL)
    {
        free(data_copy);
        free(index_copy);
        FATAL("Could not grow flux entry array");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    ctx->flux_entries = new_entries;
    utarray_push_back(ctx->flux_captures, &record);
 
    ctx->flux_entries[existing_captures] = record.entry;
    ctx->flux_data_header.identifier     = FluxDataBlock;
    ctx->flux_data_header.entries        = (uint16_t)(existing_captures + 1);
    ctx->flux_data_header.crc64 =
        aaruf_crc64_data((const uint8_t *)ctx->flux_entries, ctx->flux_data_header.entries * sizeof(FluxEntry));
    ctx->dirty_flux_block = true;
 
    FluxCaptureKey key = {head, track, subtrack, capture_index};
    if(flux_map_add(ctx, &key, (uint32_t)existing_captures) != 0)
    {
        FATAL("Could not add flux capture to lookup map");
 
        size_t len = utarray_len(ctx->flux_captures);
        if(len > 0) utarray_erase(ctx->flux_captures, len - 1, 1);
 
        if(existing_captures == 0)
        {
            free(ctx->flux_entries);
            ctx->flux_entries = NULL;
        }
        else
        {
            FluxEntry *shrunk = realloc(ctx->flux_entries, existing_captures * sizeof(FluxEntry));
            if(shrunk != NULL) ctx->flux_entries = shrunk;
        }
 
        ctx->flux_data_header.entries = (uint16_t)existing_captures;
        ctx->flux_data_header.crc64   = existing_captures == 0 ? 0
                                                               : aaruf_crc64_data((const uint8_t *)ctx->flux_entries,
                                                                                  existing_captures * sizeof(FluxEntry));
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    TRACE("Exiting aaruf_add_flux_capture() = AARUF_STATUS_OK (captures=%u)", ctx->flux_data_header.entries);
    return AARUF_STATUS_OK;
}

AARU_EXPORT int32_t AARU_CALL aaruf_clear_flux_captures(void *context)
{
    TRACE("Entering aaruf_clear_flux_captures(%p)", context);
 
    if(context == NULL)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    aaruformat_context *ctx = context;
 
    if(ctx->magic != AARU_MAGIC)
    {
        FATAL("Invalid context");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    if(ctx->flux_captures != NULL)
    {
        utarray_free(ctx->flux_captures);
        ctx->flux_captures = NULL;
    }
 
    flux_map_clear(ctx);
 
    free(ctx->flux_entries);
    ctx->flux_entries = NULL;
 
    memset(&ctx->flux_data_header, 0, sizeof(FluxHeader));
 
    TRACE("Exiting aaruf_clear_flux_captures() = AARUF_STATUS_OK");
    return AARUF_STATUS_OK;
}

static const FluxEntry *find_flux_entry_by_key(const aaruformat_context *ctx, const FluxCaptureKey *key)
{
    // Try lookup map first (O(1))
    if(ctx->flux_map != NULL)
    {
        FluxCaptureMapEntry *map_entry = NULL;
        HASH_FIND(hh, ctx->flux_map, key, sizeof(FluxCaptureKey), map_entry);
        if(map_entry != NULL && map_entry->index < ctx->flux_data_header.entries)
            return &ctx->flux_entries[map_entry->index];
    }
 
    // Fall back to linear search (O(n))
    for(uint32_t i = 0; i < ctx->flux_data_header.entries; i++)
    {
        const FluxEntry *entry = &ctx->flux_entries[i];
        if(entry->head == key->head && entry->track == key->track && entry->subtrack == key->subtrack &&
           entry->captureIndex == key->captureIndex)
            return entry;
    }
 
    return NULL;
}

static int32_t read_flux_payload_header(const aaruformat_context *ctx, uint64_t payload_offset,
                                        DataStreamPayloadHeader *header)
{
    if(aaruf_fseek(ctx->imageStream, (aaru_off_t)payload_offset, SEEK_SET) < 0)
    {
        FATAL("Could not seek to flux payload at offset %" PRIu64, payload_offset);
        TRACE("Exiting read_flux_payload_header() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    aaru_off_t file_position = aaruf_ftell(ctx->imageStream);
    if(file_position < 0 || (uint64_t)file_position != payload_offset)
    {
        FATAL("Invalid flux payload position (expected %" PRIu64 ", got %ld)", payload_offset, file_position);
        TRACE("Exiting read_flux_payload_header() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    size_t read_bytes = fread(header, 1, sizeof(DataStreamPayloadHeader), ctx->imageStream);
    if(read_bytes != sizeof(DataStreamPayloadHeader))
    {
        FATAL("Could not read flux payload header at offset %" PRIu64, payload_offset);
        TRACE("Exiting read_flux_payload_header() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    if(header->identifier != DataStreamPayloadBlock)
    {
        FATAL("Incorrect identifier 0x%08" PRIx32 " for flux payload at offset %" PRIu64, header->identifier,
              payload_offset);
        TRACE("Exiting read_flux_payload_header() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    if(header->dataType != kDataTypeFluxData)
    {
        FATAL("Incorrect data type %u for flux payload at offset %" PRIu64 " (expected FluxData)", header->dataType,
              payload_offset);
        TRACE("Exiting read_flux_payload_header() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    return AARUF_STATUS_OK;
}

static int32_t read_uncompressed_payload(const aaruformat_context *ctx, size_t cmp_length, size_t raw_length,
                                         uint8_t **cmp_buffer, uint8_t **payload)
{
    if(cmp_length != raw_length)
    {
        FATAL("Flux payload lengths mismatch for uncompressed block (cmp=%zu, raw=%zu)", cmp_length, raw_length);
        TRACE("Exiting read_uncompressed_payload() = AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK\n");
        return AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK;
    }
 
    if(cmp_length == 0)
    {
        *cmp_buffer = NULL;
        *payload    = NULL;
        return AARUF_STATUS_OK;
    }
 
    *cmp_buffer = (uint8_t *)malloc(cmp_length);
    if(*cmp_buffer == NULL)
    {
        FATAL("Could not allocate %zu bytes for flux payload", cmp_length);
        TRACE("Exiting read_uncompressed_payload() = AARUF_ERROR_NOT_ENOUGH_MEMORY\n");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    size_t read_bytes = fread(*cmp_buffer, 1, cmp_length, ctx->imageStream);
    if(read_bytes != cmp_length)
    {
        FATAL("Could not read %zu bytes of flux payload", cmp_length);
        free(*cmp_buffer);
        *cmp_buffer = NULL;
        TRACE("Exiting read_uncompressed_payload() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    *payload = *cmp_buffer;
    return AARUF_STATUS_OK;
}

static int32_t read_lzma_compressed_payload(const aaruformat_context *ctx, size_t cmp_length, size_t raw_length,
                                            uint8_t **cmp_buffer, uint8_t **payload)
{
    if(cmp_length <= LZMA_PROPERTIES_LENGTH)
    {
        FATAL("Flux payload compressed length %zu too small for LZMA", cmp_length);
        TRACE("Exiting read_lzma_compressed_payload() = AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK\n");
        return AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK;
    }
 
    *cmp_buffer = (uint8_t *)malloc(cmp_length);
    if(*cmp_buffer == NULL)
    {
        FATAL("Could not allocate %zu bytes for flux payload", cmp_length);
        TRACE("Exiting read_lzma_compressed_payload() = AARUF_ERROR_NOT_ENOUGH_MEMORY\n");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    size_t read_bytes = fread(*cmp_buffer, 1, cmp_length, ctx->imageStream);
    if(read_bytes != cmp_length)
    {
        FATAL("Could not read %zu bytes of flux payload", cmp_length);
        free(*cmp_buffer);
        *cmp_buffer = NULL;
        TRACE("Exiting read_lzma_compressed_payload() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    if(raw_length == 0)
    {
        *payload = NULL;
        return AARUF_STATUS_OK;
    }
 
    *payload = (uint8_t *)malloc(raw_length);
    if(*payload == NULL)
    {
        FATAL("Could not allocate %zu bytes for decompressed flux payload", raw_length);
        free(*cmp_buffer);
        *cmp_buffer = NULL;
        TRACE("Exiting read_lzma_compressed_payload() = AARUF_ERROR_NOT_ENOUGH_MEMORY\n");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    size_t         cmp_stream_len = cmp_length - LZMA_PROPERTIES_LENGTH;
    size_t         dst_len        = raw_length;
    size_t         src_len        = cmp_stream_len;
    const uint8_t *cmp_props      = *cmp_buffer;
    const uint8_t *cmp_stream     = *cmp_buffer + LZMA_PROPERTIES_LENGTH;
    int32_t        error_no =
        aaruf_lzma_decode_buffer(*payload, &dst_len, cmp_stream, &src_len, cmp_props, LZMA_PROPERTIES_LENGTH);
    if(error_no != 0 || dst_len != raw_length)
    {
        FATAL("LZMA decompression failed for flux payload (err=%d, dst=%zu/%zu)", error_no, dst_len, raw_length);
        free(*payload);
        free(*cmp_buffer);
        *payload    = NULL;
        *cmp_buffer = NULL;
        TRACE("Exiting read_lzma_compressed_payload() = AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK\n");
        return AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK;
    }
 
    return AARUF_STATUS_OK;
}

static int32_t read_zstd_compressed_payload(const aaruformat_context *ctx, size_t cmp_length, size_t raw_length,
                                            uint8_t **cmp_buffer, uint8_t **payload)
{
    if(cmp_length == 0)
    {
        FATAL("Flux payload compressed length is zero for zstd");
        TRACE("Exiting read_zstd_compressed_payload() = AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK\n");
        return AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK;
    }
 
    *cmp_buffer = (uint8_t *)malloc(cmp_length);
    if(*cmp_buffer == NULL)
    {
        FATAL("Could not allocate %zu bytes for flux payload", cmp_length);
        TRACE("Exiting read_zstd_compressed_payload() = AARUF_ERROR_NOT_ENOUGH_MEMORY\n");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    size_t read_bytes = fread(*cmp_buffer, 1, cmp_length, ctx->imageStream);
    if(read_bytes != cmp_length)
    {
        FATAL("Could not read %zu bytes of flux payload", cmp_length);
        free(*cmp_buffer);
        *cmp_buffer = NULL;
        TRACE("Exiting read_zstd_compressed_payload() = AARUF_ERROR_CANNOT_READ_BLOCK\n");
        return AARUF_ERROR_CANNOT_READ_BLOCK;
    }
 
    if(raw_length == 0)
    {
        *payload = NULL;
        return AARUF_STATUS_OK;
    }
 
    *payload = (uint8_t *)malloc(raw_length);
    if(*payload == NULL)
    {
        FATAL("Could not allocate %zu bytes for decompressed flux payload", raw_length);
        free(*cmp_buffer);
        *cmp_buffer = NULL;
        TRACE("Exiting read_zstd_compressed_payload() = AARUF_ERROR_NOT_ENOUGH_MEMORY\n");
        return AARUF_ERROR_NOT_ENOUGH_MEMORY;
    }
 
    size_t dst_len = aaruf_zstd_decode_buffer(*payload, raw_length, *cmp_buffer, cmp_length);
    if(dst_len != raw_length)
    {
        FATAL("Zstd decompression failed for flux payload (dst=%zu/%zu)", dst_len, raw_length);
        free(*payload);
        free(*cmp_buffer);
        *payload    = NULL;
        *cmp_buffer = NULL;
        TRACE("Exiting read_zstd_compressed_payload() = AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK\n");
        return AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK;
    }
 
    return AARUF_STATUS_OK;
}

static int32_t validate_flux_payload_crcs(const uint8_t *cmp_buffer, size_t cmp_length, const uint8_t *payload,
                                          size_t raw_length, uint64_t expected_cmp_crc, uint64_t expected_raw_crc)
{
    uint64_t cmp_crc = 0;
    if(cmp_length != 0 && cmp_buffer != NULL) cmp_crc = aaruf_crc64_data(cmp_buffer, cmp_length);
 
    if(cmp_crc != expected_cmp_crc)
    {
        FATAL("Flux payload compressed CRC mismatch (expected 0x%" PRIx64 ", got 0x%" PRIx64 ")", expected_cmp_crc,
              cmp_crc);
        TRACE("Exiting validate_flux_payload_crcs() = AARUF_ERROR_INVALID_BLOCK_CRC\n");
        return AARUF_ERROR_INVALID_BLOCK_CRC;
    }
 
    uint64_t raw_crc = 0;
    if(raw_length != 0 && payload != NULL) raw_crc = aaruf_crc64_data(payload, raw_length);
 
    if(raw_crc != expected_raw_crc)
    {
        FATAL("Flux payload raw CRC mismatch (expected 0x%" PRIx64 ", got 0x%" PRIx64 ")", expected_raw_crc, raw_crc);
        TRACE("Exiting validate_flux_payload_crcs() = AARUF_ERROR_INVALID_BLOCK_CRC\n");
        return AARUF_ERROR_INVALID_BLOCK_CRC;
    }
 
    return AARUF_STATUS_OK;
}

static int32_t extract_flux_data_buffers(const FluxEntry *flux_entry, const uint8_t *payload, size_t raw_length,
                                         uint8_t *data_data, uint32_t *data_length, uint8_t *index_data,
                                         uint32_t *index_length)
{
    if(flux_entry->indexOffset > raw_length)
    {
        FATAL("Flux index offset %" PRIu64 " beyond payload length %zu", flux_entry->indexOffset, raw_length);
        TRACE("Exiting extract_flux_data_buffers() = AARUF_ERROR_INVALID_BLOCK_CRC\n");
        return AARUF_ERROR_INVALID_BLOCK_CRC;
    }
 
    uint64_t data_length_required64  = flux_entry->indexOffset;
    uint64_t index_length_required64 = raw_length - flux_entry->indexOffset;
 
    if(data_length_required64 > UINT32_MAX || index_length_required64 > UINT32_MAX)
    {
        FATAL("Flux payload section length exceeds 32-bit limits (data=%" PRIu64 ", index=%" PRIu64 ")",
              data_length_required64, index_length_required64);
        TRACE("Exiting extract_flux_data_buffers() = AARUF_ERROR_INCORRECT_DATA_SIZE\n");
        return AARUF_ERROR_INCORRECT_DATA_SIZE;
    }
 
    uint32_t data_required  = (uint32_t)data_length_required64;
    uint32_t index_required = (uint32_t)index_length_required64;
 
    uint32_t data_capacity  = *data_length;
    uint32_t index_capacity = *index_length;
 
    *data_length  = data_required;
    *index_length = index_required;
 
    if(data_data == NULL || index_data == NULL || data_capacity < data_required || index_capacity < index_required)
    {
        TRACE("Returning required flux capture sizes (data=%u, index=%u)\n", data_required, index_required);
        return AARUF_ERROR_BUFFER_TOO_SMALL;
    }
 
    const uint8_t *index_ptr = payload ? payload + data_length_required64 : NULL;
    const uint8_t *data_ptr  = payload;
 
    if(data_required != 0 && data_ptr != NULL) memcpy(data_data, data_ptr, data_required);
    if(index_required != 0 && index_ptr != NULL) memcpy(index_data, index_ptr, index_required);
 
    return AARUF_STATUS_OK;
}

AARU_EXPORT int32_t AARU_CALL aaruf_read_flux_capture(void *context, uint32_t head, uint16_t track, uint8_t subtrack,
                                                      uint32_t capture_index, uint8_t *index_data,
                                                      uint32_t *index_length, uint8_t *data_data, uint32_t *data_length)
{
    TRACE("Entering aaruf_read_flux_capture(%p, %u, %u, %u, %u, %p, %p, %p, %p)", context, head, track, subtrack,
          capture_index, index_data, index_length, data_data, data_length);
 
    if(context == NULL)
    {
        FATAL("Invalid context");
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_NOT_AARUFORMAT");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    aaruformat_context *ctx = (aaruformat_context *)context;
 
    if(ctx->magic != AARU_MAGIC)
    {
        FATAL("Invalid context");
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_NOT_AARUFORMAT");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    // Lazy load flux entries if not already loaded
    int32_t load_res = ensure_flux_entries_loaded(ctx);
    if(load_res != AARUF_STATUS_OK)
    {
        TRACE("Exiting aaruf_read_flux_capture() = %d", load_res);
        return load_res;
    }
 
    if(ctx->flux_data_header.entries == 0 || ctx->flux_entries == NULL)
    {
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_FLUX_DATA_NOT_FOUND");
        return AARUF_ERROR_FLUX_DATA_NOT_FOUND;
    }
 
    if(index_length == NULL || data_length == NULL)
    {
        FATAL("index_length or data_length pointers are NULL");
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_BUFFER_TOO_SMALL\n");
        return AARUF_ERROR_BUFFER_TOO_SMALL;
    }
 
    if(ctx->imageStream == NULL)
    {
        FATAL("Invalid image stream");
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_NOT_AARUFORMAT\n");
        return AARUF_ERROR_NOT_AARUFORMAT;
    }
 
    FluxCaptureKey   key        = {head, track, subtrack, capture_index};
    const FluxEntry *flux_entry = find_flux_entry_by_key(ctx, &key);
    if(flux_entry == NULL)
    {
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_FLUX_DATA_NOT_FOUND\n");
        return AARUF_ERROR_FLUX_DATA_NOT_FOUND;
    }
 
    TRACE("Requested flux capture: head=%u track=%u subtrack=%u captureIndex=%u payloadOffset=%" PRIu64 "\n",
          flux_entry->head, flux_entry->track, flux_entry->subtrack, flux_entry->captureIndex,
          flux_entry->payloadOffset);
 
    // Get block alignment shift from FluxHeader
    uint8_t block_alignment_shift = ctx->flux_data_header.blockAlignmentShift;
 
    // Convert payloadOffset from block-aligned units to absolute file offset
    // payloadOffset is stored divided by (1 << blockAlignmentShift), consistent with DDT
    uint64_t absolute_payload_offset = flux_entry->payloadOffset << block_alignment_shift;
 
    DataStreamPayloadHeader payload_header;
    int32_t                 res = read_flux_payload_header(ctx, absolute_payload_offset, &payload_header);
    if(res != AARUF_STATUS_OK)
    {
        TRACE("Exiting aaruf_read_flux_capture() = %d\n", res);
        return res;
    }
 
    const CompressionType compression = (CompressionType)payload_header.compression;
    uint8_t              *cmp_buffer  = NULL;
    uint8_t              *payload     = NULL;
    size_t                cmp_length  = payload_header.cmpLength;
    size_t                raw_length  = payload_header.length;
 
    if(compression == kCompressionNone)
    {
        res = read_uncompressed_payload(ctx, cmp_length, raw_length, &cmp_buffer, &payload);
    }
    else if(compression == kCompressionLzma)
    {
        res = read_lzma_compressed_payload(ctx, cmp_length, raw_length, &cmp_buffer, &payload);
    }
    else if(compression == kCompressionZstd)
    {
        res = read_zstd_compressed_payload(ctx, cmp_length, raw_length, &cmp_buffer, &payload);
    }
    else
    {
        FATAL("Unsupported flux payload compression type %u", payload_header.compression);
        TRACE("Exiting aaruf_read_flux_capture() = AARUF_ERROR_UNSUPPORTED_COMPRESSION\n");
        return AARUF_ERROR_UNSUPPORTED_COMPRESSION;
    }
 
    if(res != AARUF_STATUS_OK)
    {
        TRACE("Exiting aaruf_read_flux_capture() = %d\n", res);
        return res;
    }
 
    res = validate_flux_payload_crcs(cmp_buffer, cmp_length, payload, raw_length, payload_header.cmpCrc64,
                                     payload_header.crc64);
    if(res != AARUF_STATUS_OK)
    {
        if(payload != NULL && payload != cmp_buffer) free(payload);
        if(cmp_buffer != NULL) free(cmp_buffer);
        TRACE("Exiting aaruf_read_flux_capture() = %d\n", res);
        return res;
    }
 
    res = extract_flux_data_buffers(flux_entry, payload, raw_length, data_data, data_length, index_data, index_length);
    if(res != AARUF_STATUS_OK)
    {
        if(payload != NULL && payload != cmp_buffer) free(payload);
        if(cmp_buffer != NULL) free(cmp_buffer);
        TRACE("Exiting aaruf_read_flux_capture() = %d\n", res);
        return res;
    }
 
    if(payload != NULL && payload != cmp_buffer) free(payload);
    if(cmp_buffer != NULL) free(cmp_buffer);
 
    TRACE("Exiting aaruf_read_flux_capture() = AARUF_STATUS_OK\n");
    return AARUF_STATUS_OK;
}